simplibs-path 0.1.0__py3-none-any.whl

simplibs/path/logic/ensure/ensure_parent_dir.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike
+from ..transformers import normalize_path
+# Inners
+from .ensure_dir import ensure_dir
+
+
+@validate_call
+def ensure_parent_dir(
+    path: PathLike,
+) -> Path:
+    """Guarantee that the directory a path lives in exists — without creating the path itself.
+
+    The step right before writing an output file: the file is not there
+    yet, but its folder must be.
+
+    Args:
+        path: The path (usually of a file about to be written).
+
+    Returns:
+        The normalized `Path` itself — not its parent — so the call can be
+        chained straight into the write.
+
+    Raises:
+        StateError: If a file occupies the place of a needed directory.
+        AccessError: If the parent directory cannot be created.
+    """
+
+    # 1. Normalize the target path
+    normalized_path = normalize_path(path)
+
+    # 2. Guarantee its parent directory (and everything above it)
+    ensure_dir(normalized_path.parent)
+
+    # 3. Return the path itself, ready for writing
+    return normalized_path
+
+
+_DESIGN_NOTES = """
+# ensure_parent_dir — the Step Before Writing
+
+## Purpose
+Writing `out/pkg/a.md` fails when `out/pkg/` is missing, and creating the
+*file* up front (what `ensure_file` does) is wrong when the writer wants to
+create it itself — with its own content, mode or encoding. This function
+prepares only the folder.
+
+## Returns the Path, Not the Parent
+In a pipeline the value flowing on is the file's path:
+`RebasePath(...) >> EnsureParentDir() >> write_step`. Returning the parent
+would force every caller to rebuild the path they started with.
+
+## Pure Composition
+No logic of its own: `normalize_path` and `ensure_dir` do the work, so the
+two stay the single source of truth for what "normalized" and "exists" mean.
+"""

simplibs/path/logic/scanners/__init__.py

@@ -0,0 +1,35 @@
+from .collect_dirs import collect_dirs
+from .collect_files import collect_files
+from .collect_paths import collect_paths
+from .filter_paths import filter_paths
+from .iter_paths import iter_paths
+from .ignore_names import (
+    DEFAULT_IGNORE_NAMES,
+    IGNORE_BUILD,
+    IGNORE_ENV,
+    IGNORE_GENERIC,
+    IGNORE_IDE,
+    IGNORE_SYSTEM,
+    IGNORE_VCS,
+)
+
+
+_DESIGN_NOTES = """
+# Path Scanners Sub-Package
+
+## Purpose
+Everything that looks at a directory tree: scanning it for files and
+directories, and filtering lists of paths. Nothing here changes the disk.
+
+## Internal Components Registry
+
+| Component              | Type     | Description                                                          |
+| :--------------------- | :------- | :------------------------------------------------------------------- |
+| `collect_dirs`         | Function | Sorted list of the directories in a tree.                            |
+| `collect_files`        | Function | Sorted list of the files in a tree.                                  |
+| `collect_paths`        | Function | Sorted list of files and/or directories in a tree.                   |
+| `filter_paths`         | Function | Keeps the paths of a list that satisfy a Rule or callable.           |
+| `iter_paths`           | Function | Lazy, unsorted iterator over the paths of a tree.                    |
+| `DEFAULT_IGNORE_NAMES` | Constant | The names every scan skips by default.                               |
+| `IGNORE_*`             | Constant | The named groups it is built from (`IGNORE_GENERIC` is opt-in).      |
+"""

simplibs/path/logic/scanners/_helpers/ScanEntry.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+from typing import NamedTuple
+
+
+class ScanEntry(NamedTuple):
+    """One entry found by `walk_tree`: its path and what kind of entry it is.
+
+    Attributes:
+        path: The entry's full path (the scan root joined with its relative part).
+        is_file: True for a regular file, or a symlink to one.
+        is_dir: True for a directory, or a symlink to one.
+    """
+
+    path: Path
+    is_file: bool
+    is_dir: bool
+
+
+_DESIGN_NOTES = """
+# ScanEntry — an Entry Plus Its Kind, Learned Once
+
+## Purpose
+`os.scandir` hands over the entry type as a by-product of listing (free on
+Windows, cached from the directory read on POSIX). Passing it along lets the
+collectors decide "file or directory?" without asking the disk again — the
+old code made two extra `stat` calls per entry.
+
+## Never Neither
+`walk_tree` yields only entries that are a file or a directory, so exactly
+one of the two flags is True. Broken symlinks, FIFOs, sockets and devices
+are not yielded at all.
+
+## Why a `NamedTuple`
+Tens of thousands are created per scan; a tuple subclass is as cheap as
+Python offers, is immutable, and still reads like an object (`entry.path`).
+"""

