feat: nested gitignore, extend-select, per-file-ignores, caching

.gitignore

@@ -1,2 +1,3 @@
 __pycache__/
 *.py[cod]
+.house-lint-cache/

CLAUDE.md

@@ -49,10 +49,20 @@ signature: `(source, options, *, limit=None) -> list[CandidateFinding]`.
 
 - `HSL900` (suppression-pragma validation) can never be disabled or suppressed — it governs how
   every other rule's findings can be silenced (`ignore`, `ignore-next`, `ignore-file` pragmas).
-- File discovery does **not** shell out to git or read nested `.gitignore` files — only the root
-  `.gitignore` plus configured excludes. `--no-gitignore` disables just that root file.
+- File discovery does **not** shell out to git. It reads the root `.gitignore` plus every nested
+  `.gitignore` between the root and each file, reimplementing git's precedence on `pathspec`.
+  `--no-gitignore` disables that at every level. Because it is a reimplementation, changes to
+  `discovery.py`'s pattern handling belong in `tests/integration/test_gitignore_parity.py`, which
+  differentially checks discovery against real `git check-ignore` — adding a case there costs one
+  `Scenario` entry and needs no expected-value literal. One divergence is known and deliberate
+  (negated directory-only patterns); see `docs/configuration.md`.
+- An ignored directory is pruned rather than enumerated, so `files_skipped` counts one skip per
+  pruned directory, not one per file inside it.
 - Default scan roots are `src`, `tests`, `scripts`, `tools`, `examples`, configurable via
   `[tool.house-lint] include`.
+- The result cache is namespaced by `<version>-<hash of house-lint's own sources>`, so editing
+  rule code invalidates it without a version bump. house-lint writes a self-ignoring `.gitignore`
+  into its own default cache base only — never into a user-supplied `--cache-dir`.
 
 ## Conventions
 

README.md

@@ -81,6 +81,21 @@ house-lint check --select HSL002,HSL103 --ignore HSL103
 
 Each `--select` or `--ignore` occurrence accepts one comma-separated list. Selection is strict: unknown, duplicate, empty, and `HSL900` IDs are usage errors.
 
+To add or remove rules without replacing the rest of your configured selection, use `extend-select`/`extend-ignore` (in `[tool.house-lint]` or as `--extend-select`/`--extend-ignore`) instead of `select`/`ignore`:
+
+```bash
+house-lint check --extend-select HSL101
+```
+
+`extend-select`/`extend-ignore` layer additively on top of the base selection (configured `select`/`ignore`, or a CLI `--select` override) regardless of where that base came from. A final CLI `--ignore` still always wins.
+
+To silence a rule only for files matching a glob, without touching the selection everywhere else, use `[tool.house-lint.per-file-ignores]`:
+
+```toml
+[tool.house-lint.per-file-ignores]
+"tests/**" = ["HSL002"]
+```
+
 Read [configuration](docs/configuration.md) for discovery, precedence, validation, excludes, and token-family options.
 
 ## Paths, roots, and Git ignores
@@ -93,7 +108,15 @@ house-lint check src/service.py tests
 
 Explicit paths are strict. Missing, out-of-root, and non-Python file arguments are errors; ignored or excluded explicit Python files are counted as skipped. `--root` fixes the project boundary and only considers `<root>/pyproject.toml`. Without `--root`, discovery starts at the current directory. `--config` selects an exact configuration file; without `--root`, its parent becomes the root.
 
