Feat: Add performance optimizations for iCloud directory scanning

[mihaho]

Description

First of all, thank you for this great library! 🙏 I'm integrating it in our app and also want to add directory tree reports, but I've hit a wall with iCloud performance. The issue is that when scanning folders on iCloud, FileManager methods like displayName, attributesOfItem, and contentsOfDirectory can each take multiple seconds when files aren't fully synced. So a single directory can take over a minute to scan, making the feature unusable.

Changes

I added two things:

1. a NameExtraction enum that lets you skip the slow displayName call. You can use .raw to get the name directly from the path (it's instant but not localized), or stick with .localized for the current behavior
2. a skipDirectoryContents closure that lets you bail out of traversing specific folders. It uses fileExists instead of attributesOfItem to check directory type, which is much faster on iCloud. The directory still shows up in the tree, it just doesn't scan inside

Both default to the current behavior so nothing breaks.

This solves our iCloud issue, but the feature is general-purpose. It works for skipping any folders you don't want to traverse (at any level). Sorry for not discussing first. Would appreciate any feedback on whether this fits the library's direction.

[github-actions]

This PR is stale because it has been open for 30 days with no activity. Remove the Stale label or comment or this will be closed in 10 days.

[mihaho]

@AvdLee just checking in on this. Happy to make changes if needed or close it if this is not a good fit