simplibs/path/logic/scanners/_helpers/__init__.py

@@ -0,0 +1,30 @@
+from .as_path_predicate import as_path_predicate
+from .build_ignore_matcher import build_ignore_matcher
+from .generate_paths import generate_paths
+from .is_link_like import is_link_like
+from .resolve_scan_root import resolve_scan_root
+from .scan_paths import scan_paths
+from .ScanEntry import ScanEntry
+from .walk_tree import walk_tree
+
+
+_DESIGN_NOTES = """
+# Path Scanners Internal Helpers Sub-Package
+
+## Purpose
+The building blocks shared by `iter_paths`, `collect_paths`, `collect_files`,
+`collect_dirs` and `filter_paths`.
+
+## Internal Components Registry
+
+| Component              | Type       | Description                                                            |
+| :--------------------- | :--------- | :--------------------------------------------------------------------- |
+| `as_path_predicate`    | Function   | Resolves a Rule or callable filter into one fast `(Path) -> bool`.     |
+| `build_ignore_matcher` | Function   | Compiles ignore names and glob patterns into an `is_ignored(name)`.    |
+| `generate_paths`       | Function   | The type-selection and filter loop over `walk_tree`.                   |
+| `is_link_like`         | Function   | Symlink or Windows junction — a directory not to be entered.           |
+| `resolve_scan_root`    | Function   | Normalizes a root and checks it exists, is a directory, is listable.   |
+| `scan_paths`           | Function   | Prepares a scan eagerly and returns the lazy result iterator.          |
+| `ScanEntry`            | NamedTuple | A found path with its kind (file or directory).                        |
+| `walk_tree`            | Function   | The `os.scandir`-based, iterative tree walker.                         |
+"""

simplibs/path/logic/scanners/_helpers/as_path_predicate.py

@@ -0,0 +1,38 @@
+from collections.abc import Callable
+from pathlib import Path
+from simplibs.rules import Rule
+
+
+def as_path_predicate(predicate: Callable[[Path], bool]) -> Callable[[Path], bool]:
+    """Turn a Rule or a plain callable into the fastest `(Path) -> bool` call.
+
+    Args:
+        predicate: A `Rule` instance or any callable taking a `Path`.
+
+    Returns:
+        `predicate.is_valid` for a `Rule` (skipping the extra call of
+        `Rule.__call__`), the callable itself otherwise.
+    """
+
+    # 1. A Rule — use its bound is_valid directly
+    if isinstance(predicate, Rule):
+        return predicate.is_valid
+
+    # 2. Any other callable is used as it is
+    return predicate
+
+
+_DESIGN_NOTES = """
+# as_path_predicate — Resolve a Filter Once
+
+## Purpose
+`collect_paths` and `filter_paths` call their filter once per entry, so the
+choice "Rule or function?" is made a single time, before the loop. A `Rule`
+is callable, but `Rule.__call__` only forwards to `is_valid` — calling
+`is_valid` directly saves one Python call per entry.
+
+## Replaces `getattr(rule, "is_valid", rule)`
+The old duck-typing accepted any object that merely *had* an `is_valid`
+attribute. An explicit `isinstance(..., Rule)` states what is meant, and the
+`HasIsValid` protocol it served no longer exists.
+"""

simplibs/path/logic/scanners/_helpers/build_ignore_matcher.py

