simplibs-path 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,24 @@
+from .raise_collect_paths_not_a_dir_error import raise_collect_paths_not_a_dir_error
+from .raise_collect_paths_not_found_error import raise_collect_paths_not_found_error
+from .raise_collect_paths_root_unreadable_error import raise_collect_paths_root_unreadable_error
+from .raise_ignore_names_not_names_error import raise_ignore_names_not_names_error
+from .raise_nothing_to_collect_error import raise_nothing_to_collect_error
+
+
+_DESIGN_NOTES = """
+# Path Scanners Diagnostic Helpers Sub-Package
+
+## Purpose
+Internal diagnostic helpers raising structured exceptions for the tree
+scanners in `scanners/`.
+
+## Internal Components Registry
+
+| Component                                     | Type     | Description                                                        |
+| :-------------------------------------------- | :------- | :----------------------------------------------------------------- |
+| `raise_collect_paths_not_a_dir_error`         | Function | Raises `StateError` when the scan root is a file.                  |
+| `raise_collect_paths_not_found_error`         | Function | Raises `NotFoundError` when the scan root does not exist.          |
+| `raise_collect_paths_root_unreadable_error`   | Function | Raises `AccessError` when the scan root is unreadable.             |
+| `raise_ignore_names_not_names_error`          | Function | Raises `ParamError` when `ignore_names` is a single string.        |
+| `raise_nothing_to_collect_error`              | Function | Raises `ParamError` when both collect flags are False.             |
+"""

