fix: sort symlinked rules files by symlink names, not target names

[roomote]

This PR fixes issue #4131 where symlinked rules files were being read in random order instead of alphabetical order.

Problem

The readTextFilesFromDirectory function in src/core/prompts/sections/custom-instructions.ts claimed to read files "in alphabetical order" but the implementation did not actually sort them. This caused symlinked files to appear in random order based on filesystem traversal. Additionally, the initial implementation sorted by target filenames instead of symlink names, which defeated the purpose of using numbered symlinks for ordering.

Solution

1. Refactored file tracking

• Changed from tracking just file paths to tracking both originalPath and resolvedPath
• For regular files: both paths are the same
• For symlinks: originalPath is the symlink path (e.g., 01-first.link), resolvedPath is the target path (e.g., ../config/shared.yaml)

2. Implemented proper sorting

• Files are now sorted alphabetically by their original names (case-insensitive)
• Symlinks sort by their symlink names, not the names of files they point to
• Uses localeCompare() for proper string comparison
• Maintains backward compatibility by still displaying target paths in output

3. Added comprehensive tests

• Test for general alphabetical sorting with mixed-case filenames
• Specific test that verifies symlinks are sorted by their symlink names, not their target names
• All existing tests continue to pass

Technical Details

The fix ensures that users can control the order of their rules files using symlink names (e.g., 01-database.yaml, 02-api.yaml, 03-frontend.yaml) even when these symlinks point to files with names that would sort differently.

Impact

This is a non-breaking change that only affects the order in which rules files are processed. Users will now see consistent, predictable ordering of their rules files, especially when using symlinks.

Fixes #4131

[daniel-lxs]

@roomote-agent The issue specifically mentions: "I believe that the correct way to handle this is to sort symlinks in the same way that normal files are sorted. The symlink name (not the name it points to) should be used for sorting."

The Problem:

When a symlink is resolved, the code stores the TARGET path in the filePaths array
The sorting then uses path.basename() on these target paths
This means symlinks are sorted by their target filenames, not their symlink names
What Should Happen:

The code needs to preserve the original symlink name for sorting purposes
Perhaps store both the symlink path and target path, sort by symlink names, but read from target paths

Make this changes on this PR, do not open a new one.

[roomote]

Hi @daniel-lxs, I understand the issue now. The current implementation sorts by the target filename after resolving symlinks, but it should sort by the symlink name itself. I'll update this PR to fix the sorting behavior so that symlinks are sorted by their own names, not their target names. Working on it now!

[roomote]

Hi @daniel-lxs, I've implemented the fix as requested! 🎉

Changes Made:

1. Modified readTextFilesFromDirectory to track both the original symlink path and the resolved target path
2. Updated resolveDirectoryEntry and resolveSymLink to store both paths in a new data structure
3. Changed the sorting logic to sort by the original path (symlink name) while still reading content from the resolved path
4. Added a comprehensive test that verifies symlinks are sorted by their names, not their target names

Technical Details:

The fix ensures that when symlinks are encountered:

• The symlink name is preserved for sorting purposes
• The target path is still used for reading the file content
• The output still shows the target path (maintaining existing behavior)
• But the ordering is based on the symlink names

This resolves issue #4131 where symlinked rules files were appearing in random order. Now they will be sorted alphabetically by their symlink names, just like regular files.

All tests are passing locally. The CI checks are currently running.