-The linter loads only the selected root's `.gitignore`, plus built-in and configured excludes. It does not search nested `.gitignore` files or shell out to Git. Use `--no-gitignore` to disable only the root `.gitignore`.
+The linter loads the selected root's `.gitignore` plus every nested `.gitignore` between the root and each discovered file, combined with git's own precedence (a closer `.gitignore` can override a farther one, including via negation), plus built-in and configured excludes. It does not shell out to Git. Use `--no-gitignore` to disable `.gitignore` handling at every level.
+
+## Caching
+
+`check` caches each file's result under `<root>/.house-lint-cache/<version>-<source fingerprint>/`, keyed by the file's content and its effective rule set for that file. A cache hit skips tokenization, parsing, and rule execution entirely for that file. Upgrading house-lint — or editing its rule code in a working checkout — starts from an empty cache automatically, because both the version and a fingerprint of house-lint's own sources are part of the cache path. Superseded directories are pruned rather than left to accumulate.
+
+`--no-cache` disables reading from the cache but still writes to it, keeping it warm for the next run. `--cache-dir` overrides where the cache lives (still namespaced underneath the path you give it).
+
+house-lint adds a self-ignoring `.gitignore` to its own default `.house-lint-cache/` directory so it stays invisible to `git status`. It never writes one into a directory you name with `--cache-dir` — that directory is yours.
 
 ## Suppressions
 

docs/configuration.md

@@ -8,19 +8,55 @@ include = ["src", "tests", "scripts", "tools", "examples"]
 exclude = []
 select = ["HSL001", "HSL002", "HSL003", "HSL004"]
 ignore = []
+extend-select = []
+extend-ignore = []
 ```
 
-`include` contains literal root-relative files or directories, not globs. An empty array intentionally selects no roots for a full scan. `exclude` uses root-relative Git-ignore-style patterns. Unknown keys, absolute paths, parent traversal, invalid patterns, duplicate IDs, and `HSL900` in `select` or `ignore` are configuration errors.
+`include` contains literal root-relative files or directories, not globs. An empty array intentionally selects no roots for a full scan. `exclude` uses root-relative Git-ignore-style patterns. Unknown keys, absolute paths, parent traversal, invalid patterns, duplicate IDs, and `HSL900` in `select`, `ignore`, `extend-select`, `extend-ignore`, or `per-file-ignores` are configuration errors. Unlike the rest of this schema, `extend-select`/`extend-ignore`/`per-file-ignores` are hyphenated by design, matching Ruff's spelling for the same concepts.
+
+## Per-file rule overrides
+
+`[tool.house-lint.per-file-ignores]` maps root-relative Git-ignore-style glob patterns to rule IDs to drop for matching files, without changing the global selection for everything else:
+
+```toml
+[tool.house-lint.per-file-ignores]
+"tests/**" = ["HSL002"]
+"legacy/*.py" = ["HSL001", "HSL003"]
+```
+
+Applied after the base selection and `extend-select`/`extend-ignore` resolve, per file: a rule dropped by `per-file-ignores` for a matching file is not detected for that file at all, so a `# house-lint: ignore[...]` pragma naming it there is flagged the same way as suppressing an already-disabled rule. `HSL900` can never appear in a `per-file-ignores` value.
 
 ## Discovery and precedence
 
 1. `--root` fixes the project boundary.
 2. `--config` selects an exact configuration. Without `--root`, its parent is the root; with `--root`, it must be inside the root.
 3. With `--root` and no `--config`, only `<root>/pyproject.toml` is considered.
 4. Without either option, the command searches upward from the current directory for the nearest `pyproject.toml` containing `[tool.house-lint]`. If none exists, it uses the nearest ancestor containing `.git` or any `pyproject.toml`; otherwise it uses the current directory.