simplibs/path/logic/scanners/_validations/raise_collect_paths_not_a_dir_error.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import StateError
+
+
+def raise_collect_paths_not_a_dir_error(path: Path) -> NoReturn:
+    """Raise StateError when a scan root is an existing file instead of a directory."""
+
+    # 1. Raise structured StateError wrapping a NotADirectoryError exception
+    raise StateError(
+        error_name="COLLECT_PATHS_NOT_A_DIRECTORY",
+        label=f"root directory '{path}'",
+        value=str(path),
+        problem=(
+            f"Cannot collect paths from '{path}'.",
+            "Expected a root directory, but an existing regular file was found at this location.",
+        ),
+        expected="A path pointing to an existing directory that can be scanned.",
+        how_to_fix=(
+            "Provide a path to a directory instead of a regular file.",
+            f"Check if '{path}' was mistakenly passed instead of its parent directory.",
+        ),
+        exception=NotADirectoryError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_collect_paths_not_a_dir_error — Scan Root Is Not a Directory
+
+## Purpose
+Counterpart of `raise_collect_paths_not_found_error`: the root exists, but
+is a file. Renamed from `raise_ensure_collect_paths_not_a_dir_error`; the
+card itself is unchanged.
+"""

simplibs/path/logic/scanners/_validations/raise_collect_paths_not_found_error.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import NotFoundError
+
+
+def raise_collect_paths_not_found_error(path: Path) -> NoReturn:
+    """Raise NotFoundError when a scan targets a non-existent root directory."""
+
+    # 1. Raise structured NotFoundError wrapping a FileNotFoundError exception
+    raise NotFoundError(
+        error_name="COLLECT_PATHS_ROOT_NOT_FOUND",
+        label=f"root directory '{path}'",
+        value=str(path),
+        problem=(
+            f"Cannot scan directory tree at '{path}'.",
+            "The specified root directory does not exist on disk.",
+        ),
+        expected="An existing directory path to use as the root for path collection.",
+        how_to_fix=(
+            f"Verify that the path '{path}' exists before collecting paths from it.",
+            "Ensure parent directories are correctly spelled and accessible.",
+        ),
+        exception=FileNotFoundError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_collect_paths_not_found_error — Missing Scan Root Diagnostic
+
+## Purpose
+Shared by every scanner that walks a tree (`collect_paths`, `collect_files`,
+`collect_dirs`, `iter_paths`).
+
+## Renamed From `raise_ensure_collect_paths_not_found_error`
+Nothing is ensured here — the `ensure` prefix was a leftover. The how-to-fix
+text no longer names `collect_paths` specifically, since four functions
+share this card.
+"""

simplibs/path/logic/scanners/_validations/raise_collect_paths_root_unreadable_error.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+from typing import NoReturn
+from simplibs.exception import AccessError
+
+
+def raise_collect_paths_root_unreadable_error(
+    path: Path,
+    caught_exc: Exception,
+) -> NoReturn:
+    """Raise AccessError when the scan root exists but its entries cannot be listed."""
+
+    # 1. Raise structured AccessError wrapping the caught OS exception
+    raise AccessError(
+        error_name="COLLECT_PATHS_ROOT_UNREADABLE",
+        label=f"root directory '{path}'",
+        value=str(path),
+        problem=(
+            f"Cannot list the entries of '{path}'.",
+            f"OS reported: {caught_exc}",
+        ),
+        expected="A root directory the current user is allowed to read.",
+        how_to_fix=(
+            f"Check read and execute permissions of '{path}'.",
+            "Scan a directory you have access to, or run with sufficient permissions.",
+        ),
+        exception=type(caught_exc),
+    )
+
+
+_DESIGN_NOTES = """
+# raise_collect_paths_root_unreadable_error — Unreadable Scan Root
+
+## Purpose
+Unreadable *sub*directories are skipped silently while walking — a normal
+tree always contains a few. An unreadable *root* is different: skipping it
+would return an empty result that looks exactly like "nothing found". The
+scanners check the root up front and report this card instead.
+"""

simplibs/path/logic/scanners/_validations/raise_ignore_names_not_names_error.py

@@ -0,0 +1,36 @@
+from typing import NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_ignore_names_not_names_error(value: str) -> NoReturn:
+    """Raise ParamError when `ignore_names` is a single string instead of a collection."""
+
+    # 1. Raise structured ParamError wrapping a TypeError
+    raise ParamError(
+        error_name="IGNORE_NAMES_NOT_A_COLLECTION",
+        label="ignore_names",
+        value=value,
+        problem=(
+            f"A single string {value!r} was passed instead of a collection of names.",
+            "A string is iterable, so it would be silently split into single characters.",
+        ),
+        expected="A collection of entry names, e.g. a tuple, list, set or frozenset of strings.",
+        how_to_fix=(
+            f"Wrap the name in a collection: ignore_names=({value!r},).",
+            "Extend the defaults with a union: DEFAULT_IGNORE_NAMES | {'my_dir'}.",
+        ),
+        exception=TypeError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_ignore_names_not_names_error — The Single-String Trap
+
+## Purpose
+`str` is a `Collection[str]`, so the `@validate_call` annotation alone
+cannot tell `ignore_names=".git"` from `ignore_names=(".git",)`. Without
+this explicit check the first form would be read as the names
+`{".", "g", "i", "t"}` — ignoring nothing useful and hiding every entry
+named `g`, `i` or `t`. The scanners check for `str` in their body and
+raise this card instead.
+"""

simplibs/path/logic/scanners/_validations/raise_nothing_to_collect_error.py

@@ -0,0 +1,34 @@
+from typing import NoReturn
+from simplibs.exception import ParamError
+
+
+def raise_nothing_to_collect_error() -> NoReturn:
+    """Raise ParamError when both `collect_files` and `collect_dirs` are False."""
+
+    # 1. Raise structured ParamError wrapping a ValueError
+    raise ParamError(
+        error_name="NOTHING_TO_COLLECT",
+        label="collect_files, collect_dirs",
+        value="collect_files=False, collect_dirs=False",
+        problem=(
+            "Both collect_files and collect_dirs are False.",
+            "Nothing could ever be collected, so the scan would be pointless.",
+        ),
+        expected="At least one of collect_files or collect_dirs set to True.",
+        how_to_fix=(
+            "Set collect_files=True to collect files.",
+            "Set collect_dirs=True to collect directories.",
+        ),
+        exception=ValueError,
+    )
+
+
+_DESIGN_NOTES = """
+# raise_nothing_to_collect_error — Contradictory Collect Flags
+
+## Purpose
+An earlier `collect_paths` returned `[]` for this combination before even
+checking the root — silently, and even for a root that does not exist. Both
+flags off is almost certainly a caller mistake, so it is now reported
+immediately instead of producing an empty result that looks like success.
+"""

simplibs/path/logic/scanners/collect_dirs.py

@@ -0,0 +1,62 @@
+from collections.abc import Collection
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike, PathPredicate, RecursionDepth
+# Inners
+from ._helpers import scan_paths
+from .ignore_names import DEFAULT_IGNORE_NAMES
+
+
+@validate_call
+def collect_dirs(
+    root_dir: PathLike,
+    *,
+    recursive: RecursionDepth = True,
+    include_filter: PathPredicate | None = None,
+    exclude_filter: PathPredicate | None = None,
+    ignore_names: Collection[str] | None = DEFAULT_IGNORE_NAMES,
+) -> list[Path]:
+    """Collect only the directories of a directory tree into a sorted list.
+
+    The same as `collect_paths(..., collect_files=False, collect_dirs=True)`,
+    with the type flags fixed. See `collect_paths` for the meaning of every
+    parameter, the sorting and the raised errors.
+
+    Args:
+        root_dir: The root directory to scan (the root itself is not included).
+        recursive: `True` for unlimited depth, `False` for the root's own
+            entries only, or an `int` for a maximum depth.
+        include_filter: A `Rule` or `(Path) -> bool` callable a directory must satisfy.
+        exclude_filter: A `Rule` or `(Path) -> bool` callable that skips a directory.
+        ignore_names: Entry names or glob patterns to skip entirely.
+
+    Returns:
+        The matching absolute directory `Path`s, sorted.
+    """
+
+    # 1. Run the shared scan with the type flags fixed, then sort
+    return sorted(
+        scan_paths(
+            root_dir,
+            recursive=recursive,
+            include_filter=include_filter,
+            exclude_filter=exclude_filter,
+            ignore_names=ignore_names,
+            collect_files=False,
+            collect_dirs=True,
+        )
+    )
+
+
+_DESIGN_NOTES = """
+# collect_dirs — Directories Only
+
+## Purpose
+The directory counterpart of `collect_files` — for "which folders exist
+under here" steps (mirroring a structure, picking project roots).
+
+## The Root Is Not Included
+Like every scanner, it lists what is *inside* `root_dir`. A caller who wants
+the root as well adds it explicitly.
+"""

simplibs/path/logic/scanners/collect_files.py

@@ -0,0 +1,64 @@
+from collections.abc import Collection
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike, PathPredicate, RecursionDepth
+# Inners
+from ._helpers import scan_paths
+from .ignore_names import DEFAULT_IGNORE_NAMES
+
+
+@validate_call
+def collect_files(
+    root_dir: PathLike,
+    *,
+    recursive: RecursionDepth = True,
+    include_filter: PathPredicate | None = None,
+    exclude_filter: PathPredicate | None = None,
+    ignore_names: Collection[str] | None = DEFAULT_IGNORE_NAMES,
+) -> list[Path]:
+    """Collect only the files of a directory tree into a sorted list.
+
+    The same as `collect_paths(..., collect_files=True, collect_dirs=False)`,
+    with the type flags fixed. See `collect_paths` for the meaning of every
+    parameter, the sorting and the raised errors.
+
+    Args:
+        root_dir: The root directory to scan.
+        recursive: `True` for unlimited depth, `False` for the root's own
+            entries only, or an `int` for a maximum depth.
+        include_filter: A `Rule` or `(Path) -> bool` callable a file must satisfy.
+        exclude_filter: A `Rule` or `(Path) -> bool` callable that skips a file.
+        ignore_names: Entry names or glob patterns to skip entirely.
+
+    Returns:
+        The matching absolute file `Path`s, sorted.
+    """
+
+    # 1. Run the shared scan with the type flags fixed, then sort
+    return sorted(
+        scan_paths(
+            root_dir,
+            recursive=recursive,
+            include_filter=include_filter,
+            exclude_filter=exclude_filter,
+            ignore_names=ignore_names,
+            collect_files=True,
+            collect_dirs=False,
+        )
+    )
+
+
+_DESIGN_NOTES = """
+# collect_files — Files Only
+
+## Why a Real Function, Not a `functools.partial`
+The `CollectFiles` action used to be built from
+`partial(collect_paths, collect_files=True, collect_dirs=False)`. A partial
+only changes the *defaults* — the flags stayed in the signature, so
+`CollectFiles(collect_dirs=True)` quietly broke the "locked" promise, and
+`create_action` needs a `__name__` that a partial does not have.
+
+A function with the flags removed from its signature cannot be mis-used,
+has a truthful docstring, and wraps cleanly into an action.
+"""

simplibs/path/logic/scanners/collect_paths.py

@@ -0,0 +1,102 @@
+from collections.abc import Collection
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathLike, PathPredicate, RecursionDepth
+# Inners
+from ._helpers import scan_paths
+from .ignore_names import DEFAULT_IGNORE_NAMES
+
+
+@validate_call
+def collect_paths(
+    root_dir: PathLike,
+    *,
+    recursive: RecursionDepth = True,
+    include_filter: PathPredicate | None = None,
+    exclude_filter: PathPredicate | None = None,
+    ignore_names: Collection[str] | None = DEFAULT_IGNORE_NAMES,
+    collect_files: bool = True,
+    collect_dirs: bool = False,
+) -> list[Path]:
+    """Scan a directory tree and collect the matching paths into a sorted list.
+
+    Args:
+        root_dir: The root directory to scan.
+        recursive: `True` for unlimited depth, `False` for the root's own
+            entries only, or an `int` for a maximum depth (0 = root's own
+            entries, 1 = one level deeper, ...).
+        include_filter: A `Rule` or `(Path) -> bool` callable. A path must
+            satisfy it to be collected.
+        exclude_filter: A `Rule` or `(Path) -> bool` callable. A path that
+            satisfies it is skipped (checked before `include_filter`).
+            Excluding a directory does not hide what is inside it — only
+            `ignore_names` prunes a subtree.
+        ignore_names: Entry names (files and directories) or glob patterns
+            (`*.egg-info`) to skip entirely — an ignored directory is not
+            entered. Defaults to `DEFAULT_IGNORE_NAMES`; extend it with
+            `DEFAULT_IGNORE_NAMES | {"my_dir"}`. Pass a collection, never a
+            bare string; `None` ignores nothing.
+        collect_files: Whether files are collected (default True).
+        collect_dirs: Whether directories are collected (default False).
+
+    Returns:
+        The matching absolute `Path`s, sorted by path parts (a directory's
+        contents sort right after the directory itself). Symlinks to files
+        and directories are collected as what they point to; broken
+        symlinks and special files never are.
+
+    Raises:
+        ParamError: If both collect flags are False, or `ignore_names` is a string.
+        NotFoundError: If `root_dir` does not exist.
+        StateError: If `root_dir` is not a directory.
+        AccessError: If `root_dir` cannot be listed.
+    """
+
+    # 1. Run the shared scan and sort what it finds
+    return sorted(
+        scan_paths(
+            root_dir,
+            recursive=recursive,
+            include_filter=include_filter,
+            exclude_filter=exclude_filter,
+            ignore_names=ignore_names,
+            collect_files=collect_files,
+            collect_dirs=collect_dirs,
+        )
+    )
+
+
+_DESIGN_NOTES = """
+# collect_paths — the General Scanner
+
+## Purpose
+The list-returning scanner every extraction pipeline starts from, with both
+type flags exposed. `collect_files` and `collect_dirs` are its fixed-flag
+presets.
+
+---
+
+## 1. What Changed From the Previous Version
+* **`ignore_dirs` → `ignore_names`**, applied to files too, with glob
+  patterns, and a narrower default (no more silently hidden `build/`, `dist/`).
+* **Broken symlinks and special files are no longer collected.** A positive
+  type check replaces two negative ones that an entry of neither kind slipped
+  through.
+* **Both flags off raises** instead of returning `[]` before even checking
+  the root.
+* **An unreadable root raises** instead of looking like an empty tree.
+* **One `scandir` per directory** instead of up to five `stat` calls per entry.
+* **`Collection`, not `Iterable`, for `ignore_names`.** `@validate_call`
+  checks `Iterable[...]` by iterating it — which would exhaust a generator
+  argument before the function ever saw it.
+
+## 2. Sorted by Path Parts
+`Path` objects compare part by part, so `a/b.txt` sorts after the directory
+`a` and before `a.txt`. That is tree order, and on Windows it is
+case-insensitive, matching how Explorer lists a folder.
+
+## 3. Absolute Paths
+Entries are the normalized root joined with their relative part, so the
+result needs no further `normalize_path`.
+"""

simplibs/path/logic/scanners/filter_paths.py

@@ -0,0 +1,51 @@
+from collections.abc import Collection
+from pathlib import Path
+from simplibs.validate import validate_call
+# Outers
+from ...annotations import PathPredicate
+# Inners
+from ._helpers import as_path_predicate
+
+
+@validate_call
+def filter_paths(
+    paths: Collection[Path],
+    rule: PathPredicate,
+) -> list[Path]:
+    """Keep only the paths that satisfy a Rule or callable predicate.
+
+    Args:
+        paths: The paths to filter — a list, tuple or set (not a generator,
+            which cannot be validated without being consumed; wrap it in
+            `list(...)` first).
+        rule: A `Rule` or `(Path) -> bool` callable. A path is kept when it
+            returns a truthy value.
+
+    Returns:
+        A new list with the paths satisfying `rule`, in their original order.
+    """
+
+    # 1. Resolve the predicate once, outside the loop
+    predicate = as_path_predicate(rule)
+
+    # 2. Keep only the paths satisfying it
+    return [path for path in paths if predicate(path)]
+
+
+_DESIGN_NOTES = """
+# filter_paths — Filter an Existing List of Paths
+
+## Purpose
+`collect_paths` filters while scanning. `filter_paths` filters a list you
+already have — the result of an earlier step, or paths from elsewhere —
+which is what `CollectFiles() >> FilterPaths(rule=...)` needs.
+
+## What Changed
+* **`rule` is required.** With `rule=None` the old version just copied the
+  list — a no-op that, as an action, could only be a mistake.
+* **`Collection[Path]` instead of `Iterable[Path]`.** `@validate_call`
+  checks `Iterable[...]` by iterating it, which would silently exhaust a
+  generator argument and then filter an empty list. A collection can be
+  checked and still used.
+* **`as_path_predicate`** replaces `getattr(rule, "is_valid", rule)`.
+"""

simplibs/path/logic/scanners/ignore_names/DEFAULT_IGNORE_NAMES.py

@@ -0,0 +1,36 @@
+from typing import Final
+# Inners
+from .IGNORE_BUILD import IGNORE_BUILD
+from .IGNORE_ENV import IGNORE_ENV
+from .IGNORE_IDE import IGNORE_IDE
+from .IGNORE_SYSTEM import IGNORE_SYSTEM
+from .IGNORE_VCS import IGNORE_VCS
+
+
+DEFAULT_IGNORE_NAMES: Final[frozenset[str]] = (
+    IGNORE_VCS
+    | IGNORE_ENV
+    | IGNORE_BUILD
+    | IGNORE_IDE
+    | IGNORE_SYSTEM
+)
+"""The names every scan skips unless told otherwise.
+
+Extend it with a union: `DEFAULT_IGNORE_NAMES | {"my_dir"}`.
+"""
+
+
+_DESIGN_NOTES = """
+# DEFAULT_IGNORE_NAMES — the Scanners' Default
+
+## Purpose
+The union of every group that is safe to hide without surprising anyone:
+version control, environments, generated artifacts with unmistakable names,
+IDE settings and OS housekeeping. `IGNORE_GENERIC` is deliberately not
+included (see its notes).
+
+## A `frozenset` So the Default Is Safe
+A mutable default shared by every call could be changed by accident
+(`DEFAULT_IGNORE_NAMES.add(...)`) and affect all later scans. A frozenset
+cannot, and `|` still builds a new, extended one.
+"""

simplibs/path/logic/scanners/ignore_names/IGNORE_BUILD.py

@@ -0,0 +1,48 @@
+from typing import Final
+
+
+IGNORE_BUILD: Final[frozenset[str]] = frozenset({
+    "*.egg-info",
+    ".cache",
+    ".coverage",
+    ".coverage.*",
+    ".eggs",
+    ".gradle",
+    ".hypothesis",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".next",
+    ".nox",
+    ".nuxt",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".serverless",
+    ".terraform",
+    ".tox",
+    "__pycache__",
+    "htmlcov",
+})
+"""Caches, coverage data and tool output that are unambiguous by name.
+
+Entries containing `*`, `?` or `[` are glob patterns (`*.egg-info`).
+"""
+
+
+_DESIGN_NOTES = """
+# IGNORE_BUILD — Generated Artifacts With Unmistakable Names
+
+## Purpose
+Everything here is produced by a tool, never written by hand, and its name
+says so (`__pycache__`, `.mypy_cache`, `htmlcov`).
+
+## What Changed
+* **`build`, `dist`, `site`, `_build` moved to `IGNORE_GENERIC`.** They are
+  real output folders in many projects but also ordinary source folders in
+  others; hiding them by default silently dropped legitimate content.
+* **`.coverage` now works** (it is a file) and `.coverage.*` covers the
+  parallel-run files; `*.egg-info` is a glob, which the exact-name matching
+  of the old version could not express.
+* Added `.cache`, `.eggs`, `.gradle`, `.hypothesis`, `.ipynb_checkpoints`,
+  `.pytype`, `.terraform`.
+"""

simplibs/path/logic/scanners/ignore_names/IGNORE_ENV.py

@@ -0,0 +1,31 @@
+from typing import Final
+
+
+IGNORE_ENV: Final[frozenset[str]] = frozenset({
+    ".direnv",
+    ".env",
+    ".poetry",
+    ".venv",
+    ".virtualenv",
+    "__pypackages__",
+    "node_modules",
+    "venv",
+})
+"""Virtual environments and installed dependencies — plus the `.env` secrets file."""
+
+
+_DESIGN_NOTES = """
+# IGNORE_ENV — Environments and Dependencies
+
+## Purpose
+Installed third-party code (`venv`, `node_modules`, `__pypackages__`) dwarfs
+the project itself and is never part of its sources.
+
+## What Changed
+* **`env` moved to `IGNORE_GENERIC`.** Too common as an ordinary folder name
+  (`src/env/`, `config/env/`) to be hidden by default.
+* **`.env` stays, and now works.** It is usually a *file* (dotenv secrets).
+  The old directory-only ignore never matched it; names now apply to files
+  too, so a scan no longer picks up secrets by accident.
+* Added `.direnv` and `__pypackages__` (PEP 582).
+"""

simplibs/path/logic/scanners/ignore_names/IGNORE_GENERIC.py

@@ -0,0 +1,30 @@
+from typing import Final
+
+
+IGNORE_GENERIC: Final[frozenset[str]] = frozenset({
+    "_build",
+    "build",
+    "dist",
+    "env",
+    "out",
+    "site",
+    "target",
+})
+"""Common output-folder names that can also be ordinary source folders.
+
+NOT part of `DEFAULT_IGNORE_NAMES` — opt in explicitly:
+`ignore_names=DEFAULT_IGNORE_NAMES | IGNORE_GENERIC`.
+"""
+
+
+_DESIGN_NOTES = """
+# IGNORE_GENERIC — Opt-In, Because the Names Are Ambiguous
+
+## Purpose
+`build/`, `dist/`, `site/`, `target/` are the output folders of setuptools,
+MkDocs, Cargo and Maven — but `src/site/`, `docs/build-notes/`-style
+folders and a package literally named `env` exist too. A scan that hides
+them by default loses content without saying so, which is worse than a scan
+that is a bit noisy. This set exists so that dropping them is a conscious,
+one-expression choice.
+"""

simplibs/path/logic/scanners/ignore_names/IGNORE_IDE.py

@@ -0,0 +1,20 @@
+from typing import Final
+
+
+IGNORE_IDE: Final[frozenset[str]] = frozenset({
+    ".fleet",       # JetBrains Fleet
+    ".idea",        # PyCharm / JetBrains IDEs
+    ".settings",    # Eclipse
+    ".vs",          # Visual Studio
+    ".vscode",      # Visual Studio Code
+})
+"""Editor and IDE project settings."""
+
+
+_DESIGN_NOTES = """
+# IGNORE_IDE — Editor Settings
+
+## Purpose
+Per-project IDE state: personal, machine-specific and not part of the
+sources. Only `.fleet` is new compared to the former version.
+"""