Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(precedent): record structural facts about a checkout at index time (#1317)
Raghav Chamadiyab9df47818ab5
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.pyindex 64a266ec1..abdbae4e2 100644--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py@@ -1293,6 +1293,9 @@ def init_command(coverage_report_paths=([Path(p) for p in coverage_report] if coverage_report else None),+ # Local `init` is the one place a fact about this machine's+ # environment is a fact about the user's environment.+ derive_environment_facts=True,)finally:if engine is not None:diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.pyindex 5f639fe0e..0b9db8648 100644--- a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py+++ b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py@@ -332,6 +332,7 @@ def _ingest_and_generate_repo(repo: Any, idx: int, total: int, ctx: _WorkspaceCt),progress=callback,existing_kg_fingerprint=_prev_kg_fp,+ derive_environment_facts=True,))repo_phase_timings: dict[str, float] = callback.timingsdiff --git a/packages/core/src/repowise/core/ingestion/traverser.py b/packages/core/src/repowise/core/ingestion/traverser.pyindex db18edd93..832a4a26b 100644--- a/packages/core/src/repowise/core/ingestion/traverser.py+++ b/packages/core/src/repowise/core/ingestion/traverser.py@@ -22,6 +22,7 @@ from collections.abc import Iterable, Iteratorfrom dataclasses import dataclass, fieldfrom datetime import datetimefrom pathlib import Path+from typing import NamedTupleimport pathspecimport structlog@@ -62,10 +63,23 @@ class TraversalStats:skipped_submodule: int = 0skipped_nested_repo: int = 0lang_counts: dict[str, int] = field(default_factory=dict)+ nested_repo_paths: list[str] = field(default_factory=list)+ """Repo-relative paths of the nested git repos behind ``skipped_nested_repo``.++ The counter alone cannot say *which* directories are separate checkouts,+ which is what makes the fact actionable ("run git from inside them"). Capped+ at :data:`_MAX_NESTED_REPO_PATHS` — a memory bound on a pathological tree,+ not a threshold: the count stays exact either way.+ """+ nested_repo_paths_truncated: bool = False+ """True once the cap above dropped a name, so a reader can say "at least"."""log = structlog.get_logger(__name__)+#: Cap on the nested-repo names retained in :class:`TraversalStats`.+_MAX_NESTED_REPO_PATHS = 50+# ---------------------------------------------------------------------------# Blocklists# ---------------------------------------------------------------------------@@ -275,10 +289,13 @@ class FileTraverser:# module (``repowise-augment = "repowise.cli.augment_hook:main"``)# has no in-repo importer, so without this it reads as unreachable# unless its filename happens to match an entry-stem heuristic.- self._console_script_modules = _collect_console_script_modules(+ console_scripts = _collect_console_scripts(self.repo_root,prune_nested_git=not (include_submodules or include_nested_repos),)+ self._console_script_names = console_scripts.names+ self._console_script_modules = console_scripts.modules+ self._distributions = console_scripts.distributionsself.stats = TraversalStats()self._count_lock = threading.Lock()log.info(@@ -414,6 +431,10 @@ class FileTraverser:# to the gitignore/exclude checks below).if not self._include_nested_repos and not is_submodule and _is_nested_git_repo(abs_path):self.stats.skipped_nested_repo += 1+ if len(self.stats.nested_repo_paths) < _MAX_NESTED_REPO_PATHS:+ self.stats.nested_repo_paths.append(rel_str)+ else:+ self.stats.nested_repo_paths_truncated = Truelog.debug("Skipping nested git repo", path=rel_str)return Trueif self._gitignore.match_file(rel_str + "/"):@@ -668,28 +689,46 @@ def _stem_is_entry_point(abs_path: Path) -> bool:return stem in _ENTRY_POINT_STEMS-def _collect_console_script_modules(+class ConsoleScriptTables(NamedTuple):+ """What one pass over the repo's ``pyproject.toml`` files yields."""++ names: frozenset[str]+ """Launcher names an installer drops in the environment's script dir."""+ modules: frozenset[str]+ """Dotted module targets, used for entry-point detection."""+ distributions: frozenset[str]+ """``[project].name`` values — the distributions this repo installs as."""+++def _collect_console_scripts(repo_root: Path, *, prune_nested_git: bool = True-) -> frozenset[str]:- """Dotted-module targets declared in pyproject console-script tables.+) -> ConsoleScriptTables:+ """Console-script names, module targets and distribution names.Reads ``[project.scripts]``, ``[project.gui-scripts]``, and every``[project.entry-points.*]`` group from each ``pyproject.toml`` in therepo. Values look like ``"repowise.cli.augment_hook:main"`` — the part- before the colon names the module a console launcher imports at runtime.+ before the colon names the module a console launcher imports at runtime;+ the key is the launcher an installer drops in the environment's script+ directory, and ``[project].name`` is the distribution it installs as.+ All three come out of the same read: entry-point detection wants the+ modules, shadowed-launcher detection wants the names and needs the+ distribution to tell this repo's editable install from a dependency's.Best-effort: unparsable files are skipped."""import tomllibfrom repowise.core.fs_walk import iter_glob+ names: set[str] = set()modules: set[str] = set()+ distributions: set[str] = set()try:config_files = list(iter_glob(repo_root, ("pyproject.toml",), prune_nested_git=prune_nested_git))except OSError:- return frozenset()+ return ConsoleScriptTables(frozenset(), frozenset(), frozenset())for config_file in config_files:try:data = tomllib.loads(config_file.read_text(encoding="utf-8"))@@ -698,19 +737,29 @@ def _collect_console_script_modules(project = data.get("project")if not isinstance(project, dict):continue- groups = [project.get("scripts"), project.get("gui-scripts")]+ dist = project.get("name")+ if isinstance(dist, str) and dist.strip():+ distributions.add(dist.strip())+ # Only [project.scripts] / [project.gui-scripts] produce a launcher on+ # PATH; other entry-point groups are plugin registrations, so their+ # keys are collected as modules only.+ launcher_groups = [project.get("scripts"), project.get("gui-scripts")]+ groups = list(launcher_groups)entry_points = project.get("entry-points")if isinstance(entry_points, dict):groups.extend(entry_points.values())for group in groups:if not isinstance(group, dict):continue- for target in group.values():+ is_launcher = any(group is g for g in launcher_groups)+ for name, target in group.items():+ if is_launcher and isinstance(name, str) and name.strip():+ names.add(name.strip())if isinstance(target, str):module = target.split(":", 1)[0].strip()if module:modules.add(module)- return frozenset(modules)+ return ConsoleScriptTables(frozenset(names), frozenset(modules), frozenset(distributions))def _is_console_script_target(rel_path: str, modules: frozenset[str]) -> bool:diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.pyindex 91a30ef46..0f7c5fd17 100644--- a/packages/core/src/repowise/core/pipeline/incremental.py+++ b/packages/core/src/repowise/core/pipeline/incremental.py@@ -92,6 +92,16 @@ def build_repo_graph(file_infos = [fi for fi in maybe_infos if fi is not None]repo_structure = traverser.get_repo_structure(file_infos)+ # Structural episodes, minus the formatter check: this path is the hot one+ # (every update, plus the config-triggered re-score), so it derives only+ # what the walk has already paid for and never spawns a subprocess.+ try:+ from repowise.core.precedent.structural import record_structural_episodes++ record_structural_episodes(repo_path, traverser, allow_formatter_check=False)+ except Exception:+ pass+# Thread-pool source reads + content-hash parse cache split, shared with# the init parse phase: only changed files need a tree-sitter parse.# Cache failures degrade to all-miss (full parse), as before.diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.pyindex 161b1ebca..67c4f90f9 100644--- a/packages/core/src/repowise/core/pipeline/orchestrator.py+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py@@ -199,6 +199,7 @@ async def run_pipeline(on_page_ready: Any | None = None,resume_controller: ResumeController | None = None,coverage_report_paths: list[Path] | None = None,+ derive_environment_facts: bool = False,) -> PipelineResult:"""Run the repowise indexing/analysis/generation pipeline.@@ -238,6 +239,14 @@ async def run_pipeline(generation uses repo-local config such as ``reasoning`` from``.repowise/config.yaml`` and ``REPOWISE_REASONING``.+ derive_environment_facts:+ Derive the structural facts that describe the *machine* this index runs+ on (currently whether the tree is formatter-clean, which costs one+ subprocess). Off by default and set only by the local ``init`` command:+ a hosted or CI indexer would otherwise measure its own container and+ store the answer as a fact about the user's repository. The facts read+ off the walk itself are unconditional and unaffected by this flag.+Returns-------PipelineResult@@ -303,6 +312,7 @@ async def run_pipeline(skip_tests=skip_tests,skip_infra=skip_infra,progress=progress,+ derive_environment_facts=derive_environment_facts,)# Resume fast-path: when a prior run already persisted the INDEX phase@@ -331,6 +341,7 @@ async def run_pipeline(skip_tests=skip_tests,skip_infra=skip_infra,progress=progress,+ derive_environment_facts=derive_environment_facts,)traversal_stats = Nonegit_metadata_list = list(git_meta_map.values())diff --git a/packages/core/src/repowise/core/pipeline/phases/ingestion.py b/packages/core/src/repowise/core/pipeline/phases/ingestion.pyindex 673ab0f5f..a917fce02 100644--- a/packages/core/src/repowise/core/pipeline/phases/ingestion.py+++ b/packages/core/src/repowise/core/pipeline/phases/ingestion.py@@ -84,6 +84,32 @@ _TOP_LANGUAGES_SHOWN = 6_SLOW_GRAPH_BUILD_FILES = 2000+async def _record_structural_episodes(+ repo_path: Path,+ traverser: Any,+ *,+ allow_formatter_check: bool,+) -> None:+ """Persist structural episodes for the walk that just finished.++ Imported lazily and swallowed whole: an episode is enrichment, and nothing+ here may fail or slow an index. Off the event loop because the formatter+ check is a blocking subprocess with a timeout, and this loop is also+ driving progress rendering.+ """+ try:+ from repowise.core.precedent.structural import record_structural_episodes++ await asyncio.to_thread(+ record_structural_episodes,+ repo_path,+ traverser,+ allow_formatter_check=allow_formatter_check,+ )+ except Exception:+ logger.debug("structural_episodes_skipped", exc_info=True)++def _emit_traversal_summary(progress: ProgressCallback | None,stats: Any,@@ -241,6 +267,7 @@ async def _run_ingestion(skip_tests: bool,skip_infra: bool,progress: ProgressCallback | None,+ derive_environment_facts: bool = False,) -> tuple[list[Any], list[Any], Any, dict[str, bytes], Any, Any]:"""Traverse, parse, and build the dependency graph.@@ -291,6 +318,15 @@ async def _run_ingestion(await asyncio.to_thread(io_pool.shutdown, wait=True)repo_structure = traverser.get_repo_structure(file_infos)++ # Structural episodes ride the walk that just finished — nested-repo names+ # and console scripts are by-products of it. The one check that describes+ # the machine rather than the repository is opt-in: this function is the+ # *full pipeline*, not ``init``, and the workspace updater and the hosted+ # job executor both reach it.+ await _record_structural_episodes(+ repo_path, traverser, allow_formatter_check=derive_environment_facts+ )_phase_done(progress, "traverse")# Filter@@ -525,6 +561,7 @@ async def reparse_for_resume(skip_tests: bool,skip_infra: bool,progress: ProgressCallback | None,+ derive_environment_facts: bool = False,) -> tuple[list[Any], list[Any], Any, dict[str, bytes], list[Any]]:"""Parse-only ingestion for a resumed run: traverse + parse, **no graphbuild or centrality**.@@ -572,6 +609,12 @@ async def reparse_for_resume(await asyncio.to_thread(io_pool.shutdown, wait=True)repo_structure = traverser.get_repo_structure(file_infos)+ # A resumed run is still the same command: the interrupted one may never+ # have reached the derivation, so it runs here too rather than leaving a+ # resumed repo without the facts a fresh one gets.+ await _record_structural_episodes(+ repo_path, traverser, allow_formatter_check=derive_environment_facts+ )_phase_done(progress, "traverse")if skip_tests:diff --git a/packages/core/src/repowise/core/precedent/__init__.py b/packages/core/src/repowise/core/precedent/__init__.pynew file mode 100644index 000000000..a77f36d2e--- /dev/null+++ b/packages/core/src/repowise/core/precedent/__init__.py@@ -0,0 +1,12 @@+"""Precedent: dated things that happened to this code, bound to the code.++The episode store (:mod:`repowise.core.precedent.store`) is deliberately+stdlib-only so hook-time readers can open it without paying for the core+import graph. Derivation lives beside it, one module per tier.+"""++from __future__ import annotations++from .store import Episode, EpisodeStore, default_store_path++__all__ = ["Episode", "EpisodeStore", "default_store_path"]diff --git a/packages/core/src/repowise/core/precedent/store.py b/packages/core/src/repowise/core/precedent/store.pynew file mode 100644index 000000000..00382d6bf--- /dev/null+++ b/packages/core/src/repowise/core/precedent/store.py@@ -0,0 +1,276 @@+"""EpisodeStore — one row per dated thing that happened to this repo.++Lives in its own SQLite sidecar (``.repowise/episodes/episodes.db``, WAL)+rather than wiki.db, the pattern :mod:`repowise.core.distill.store` set and+:mod:`repowise.core.sessions.staging` already followed: index-time writes+never contend with hook-time reads, and a corrupt episode index degrades this+feature rather than the product.++An episode is a claim with a birth, a scope and a body kept whole — which is+what a metric cannot have. ``tier`` says where it came from and whether it is+shareable: ``structural`` and ``git`` episodes are facts about the repository+and travel with it; ``transcript`` episodes are per-machine and never feed a+stored value another surface reads.++Stdlib only, deliberately: a hook reads this store under a 155 ms budget, and+that budget has already been lost once to module-level imports.+"""++from __future__ import annotations++import hashlib+import json+import sqlite3+import time+from collections.abc import Iterable, Sequence+from dataclasses import dataclass, field+from pathlib import Path++EPISODES_DIRNAME = "episodes"+EPISODES_DB_FILENAME = "episodes.db"++#: Tiers, in availability order. Only the first two are shareable.+TIER_STRUCTURAL = "structural"+TIER_GIT = "git"+TIER_TRANSCRIPT = "transcript"++#: Rows not re-observed for this long are dropped. Every index refreshes+#: ``last_seen_at`` for a fact that still holds, so this evicts only episodes+#: whose repository has stopped being indexed — never a live one. (Contrast+#: the OmissionStore, whose TTL is over *creation* because its rows are a+#: transient stash.)+DEFAULT_TTL_DAYS = 90.0+#: Row-count cap; oldest-seen rows pruned first when exceeded.+DEFAULT_MAX_ROWS = 5000++_SCHEMA = """+CREATE TABLE IF NOT EXISTS episodes (+ id TEXT PRIMARY KEY,+ tier TEXT NOT NULL,+ kind TEXT NOT NULL,+ subject TEXT NOT NULL,+ body TEXT NOT NULL,+ evidence TEXT NOT NULL,+ nodes TEXT NOT NULL,+ birth_commit TEXT,+ birth_at REAL NOT NULL,+ last_seen_at REAL NOT NULL+);+CREATE INDEX IF NOT EXISTS idx_episodes_tier_kind ON episodes(tier, kind);+CREATE INDEX IF NOT EXISTS idx_episodes_last_seen ON episodes(last_seen_at);+"""+++def default_store_path(repo_path: Path | str) -> Path:+ """Path to *repo_path*'s episode database (not created here)."""+ return Path(repo_path) / ".repowise" / EPISODES_DIRNAME / EPISODES_DB_FILENAME+++def episode_id(tier: str, kind: str, subject: str) -> str:+ """Stable identity for an episode: same claim about the same subject."""+ raw = "\x00".join((tier, kind, subject)).encode("utf-8")+ return hashlib.sha256(raw).hexdigest()[:16]+++@dataclass(frozen=True)+class Episode:+ """One dated thing that happened, kept whole.++ ``subject`` discriminates episodes within a kind and is part of the+ identity, so re-deriving the same fact updates a row instead of adding+ one. ``nodes`` is the repo-relative file set the claim is bound to — the+ scope a later staleness query asks git about.+ """++ tier: str+ kind: str+ subject: str+ body: str+ evidence: str+ nodes: tuple[str, ...] = field(default_factory=tuple)+ birth_commit: str | None = None++ @property+ def id(self) -> str:+ return episode_id(self.tier, self.kind, self.subject)+++class EpisodeStore:+ """Synchronous SQLite store for episodes.++ Synchronous on purpose, like the OmissionStore and the session staging+ store: callers are CLI commands, index phases and hooks, where an asyncio+ loop around SQLite is pure overhead.+ """++ def __init__(+ self,+ db_path: Path,+ *,+ ttl_days: float = DEFAULT_TTL_DAYS,+ max_rows: int = DEFAULT_MAX_ROWS,+ ) -> None:+ self.db_path = db_path+ self.ttl_days = ttl_days+ self.max_rows = max_rows+ db_path.parent.mkdir(parents=True, exist_ok=True)+ self._conn = sqlite3.connect(db_path)+ self._conn.execute("PRAGMA journal_mode=WAL")+ self._conn.execute("PRAGMA synchronous=NORMAL")+ self._conn.execute("PRAGMA busy_timeout=5000")+ self._conn.executescript(_SCHEMA)+ self._conn.commit()++ @classmethod+ def open_for_repo(cls, repo_path: Path | str) -> EpisodeStore:+ """Open the store for *repo_path*.++ The caller is responsible for checking that the repo opted in (a+ ``.repowise`` directory exists); this never creates one where a user+ has not run ``repowise init``.+ """+ return cls(default_store_path(repo_path))++ # -- writes ------------------------------------------------------------++ def replace_kinds(+ self,+ *,+ tier: str,+ kinds: Sequence[str],+ episodes: Iterable[Episode],+ now: float | None = None,+ ) -> int:+ """Make *kinds* within *tier* say exactly what *episodes* say.++ Upsert-then-sweep rather than delete-then-insert, so ``birth_at``+ survives on a fact that still holds — an episode whose birth resets on+ every index is a metric wearing a record's clothes.++ Scoped to *kinds* on purpose: a run that derives only some kinds (an+ incremental update skips the ones that cost a subprocess) must not+ delete the episodes it did not look for. Returns rows retired.+ """+ if not kinds:+ return 0+ stamp = time.time() if now is None else now+ rows = [+ (+ ep.id,+ ep.tier,+ ep.kind,+ ep.subject,+ ep.body,+ ep.evidence,+ json.dumps(list(ep.nodes)),+ ep.birth_commit,+ stamp,+ stamp,+ )+ for ep in episodes+ ]+ with self._conn: # one transaction: never half-replaced+ if rows:+ self._conn.executemany(+ """+ INSERT INTO episodes+ (id, tier, kind, subject, body, evidence, nodes,+ birth_commit, birth_at, last_seen_at)+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)+ ON CONFLICT(id) DO UPDATE SET+ body = excluded.body,+ evidence = excluded.evidence,+ nodes = excluded.nodes,+ birth_commit = excluded.birth_commit,+ last_seen_at = excluded.last_seen_at+ """,+ rows,+ )+ placeholders = ",".join("?" * len(kinds))+ cur = self._conn.execute(+ f"DELETE FROM episodes WHERE tier = ? AND kind IN ({placeholders}) "+ "AND last_seen_at < ?",+ (tier, *kinds, stamp),+ )+ retired = cur.rowcount or 0+ self.prune(now=stamp)+ return retired++ def prune(self, *, now: float | None = None) -> None:+ """Drop rows past TTL, then oldest-seen until under the row cap.++ *now* is the write's own stamp when pruning follows a write: reading+ the wall clock instead would make a row written microseconds earlier+ older than the cutoff it is measured against.+ """+ cutoff = (time.time() if now is None else now) - self.ttl_days * 86400+ with self._conn:+ self._conn.execute("DELETE FROM episodes WHERE last_seen_at < ?", (cutoff,))+ while True:+ (rows,) = self._conn.execute("SELECT COUNT(*) FROM episodes").fetchone()+ # Never evict the last row: it may be the one just written.+ if rows <= max(self.max_rows, 1) or rows <= 1:+ break+ self._conn.execute(+ """+ DELETE FROM episodes WHERE id IN (+ SELECT id FROM episodes ORDER BY last_seen_at ASC+ LIMIT MIN(64, (SELECT COUNT(*) - 1 FROM episodes))+ )+ """+ )++ # -- reads -------------------------------------------------------------++ def list_episodes(self, *, tier: str | None = None, kind: str | None = None) -> list[dict]:+ """Episodes, newest birth first. Both filters are optional."""+ sql = (+ "SELECT id, tier, kind, subject, body, evidence, nodes, "+ "birth_commit, birth_at, last_seen_at FROM episodes"+ )+ clauses: list[str] = []+ params: list[object] = []+ if tier is not None:+ clauses.append("tier = ?")+ params.append(tier)+ if kind is not None:+ clauses.append("kind = ?")+ params.append(kind)+ if clauses:+ sql += " WHERE " + " AND ".join(clauses)+ sql += " ORDER BY birth_at DESC, id ASC"+ return [_row_to_dict(row) for row in self._conn.execute(sql, params)]++ def count(self) -> int:+ (rows,) = self._conn.execute("SELECT COUNT(*) FROM episodes").fetchone()+ return int(rows)++ # -- lifecycle ---------------------------------------------------------++ def close(self) -> None:+ self._conn.close()++ def __enter__(self) -> EpisodeStore:+ return self++ def __exit__(self, *exc: object) -> None:+ self.close()+++def _row_to_dict(row: tuple) -> dict:+ try:+ nodes = json.loads(row[6])+ except (TypeError, ValueError):+ nodes = []+ return {+ "id": row[0],+ "tier": row[1],+ "kind": row[2],+ "subject": row[3],+ "body": row[4],+ "evidence": row[5],+ "nodes": nodes,+ "birth_commit": row[7],+ "birth_at": row[8],+ "last_seen_at": row[9],+ }diff --git a/packages/core/src/repowise/core/precedent/structural.py b/packages/core/src/repowise/core/precedent/structural.pynew file mode 100644index 000000000..27e102390--- /dev/null+++ b/packages/core/src/repowise/core/precedent/structural.py@@ -0,0 +1,498 @@+"""Structural episodes: facts about the checkout, derived at index time.++These are the only episodes available on a first-ever index of a repository+with no history, no transcripts and no API key, which is the cold start every+previous shape of this idea died on.++**No new walk.** Three of the four facts are read off work the ingestion walk+already did: the nested-repo names come from the traverser's own skip counter+(:attr:`TraversalStats.nested_repo_paths`), the declared console scripts from+the ``pyproject.toml`` pass the traverser already runs in ``__init__``, and the+configuration from :func:`repo_config.load_repo_config`. The formatter check is+the one genuinely new cost in the module — one subprocess, init only, hard+timeout, and it degrades to **silence** rather than to a partial count+presented as a whole one.++Silence is the normal output: a repo where none of these hold emits nothing.+There is no "no issues found" episode.+"""++from __future__ import annotations++import logging+import os+import shutil+import subprocess+from pathlib import Path+from typing import Any++from .store import TIER_STRUCTURAL, Episode, EpisodeStore++_log = logging.getLogger(__name__)++KIND_NESTED_REPOS = "nested_repos"+KIND_EDITABLE_SHADOW = "editable_shadow"+KIND_CONFIG_OVERRIDE = "config_override"+KIND_FORMATTER_DRIFT = "formatter_drift"++#: Kinds derivable from work that has already happened. Cheap enough for the+#: update path.+FREE_KINDS: tuple[str, ...] = (KIND_NESTED_REPOS, KIND_EDITABLE_SHADOW, KIND_CONFIG_OVERRIDE)+#: Everything, including the kind that costs a subprocess. Init only.+ALL_KINDS: tuple[str, ...] = (*FREE_KINDS, KIND_FORMATTER_DRIFT)++#: Wall-clock ceiling on the formatter check. Exceeding it yields no episode.+#: A whole-repo ``ruff format --check .`` over ~2,000 files measures around a+#: second, so this is generous by an order of magnitude and still far short of+#: anything a user would notice against a full index.+FORMATTER_TIMEOUT_S = 10.0++#: Ceiling on the one-shot ``git rev-parse`` that stamps the formatter fact.+_GIT_TIMEOUT_S = 5.0++#: Nested-repo names quoted in the episode body; the count stays exact.+_MAX_NAMED_REPOS = 10++#: Repo-local virtualenv directory names. Only in-repo environments are+#: inspected: ``VIRTUAL_ENV`` on a CI or hosted indexer points at the+#: *indexer's* environment, and a fact derived from that describes the wrong+#: machine. Ceiling accepted deliberately — a developer whose venv lives+#: outside the checkout gets silence, not a wrong episode.+_VENV_DIRNAMES = (".venv", "venv")++#: Config keys that change what a command does, with the reason each matters.+#: Keyed on repowise's own config schema, so this carries to any repo.+_CONFIG_CLAIMS: tuple[tuple[str, str], ...] = (+ (+ "exclude_patterns",+ "files matching these patterns are never indexed, so the index cannot "+ "answer questions about them and their absence is not evidence they do "+ "not exist",+ ),+ (+ "mcp.tools",+ "the MCP tool surface is restricted to this list, so tools outside it "+ "are unavailable in this repo regardless of what the docs describe",+ ),+)+++def derive_structural_episodes(+ repo_path: Path | str,+ traverser: Any,+ *,+ allow_formatter_check: bool,+) -> list[Episode]:+ """Derive structural episodes for *repo_path* from an exhausted *traverser*.++ *traverser* must be a :class:`~repowise.core.ingestion.FileTraverser` whose+ walk has already run — the nested-repo names are a by-product of it. Pass+ ``allow_formatter_check=False`` on any path that is not ``init``.++ Every check is independently best-effort: one that fails contributes+ nothing and does not stop the others.+ """+ root = Path(repo_path)+ episodes: list[Episode] = []+ for check, enabled in (+ (_nested_repos, True),+ (_editable_shadow, True),+ (_config_overrides, True),+ (_formatter_drift, allow_formatter_check),+ ):+ if not enabled:+ continue+ try:+ episodes.extend(check(root, traverser))+ except Exception:+ # A failing check costs its own fact and nothing else. Logged+ # because this branch is otherwise indistinguishable from the+ # fact not holding, which is the normal case.+ _log.debug("structural check failed: %s", check.__name__, exc_info=True)+ continue+ return episodes+++def record_structural_episodes(+ repo_path: Path | str,+ traverser: Any,+ *,+ allow_formatter_check: bool,+) -> int:+ """Derive and persist structural episodes. Returns the number written.++ A no-op when the repo has not opted in (no ``.repowise`` directory): this+ never creates one. Best-effort throughout — the episode store is an+ enrichment, and no failure here may fail an index.+ """+ root = Path(repo_path)+ if not (root / ".repowise").is_dir():+ return 0+ kinds = ALL_KINDS if allow_formatter_check else FREE_KINDS+ try:+ episodes = derive_structural_episodes(+ root, traverser, allow_formatter_check=allow_formatter_check+ )+ with EpisodeStore.open_for_repo(root) as store:+ store.replace_kinds(tier=TIER_STRUCTURAL, kinds=kinds, episodes=episodes)+ return len(episodes)+ except Exception:+ return 0+++# ---------------------------------------------------------------------------+# 1. Nested and sibling git repositories — free, from the walk's own counter+# ---------------------------------------------------------------------------+++def _nested_repos(root: Path, traverser: Any) -> list[Episode]:+ stats = getattr(traverser, "stats", None)+ # dict.fromkeys rather than the raw list: the counter and the sink both+ # accumulate across walks, and a traverser walked twice would otherwise+ # name every repo twice.+ walked = sorted(dict.fromkeys(getattr(stats, "nested_repo_paths", ()) or ()))+ separate = [rel for rel in walked if _is_separate_checkout(root / rel)]+ if not separate:+ return []+ capped = bool(getattr(stats, "nested_repo_paths_truncated", False))+ named = separate[:_MAX_NAMED_REPOS]+ listed = ", ".join(named)+ if len(separate) > len(named):+ listed += f", and {len(separate) - len(named)} more"+ count = f"At least {len(separate)}" if capped else str(len(separate))+ plural = len(separate) != 1+ body = (+ f"{count} director{'ies' if plural else 'y'} inside this checkout "+ f"{'are' if plural else 'is'} a separate git repository: {listed}. "+ "Run git from inside them rather than from the root — the root's status "+ "will not show their changes, and they are not indexed as part of this repo. "+ "Declared submodules and linked worktrees of this same repository are "+ "excluded; these are independent checkouts."+ )+ return [+ Episode(+ tier=TIER_STRUCTURAL,+ kind=KIND_NESTED_REPOS,+ subject=".",+ body=body,+ evidence=f"ingestion walk stopped at {len(separate)} nested .git boundaries",+ nodes=tuple(separate),+ )+ ]+++def _is_separate_checkout(path: Path) -> bool:+ """True when *path*'s ``.git`` marks a genuinely independent repository.++ The traverser stops at any ``.git`` entry, which is right for indexing and+ too broad for this claim: a ``.git`` **file** also marks a linked worktree+ of this same repository and a submodule declared in a nested (rather than+ root) ``.gitmodules``, neither of which is an independent checkout. The+ file names its gitdir, so one small read separates the three. A ``.git``+ directory is always a real repository.+ """+ marker = path / ".git"+ try:+ if marker.is_dir():+ return True+ gitdir = marker.read_text(encoding="utf-8", errors="replace")[:512]+ except OSError:+ return False+ lowered = gitdir.replace("\\", "/").lower()+ return "/worktrees/" not in lowered and "/modules/" not in lowered+++# ---------------------------------------------------------------------------+# 2. An editable install shadowing a console script — half free+# ---------------------------------------------------------------------------+++def _editable_shadow(root: Path, traverser: Any) -> list[Episode]:+ names = getattr(traverser, "_console_script_names", None) or frozenset()+ distributions = getattr(traverser, "_distributions", None) or frozenset()+ if not names or not distributions:+ return []+ for venv in (root / name for name in _VENV_DIRNAMES):+ if not venv.is_dir():+ continue+ pth = _editable_pth(venv, distributions)+ if pth is None:+ continue+ shadowed = sorted(+ (name, launcher) for name in names if (launcher := _launcher(venv, name)) is not None+ )+ if not shadowed:+ continue+ return [+ Episode(+ tier=TIER_STRUCTURAL,+ kind=KIND_EDITABLE_SHADOW,+ subject=name,+ body=(+ f"`{name}` is installed as a console script in {venv.name} "+ f"alongside an editable install ({pth}). Invoking the bare "+ f"command can run a different copy than the source in this "+ f"checkout; run the module through the environment's own "+ f"interpreter (`-m`) when the distinction matters."+ ),+ evidence=f"{launcher} beside {pth}",+ )+ for name, launcher in shadowed+ ]+ return []+++def _editable_pth(venv: Path, distributions: frozenset[str]) -> str | None:+ """Name of an editable ``.pth`` for one of *distributions*, or None.++ The distribution match is what makes the claim true rather than merely+ alarming: a venv with an unrelated dependency installed ``-e`` plus a+ normally-installed launcher of the same name is not a shadowed checkout,+ and without this it read as one. Editable ``.pth`` filenames embed the+ distribution (``__editable__.my_pkg-1.2.pth``), so both sides are+ normalised the way packaging does before comparing.++ One listing per site-packages directory, bounded by the venv layout —+ never a tree walk.+ """+ wanted = {_normalise_dist(dist) for dist in distributions}+ wanted.discard("")+ if not wanted:+ return None+ for site in (*venv.glob("Lib/site-packages"), *venv.glob("lib/*/site-packages")):+ for entry in site.glob("*.pth"):+ lowered = entry.name.lower()+ if "editable" not in lowered:+ continue+ normalised = _normalise_dist(entry.stem)+ if any(dist in normalised for dist in wanted):+ return entry.name+ return None+++def _normalise_dist(name: str) -> str:+ """Fold a distribution or filename to compare across packaging spellings.++ ``my-pkg``, ``my_pkg`` and ``My.Pkg`` are the same distribution, and an+ editable ``.pth`` may spell it any of those ways.+ """+ return "".join(ch for ch in name.lower() if ch.isalnum())+++def _launcher(venv: Path, name: str) -> str | None:+ """The launcher *venv* installed for console script *name*, if any."""+ for scripts_dir, suffixes in ((venv / "Scripts", (".exe", "")), (venv / "bin", ("",))):+ for suffix in suffixes:+ candidate = scripts_dir / f"{name}{suffix}"+ if candidate.is_file():+ return f"{scripts_dir.name}/{candidate.name}"+ return None+++# ---------------------------------------------------------------------------+# 3. Config that changes what a command does — free, via the loader+# ---------------------------------------------------------------------------+++def _config_overrides(root: Path, _traverser: Any) -> list[Episode]:+ from repowise.core.repo_config import load_repo_config++ config = load_repo_config(root)+ if not config:+ return []+ episodes: list[Episode] = []+ for key, consequence in _CONFIG_CLAIMS:+ value = _dotted_get(config, key)+ if not value:+ continue+ episodes.append(+ Episode(+ tier=TIER_STRUCTURAL,+ kind=KIND_CONFIG_OVERRIDE,+ subject=key,+ body=(+ f"`{key}` is set in .repowise/config.yaml ({_render(value)}): "+ f"{consequence}."+ ),+ evidence=f".repowise/config.yaml: {key} = {_render(value)}",+ )+ )+ episodes.extend(_disabled_switches(config))+ return episodes+++def _disabled_switches(config: dict) -> list[Episode]:+ """Episodes for boolean blocks a user turned off (hooks, distill)."""+ episodes: list[Episode] = []+ for block_name, block in (("hooks", config.get("hooks")), ("distill", config.get("distill"))):+ off = sorted(_falsy_leaves(block, block_name))+ if not off:+ continue+ episodes.append(+ Episode(+ tier=TIER_STRUCTURAL,+ kind=KIND_CONFIG_OVERRIDE,+ subject=block_name,+ body=(+ f"{', '.join(f'`{key}`' for key in off)} "+ f"{'is' if len(off) == 1 else 'are'} disabled in "+ f".repowise/config.yaml, so the behaviour they gate does not "+ f"happen in this repo even where it is documented as default."+ ),+ evidence=f".repowise/config.yaml: {', '.join(f'{key} = false' for key in off)}",+ )+ )+ return episodes+++def _falsy_leaves(value: Any, prefix: str) -> list[str]:+ """Dotted keys under *prefix* whose value is exactly ``False``."""+ if not isinstance(value, dict):+ return []+ found: list[str] = []+ for key, leaf in value.items():+ path = f"{prefix}.{key}"+ if leaf is False:+ found.append(path)+ elif isinstance(leaf, dict):+ found.extend(_falsy_leaves(leaf, path))+ return found+++def _dotted_get(config: dict, dotted: str) -> Any:+ current: Any = config+ for part in dotted.split("."):+ if not isinstance(current, dict):+ return None+ current = current.get(part)+ return current+++def _render(value: Any) -> str:+ if isinstance(value, list):+ shown = ", ".join(str(v) for v in value[:5])+ return f"{shown}, …" if len(value) > 5 else shown+ return str(value)+++# ---------------------------------------------------------------------------+# 4. Formatter-clean tree — the one new subprocess+# ---------------------------------------------------------------------------+++def _formatter_drift(root: Path, _traverser: Any) -> list[Episode]:+ """One ``ruff format --check`` when the repo declares ruff as its formatter.++ Any failure — no formatter declared, another formatter declared, no+ executable, a timeout, a crash, unparsable output — yields no episode. A+ budget that quietly produces a partial count is worse than no fact at all.+ """+ if not _declares_ruff_format(root):+ return []+ executable = _ruff_executable(root)+ if executable is None:+ return []+ try:+ completed = subprocess.run(+ [executable, "format", "--check", "."],+ cwd=str(root),+ capture_output=True,+ text=True,+ timeout=FORMATTER_TIMEOUT_S,+ env={**os.environ, "NO_COLOR": "1"},+ )+ except (subprocess.TimeoutExpired, OSError):+ return []+ if completed.returncode == 0:+ return [] # clean tree: nothing happened, so there is no episode+ drifted = [+ line.split(":", 1)[1].strip()+ for line in completed.stdout.splitlines()+ if line.startswith("Would reformat:") and ":" in line+ ]+ if not drifted:+ return [] # non-zero for some other reason — say nothing+ return [+ Episode(+ tier=TIER_STRUCTURAL,+ kind=KIND_FORMATTER_DRIFT,+ subject="ruff format",+ body=(+ f"This tree is not formatter-clean: {len(drifted)} files would be "+ f"reformatted by `ruff format`. Running it repo-wide produces a large "+ f"diff unrelated to any change in progress. Format only the files you "+ f"touched, and check what CI actually enforces before assuming the "+ f"declared format command is a gate."+ ),+ evidence=f"ruff format --check .: {len(drifted)} files would be reformatted",+ # The count is true of the tree at this commit and of no other. It+ # is the only structural fact that cannot re-derive itself on an+ # update (the check is init-only), so it carries its birth and a+ # reader is expected to stop trusting it once the tree has moved.+ birth_commit=_head_commit(root),+ )+ ]+++def _declares_ruff_format(root: Path) -> bool:+ """True when the repo names ruff, and only ruff, as its formatter.++ Deliberately stricter than :func:`detect_build_commands`, whose format+ inference fires on a ``pyproject.toml`` containing the words "ruff" and+ "format" anywhere. That is fine for a suggested command and wrong as the+ premise of a stored fact: ruff-as-linter beside black-as-formatter is a+ common pairing, and the two disagree, so the inference would tell a+ black-clean repo it is not formatter-clean by a formatter it never chose.+ A repo that declares any competing formatter is silent regardless.+ """+ pyproject = _read_text(root / "pyproject.toml")+ if any(marker in pyproject for marker in _COMPETING_FORMATTERS):+ return False+ if "[tool.ruff.format]" in pyproject:+ return True+ # An explicit invocation anywhere a project records its own commands.+ for candidate in ("Makefile", "package.json", ".pre-commit-config.yaml", "justfile"):+ text = _read_text(root / candidate)+ if "ruff format" in text or "ruff-format" in text:+ return True+ return False+++#: Declaring one of these means the repo formats with something else.+_COMPETING_FORMATTERS: tuple[str, ...] = ("[tool.black]", "[tool.blue]", "[tool.yapf]")+++def _read_text(path: Path) -> str:+ try:+ return path.read_text(encoding="utf-8", errors="replace")+ except OSError:+ return ""+++def _head_commit(root: Path) -> str | None:+ """The commit the checkout is on, or None. Best-effort, never fatal."""+ try:+ completed = subprocess.run(+ ["git", "rev-parse", "HEAD"],+ cwd=str(root),+ capture_output=True,+ text=True,+ timeout=_GIT_TIMEOUT_S,+ )+ except (subprocess.TimeoutExpired, OSError):+ return None+ sha = completed.stdout.strip()+ return sha if completed.returncode == 0 and sha else None+++def _ruff_executable(root: Path) -> str | None:+ """Prefer the checkout's own environment, then PATH."""+ for venv_name in _VENV_DIRNAMES:+ for scripts_dir, filename in (+ (root / venv_name / "Scripts", "ruff.exe"),+ (root / venv_name / "bin", "ruff"),+ ):+ candidate = scripts_dir / filename+ if candidate.is_file():+ return str(candidate)+ return shutil.which("ruff")diff --git a/tests/unit/precedent/test_environment_fact_gate.py b/tests/unit/precedent/test_environment_fact_gate.pynew file mode 100644index 000000000..f5e5ab972--- /dev/null+++ b/tests/unit/precedent/test_environment_fact_gate.py@@ -0,0 +1,41 @@+"""The one check that describes the machine must stay opt-in.++``_run_ingestion`` is the *full pipeline*, not ``init``: the workspace updater+falls back to it, and so does the hosted job executor. A formatter check run+there measures the indexer's container and stores the answer as a fact about+the user's repository, which is the failure mode this gate exists to prevent.+"""++from __future__ import annotations++import inspect+from pathlib import Path++from repowise.core.pipeline.orchestrator import run_pipeline+from repowise.core.pipeline.phases.ingestion import _run_ingestion, reparse_for_resume+++def _default(fn, name: str):+ return inspect.signature(fn).parameters[name].default+++def test_pipeline_entry_points_default_to_off() -> None:+ for fn in (run_pipeline, _run_ingestion, reparse_for_resume):+ assert _default(fn, "derive_environment_facts") is False, fn.__qualname__+++def test_only_the_local_init_command_opts_in() -> None:+ """Anything else that turns this on has to justify itself here first."""+ cli = Path(__file__).resolve().parents[3] / "packages" / "cli" / "src"+ core = Path(__file__).resolve().parents[3] / "packages" / "core" / "src"+ server = Path(__file__).resolve().parents[3] / "packages" / "server" / "src"+ opted_in = {+ py.relative_to(py.parents[4]).as_posix()+ for root in (cli, core, server)+ for py in root.rglob("*.py") # tests may rglob; src may not+ if "derive_environment_facts=True" in py.read_text(encoding="utf-8", errors="ignore")+ }+ assert opted_in == {+ "repowise/cli/commands/init_cmd/command.py",+ "repowise/cli/commands/init_cmd/workspace.py",+ }, opted_indiff --git a/tests/unit/precedent/test_episode_store.py b/tests/unit/precedent/test_episode_store.pynew file mode 100644index 000000000..695779d20--- /dev/null+++ b/tests/unit/precedent/test_episode_store.py@@ -0,0 +1,123 @@+"""Unit tests for the episode store (``repowise.core.precedent.store``)."""++from __future__ import annotations++from pathlib import Path++from repowise.core.precedent.store import (+ TIER_STRUCTURAL,+ Episode,+ EpisodeStore,+ default_store_path,+)+++def _episode(kind: str = "nested_repos", subject: str = ".", body: str = "a") -> Episode:+ return Episode(+ tier=TIER_STRUCTURAL,+ kind=kind,+ subject=subject,+ body=body,+ evidence="e",+ nodes=("backend",),+ )+++def _store(tmp_path: Path) -> EpisodeStore:+ (tmp_path / ".repowise").mkdir(exist_ok=True)+ return EpisodeStore.open_for_repo(tmp_path)+++class TestReplaceKinds:+ def test_writes_and_reads_back(self, tmp_path: Path) -> None:+ with _store(tmp_path) as store:+ store.replace_kinds(+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()]+ )+ rows = store.list_episodes(tier=TIER_STRUCTURAL)+ assert len(rows) == 1+ assert rows[0]["kind"] == "nested_repos"+ assert rows[0]["nodes"] == ["backend"]++ def test_rederiving_preserves_birth(self, tmp_path: Path) -> None:+ """A fact that still holds keeps its birth; only the body may move."""+ with _store(tmp_path) as store:+ store.replace_kinds(+ tier=TIER_STRUCTURAL,+ kinds=["nested_repos"],+ episodes=[_episode(body="first")],+ now=1000.0,+ )+ store.replace_kinds(+ tier=TIER_STRUCTURAL,+ kinds=["nested_repos"],+ episodes=[_episode(body="second")],+ now=2000.0,+ )+ rows = store.list_episodes()+ assert len(rows) == 1+ assert rows[0]["birth_at"] == 1000.0+ assert rows[0]["last_seen_at"] == 2000.0+ assert rows[0]["body"] == "second"++ def test_fact_that_stopped_holding_is_retired(self, tmp_path: Path) -> None:+ with _store(tmp_path) as store:+ store.replace_kinds(+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()], now=1000.0+ )+ retired = store.replace_kinds(+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[], now=2000.0+ )+ assert retired == 1+ with _store(tmp_path) as store:+ assert store.count() == 0++ def test_replace_is_scoped_to_named_kinds(self, tmp_path: Path) -> None:+ """An update that skips the formatter check must not delete its episode."""+ with _store(tmp_path) as store:+ store.replace_kinds(+ tier=TIER_STRUCTURAL,+ kinds=["nested_repos", "formatter_drift"],+ episodes=[_episode(), _episode(kind="formatter_drift", subject="ruff format .")],+ now=1000.0,+ )+ store.replace_kinds(+ tier=TIER_STRUCTURAL,+ kinds=["nested_repos"],+ episodes=[_episode()],+ now=2000.0,+ )+ kinds = {row["kind"] for row in store.list_episodes()}+ assert kinds == {"nested_repos", "formatter_drift"}++ def test_no_kinds_is_a_no_op(self, tmp_path: Path) -> None:+ with _store(tmp_path) as store:+ store.replace_kinds(tier=TIER_STRUCTURAL, kinds=[], episodes=[_episode()])+ assert store.count() == 0+++class TestPrune:+ def test_ttl_drops_only_unseen_rows(self, tmp_path: Path) -> None:+ (tmp_path / ".repowise").mkdir()+ with EpisodeStore(default_store_path(tmp_path), ttl_days=0.0) as store:+ store.replace_kinds(+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()]+ )+ # Written with a current timestamp, so a zero TTL must not evict it.+ assert store.count() == 1++ def test_row_cap_never_evicts_the_last_row(self, tmp_path: Path) -> None:+ (tmp_path / ".repowise").mkdir()+ with EpisodeStore(default_store_path(tmp_path), max_rows=0) as store:+ store.replace_kinds(+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()]+ )+ assert store.count() == 1+++class TestPaths:+ def test_store_path_is_a_sidecar(self, tmp_path: Path) -> None:+ path = default_store_path(tmp_path)+ assert path.parent.parent.name == ".repowise"+ assert path.name == "episodes.db"+ assert not path.exists() # resolving must not create anythingdiff --git a/tests/unit/precedent/test_structural_episodes.py b/tests/unit/precedent/test_structural_episodes.pynew file mode 100644index 000000000..ac5f448e9--- /dev/null+++ b/tests/unit/precedent/test_structural_episodes.py@@ -0,0 +1,436 @@+"""Unit tests for structural episode derivation.++Silence is the behaviour under test as much as the facts are: a repo where+none of these hold must produce an empty store, and a check that cannot answer+must produce nothing rather than a partial answer.+"""++from __future__ import annotations++import subprocess+from pathlib import Path+from types import SimpleNamespace++from repowise.core.ingestion.traverser import FileTraverser+from repowise.core.precedent import EpisodeStore+from repowise.core.precedent.structural import (+ FREE_KINDS,+ KIND_CONFIG_OVERRIDE,+ KIND_EDITABLE_SHADOW,+ KIND_FORMATTER_DRIFT,+ KIND_NESTED_REPOS,+ derive_structural_episodes,+ record_structural_episodes,+)+++def _repo(tmp_path: Path) -> Path:+ (tmp_path / ".repowise").mkdir()+ (tmp_path / "pkg").mkdir()+ (tmp_path / "pkg" / "app.py").write_text("x = 1\n", encoding="utf-8")+ return tmp_path+++def _traverser(tmp_path: Path) -> FileTraverser:+ traverser = FileTraverser(tmp_path)+ list(traverser._walk()) # the derivation reads what the walk left behind+ return traverser+++def _kinds(episodes: list) -> set[str]:+ return {ep.kind for ep in episodes}+++class TestSilence:+ def test_plain_repo_emits_nothing(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ assert episodes == []++ def test_plain_repo_leaves_an_empty_store(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ record_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)+ with EpisodeStore.open_for_repo(repo) as store:+ assert store.count() == 0++ def test_uninitialised_repo_is_never_given_a_repowise_dir(self, tmp_path: Path) -> None:+ (tmp_path / "pkg").mkdir()+ written = record_structural_episodes(+ tmp_path, _traverser(tmp_path), allow_formatter_check=False+ )+ assert written == 0+ assert not (tmp_path / ".repowise").exists()+++class TestNestedRepos:+ def test_names_the_separate_checkouts(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ for name in ("backend", "frontend"):+ (repo / name / ".git").mkdir(parents=True)+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ [nested] = [ep for ep in episodes if ep.kind == KIND_NESTED_REPOS]+ assert set(nested.nodes) == {"backend", "frontend"}+ assert "backend" in nested.body and "frontend" in nested.body++ def test_git_file_form_counts(self, tmp_path: Path) -> None:+ """A repo whose gitdir lives elsewhere is still an independent repo."""+ repo = _repo(tmp_path)+ (repo / "linked").mkdir()+ (repo / "linked" / ".git").write_text(+ "gitdir: C:/elsewhere/other-project/.git", encoding="utf-8"+ )+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ assert KIND_NESTED_REPOS in _kinds(episodes)++ def test_linked_worktree_is_not_a_separate_repo(self, tmp_path: Path) -> None:+ """A worktree of THIS repo is the same repository, not an independent one."""+ repo = _repo(tmp_path)+ (repo / "wt-feature").mkdir()+ (repo / "wt-feature" / ".git").write_text(+ "gitdir: C:/repo/.git/worktrees/wt-feature\n", encoding="utf-8"+ )+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ assert KIND_NESTED_REPOS not in _kinds(episodes)++ def test_nested_submodule_is_not_a_separate_repo(self, tmp_path: Path) -> None:+ """A submodule declared in a nested .gitmodules is absent from the root one."""+ repo = _repo(tmp_path)+ (repo / "vendored").mkdir()+ (repo / "vendored" / ".git").write_text(+ "gitdir: ../.git/modules/outer/modules/vendored\n", encoding="utf-8"+ )+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ assert KIND_NESTED_REPOS not in _kinds(episodes)++ def test_declared_submodule_is_not_a_separate_repo(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ (repo / "vendored").mkdir()+ (repo / "vendored" / ".git").write_text("gitdir: ../.git/modules/vendored", "utf-8")+ (repo / ".gitmodules").write_text(+ '[submodule "vendored"]\n\tpath = vendored\n\turl = https://example.invalid/x\n',+ encoding="utf-8",+ )+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ assert KIND_NESTED_REPOS not in _kinds(episodes)+++class TestEditableShadow:+ def _venv_with_editable_install(self, repo: Path, *, script: str) -> None:+ (repo / "pyproject.toml").write_text(+ f'[project]\nname = "x"\nversion = "0"\n\n'+ f'[project.scripts]\n{script} = "x.cli:main"\n',+ encoding="utf-8",+ )+ site = repo / ".venv" / "Lib" / "site-packages"+ site.mkdir(parents=True)+ (site / "__editable__.x-0.pth").write_text("/src", encoding="utf-8")++ def test_launcher_beside_an_editable_pth(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ self._venv_with_editable_install(repo, script="mytool")+ scripts = repo / ".venv" / "Scripts"+ scripts.mkdir()+ (scripts / "mytool.exe").write_bytes(b"MZ")+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ [shadow] = [ep for ep in episodes if ep.kind == KIND_EDITABLE_SHADOW]+ assert shadow.subject == "mytool"+ assert "__editable__.x-0.pth" in shadow.evidence++ def test_no_launcher_means_no_episode(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ self._venv_with_editable_install(repo, script="mytool")+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ assert KIND_EDITABLE_SHADOW not in _kinds(episodes)++ def test_editable_install_of_another_distribution_means_no_episode(+ self, tmp_path: Path+ ) -> None:+ """An unrelated dependency installed -e does not shadow this checkout."""+ repo = _repo(tmp_path)+ (repo / "pyproject.toml").write_text(+ '[project]\nname = "my-tool"\nversion = "0"\n\n'+ '[project.scripts]\nmytool = "my_tool.cli:main"\n',+ encoding="utf-8",+ )+ site = repo / ".venv" / "Lib" / "site-packages"+ site.mkdir(parents=True)+ (site / "__editable__.some_dependency-2.1.pth").write_text("/elsewhere", encoding="utf-8")+ scripts = repo / ".venv" / "Scripts"+ scripts.mkdir()+ (scripts / "mytool.exe").write_bytes(b"MZ")+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ assert KIND_EDITABLE_SHADOW not in _kinds(episodes)++ def test_distribution_spelling_does_not_matter(self, tmp_path: Path) -> None:+ """my-tool, my_tool and My.Tool are one distribution."""+ repo = _repo(tmp_path)+ (repo / "pyproject.toml").write_text(+ '[project]\nname = "My.Tool"\nversion = "0"\n\n'+ '[project.scripts]\nmytool = "my_tool.cli:main"\n',+ encoding="utf-8",+ )+ site = repo / ".venv" / "Lib" / "site-packages"+ site.mkdir(parents=True)+ (site / "__editable__.my_tool-0.1.pth").write_text("/src", encoding="utf-8")+ scripts = repo / ".venv" / "Scripts"+ scripts.mkdir()+ (scripts / "mytool.exe").write_bytes(b"MZ")+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ assert KIND_EDITABLE_SHADOW in _kinds(episodes)++ def test_launcher_without_editable_install_means_no_episode(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ (repo / "pyproject.toml").write_text(+ '[project]\nname = "x"\nversion = "0"\n\n[project.scripts]\nmytool = "x.cli:main"\n',+ encoding="utf-8",+ )+ scripts = repo / ".venv" / "Scripts"+ scripts.mkdir(parents=True)+ (scripts / "mytool.exe").write_bytes(b"MZ")+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ assert KIND_EDITABLE_SHADOW not in _kinds(episodes)+++class TestConfigOverrides:+ def test_exclude_patterns_are_reported(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ (repo / ".repowise" / "config.yaml").write_text(+ "exclude_patterns:\n - vendor/**\n", encoding="utf-8"+ )+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ [cfg] = [ep for ep in episodes if ep.kind == KIND_CONFIG_OVERRIDE]+ assert cfg.subject == "exclude_patterns"+ assert "vendor/**" in cfg.evidence++ def test_disabled_switch_is_reported_once_per_block(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ (repo / ".repowise" / "config.yaml").write_text(+ "hooks:\n read_skeleton: false\n search_digest: false\n", encoding="utf-8"+ )+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ [cfg] = [ep for ep in episodes if ep.kind == KIND_CONFIG_OVERRIDE]+ assert cfg.subject == "hooks"+ assert "read_skeleton" in cfg.body and "search_digest" in cfg.body++ def test_default_config_says_nothing(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ (repo / ".repowise" / "config.yaml").write_text(+ "provider: openai\nhooks:\n read_skeleton: true\n", encoding="utf-8"+ )+ episodes = derive_structural_episodes(+ repo, _traverser(repo), allow_formatter_check=False+ )+ assert KIND_CONFIG_OVERRIDE not in _kinds(episodes)+++class TestFormatterDrift:+ """The one check that costs a subprocess, and the one that must stay silent+ whenever it cannot answer."""++ def _declaring_repo(self, tmp_path: Path) -> Path:+ repo = _repo(tmp_path)+ (repo / "pyproject.toml").write_text(+ '[project]\nname = "x"\nversion = "0"\n\n[tool.ruff.format]\nquote-style = "double"\n',+ encoding="utf-8",+ )+ return repo++ def test_not_run_when_the_repo_declares_no_formatter(+ self, tmp_path: Path, monkeypatch+ ) -> None:+ repo = _repo(tmp_path)+ monkeypatch.setattr(+ "repowise.core.precedent.structural._ruff_executable",+ lambda _root: (_ for _ in ()).throw(AssertionError("must not resolve")),+ )+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)++ def test_drift_is_reported_with_the_true_count(self, tmp_path: Path, monkeypatch) -> None:+ repo = self._declaring_repo(tmp_path)+ monkeypatch.setattr(+ "repowise.core.precedent.structural._ruff_executable", lambda _root: "ruff"+ )+ monkeypatch.setattr(+ subprocess,+ "run",+ lambda *a, **k: SimpleNamespace(+ returncode=1,+ stdout="Would reformat: a.py\nWould reformat: b.py\n2 files would be reformatted\n",+ stderr="",+ ),+ )+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)+ [drift] = [ep for ep in episodes if ep.kind == KIND_FORMATTER_DRIFT]+ assert "2 files" in drift.body+ assert "ruff format --check ." in drift.evidence+ assert "2 files would be reformatted" in drift.evidence++ def test_a_repo_that_formats_with_something_else_is_silent(+ self, tmp_path: Path, monkeypatch+ ) -> None:+ """Ruff-as-linter beside another formatter must not be read as ruff-as-formatter."""+ repo = _repo(tmp_path)+ (repo / "pyproject.toml").write_text(+ '[project]\nname = "x"\nversion = "0"\n\n'+ '[tool.ruff.lint]\nselect = ["E"]\n\n[tool.black]\nline-length = 88\n',+ encoding="utf-8",+ )+ monkeypatch.setattr(+ subprocess,+ "run",+ lambda *a, **k: (_ for _ in ()).throw(AssertionError("must not run ruff")),+ )+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)++ def test_ruff_as_linter_only_is_silent(self, tmp_path: Path, monkeypatch) -> None:+ """A pyproject mentioning ruff and the word format is not a declaration."""+ repo = _repo(tmp_path)+ (repo / "pyproject.toml").write_text(+ '[project]\nname = "x"\nversion = "0"\ndescription = "formats things"\n\n'+ '[tool.ruff.lint]\nselect = ["E"]\n',+ encoding="utf-8",+ )+ monkeypatch.setattr(+ subprocess,+ "run",+ lambda *a, **k: (_ for _ in ()).throw(AssertionError("must not run ruff")),+ )+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)++ def test_a_pre_commit_declaration_counts(self, tmp_path: Path, monkeypatch) -> None:+ repo = _repo(tmp_path)+ (repo / "pyproject.toml").write_text(+ '[project]\nname = "x"\nversion = "0"\n', encoding="utf-8"+ )+ (repo / ".pre-commit-config.yaml").write_text(+ "repos:\n - hooks:\n - id: ruff-format\n", encoding="utf-8"+ )+ monkeypatch.setattr(+ "repowise.core.precedent.structural._ruff_executable", lambda _root: "ruff"+ )+ monkeypatch.setattr(+ subprocess,+ "run",+ lambda *a, **k: SimpleNamespace(+ returncode=1, stdout="Would reformat: a.py\n", stderr=""+ ),+ )+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)+ assert KIND_FORMATTER_DRIFT in _kinds(episodes)++ def test_clean_tree_produces_no_episode(self, tmp_path: Path, monkeypatch) -> None:+ repo = self._declaring_repo(tmp_path)+ monkeypatch.setattr(+ "repowise.core.precedent.structural._ruff_executable", lambda _root: "ruff"+ )+ monkeypatch.setattr(+ subprocess,+ "run",+ lambda *a, **k: SimpleNamespace(returncode=0, stdout="12 files already formatted\n", stderr=""),+ )+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)++ def test_timeout_produces_no_episode(self, tmp_path: Path, monkeypatch) -> None:+ """An exceeded budget must produce nothing, never a partial count."""+ repo = self._declaring_repo(tmp_path)+ monkeypatch.setattr(+ "repowise.core.precedent.structural._ruff_executable", lambda _root: "ruff"+ )++ def _timeout(*_a, **_k):+ raise subprocess.TimeoutExpired(cmd="ruff", timeout=1)++ monkeypatch.setattr(subprocess, "run", _timeout)+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)++ def test_crash_produces_no_episode(self, tmp_path: Path, monkeypatch) -> None:+ repo = self._declaring_repo(tmp_path)+ monkeypatch.setattr(+ "repowise.core.precedent.structural._ruff_executable", lambda _root: "ruff"+ )+ monkeypatch.setattr(+ subprocess,+ "run",+ lambda *a, **k: SimpleNamespace(returncode=2, stdout="", stderr="boom"),+ )+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)++ def test_update_path_never_runs_it(self, tmp_path: Path, monkeypatch) -> None:+ repo = self._declaring_repo(tmp_path)+ monkeypatch.setattr(+ subprocess,+ "run",+ lambda *a, **k: (_ for _ in ()).throw(AssertionError("no subprocess on update")),+ )+ derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)+ assert KIND_FORMATTER_DRIFT not in FREE_KINDS+++class TestDegradation:+ def test_a_broken_traverser_costs_only_its_own_fact(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ (repo / ".repowise" / "config.yaml").write_text(+ "exclude_patterns:\n - vendor/**\n", encoding="utf-8"+ )+ broken = SimpleNamespace() # no stats, no console-script names+ episodes = derive_structural_episodes(repo, broken, allow_formatter_check=False)+ assert _kinds(episodes) == {KIND_CONFIG_OVERRIDE}+++class TestPersistence:+ def test_recording_twice_is_idempotent(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ (repo / "backend" / ".git").mkdir(parents=True)+ for _ in range(2):+ record_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)+ with EpisodeStore.open_for_repo(repo) as store:+ assert store.count() == 1++ def test_a_fact_that_stops_holding_is_dropped(self, tmp_path: Path) -> None:+ repo = _repo(tmp_path)+ (repo / "backend" / ".git").mkdir(parents=True)+ record_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)+ (repo / "backend" / ".git").rmdir()+ record_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)+ with EpisodeStore.open_for_repo(repo) as store:+ assert store.count() == 0++ def test_episodes_are_tiered_in_the_payload(self, tmp_path: Path) -> None:+ """The tier is the line between this layer and a per-user memory."""+ repo = _repo(tmp_path)+ (repo / "backend" / ".git").mkdir(parents=True)+ record_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)+ with EpisodeStore.open_for_repo(repo) as store:+ assert {row["tier"] for row in store.list_episodes()} == {"structural"}diff --git a/tests/unit/precedent/test_structural_perf.py b/tests/unit/precedent/test_structural_perf.pynew file mode 100644index 000000000..3ec4ae93e--- /dev/null+++ b/tests/unit/precedent/test_structural_perf.py@@ -0,0 +1,82 @@+"""Budget guarantees for structural episode derivation.++Two layers, because a wall clock alone is a weak gate on a loaded box:++ 1. An import-graph guard. The episode store is read on hook paths whose+ budget was fought down from 965 ms to 155 ms by deleting three+ module-level imports, so the store must stay stdlib-only. This is the+ half that catches a regression before it is a stopwatch problem.+ 2. A wall-clock ceiling on the free facts, which run on every update. Loose+ on purpose: it exists to catch an added walk or subprocess, not to+ measure the machine.+"""++from __future__ import annotations++import subprocess+import sys+import time+from pathlib import Path++from repowise.core.ingestion.traverser import FileTraverser+from repowise.core.precedent.structural import derive_structural_episodes++#: Nothing in this list may be reachable from the episode store's imports.+_HEAVY_PREFIXES = (+ "click",+ "sqlalchemy",+ "structlog",+ "networkx",+ "yaml",+ "rich",+ "pathspec",+ "repowise.core.ingestion",+ "repowise.core.persistence",+ "repowise.core.generation",+)++#: Ceiling for deriving the three subprocess-free facts on a small tree.+#: The update-path allowance is 200 ms for everything Precedent adds; this is+#: an order of magnitude under it so a real regression is unambiguous.+_FREE_FACTS_BUDGET_MS = 250.0+++def test_store_import_stays_stdlib_only() -> None:+ code = (+ "import sys; "+ "import repowise.core.precedent.store; "+ f"heavy = [m for m in sys.modules if m.startswith({_HEAVY_PREFIXES!r})]; "+ "print('\\n'.join(heavy)); "+ "sys.exit(1 if heavy else 0)"+ )+ result = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True)+ assert result.returncode == 0, f"heavy imports leaked:\n{result.stdout}{result.stderr}"+++def test_free_facts_add_no_subprocess(tmp_path: Path, monkeypatch) -> None:+ """The update path derives only what the walk already paid for."""+ (tmp_path / ".repowise").mkdir()+ (tmp_path / "backend" / ".git").mkdir(parents=True)+ monkeypatch.setattr(+ subprocess,+ "run",+ lambda *a, **k: (_ for _ in ()).throw(AssertionError("no subprocess allowed here")),+ )+ traverser = FileTraverser(tmp_path)+ list(traverser._walk())+ assert derive_structural_episodes(tmp_path, traverser, allow_formatter_check=False)+++def test_free_facts_stay_within_budget(tmp_path: Path) -> None:+ (tmp_path / ".repowise").mkdir()+ (tmp_path / "backend" / ".git").mkdir(parents=True)+ for i in range(200):+ (tmp_path / f"mod_{i}.py").write_text("x = 1\n", encoding="utf-8")+ traverser = FileTraverser(tmp_path)+ list(traverser._walk())++ derive_structural_episodes(tmp_path, traverser, allow_formatter_check=False) # warm+ start = time.perf_counter()+ derive_structural_episodes(tmp_path, traverser, allow_formatter_check=False)+ elapsed_ms = (time.perf_counter() - start) * 1000+ assert elapsed_ms < _FREE_FACTS_BUDGET_MS, f"free facts took {elapsed_ms:.1f} ms"