[BUG] filesystem: skip symbolic links instead of aborting

[CybotTM]

Problem

FlySystemAdapter::createForPath() in packages/filesystem/src/FlySystemAdapter.php instantiates the Local/Flysystem adapter with the default link-handling mode, which is DISALLOW_LINKS in both league/flysystem v1 and v3. Any symbolic link encountered during listContents() throws and aborts the caller — v1 with NotSupportedException, v3 with SymbolicLinkEncountered.

phpDocumentor\Guides\Handlers\ParseDirectoryHandler uses FlySystemAdapter::listContents() to discover the entrypoint file of an input directory, so a single symlink anywhere in the input tree kills the run, even for symlinks that point to files the parser would otherwise ignore (e.g. CLAUDE.md -> AGENTS.md for cross-tool AI instructions, vendored references, build artefacts).

Downstream report in the TYPO3 render-guides wrapper: TYPO3-Documentation/render-guides#1234.

Fix

Pass SKIP_LINKS as the link-handling argument to both the v1 and v3 Local adapters. This preserves the current "do not follow links" posture but turns an abort into a silent skip — matching how most documentation builders treat filesystem entries they can't or shouldn't parse.

-            $filesystem = new FlysystemV1(new LeagueFilesystem(new Local($path)));
+            $filesystem = new FlysystemV1(new LeagueFilesystem(new Local($path, LOCK_EX, Local::SKIP_LINKS)));
         } else {
             $filesystem = new FlysystemV3(
                 new LeagueFilesystem(
-                    new LocalFilesystemAdapter($path),
+                    new LocalFilesystemAdapter($path, linkHandling: LocalFilesystemAdapter::SKIP_LINKS),

• v1 uses positional args (its constructor predates named arguments); LOCK_EX is the library's own default for $writeFlags and has to be restated to reach the $linkHandling slot.
• v3 uses a named argument, skipping the unchanged $visibility and $writeFlags.

Rationale

Two paths would have been equivalent from Flysystem's side:

1. SKIP_LINKS — encounters are silently skipped during listing.
2. DISALLOW_LINKS with the exception caught at call sites and treated as skip.

SKIP_LINKS is the narrower, non-intrusive change: it fixes every caller at once, requires no error-handling adjustments in ParseDirectoryHandler or any future consumer, and the semantics ("do not follow symlinks but do not error on them") are what almost all docs builders actually want.

If a stricter mode is ever needed, FlySystemAdapter::createForPath could grow an optional parameter; default stays SKIP_LINKS.

Reproduction

mkdir -p /tmp/repro && cd /tmp/repro
mkdir docs && echo -e "=====\nIndex\n=====" > docs/index.rst
ln -s index.rst docs/alias.rst
# Using any current render-guides build:
# guides render --config=docs --output=out docs
# before: abort with SymbolicLinkEncountered at docs/alias.rst
# after:  alias.rst silently skipped, build succeeds

Tests

I didn't add a unit test — packages/filesystem/tests/unit/ currently has no tests for FlySystemAdapter::createForPath and the existing tests exercise Path and Finder\SpecificationFactory. Happy to add one if you point me at the preferred style (tmpdir + symlink + assert no throw); didn't want to invent a pattern.