-5. CLI `--select` replaces configured selection, then CLI `--ignore` subtracts IDs. `HSL900` is always added.
+5. The base selection is configured `select` minus configured `ignore`, or a CLI `--select` wholesale override when given.
+6. `extend-select`/`extend-ignore` (config and CLI, unioned together) layer additively on top of that base, regardless of whether the base came from config or `--select`. `extend-ignore` removes rules from the whole base, not just from `extend-select` — `select = ["HSL001"]` with `extend-ignore = ["HSL001"]` drops HSL001 entirely, it isn't limited to canceling out `extend-select` additions.
+7. CLI `--ignore` is applied last and always wins over everything above. `HSL900` is always added.
+
+The root `.gitignore` and every nested `.gitignore` between the root and each discovered file are loaded and combined with git's own precedence — a closer `.gitignore` can override a farther one, including via negation (`!pattern`). Built-in excludes are `.git/`, `.venv/`, `.nox/`, `__pycache__/`, `site-packages/`, and `node_modules/`; configured excludes are added afterwards. `--no-gitignore` disables `.gitignore` handling at every level.
+
+An ignored directory is skipped without being enumerated, which is what keeps a large `.venv/` or `node_modules/` cheap to exclude. The reported `files skipped` count follows from that: one pruned directory counts as one skip, however many files it contains.
+
+house-lint reimplements git's ignore rules on top of [`pathspec`](https://pypi.org/project/pathspec/) rather than shelling out to git, and `tests/integration/test_gitignore_parity.py` checks that reimplementation against real `git check-ignore`.
+
+One divergence is known and deliberate: a negated directory-only pattern (`!sub/`) re-includes everything beneath it, whereas git re-includes only the `sub` entry itself and re-evaluates each descendant against the remaining patterns. Closing it would mean matching path components by hand instead of delegating to `pathspec`. It only changes the outcome when such a negation sits under a broader ignore that also covers the descendants — and it always errs toward linting a file git would ignore, never toward silently skipping one, so it cannot hide a finding. Randomised differential runs against `git check-ignore` put it at well under 1% of generated pattern combinations, all of that one shape.
+
+## Caching
+
+There is no TOML key for caching — it's controlled entirely by CLI flags, since it's a run-to-run performance concern rather than a project convention.
+
+Each file's result is cached under `<root>/.house-lint-cache/<version>-<source fingerprint>/`, flat and keyed by two hashes: the file's raw content, and the file's *effective* rule set for that run (`select`/`ignore`/`extend-select`/`extend-ignore`/`per-file-ignores` and CLI overrides already resolved, plus all three `HSL101`/`HSL102`/`HSL103` option tables, whether or not each of those rules is currently enabled — simpler than tracking which options are actually load-bearing, at the cost of some extra cache invalidation when an unused rule's options change). The file's own name is folded in too whenever an enabled `HSL101` token family scopes to `"filenames"`, since that's the one detector whose output depends on the filename rather than purely the content. house-lint is a single-file analyzer with no cross-file dependencies, so this flat scheme is sufficient — there is no dependency graph to invalidate. A cache hit skips tokenization, parsing, and rule execution for that file entirely.
+
+The directory name carries both house-lint's version and a hash of its own Python sources. The version alone would not be enough: it only moves when a release is cut, so editing a detector in a working checkout and re-running would replay the previous detector's results for every unchanged file. The source fingerprint is content-based, so a released install keeps exactly one cache directory across machines and fresh clones.
+
+Superseded directories house-lint created are pruned so they do not accumulate — but only by a run that actually writes a cache entry. A scan where every file is a cache hit deletes nothing, which keeps the sweep from removing a namespace that a concurrent house-lint of a different version is still writing to.
+
+house-lint writes a self-ignoring `.gitignore` into its own default `.house-lint-cache/` base so the cache stays invisible to `git status`. It never writes one into a `--cache-dir` you supply, since that directory may hold unrelated data — or be a project root, where a wildcard ignore would hide the whole project.
 
-Only the root `.gitignore` is loaded. Built-in excludes are `.git/`, `.venv/`, `.nox/`, `__pycache__/`, `site-packages/`, and `node_modules/`; configured excludes are added afterwards. `--no-gitignore` disables only the root `.gitignore`.
+`--no-cache` disables reading from the cache but still writes to it, keeping it warm for the next run — the same semantics as Ruff's `--no-cache`. `--cache-dir <path>` overrides the base directory (the namespace segment is still appended underneath it).
 
 ## Rule options