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

.gitignore

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

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,13 @@ 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/<house-lint version>/` (gitignored by default), 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; an upgrade to a new house-lint version starts from an empty cache automatically, since the version is part of the cache path.
+
+`--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 version-namespaced underneath the path you give it).
 
 ## Suppressions
 

docs/configuration.md

@@ -8,19 +8,43 @@ 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.
+
+## 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/<house-lint version>/` (gitignored by default), 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; a version upgrade starts from an empty cache automatically, since the version is part of the cache path.
 
-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 and mypy's `--no-cache`/`--no-incremental`. `--cache-dir <path>` overrides the base directory (the version segment is still appended underneath it).
 
 ## Rule options
 

src/house_lint/cache.py

@@ -0,0 +1,207 @@
+"""Flat, version-namespaced per-file result cache.
+
+House-lint is a single-file analyzer with no cross-file dependencies, so a flat cache keyed
+by (file content hash, effective config hash) is semantically correct — unlike a dependency-
+graph cache (e.g. mypy's `.mypy_cache`), there is no invalidation-graph to track. The cache
+directory is namespaced by house-lint's own version, so an upgrade invalidates stale entries
+automatically without an explicit migration step.
+
+Cache entries are addressed purely by content and config hashes, not by file path — two files
+with identical content and an identical effective rule set produce the same entry. Cached
+findings and errors are therefore stored without their `path` field; `read_cached_result` takes
+the caller-supplied `relative_path` of the file actually being scanned and re-attaches it to
+each reconstructed finding/error.
+"""
+
+import hashlib
+import json
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from house_lint import __version__
+from house_lint.config import HSL101Options, HSL102Options, HSL103Options
+from house_lint.results import Finding, LintError
+from house_lint.source import MAX_SOURCE_BYTES, read_regular_file_bytes
+
+CACHE_DIRNAME = ".house-lint-cache"
+
+
+def default_cache_base(root: Path) -> Path:
+    """Default cache base directory: `<root>/.house-lint-cache/` (before version-namespacing)."""
+    return root / CACHE_DIRNAME
+
+
+def versioned_cache_dir(base: Path) -> Path:
+    """Version-namespace a cache base directory, so an upgrade invalidates stale entries.
+
+    Applies uniformly to the default base and to a user-supplied `--cache-dir` override —
+    the override changes *where* the cache lives, not whether it's still safe across upgrades.
+    """
+    return base / __version__
+
+
+def hash_file_content(path: Path) -> str | None:
+    """Hash a file's raw bytes for cache-key purposes, or None if it can't be safely cached.
+
+    Reuses `SourceFile`'s nonblocking-read and regular-file guard (via
+    `read_regular_file_bytes`) so hashing can't stall on a raced FIFO. Any failure here just
+    means this file is treated as a cache miss for this run — `SourceFile`'s own loading still
+    runs the real scan and reports a proper `LintError` if warranted.
+    """
+    try:
+        content = read_regular_file_bytes(path, max_bytes=MAX_SOURCE_BYTES)
+    except OSError:
+        return None
+    if content is None or len(content) > MAX_SOURCE_BYTES:
+        return None
+    return hashlib.sha256(content).hexdigest()
+
+
+def hash_effective_config(
+    enabled_rules: tuple[str, ...],
+    hsl101: HSL101Options,
+    hsl102: HSL102Options,
+    hsl103: HSL103Options,
+    *,
+    filename: str,
+) -> str:
+    """Hash the config inputs that can change a file's scan outcome, given fixed content.
+
+    `enabled_rules` is the per-file effective set (after `per-file-ignores`, `extend-select`,
+    etc. have already resolved it), not the raw configured selection.
+
+    `filename` (the file's own basename, e.g. `path.name`) is folded in only when an enabled
+    HSL101 token family scopes to `"filenames"` — that's the one detector in this codebase whose
+    output depends on the file's name rather than purely its content, since it matches spec
+    tokens against the filename itself (see `_filename_candidates` in rules/spec_tokens.py).
+    Without this, two files with identical content but different names could otherwise collide
+    on the same cache entry and silently swap each other's filename-derived findings.
+    """
+    payload: dict[str, object] = {
+        "enabled_rules": sorted(enabled_rules),
+        "hsl101": asdict(hsl101),
+        "hsl102": asdict(hsl102),
+        "hsl103": asdict(hsl103),
+    }
+    if "HSL101" in enabled_rules and any("filenames" in family.scopes for family in hsl101.tokens):
+        payload["filename"] = filename
+    return hashlib.sha256(json.dumps(payload, sort_keys=True).encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class CachedFileResult:
+    """A cacheable per-file scan outcome — everything `FileScanResult` carries except `stop`.
+
+    `stop` (the process-boundary internal-error signal) is deliberately excluded: internal
+    errors are non-deterministic failures, not something a re-run with the same content and
+    config should replay from cache.
+    """
+
+    findings: tuple[Finding, ...] = ()
+    errors: tuple[LintError, ...] = ()
+    suppressed_count: int = 0
+    files_scanned: int = 0
+
+
+def _entry_path(cache_dir: Path, content_hash: str, config_hash: str) -> Path:
+    return cache_dir / f"{content_hash}-{config_hash}.json"
+
+
+def _finding_to_payload(finding: Finding) -> dict[str, Any]:
+    data = finding.to_dict()
+    del data["path"]
+    return data
+
+
+def _finding_from_payload(data: dict[str, Any], *, path: str) -> Finding:
+    return Finding(path=path, **data)
+
+
+def _error_to_payload(err: LintError) -> dict[str, Any]:
+    data = err.to_dict()
+    del data["path"]
+    return data
+
+
+def _error_from_payload(data: dict[str, Any], *, path: str) -> LintError:
+    return LintError(path=path, **data)
+
+
+def read_cached_result(
+    cache_dir: Path, content_hash: str, config_hash: str, *, relative_path: str, debug: bool = False
+) -> CachedFileResult | None:
+    """Return the cached result for this (content, config) pair, or None on a miss.
+
+    A missing entry (the common case — nothing has cached this file/config pair yet) is a
+    silent miss. An entry that exists but can't be read or parsed is also treated as a miss —
+    a stale or corrupted cache entry must never fail a scan, only fall back to re-analyzing —
+    but that case is unusual enough to report under `--debug`, matching how other best-effort
+    I/O in this codebase (e.g. `scan_file`'s internal-error path) stays silent by default but
+    diagnosable on request.
+    """
+    path = _entry_path(cache_dir, content_hash, config_hash)
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    except OSError as exc:
+        if debug:
+            print(f"debug: cache read failed for {relative_path}: {exc}", file=sys.stderr)
+        return None
+    try:
+        payload = json.loads(raw)
+        return CachedFileResult(
+            findings=tuple(
+                _finding_from_payload(item, path=relative_path) for item in payload["findings"]
+            ),
+            errors=tuple(
+                _error_from_payload(item, path=relative_path) for item in payload["errors"]
+            ),
+            suppressed_count=payload["suppressed_count"],
+            files_scanned=payload["files_scanned"],
+        )
+    except (ValueError, KeyError, TypeError) as exc:
+        if debug:
+            print(f"debug: cache entry for {relative_path} is corrupted: {exc}", file=sys.stderr)
+        return None
+
+
+def write_cached_result(
+    cache_dir: Path,
+    content_hash: str,
+    config_hash: str,
+    result: CachedFileResult,
+    *,
+    debug: bool = False,
+) -> None:
+    """Write a cache entry, best-effort. A failed write must never fail the scan itself —
+    but is reported under `--debug`, so `house-lint check --debug` can diagnose "why isn't
+    caching working" for a broken cache directory or permissions issue.
+    """
+    path = _entry_path(cache_dir, content_hash, config_hash)
+    payload = {
+        "findings": [_finding_to_payload(finding) for finding in result.findings],
+        "errors": [_error_to_payload(err) for err in result.errors],
+        "suppressed_count": result.suppressed_count,
+        "files_scanned": result.files_scanned,
+    }
+    try:
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload), encoding="utf-8")
+    except OSError as exc:
+        if debug:
+            print(f"debug: cache write failed: {exc}", file=sys.stderr)
+
+
+__all__ = [
+    "CACHE_DIRNAME",
+    "CachedFileResult",
+    "default_cache_base",
+    "hash_effective_config",
+    "hash_file_content",
+    "read_cached_result",
+    "versioned_cache_dir",
+    "write_cached_result",
+]