@@ -0,0 +1,88 @@
+import os
+from collections.abc import Callable, Collection
+from fnmatch import fnmatchcase
+# Inners
+from .._validations import raise_ignore_names_not_names_error
+
+
+_GLOB_CHARS = "*?["
+
+
+def _ignore_nothing(name: str) -> bool:
+    """The matcher used when no names are ignored."""
+    return False
+
+
+def build_ignore_matcher(
+    ignore_names: Collection[str] | None,
+) -> Callable[[str], bool]:
+    """Build a fast `is_ignored(name)` function from a collection of names and patterns.
+
+    Args:
+        ignore_names: Entry names to skip. A name containing `*`, `?` or `[`
+            is a glob pattern (`*.egg-info`); every other name matches
+            exactly. `None` or an empty collection ignores nothing.
+
+    Returns:
+        A function answering True for a name that must be skipped. Matching
+        follows the platform's case rules (case-insensitive on Windows).
+
+    Raises:
+        ParamError: If `ignore_names` is a single string — it would be
+            split into characters.
+    """
+
+    # 1. A bare string is iterable — reject it before it becomes a set of characters
+    if isinstance(ignore_names, str):
+        raise_ignore_names_not_names_error(ignore_names)
+
+    # 2. Nothing to ignore
+    if not ignore_names:
+        return _ignore_nothing
+
+    # 3. Split exact names from glob patterns, case-normalized for the platform
+    exact: set[str] = set()
+    patterns: list[str] = []
+    for name in ignore_names:
+        key = os.path.normcase(name)
+        if any(char in name for char in _GLOB_CHARS):
+            patterns.append(key)
+        else:
+            exact.add(key)
+
+    # 4. Exact names only — a single set lookup per entry
+    if not patterns:
+        return lambda name: os.path.normcase(name) in exact
+
+    # 5. Exact names first, patterns only for names that did not match
+    def is_ignored(name: str) -> bool:
+        key = os.path.normcase(name)
+        if key in exact:
+            return True
+        return any(fnmatchcase(key, pattern) for pattern in patterns)
+
+    return is_ignored
+
+
+_DESIGN_NOTES = """
+# build_ignore_matcher — Names and Patterns, Compiled Once
+
+## Purpose
+The walker asks "is this name ignored?" for every entry. This function
+prepares the answer once: a set for exact names (one hash lookup) and a
+short list for glob patterns, consulted only when the set did not match.
+
+## Why `normcase` + `fnmatchcase`
+`os.path.normcase` makes names lower-case on Windows and leaves them alone
+elsewhere, and `fnmatchcase` then compares *without* a second, implicit
+normalization — one consistent platform rule for exact names and patterns.
+
+## The Single-String Guard Lives Here
+It is the one place every scanner passes `ignore_names` through, so the
+`str` trap is caught once, with the dedicated error card, and cannot be
+forgotten by a new scanner.
+
+## Returns a Function, Not a Class
+A closure over two local containers is the lightest thing that holds
+prepared state, and it is trivial to replace in a test.
+"""

simplibs/path/logic/scanners/_helpers/generate_paths.py

@@ -0,0 +1,74 @@
+from collections.abc import Callable, Iterator
+from pathlib import Path
+# Inners
+from .walk_tree import walk_tree
+
+
+def generate_paths(
+    root: Path,
+    *,
+    max_depth: float | int,
+    is_ignored: Callable[[str], bool],
+    include: Callable[[Path], bool] | None,
+    exclude: Callable[[Path], bool] | None,
+    collect_files: bool,
+    collect_dirs: bool,
+) -> Iterator[Path]:
+    """Lazily yield the paths of a tree that pass the type and filter checks.
+
+    Args:
+        root: The validated, normalized scan root.
+        max_depth: See `walk_tree`.
+        is_ignored: See `walk_tree`.
+        include: If given, only paths it accepts are yielded.
+        exclude: If given, paths it accepts are skipped (checked first).
+        collect_files: Whether files are yielded.
+        collect_dirs: Whether directories are yielded.
+
+    Yields:
+        Matching `Path`s, in walk order (unsorted).
+    """
+
+    # 1. Walk the tree
+    for entry in walk_tree(root, max_depth=max_depth, is_ignored=is_ignored):
+
+        # 1.1 Apply the file/directory type selection (a directory symlink counts as a directory)
+        if entry.is_dir:
+            if not collect_dirs:
+                continue
+        elif not collect_files:
+            continue
+
+        # 1.2 Apply the exclude filter — it wins over include
+        if exclude is not None and exclude(entry.path):
+            continue
+
+        # 1.3 Apply the include filter
+        if include is not None and not include(entry.path):
+            continue
+
+        # 1.4 Yield the matching path
+        yield entry.path
+
+
+_DESIGN_NOTES = """
+# generate_paths — the Selection Loop, Written Once
+
+## Purpose
+The common core of `iter_paths` (yields it), `collect_paths` (sorts it) and
+`collect_files`/`collect_dirs` (fix the flags): type selection, then
+`exclude`, then `include`.
+
+## Positive Type Selection
+The old loop skipped "files when files are off" and "directories when
+directories are off" separately, so an entry that was neither (a broken
+symlink) slipped through *both* guards and was collected. `walk_tree` now
+yields only files and directories, and the selection below handles both
+cases explicitly.
+
+## Filters Do Not Prune
+`exclude` hides a directory *entry* but its contents are still walked and
+judged on their own — only `ignore_names` prunes a subtree. This is
+deliberate (a filter on a directory says nothing about its children) and
+documented on the public functions.
+"""

