BUG: Custom Sort always called with a {type="Dir", path="foo"} argument

[FalcoGer]

Did you check docs and existing issues?

• I have read all the docs.
• I have searched the existing issues.
• I have searched the existing discussions.

Neovim Version (nvim -v)

NVIM v0.10.0-dev-e59cf3b3a

Operating System / Version

Ubuntu Mate 22.04

Describe the Bug

When using a custom sorting function, it is always called at least once with an object that doesn't actually exist. The object looks like

local fooObj = {
  type = "Dir",
  path = "foo"
}

This is a problem because one needs to filter out this object from their search, because sorting by another field like name causes a lua error to occur, because the erroneous foo object doesn't have such other fields that one might want to sort by.

Screenshots, Traceback

No response

Steps to Reproduce

1. Use this sort function

-- Sort function for files
local sortFunc = function(a, b)
    -- keys of a and b
    -- not documented anywhere
    --   parent_path:           full, absolute path of parent directory
    --   type:                  "directory" (even for links), or "file"
    --   path:                  full, absolute path, no trailing slash
    --   name:                  file name
    --   is_link                bool is a symlink
    --   is_reveal_target       bool ??
    --   link_to                full, absolute path to link target
    --   loaded                 bool if file is loaded in editor
    --   id                     seems to be same as path
    --   children               type of a/b table, directories only
    --   exts                   file extension  ??, files only
    --   ext                    file extension  ??, filey only
    --   name_lcase             name, but lowercase, files only?

    if a.name == nil then
        local s = ""
        if a ~= nil and type(a) == 'table' then
            for k, v in pairs(a) do
                s = s .. '[' .. k .. '] = ' .. tostring(v) .. ' , '
            end
        else
            s = s .. tostring(a)
        end
        print(s)
        return false
    end

    if b.name == nil then
        local s = ""
        if b ~= nil and type(b) == 'table' then
            for k, v in pairs(b) do
                s = s .. '[' .. k .. '] = ' .. tostring(v) .. ' , '
            end
        else
            s = s .. tostring(b)
        end
        print(s)
        return true
    end

    if a.type == "directory" and b.type ~= "directory" then
         -- directories first
        return true
    end
    if b.type == "directory" and a.type ~= "directory" then
        -- directories first
        return false
    end

    if a.name:sub(1, 1) == '.' and b.name:sub(1, 1) ~= '.' then
        -- dotfiles last
        return false
    end
    if b.name:sub(1, 1) == '.' and a.name:sub(1, 1) ~= '.' then
        -- dotfiles last
        return true
    end
    -- otherwise just sort by name, case insensitive
    return a.name:upper() < b.name:upper()
end

2. Open :Neotree
3. Observe output from print

Expected Behavior

Every item has a field "name"
Documentation on what the sort function's arguments are is available in :h neo-tree

Your Configuration

-

[cseickel]

That is a test function that is used to confirm your custom sort function is valid before it is used. Your sort function should not assume that any particular field exists, and must always return a boolean value no matter what was passed in.

[FalcoGer]

Then that test function should at least have all the same fields that are guaranteed to be present in all other items, and it should be documented, as should be the fields and what they mean.

[cseickel]

Then that test function should at least have all the same fields that are guaranteed to be present in all other items,

There is no such guarantee. I think that in practice type and id are required, but everything else is source specific. A sort function should not assume that any particular field exists.

If you want to submit a PR that to enhance that documentation, I'll happily accept it. For the most part however, the fields are internal implementation details that could change at any time. type and path are the two that you are expected to use for this custom sort function.

I should also point out that the custom sort function is mostly legacy at this point, as there are now built in sort mappings for most fields.

o  = order_by...     Show help menu for order by choices.

oc = ...created:     Sort the tree by created date.

od = ...diagnostics: Sort by diagnostic severity.

og = ...git_status:  Sort by git status.

om = ...modified:    Sort by last modified date.

on = ...name:        Sort by name (default sort).

os = ...size:        Sort by size.

ot = ...type:        Sort by type.

[FalcoGer]

I want to sort directories before files and dotfiles at the end of directories/files respectively. currently such a sort is only possible with that custom sort.

[MangoMagoCane]

Besides the keys listed above there is also an additional key filtered_by that is a table if an item is hidden and nil otherwise.

[quadruple-output]

I realize a few things:

1. The help texts for the sort mappings mentioned above are not quite accurate. The description for on is "Sort by name", but the actual algorithm first sorts by type (dir vs. file), and only then by name.
2. When I implement the custom sort function, and then use any of the pre-defined sort mappings, I do not know how to go back to my custom function.
3. (feature request) There does not seem to be a built-in way of sorting by name only.

This last missing feature brought me here :). It would be helpful for Rust src directories, where modules are typically located in sub dirs, with an additional file for each subdirectory, where the filename is like the dirname, but with the .rs extension.

src/
  module_a/
  main.rs
  module_a.rs

It would be great if the dir module_a could be shown adjacent to the file module_a.rs. Therefore, I implemented (with the help of the descriptions in this issue) a custom sort function. It reads like this:

sort_function = function(a, b)
    -- see https://github.com/nvim-neo-tree/neo-tree.nvim/issues/1226
    if a.name == nil then
        return false
    end
    if b.name == nil then
        return true
    end
    -- do not use the entry type for sorting --> mix files and folders
    return a.name:upper() < b.name:upper()
end