simplibs/path/logic/scanners/_helpers/is_link_like.py

@@ -0,0 +1,45 @@
+import os
+import stat
+
+
+def is_link_like(entry: os.DirEntry) -> bool:
+    """Check whether a directory entry is a symlink or a Windows junction.
+
+    Args:
+        entry: A directory entry from `os.scandir`.
+
+    Returns:
+        True for a symlink on any platform, and — on Windows — for a
+        directory junction (mount point). Entering such a directory could
+        loop forever or leave the scanned tree.
+    """
+
+    # 1. A symlink, on any platform
+    if entry.is_symlink():
+        return True
+
+    # 2. Only Windows has junctions — nothing more to check elsewhere
+    if os.name != "nt":
+        return False
+
+    # 3. A junction reports itself as a mount-point reparse tag (cached by scandir, no extra syscall)
+    reparse_tag = getattr(entry.stat(follow_symlinks=False), "st_reparse_tag", 0)
+    return reparse_tag == stat.IO_REPARSE_TAG_MOUNT_POINT
+
+
+_DESIGN_NOTES = """
+# is_link_like — Do Not Follow This Directory
+
+## Purpose
+`walk_tree` follows real directories only. Python's `is_symlink()` misses
+Windows **junctions** (created by `mklink /J`, common for relocated user
+folders): `is_dir()` is True, `is_symlink()` is False, and a junction
+pointing at a parent directory makes a naive walk run until the path is too
+long.
+
+## Why the Reparse Tag, Not "Any Reparse Point"
+Cloud-sync placeholders (OneDrive Files On-Demand) are reparse points too,
+but ordinary folders in every other respect — treating all reparse points
+as links would silently skip real content. Only the mount-point tag
+identifies a junction.
+"""

simplibs/path/logic/scanners/_helpers/resolve_scan_root.py

@@ -0,0 +1,66 @@
+import os
+from pathlib import Path
+# Outers
+from ...transformers import normalize_path
+# Inners
+from .._validations import (
+    raise_collect_paths_not_a_dir_error,
+    raise_collect_paths_not_found_error,
+    raise_collect_paths_root_unreadable_error,
+)
+
+
+def resolve_scan_root(root_dir: str | Path) -> Path:
+    """Normalize a scan root and make sure it can actually be scanned.
+
+    Args:
+        root_dir: The directory the caller wants to scan.
+
+    Returns:
+        The normalized absolute directory `Path`.
+
+    Raises:
+        NotFoundError: If the root does not exist.
+        StateError: If the root is not a directory.
+        AccessError: If the root's entries cannot be listed.
+    """
+
+    # 1. Normalize the root
+    normalized_root = normalize_path(root_dir)
+
+    # 2. It must exist
+    if not normalized_root.exists():
+        raise_collect_paths_not_found_error(normalized_root)
+
+    # 3. It must be a directory
+    if not normalized_root.is_dir():
+        raise_collect_paths_not_a_dir_error(normalized_root)
+
+    # 4. It must be listable — otherwise the walk would silently return nothing
+    try:
+        with os.scandir(normalized_root):
+            pass
+    except OSError as caught_exc:
+        raise_collect_paths_root_unreadable_error(normalized_root, caught_exc)
+
+    # 5. Return the checked root
+    return normalized_root
+
+
+_DESIGN_NOTES = """
+# resolve_scan_root — Fail Early, Before Any Walking
+
+## Purpose
+The root checks that used to sit inline in `collect_paths`, extracted so all
+four scanners share them — and extended with the "unreadable" case.
+
+## Why the Extra `scandir`
+`walk_tree` skips what it cannot read. Without this probe, an unreadable root
+would yield an empty list indistinguishable from an empty directory. One
+`scandir` open on the root costs microseconds and turns a silent wrong answer
+into an error.
+
+## Eager by Design
+It runs when the scanner is *called*. This matters for `iter_paths`: a bad
+root must raise at the call, not at the first `next()` somewhere far away.
+"""

simplibs/path/logic/scanners/_helpers/scan_paths.py

@@ -0,0 +1,92 @@
+import math
+from collections.abc import Callable, Collection, Iterator
+from pathlib import Path
+# Outers
+from ....annotations import PathLike
+from .._validations import raise_nothing_to_collect_error
+# Inners
+from .as_path_predicate import as_path_predicate
+from .build_ignore_matcher import build_ignore_matcher
+from .generate_paths import generate_paths
+from .resolve_scan_root import resolve_scan_root
+
+
+def scan_paths(
+    root_dir: PathLike,
+    *,
+    recursive: bool | int,
+    include_filter: Callable[[Path], bool] | None,
+    exclude_filter: Callable[[Path], bool] | None,
+    ignore_names: Collection[str] | None,
+    collect_files: bool,
+    collect_dirs: bool,
+) -> Iterator[Path]:
+    """Prepare a scan and return the lazy iterator over its results.
+
+    All checks and preparation happen now, when this is called; only the walk
+    itself is deferred to iteration. Shared by every public scanner.
+
+    Args:
+        root_dir: The directory to scan.
+        recursive: `True` for unlimited depth, `False` for the root's own
+            entries only, or a non-negative `int` for a maximum depth.
+        include_filter: Only paths it accepts are kept.
+        exclude_filter: Paths it accepts are skipped.
+        ignore_names: Entry names or glob patterns to skip entirely.
+        collect_files: Whether files are collected.
+        collect_dirs: Whether directories are collected.
+
+    Returns:
+        An iterator over the matching `Path`s (unsorted).
+
+    Raises:
+        ParamError: If both collect flags are False, or `ignore_names` is a string.
+        NotFoundError: If the root does not exist.
+        StateError: If the root is not a directory.
+        AccessError: If the root cannot be listed.
+    """
+
+    # 1. Both flags off is a caller mistake, not an empty result
+    if not collect_files and not collect_dirs:
+        raise_nothing_to_collect_error()
+
+    # 2. Validate and normalize the root now, not at the first iteration
+    root = resolve_scan_root(root_dir)
+
+    # 3. Prepare depth, ignore matcher and filters once, outside the loop
+    max_depth = math.inf if recursive is True else int(recursive)
+    is_ignored = build_ignore_matcher(ignore_names)
+    include = None if include_filter is None else as_path_predicate(include_filter)
+    exclude = None if exclude_filter is None else as_path_predicate(exclude_filter)
+
+    # 4. Hand back the lazy generator
+    return generate_paths(
+        root,
+        max_depth=max_depth,
+        is_ignored=is_ignored,
+        include=include,
+        exclude=exclude,
+        collect_files=collect_files,
+        collect_dirs=collect_dirs,
+    )
+
+
+_DESIGN_NOTES = """
+# scan_paths — Prepare Eagerly, Walk Lazily
+
+## Purpose
+Every public scanner differs only in its flags and what it does with the
+result (return lazily, sort, ...). The preparation is identical, so it lives
+here once, and each public function validates its own parameters
+(`@validate_call`) and calls this.
+
+## Why Not `collect_paths` Calling `iter_paths`
+A chain of public functions would validate the same arguments two or three
+times. Calling one internal, unvalidated function validates each public call
+exactly once.
+
+## `recursive` Semantics
+`True` is unlimited, `False` is 0 (only the root's entries), an `int` is the
+maximum depth below the root. `recursive is True` is an identity check on
+purpose: `1 == True`, so equality would turn depth 1 into "unlimited".
+"""

simplibs/path/logic/scanners/_helpers/walk_tree.py

@@ -0,0 +1,118 @@
+import os
+from collections.abc import Callable, Iterator
+from pathlib import Path
+# Inners
+from .is_link_like import is_link_like
+from .ScanEntry import ScanEntry
+
+
+def walk_tree(
+    root: Path,
+    *,
+    max_depth: float | int,
+    is_ignored: Callable[[str], bool],
+) -> Iterator[ScanEntry]:
+    """Walk a directory tree, yielding every file and directory it contains.
+
+    Args:
+        root: The directory to walk (must already be validated and normalized).
+        max_depth: The deepest directory level whose entries are listed
+            (0 = only the entries of `root`; `math.inf` = unlimited).
+        is_ignored: Called with each entry's name — a True answer skips the
+            entry and, for a directory, everything below it.
+
+    Yields:
+        A `ScanEntry` for every non-ignored file and directory. Symlinks to
+        files or directories are yielded (as what they point to) but a
+        symlinked or junctioned directory is never entered. Broken symlinks
+        and special files (FIFOs, sockets, devices) are not yielded.
+        Directories that cannot be read are skipped silently.
+    """
+
+    # 1. Directories still to be listed, each with its depth (iterative — no recursion limit)
+    pending: list[tuple[str, int]] = [(os.fspath(root), 0)]
+
+    # 2. List one directory at a time
+    while pending:
+        directory, depth = pending.pop()
+
+        # 2.1 A directory that cannot be opened is skipped
+        try:
+            entries = os.scandir(directory)
+        except OSError:
+            continue
+
+        # 2.2 Inspect its entries; a failure while listing ends only this directory
+        with entries:
+            try:
+                for entry in entries:
+
+                    # 2.2.1 Ignored names are skipped entirely — no yield, no descent
+                    if is_ignored(entry.name):
+                        continue
+
+                    # 2.2.2 Learn the entry's kind (symlinks are followed for the answer)
+                    try:
+                        is_dir = entry.is_dir()
+                        is_file = not is_dir and entry.is_file()
+                        enter = is_dir and depth < max_depth and not is_link_like(entry)
+                    except OSError:
+                        continue
+
+                    # 2.2.3 Neither a file nor a directory — broken symlink, FIFO, device, ...
+                    if not (is_dir or is_file):
+                        continue
+
+                    # 2.2.4 Yield the entry, then queue real directories within the depth limit
+                    yield ScanEntry(Path(entry.path), is_file, is_dir)
+                    if enter:
+                        pending.append((entry.path, depth + 1))
+
+            except OSError:
+                continue
+
+
+_DESIGN_NOTES = """
+# walk_tree — the Shared Walker Behind Every Scanner
+
+## Purpose
+One place that knows how to traverse a directory tree safely. `iter_paths`,
+`collect_paths`, `collect_files` and `collect_dirs` all sit on it.
+
+---
+
+## 1. Rewritten on `os.scandir`, Iterative
+The old version used recursive `Path.iterdir()` generators plus separate
+`is_dir()`/`is_symlink()` calls per entry, and `collect_paths` asked the disk
+twice more. `os.scandir` returns the entry type with the listing itself, so
+each entry costs no extra syscall for its kind (on Windows none at all), and
+the `ScanEntry` carries that answer to the caller. A work list instead of
+recursion means a very deep tree cannot hit Python's recursion limit.
+
+## 2. Errors: Skipped Here, Reported at the Root
+A normal tree contains unreadable folders (permissions, sync placeholders);
+dying on the first one would make scanning home directories impractical, so
+`walk_tree` skips them. The old version also lost the *rest* of a directory
+when one entry failed; now only the failing entry is skipped. An unreadable
+**root** is caught before the walk (`resolve_scan_root`) so it cannot masquerade
+as an empty result.
+
+## 3. Ignoring Applies to Files and Directories
+`is_ignored(name)` is asked for every entry. An ignored directory is neither
+yielded nor entered, which is what makes `.git` and `node_modules` cheap.
+
+## 4. Symlinks and Junctions
+A symlink to a directory is reported (it *is* a directory to the caller) but
+not entered, so link cycles and escapes from the tree are impossible.
+Windows junctions get the same treatment via `is_link_like`.
+
+## 5. Pre-Order Within a Directory, No Global Order
+Entries of a directory are yielded in the order the OS lists them, and
+directories are processed last-queued-first. No order is promised —
+`collect_paths` sorts; `iter_paths` documents that it does not.
+
+## 6. No `@validate_call`
+Internal helper, called with arguments the scanners have already validated.
+Re-validating a set of names on every directory (as the old version did)
+was pure overhead on the hottest path.
+"""