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(decisions): propose conventions the import graph proves (#2141)
Raghav Chamadiya5f8d5e39c448
diff --git a/docs/layers/DECISIONS.md b/docs/layers/DECISIONS.mdindex a2542a318..0932ef223 100644--- a/docs/layers/DECISIONS.md+++ b/docs/layers/DECISIONS.md@@ -242,8 +242,8 @@ get_why() # health dashboard## Where decisions come from-Five capture sources run at index time, each a pass over the repo and its git-history.+Six capture sources run at index time, each a pass over the repo, its git+history, or the graph it just built.| Source | Key | Reads | Notes ||--------|-----|-------|-------|@@ -252,6 +252,7 @@ history.| Git archaeology | `git_archaeology` | Commit messages | Gated on 19 decision verbs (migrate, switch to, replace, adopt, deprecate, drop, rewrite, split, revert, and the rest). || PR bodies | `pr` | Squash-merge and PR commit bodies | A body only qualifies when it looks like a PR description (`## Why`, `## Motivation`, `## Context`, `Closes #`, `Before:` / `After:`). Up to 25 bodies. || Code comments | `comment` | Block comments and docstrings on high-centrality files | Bounded to 30 nodes, and to prose carrying a rationale cue ("because", "instead of", "rather than", "trade-off", "we chose", "deliberately"). Centrality-bounded on purpose: comment archaeology across a whole repo is noise. |+| Conventions | `conventions` | Import edges and wrapper bodies | Off by default (`repowise decision source set conventions --on`), no model. A wrapper of an I/O library (HTTP client, database driver, subprocess, filesystem, lock) that most files reach the library through while few import it directly; the record states the counts and names the direct importers. Go and Java are counted by package. Up to 10 per index. |Three more sources sit outside the index-time set: `session` (deterministicgates over your coding-agent transcripts, below), `session_discovery` (one@@ -290,6 +291,7 @@ pr disabled no This source is switched off.comment disabled no This source is switched off.session deterministic_only no Decision LLM extraction is off. The deterministic stage still runs.session_discovery disabled no This source is switched off.+conventions disabled no This source is switched off.cli always_on - Manual entry is always available.Discovery budget: up to 12 session(s), 30,000 input tokens per update.@@ -349,7 +351,7 @@ confidence = 0.4 + 0.5 * (best_source_rank / 9)```The rank ladder is `cli` 9, `session` 8, `adr` and `pr` 7, `commit` and-`git_archaeology` 6, `inline_marker` 4, `comment` 3, and the heuristic tiers+`git_archaeology` 6, `conventions` 6, `inline_marker` 4, `comment` 3, and the heuristic tiersbelow that. `session` sits above `adr` because a transcript carries what a personactually said while deciding, and a document is someone's later write-up of it;with the order reversed the write-up overwrote the words. Retired sources keepdiff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.mdindex dc8f7b427..fdaa94f28 100644--- a/docs/reference/CLI_REFERENCE.md+++ b/docs/reference/CLI_REFERENCE.md@@ -997,7 +997,7 @@ repowise decision llm --on|--off [PATH] # all decision-extraction mode| `--reason TEXT` | On `dismiss`: why it was tombstoned. || `--superseded-by ID` | On `deprecate`: writes an explicit lineage edge and keeps the retired id resolving. || `--state STATE` | On `candidates`: `open` (default), `accepted`, `merged`, `needs_split`, `dismissed`, `all`. |-| `--lane NAME` | On `candidates`: only candidates raised by that extraction lane (`pr`, `session`, `session_discovery`, `comment`, `git_archaeology`, `adr`, `inline_marker`, `cli`). Unrelated to the review lanes the Decisions page splits on. |+| `--lane NAME` | On `candidates`: only candidates raised by that extraction lane (`pr`, `session`, `session_discovery`, `comment`, `git_archaeology`, `adr`, `inline_marker`, `conventions`, `cli`). Unrelated to the review lanes the Decisions page splits on. || `--apply` | On `migrate`: write the plan. Without it the command reports and writes nothing. || `--dry-run` | On `import`: report and write nothing. |@@ -1098,7 +1098,7 @@ typo from a successful transition. `dismiss` skips its confirmation prompt under| Flag | Description ||------|-------------|| `--status` | `active`, `proposed`, `deprecated`, `superseded`, `dismissed`, `all` |-| `--source` | `adr`, `cli`, `comment`, `commit`, `git_archaeology`, `inline_marker`, `llm_inferred`, `pr`, `session`, `all` |+| `--source` | `adr`, `cli`, `comment`, `commit`, `conventions`, `git_archaeology`, `inline_marker`, `llm_inferred`, `pr`, `session`, `all` || `--proposed` | Shortcut for `--status proposed` || `--stale-only` | Only stale decisions || `--format` | `table` (default) or `json` |diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.mdindex d09616ac1..9fe0b209a 100644--- a/docs/reference/CONFIG.md+++ b/docs/reference/CONFIG.md@@ -401,6 +401,7 @@ decisions:enabled: truellm: falsesession_discovery: true # one broad model pass over new transcript prose+ conventions: false # import patterns the graph proves, no modeldiscovery: # budget for that one pass, per updatemax_sessions: 12 # 1-24max_input_tokens: 30000 # 2000-60000@@ -409,7 +410,7 @@ decisions:Every key is optional. **A config with no `decisions:` block behaves exactly asit did before these switches existed**: every source that shipped on is on,model stages on. That resolved policy is named `default`. A source added after-those switches existed (`session_discovery` is the first) stays off until you+those switches existed (`session_discovery` and `conventions`) stays off until youask for it, so upgrading never starts a model call nobody enabled. The sameholds for a config that names a preset *and* lists its sources: that list iswhat the preset covered when it was written, so a source added to that presetdiff --git a/packages/core/src/repowise/core/analysis/decisions/conventions.py b/packages/core/src/repowise/core/analysis/decisions/conventions.pynew file mode 100644index 000000000..f2712c780--- /dev/null+++ b/packages/core/src/repowise/core/analysis/decisions/conventions.py@@ -0,0 +1,550 @@+"""Conventions: majority import patterns the graph proves.++A convention is a choice point the repository has already settled: an in-repo+wrapper W whose body uses an external library X that performs I/O (an HTTP+client, a database driver, a subprocess runner, a filesystem or lock+primitive), where most files reach X through W and few import X directly.+The candidate says so in counts and nothing else, and it lands ``proposed``:+a person confirms it before any agent sees it as a rule.++Everything here is read from the in-memory graph, the parsed files and the+source bytes ingestion already holds. No database, no model, no tree walk.++What the graph can and cannot say shapes the rule. A ``calls`` edge is only+minted between two in-repo symbols, so "which files call X" is not in the+graph for any language. "Which files import X" is, once the resolver+registers the miss as an ``external:`` node, and "which files import W" is an+ordinary file-to-file import edge. The wrapper itself is confirmed by reading+its callable symbols' bodies, bounded by their indexed line spans, for a+reference to the name the file bound X to. Co-location is not wrapping: a+file that imports X and happens to be imported by many files is only a+wrapper when one of its functions actually uses X.+"""++from __future__ import annotations++import re+from collections import defaultdict+from dataclasses import dataclass+from pathlib import Path+from typing import TYPE_CHECKING, Any++from repowise.core.analysis.decisions.provenance import compute_confidence, rank_for_source+from repowise.core.analysis.decisions.scope import resolve_module_nodes+from repowise.core.analysis.external_systems.links import declaration_name_candidates+from repowise.core.ingestion.cohesion import UNIT_FANOUT_LANGUAGES+from repowise.core.ingestion.external_systems.io_kind import classify_io_kind+from repowise.core.workspace.extractors.http.wrappers import mask_source, symbol_body++if TYPE_CHECKING:+ import networkx as nx++ from repowise.core.analysis.decisions.extractor import ExtractedDecision++__all__ = [+ "MAX_PROPOSALS",+ "MIN_RATIO",+ "MIN_THROUGH",+ "SOURCE_KEY",+ "scan_conventions",+]++SOURCE_KEY = "conventions"++#: Files that must reach the library through the wrapper before a pattern is+#: worth proposing. Below this there is no majority to speak of.+MIN_THROUGH = 5++#: At most one direct importer per this many files through the wrapper.+MIN_RATIO = 4++#: Proposals per index. Nothing else caps a deterministic source.+MAX_PROPOSALS = 10++#: How many direct importers a record lists by path before it counts the rest.+MAX_LISTED_EXCEPTIONS = 25++_CALLABLE_KINDS = frozenset({"function", "method", "constructor"})+#: Module-level bindings that can hold a client instance built from the library.+_BINDING_KINDS = frozenset({"variable", "constant"})+_EXTERNAL_PREFIX = "external:"+_ECOSYSTEM_PREFIXES = ("gem:", "nuget:")+++@dataclass(frozen=True, slots=True)+class _Use:+ """One file's import of one I/O package."""++ package: str+ io_kind: str+ local_names: tuple[str, ...]+ reexport_only: bool+++def _package_of(external_key: str) -> tuple[str, str] | None:+ """``(package, io_kind)`` for an ``external:`` node id, or None when untyped."""+ name = external_key[len(_EXTERNAL_PREFIX) :]+ for prefix in _ECOSYSTEM_PREFIXES:+ if name.startswith(prefix):+ name = name[len(prefix) :]+ for candidate in declaration_name_candidates(name):+ kind = classify_io_kind(candidate)+ if kind is not None:+ return candidate, kind+ return None+++def _uses_by_file(parsed_files: list[Any]) -> dict[str, dict[str, _Use]]:+ """Per file, the I/O packages it imports, merged across import statements."""+ out: dict[str, dict[str, _Use]] = {}+ for parsed in parsed_files:+ path = parsed.file_info.path+ merged: dict[str, _Use] = {}+ for imp in parsed.imports:+ target = imp.resolved_file or ""+ if not target.startswith(_EXTERNAL_PREFIX):+ continue+ typed = _package_of(target)+ if typed is None:+ continue+ package, kind = typed+ names = tuple(n for n in imp.local_names if n and n != "*")+ prior = merged.get(package)+ reexport_only = bool(imp.is_reexport) and (prior is None or prior.reexport_only)+ merged[package] = _Use(+ package=package,+ io_kind=kind,+ local_names=tuple(dict.fromkeys((*(prior.local_names if prior else ()), *names))),+ reexport_only=reexport_only,+ )+ if merged:+ out[path] = merged+ return out+++def _file_text(path: str, source_map: dict[str, bytes] | None, repo_path: Path) -> str | None:+ """The bytes ingestion read for *path*, or one bounded read of that file."""+ raw = source_map.get(path) if source_map else None+ if raw is None:+ try:+ raw = (repo_path / path).read_bytes()+ except OSError:+ return None+ return raw.decode("utf-8", errors="replace")+++def _reference_pattern(names: tuple[str, ...]) -> re.Pattern[str] | None:+ """A use of one of the bound names as a standalone identifier.++ Not preceded by ``.`` or an identifier character, so ``self.client`` does+ not match a binding called ``client`` and ``myrequests`` does not match+ ``requests``.+ """+ if not names:+ return None+ alternatives = "|".join(re.escape(n) for n in sorted(names, key=len, reverse=True))+ return re.compile(r"(?<![\w.$])(?:" + alternatives + r")(?![\w$])")+++def _confirmed_callables(parsed: Any, use: _Use, text: str) -> list[Any]:+ """Callable symbols of *parsed* whose own body references the bound name."""+ pattern = _reference_pattern(use.local_names)+ if pattern is None:+ return []+ suffix = Path(parsed.file_info.path).suffix+ lines = mask_source(text, suffix, strings=True).split("\n")+ out = []+ for sym in parsed.symbols:+ if sym.kind not in _CALLABLE_KINDS:+ continue+ if pattern.search(symbol_body(lines, sym)):+ out.append(sym)+ return out+++def _call_pattern(names: tuple[str, ...] | set[str]) -> re.Pattern[str] | None:+ """A call into one of *names*: ``name(``, ``name.member(`` or ``new name``."""+ if not names:+ return None+ alt = "|".join(re.escape(n) for n in sorted(names, key=len, reverse=True))+ return re.compile(+ r"(?<![\w.$])(?:" + alt + r")\s*(?:\.\s*[\w$]+\s*)*\(|new\s+(?:" + alt + r")(?![\w$])"+ )+++def _confirmed_bindings(parsed: Any, use: _Use, text: str) -> list[Any]:+ """Module-level bindings whose own initializer calls into the library.++ The second wrapper shape: ``service = axios.create()``, ``client =+ httpx.Client()``, an exported ``fetch`` built over undici. A binding that+ merely names the library (``TIMEOUT = httpx.Timeout(5)``) also matches+ here; what separates a client from a setting is whether importers call+ it, which :func:`_calling_importers` decides.+ """+ pattern = _call_pattern(use.local_names)+ if pattern is None:+ return []+ suffix = Path(parsed.file_info.path).suffix+ lines = mask_source(text, suffix, strings=True).split("\n")+ out = []+ for sym in parsed.symbols:+ if sym.kind not in _BINDING_KINDS or sym.parent_name:+ continue+ span = "\n".join(lines[max(sym.start_line - 1, 0) : max(sym.end_line, sym.start_line)])+ if pattern.search(span):+ out.append(sym)+ return out+++def _first_call_line(text: str, suffix: str, name: str) -> int | None:+ """Line of the first call through *name* in *text*, or None when it is only read."""+ pattern = _call_pattern((name,))+ if pattern is None:+ return None+ masked = mask_source(text, suffix, strings=True)+ m = pattern.search(masked)+ return masked.count("\n", 0, m.start()) + 1 if m else None+++def _inbound_calls(graph: nx.DiGraph, symbol_id: str, own_file: str) -> list[tuple[str, int | None]]:+ """``(caller file, first call line)`` for calls into *symbol_id* from other files."""+ if symbol_id not in graph:+ return []+ sites: list[tuple[str, int | None]] = []+ for caller in graph.predecessors(symbol_id):+ data = graph[caller][symbol_id]+ if data.get("edge_type") != "calls":+ continue+ caller_file = graph.nodes[caller].get("file_path")+ if not caller_file or caller_file == own_file:+ continue+ lines = data.get("call_lines") or []+ sites.append((caller_file, min(lines) if lines else None))+ return sorted(sites, key=lambda s: (s[0], s[1] if s[1] is not None else 0))+++def _importers(graph: nx.DiGraph, path: str) -> set[str]:+ """Files with an import edge into *path*."""+ if path not in graph:+ return set()+ return {+ src+ for src in graph.predecessors(path)+ if graph[src][path].get("edge_type") == "imports"+ and graph.nodes[src].get("node_type", "file") == "file"+ }+++def _reaches(graph: nx.DiGraph, importer: str, wrapper: str, names: set[str]) -> bool:+ """Whether *importer*'s import of *wrapper* binds a confirmed callable."""+ imported = graph[importer][wrapper].get("imported_names") or []+ if not imported or "*" in imported:+ return True # the module as a whole; the callable is reachable through it+ return any(n in names for n in imported)+++def _calling_importers(+ graph: nx.DiGraph,+ importers: set[str],+ wrapper: str,+ name: str,+ parsed_by_path: dict[str, Any],+ source_map: dict[str, bytes] | None,+ repo_path: Path,+) -> dict[str, int | None]:+ """Importers that bind *name* from *wrapper* and call it: ``{file: line}``.++ A setting is read; a client is called. Reading each importer once,+ bounded to the files that already import the wrapper, is what tells the+ two apart without a vocabulary of constructors per library.+ """+ out: dict[str, int | None] = {}+ for f in sorted(importers):+ imported = graph[f][wrapper].get("imported_names") or []+ if name not in imported:+ continue+ text = _file_text(f, source_map, repo_path)+ if text is None:+ continue+ line = _first_call_line(text, Path(f).suffix, name)+ if line is not None:+ out[f] = line+ return out+++def _is_test(graph: nx.DiGraph, path: str) -> bool:+ return bool(graph.nodes[path].get("is_test")) if path in graph else False+++@dataclass(slots=True)+class _Candidate:+ package: str+ io_kind: str+ wrapper: str+ symbol: Any+ through: set[str]+ direct: set[str]+ call_sites: list[tuple[str, int | None]]+ #: What the counts are counts of: "files", or "packages" for languages+ #: whose imports name a package directory.+ unit: str = "files"+ #: The direct importers as files, for the record's scope; equals+ #: ``direct`` when the unit is files.+ direct_files: set[str] | None = None+++def _package_dir(path: str) -> str:+ parent = path.rpartition("/")[0]+ return parent or "."+++def _package_candidate(+ graph: nx.DiGraph,+ package: str,+ io_kind: str,+ wrapper: str,+ parsed: Any,+ use: _Use,+ text: str,+ direct_files: set[str],+) -> _Candidate | None:+ """The package-level shape for Go and Java.++ An import there names a package directory and the builder fans the edge+ out to every file in it, so a file-level import count would say every+ file in an importing package reaches the library. Packages are the unit+ instead, and a package reaches the library through the wrapper only when+ one of its files calls a confirmed callable: the call edges are symbol+ level and carry no fan-out.+ """+ confirmed = _confirmed_callables(parsed, use, text)+ if not confirmed:+ return None+ own = _package_dir(wrapper)+ direct_pkgs = {_package_dir(f) for f in direct_files} - {own}+ ranked = sorted(+ ((sym, _inbound_calls(graph, sym.id, wrapper)) for sym in confirmed),+ key=lambda pair: (-len(pair[1]), pair[0].start_line),+ )+ symbol, sites = ranked[0]+ caller_pkgs = {+ _package_dir(f)+ for _sym, sites_ in ranked+ for f, _line in sites_+ if not _is_test(graph, f)+ }+ through = caller_pkgs - direct_pkgs - {own}+ if len(through) < MIN_THROUGH:+ return None+ return _Candidate(+ package=package,+ io_kind=io_kind,+ wrapper=wrapper,+ symbol=symbol,+ through=through,+ direct=direct_pkgs,+ call_sites=sites,+ unit="packages",+ direct_files={f for f in direct_files if _package_dir(f) != own},+ )+++def _candidates_for(+ graph: nx.DiGraph,+ package: str,+ io_kind: str,+ direct_files: set[str],+ parsed_by_path: dict[str, Any],+ uses: dict[str, dict[str, _Use]],+ source_map: dict[str, bytes] | None,+ repo_path: Path,+) -> list[_Candidate]:+ """Every confirmed wrapper of *package* that clears the minimum count."""+ out: list[_Candidate] = []+ by_package_dir: dict[str, _Candidate] = {}+ for wrapper in sorted(direct_files):+ parsed = parsed_by_path.get(wrapper)+ if parsed is None:+ continue+ if parsed.file_info.language in UNIT_FANOUT_LANGUAGES:+ text = _file_text(wrapper, source_map, repo_path)+ if text is None:+ continue+ candidate = _package_candidate(+ graph, package, io_kind, wrapper, parsed, uses[wrapper][package], text, direct_files+ )+ if candidate is None:+ continue+ # Two files of one package are one wrapper; keep the wider one.+ key = _package_dir(wrapper)+ prior = by_package_dir.get(key)+ if prior is None or len(candidate.through) > len(prior.through):+ by_package_dir[key] = candidate+ continue+ importers = {+ f+ for f in _importers(graph, wrapper)+ if f != wrapper and not _is_test(graph, f) and f not in direct_files+ }+ if len(importers) < MIN_THROUGH:+ continue+ text = _file_text(wrapper, source_map, repo_path)+ if text is None:+ continue+ use = uses[wrapper][package]+ confirmed = _confirmed_callables(parsed, use, text)+ symbol = None+ sites: list[tuple[str, int | None]] = []+ through: set[str] = set()+ if confirmed:+ # The symbol other files call most is the entry point the+ # convention names; a tie falls to the earliest declaration.+ ranked = sorted(+ ((sym, _inbound_calls(graph, sym.id, wrapper)) for sym in confirmed),+ key=lambda pair: (-len(pair[1]), pair[0].start_line),+ )+ symbol, sites = ranked[0]+ # A file reaches the library through the wrapper only if it+ # imports one of the confirmed callables, the class holding one,+ # or the module whole, or calls one. Importing the file for an+ # unrelated helper is not reaching the library.+ names = {s.name for s in confirmed} | {s.parent_name for s in confirmed if s.parent_name}+ callers = {f for _sym, sites_ in ranked for f, _line in sites_}+ through = {f for f in importers if _reaches(graph, f, wrapper, names) or f in callers}+ if len(through) < MIN_THROUGH:+ # Second shape: a client instance built at module level and+ # called by its importers. Only importers that call it count.+ for binding in _confirmed_bindings(parsed, use, text):+ calling = _calling_importers(+ graph, importers, wrapper, binding.name, parsed_by_path, source_map, repo_path+ )+ if len(calling) > len(through):+ symbol = binding+ through = set(calling)+ sites = sorted(calling.items())+ if symbol is None or len(through) < MIN_THROUGH:+ continue+ out.append(+ _Candidate(+ package=package,+ io_kind=io_kind,+ wrapper=wrapper,+ symbol=symbol,+ through=through,+ direct=direct_files - {wrapper},+ call_sites=sites,+ )+ )+ return [*out, *by_package_dir.values()]+++def _record(candidate: _Candidate) -> ExtractedDecision:+ from repowise.core.analysis.decisions.extractor import ExtractedDecision++ through = len(candidate.through)+ direct = len(candidate.direct)+ exceptions = sorted(candidate.direct)+ unit = candidate.unit+ decision = (+ f"{through} of {through + direct} {unit} reach {candidate.package} through "+ f"{candidate.wrapper}; {direct} import it directly."+ )+ basis = "call edges" if unit == "packages" else "import edges"+ rationale = (+ f"Counted from {basis}, excluding test files and the wrapper's own {unit[:-1]}. "+ f"Threshold: at least {MIN_THROUGH} {unit} through the wrapper and at most one "+ f"direct importer per {MIN_RATIO}."+ )+ consequences = [f"{path} imports {candidate.package} directly" for path in exceptions]+ if len(consequences) > MAX_LISTED_EXCEPTIONS:+ rest = len(consequences) - MAX_LISTED_EXCEPTIONS+ consequences = [*consequences[:MAX_LISTED_EXCEPTIONS], f"and {rest} more direct importers"]+ sites = candidate.call_sites[:3]+ if sites:+ sample = ", ".join(f"{f}:{line}" if line else f for f, line in sites)+ else:+ sample = ", ".join(sorted(candidate.through)[:3])+ what = "instance" if candidate.symbol.kind in _BINDING_KINDS else "symbol"+ context = (+ f"Wrapper {what} {candidate.symbol.id} at {candidate.wrapper}:"+ f"{candidate.symbol.start_line}. Sample call sites: {sample}."+ )+ quote = "; ".join([decision, *consequences])+ direct_files = sorted(candidate.direct_files if candidate.direct_files is not None else exceptions)+ affected_files = [candidate.wrapper, *direct_files][:20]+ return ExtractedDecision(+ title=f"{candidate.package} goes through {candidate.wrapper}",+ context=context,+ decision=decision,+ rationale=rationale,+ consequences=consequences,+ affected_files=affected_files,+ affected_modules=resolve_module_nodes(affected_files),+ tags=["convention", candidate.io_kind],+ source=SOURCE_KEY,+ evidence_file=candidate.wrapper,+ evidence_line=candidate.symbol.start_line,+ confidence=compute_confidence(rank_for_source(SOURCE_KEY), 1, "exact"),+ status="proposed",+ source_quote=quote,+ # The counts are the ground truth, so the gate reads them as exact.+ source_text=quote,+ # The share of files that bypass the wrapper. It moves when the+ # pattern erodes, which is what stale means for a convention.+ staleness_score=round(direct / (direct + through), 3),+ )+++def scan_conventions(+ graph: nx.DiGraph | None,+ parsed_files: list[Any],+ source_map: dict[str, bytes] | None,+ repo_path: Path,+ *,+ limit: int = MAX_PROPOSALS,+) -> list[ExtractedDecision]:+ """Propose one candidate per (wrapper, I/O package) the graph proves.++ A package with two confirmed wrappers yields nothing: two legitimate+ wrappers would each read as the other's minority, and a wrong convention+ costs more than a missed one.+ """+ if graph is None or not parsed_files:+ return []+ repo_path = Path(repo_path)+ parsed_by_path = {pf.file_info.path: pf for pf in parsed_files}+ uses = _uses_by_file(parsed_files)++ direct_by_package: dict[str, set[str]] = defaultdict(set)+ kind_by_package: dict[str, str] = {}+ for path, per_package in uses.items():+ if _is_test(graph, path):+ continue+ for package, use in per_package.items():+ if use.reexport_only:+ continue # a barrel forwards the name; it neither wraps nor uses it+ direct_by_package[package].add(path)+ kind_by_package[package] = use.io_kind++ proposals: list[_Candidate] = []+ for package in sorted(direct_by_package):+ direct_files = direct_by_package[package]+ candidates = _candidates_for(+ graph,+ package,+ kind_by_package[package],+ direct_files,+ parsed_by_path,+ uses,+ source_map,+ repo_path,+ )+ if len(candidates) != 1:+ continue+ candidate = candidates[0]+ if len(candidate.direct) * MIN_RATIO > len(candidate.through):+ continue+ proposals.append(candidate)++ proposals.sort(key=lambda c: (-len(c.through), c.package, c.wrapper))+ return [_record(c) for c in proposals[:limit]]diff --git a/packages/core/src/repowise/core/analysis/decisions/extractor.py b/packages/core/src/repowise/core/analysis/decisions/extractor.pyindex d6731193f..5c80a0562 100644--- a/packages/core/src/repowise/core/analysis/decisions/extractor.py+++ b/packages/core/src/repowise/core/analysis/decisions/extractor.py@@ -162,6 +162,9 @@ class ExtractedDecision:# mean the lane said nothing, not that it said no.lane: str = ""needs_split: bool = False+ # A source that measures its own conformance writes it; None means the+ # git-diff recompute owns it.+ staleness_score: float | None = Noneclass DecisionSourceError(RuntimeError):@@ -1059,6 +1062,20 @@ class DecisionExtractor:decisions.extend(_collect_batches("comment", list(results)))return decisions+ # ------------------------------------------------------------------+ # Source 6: Conventions (deterministic, graph-counted)+ # ------------------------------------------------------------------++ async def scan_conventions(self) -> list[ExtractedDecision]:+ """Majority import patterns the graph proves, one candidate per wrapper and library."""+ from repowise.core.analysis.decisions.conventions import scan_conventions++ if self._graph is None:+ return []+ return scan_conventions(+ self._graph, self._parsed_files, self._source_map, self._repo_path+ )+# Above this node count, skip the iterative PageRank solve and use degree# centrality (O(nodes)) instead — comment archaeology only needs a rough# "most depended-on files" ranking, not exact PageRank, and the iterative@@ -1314,6 +1331,7 @@ class DecisionExtractor:("adr", self.discover_adrs),("pr", self.mine_pr_bodies),("comment", self.mine_comment_archaeology),+ ("conventions", self.scan_conventions),]if enabled_sources is None and self._policy is not None:enabled_sources = self._policy.enabled_index_sources()diff --git a/packages/core/src/repowise/core/analysis/decisions/policy.py b/packages/core/src/repowise/core/analysis/decisions/policy.pyindex 44bf841d0..583bb3c97 100644--- a/packages/core/src/repowise/core/analysis/decisions/policy.py+++ b/packages/core/src/repowise/core/analysis/decisions/policy.py@@ -134,6 +134,15 @@ SOURCE_SPECS: tuple[SourceSpec, ...] = (authority="machine",default_enabled=False,),+ SourceSpec(+ key="conventions",+ label="Conventions",+ description="Import patterns the graph proves: a wrapper most files reach a library through.",+ deterministic=True,+ llm=False,+ authority="machine",+ default_enabled=False,+ ),SourceSpec(key="cli",label="Manual entry",@@ -162,6 +171,7 @@ INDEX_SOURCE_KEYS: tuple[str, ...] = ("adr","pr","comment",+ "conventions",)diff --git a/packages/core/src/repowise/core/analysis/decisions/provenance.py b/packages/core/src/repowise/core/analysis/decisions/provenance.pyindex 65a60f1bd..e1a56e77c 100644--- a/packages/core/src/repowise/core/analysis/decisions/provenance.py+++ b/packages/core/src/repowise/core/analysis/decisions/provenance.py@@ -57,6 +57,7 @@ SOURCE_RANK: dict[str, int] = {"pr": 7, # PR / squash-merge body"commit": 6, # individual commit message"git_archaeology": 6, # alias for commit-mined decisions+ "conventions": 6, # counted from the code itself, so it sits with commit"changelog": 5, # legacy rows from the removed changelog miner"inline_marker": 4, # # WHY: / # DECISION: code markers"comment": 3, # LLM-curated rationale prose on high-centrality codediff --git a/packages/core/src/repowise/core/persistence/crud/decisions.py b/packages/core/src/repowise/core/persistence/crud/decisions.pyindex ced22f30d..ec172617d 100644--- a/packages/core/src/repowise/core/persistence/crud/decisions.py+++ b/packages/core/src/repowise/core/persistence/crud/decisions.py@@ -1075,7 +1075,9 @@ async def bulk_upsert_decisions(# No title match → ask the store whether a semantically-equivalent# decision already exists, and fold into it if so (cheap title dedup# stays the first pass; this only runs on the residual).- if rec is None and vector_store is not None:+ # A computed record must not fold into a prose record that merely+ # sounds alike; title dedup still applies to it.+ if rec is None and vector_store is not None and headline.get("source") != "conventions":q_vec = group_vecs.get(norm)if batch_mode and q_vec is not None:match_id = await find_duplicate_decision_by_vector(@@ -1101,6 +1103,9 @@ async def bulk_upsert_decisions(headline_title = headline.get("title", "")headline_source = headline.get("source", "cli")headline_evidence_file = headline.get("evidence_file")+ # A source that measures its own conformance supplies the score;+ # otherwise the git-diff recompute fills it in later.+ headline_staleness = headline.get("staleness_score")rec = DecisionRecord(id=derive_decision_id(repository_id,@@ -1124,6 +1129,9 @@ async def bulk_upsert_decisions(evidence_file=headline_evidence_file,evidence_line=headline.get("evidence_line"),confidence=headline.get("confidence", 0.5),+ staleness_score=(+ float(headline_staleness) if headline_staleness is not None else 0.0+ ),)session.add(rec)await session.flush()@@ -1146,6 +1154,9 @@ async def bulk_upsert_decisions(rec.source = headline.get("source", rec.source)rec.evidence_file = headline.get("evidence_file")rec.evidence_line = headline.get("evidence_line")+ # Only a source that measures its own conformance supplies this.+ if headline.get("staleness_score") is not None:+ rec.staleness_score = float(headline["staleness_score"])# Accrete one evidence row per contributing source occurrence.for d in members:@@ -1444,6 +1455,10 @@ async def recompute_decision_staleness(affected = affected_by_id.get(dec.id)if not affected:continue+ # The source writes its own conformance share, and a git-diff score+ # would overwrite it. The module backfill above still applies.+ if dec.source == "conventions":+ continuefrom repowise.core.analysis.decision_extractor import DecisionExtractordiff --git a/packages/server/src/repowise/server/mcp_server/_why_evidence.py b/packages/server/src/repowise/server/mcp_server/_why_evidence.pyindex c8fc2a037..3da1a49c1 100644--- a/packages/server/src/repowise/server/mcp_server/_why_evidence.py+++ b/packages/server/src/repowise/server/mcp_server/_why_evidence.py@@ -36,6 +36,7 @@ ProvenanceKind = Literal["human_decision","extracted_rationale","historical",+ "computed","inferred","unknown",]@@ -47,6 +48,9 @@ _RATIONALE_SOURCES = frozenset(_HISTORICAL_SOURCES = frozenset({"changelog", "commit", "git_archaeology", "pr", "readme_mining"})+# Counted from the code itself rather than written by anyone, so neither+# rationale prose nor history nor a guess.+_COMPUTED_SOURCES = frozenset({"conventions"})_INFERRED_SOURCES = frozenset({"inferred", "semantic"})_FULL_COMMIT_RE = re.compile(r"^[0-9a-fA-F]{40}(?:[0-9a-fA-F]{24})?$")_REFERENCE_CACHE_LIMIT = 4096@@ -161,6 +165,8 @@ def provenance_for_source(source: str | None) -> ProvenanceKind:return "extracted_rationale"if normalized in _HISTORICAL_SOURCES:return "historical"+ if normalized in _COMPUTED_SOURCES:+ return "computed"if normalized in _INFERRED_SOURCES:return "inferred"return "unknown"diff --git a/packages/types/src/decisions.ts b/packages/types/src/decisions.tsindex 879c744b3..0afb6924c 100644--- a/packages/types/src/decisions.ts+++ b/packages/types/src/decisions.ts@@ -69,6 +69,7 @@ export const DECISION_SOURCES = ["cli","comment","commit",+ "conventions","git_archaeology","inline_marker","llm_inferred",@@ -108,6 +109,7 @@ export const DECISION_SOURCE_LABELS: Record<cli: "Manual",comment: "Comment",commit: "Commit",+ conventions: "Convention",git_archaeology: "Git history",inline_marker: "Marker",llm_inferred: "Model",diff --git a/packages/ui/src/decisions/decision-detail.tsx b/packages/ui/src/decisions/decision-detail.tsxindex 6b7cdc7dd..cf6a7b006 100644--- a/packages/ui/src/decisions/decision-detail.tsx+++ b/packages/ui/src/decisions/decision-detail.tsx@@ -59,6 +59,7 @@ const SOURCE_LABEL: Record<string, string> = {adr: "ADR",changelog: "Changelog",session: "Session",+ conventions: "Convention",};const MICRO_LABEL =diff --git a/packages/ui/src/decisions/decision-evidence-drawer.tsx b/packages/ui/src/decisions/decision-evidence-drawer.tsxindex ee5aad21c..c74501ab4 100644--- a/packages/ui/src/decisions/decision-evidence-drawer.tsx+++ b/packages/ui/src/decisions/decision-evidence-drawer.tsx@@ -12,6 +12,7 @@ const SOURCE_LABEL: Record<string, string> = {git_archaeology: "Git archaeology",readme_mining: "Docs mining",cli: "Manual",+ conventions: "Convention",};export interface DecisionEvidenceDrawerProps {diff --git a/tests/fixtures/decision_vocabulary.json b/tests/fixtures/decision_vocabulary.jsonindex 6e8a88508..446ae458d 100644--- a/tests/fixtures/decision_vocabulary.json+++ b/tests/fixtures/decision_vocabulary.json@@ -5,6 +5,7 @@"cli","comment","commit",+ "conventions","git_archaeology","inline_marker","llm_inferred",@@ -58,7 +59,8 @@"pr","comment","session",- "session_discovery"+ "session_discovery",+ "conventions"],"presets": ["default",diff --git a/tests/unit/analysis/test_decision_conventions.py b/tests/unit/analysis/test_decision_conventions.pynew file mode 100644index 000000000..4c564f9df--- /dev/null+++ b/tests/unit/analysis/test_decision_conventions.py@@ -0,0 +1,369 @@+"""The conventions source: majority import patterns proposed from the graph.++Each hazard has an ablation partner, and no count ever makes a record active.+"""++from __future__ import annotations++from datetime import datetime+from pathlib import Path++import pytest++from repowise.core.analysis.decisions.conventions import (+ MAX_PROPOSALS,+ MIN_RATIO,+ MIN_THROUGH,+ scan_conventions,+)+from repowise.core.analysis.decisions.extractor import DecisionExtractor+from repowise.core.analysis.decisions.gate import apply_substring_gate+from repowise.core.ingestion.graph import GraphBuilder+from repowise.core.ingestion.models import FileInfo+from repowise.core.ingestion.parser import parse_file+from repowise.server.mcp_server._helpers import _compute_alignment++WRAPPER = "net/client.py"+WRAPPER_SRC = "import httpx\n\n\ndef get(url):\n return httpx.get(url)\n\n\ndef other_helper():\n return 1\n"+DIRECT_SRC = "import httpx\n\n\ndef raw(url):\n return httpx.get(url)\n"+++def _language(path: str) -> str:+ return {"py": "python", "go": "go", "ts": "typescript", "mod": "go"}[path.rsplit(".", 1)[1]]+++def _build(tmp_path: Path, files: dict[str, str]):+ """Write *files*, parse them with the real parser, and build the graph."""+ parsed_files = []+ source_map: dict[str, bytes] = {}+ for rel, src in files.items():+ target = tmp_path / rel+ target.parent.mkdir(parents=True, exist_ok=True)+ target.write_text(src, encoding="utf-8")+ raw = src.encode("utf-8")+ info = FileInfo(+ path=rel,+ abs_path=str(target),+ language=_language(rel),+ size_bytes=len(raw),+ git_hash="",+ last_modified=datetime.now(),+ is_test=rel.startswith("tests/"),+ is_config=False,+ is_api_contract=False,+ is_entry_point=False,+ )+ parsed_files.append(parse_file(info, raw))+ source_map[rel] = raw+ builder = GraphBuilder(repo_path=tmp_path)+ for pf in parsed_files:+ builder.add_file(pf)+ builder.build()+ return builder.graph(), parsed_files, source_map+++def _repo(through: int = 6, direct: int = 1, **extra: str) -> dict[str, str]:+ files = {"net/__init__.py": "", "svc/__init__.py": "", WRAPPER: WRAPPER_SRC}+ for i in range(through):+ files[f"svc/user{i}.py"] = f"from net.client import get\n\n\ndef load{i}():\n return get('u')\n"+ for i in range(direct):+ files[f"svc/raw{i}.py"] = DIRECT_SRC+ files.update(extra)+ return files+++GO_CLIENT = '''package client++import "net/http"++func Get(u string) (*http.Response, error) {+ return http.Get(u)+}++func Other() int {+ return 1+}+'''++GO_CALLER = '''package svc++import "example.com/x/client"++func F() {+ client.Get("u")+}+'''++GO_RAW = '''package raw++import "net/http"++func R() {+ http.Get("u")+}+'''+++def _go_repo(callers: int, direct: int) -> dict[str, str]:+ files = {"go.mod": "module example.com/x\n\ngo 1.22\n", "client/client.go": GO_CLIENT}+ for i in range(callers):+ files[f"svc{i}/main.go"] = GO_CALLER+ for i in range(direct):+ files[f"raw{i or ''}/raw.go"] = GO_RAW+ return files+++def _scan(tmp_path: Path, files: dict[str, str], **kw):+ graph, parsed, source_map = _build(tmp_path, files)+ return scan_conventions(graph, parsed, source_map, tmp_path, **kw)+++class TestOneWrapperOneLibrary:+ def test_proposes_exactly_one_candidate_with_the_counts(self, tmp_path):+ out = _scan(tmp_path, _repo(through=6, direct=1))++ assert len(out) == 1+ d = out[0]+ assert d.title == f"httpx goes through {WRAPPER}"+ assert d.decision == f"6 of 7 files reach httpx through {WRAPPER}; 1 import it directly."+ assert d.consequences == ["svc/raw0.py imports httpx directly"]+ assert d.affected_files == [WRAPPER, "svc/raw0.py"]+ assert d.affected_modules == ["net", "svc"]+ assert d.evidence_file == WRAPPER+ assert d.evidence_line == 4+ assert d.tags == ["convention", "network"]+ assert d.source == "conventions"+ assert d.status == "proposed"+ assert d.staleness_score == pytest.approx(1 / 7, abs=1e-3)+ assert f"Wrapper symbol {WRAPPER}::get at {WRAPPER}:4" in d.context+ assert "svc/user0.py:5" in d.context++ def test_the_gate_reads_the_counts_as_exact(self, tmp_path):+ kept, rejected = apply_substring_gate(_scan(tmp_path, _repo()))++ assert rejected == 0+ assert kept[0].verification == "exact"+ assert kept[0].source_text == ""+ assert kept[0].source_quote.startswith("6 of 7 files reach httpx")++ def test_no_direct_importers_is_a_clean_majority(self, tmp_path):+ out = _scan(tmp_path, _repo(through=6, direct=0))++ assert len(out) == 1+ assert out[0].decision.endswith("; 0 import it directly.")+ assert out[0].consequences == []+ assert out[0].staleness_score == 0.0+++class TestThresholds:+ def test_below_min_through_emits_nothing(self, tmp_path):+ assert _scan(tmp_path, _repo(through=MIN_THROUGH - 1, direct=0)) == []++ def test_at_min_through_emits(self, tmp_path):+ assert len(_scan(tmp_path, _repo(through=MIN_THROUGH, direct=0))) == 1++ def test_too_many_direct_importers_emits_nothing(self, tmp_path):+ through = MIN_RATIO * 2+ assert _scan(tmp_path, _repo(through=through, direct=3)) == []++ def test_direct_importers_at_the_ratio_still_emit(self, tmp_path):+ through = MIN_RATIO * 2+ assert len(_scan(tmp_path, _repo(through=through, direct=2))) == 1++ def test_the_cap_holds_and_orders_by_reach(self, tmp_path):+ files = _repo(through=6, direct=0)+ files["os/runner.py"] = "import subprocess\n\n\ndef run(cmd):\n return subprocess.run(cmd)\n"+ for i in range(8):+ files[f"jobs/job{i}.py"] = "from os.runner import run\n\n\ndef go():\n return run('x')\n"+ files["jobs/__init__.py"] = ""+ files["os/__init__.py"] = ""++ out = _scan(tmp_path, files)+ assert [d.title.split(" goes")[0] for d in out] == ["subprocess", "httpx"]+ assert len(_scan(tmp_path, files, limit=1)) == 1+ assert MAX_PROPOSALS >= 2+++class TestHazards:+ def test_test_files_count_on_neither_side(self, tmp_path):+ files = _repo(through=6, direct=1)+ files["tests/test_client.py"] = "import httpx\nfrom net.client import get\n\n\ndef test_it():\n assert httpx and get\n"++ out = _scan(tmp_path, files)+ assert out[0].decision.startswith("6 of 7 files")++ def test_the_wrapper_own_file_is_not_a_direct_importer(self, tmp_path):+ out = _scan(tmp_path, _repo(through=6, direct=0))++ assert out[0].decision.endswith("; 0 import it directly.")++ def test_two_confirmed_wrappers_emit_nothing(self, tmp_path):+ files = _repo(through=6, direct=0)+ files["net/client2.py"] = WRAPPER_SRC+ for i in range(6):+ files[f"svc/second{i}.py"] = "from net.client2 import get\n\n\ndef f():\n return get('u')\n"++ assert _scan(tmp_path, files) == []++ def test_co_location_is_not_wrapping(self, tmp_path):+ files = _repo(through=6, direct=0)+ # The library is imported and used at module level, but no callable+ # in the file reaches it, so importing the file is not reaching httpx.+ files[WRAPPER] = "import httpx\n\nTIMEOUT = httpx.Timeout(5)\n\n\ndef get(url):\n return url\n"++ assert _scan(tmp_path, files) == []++ def test_a_reference_inside_a_string_or_comment_does_not_confirm(self, tmp_path):+ files = _repo(through=6, direct=0)+ files[WRAPPER] = (+ "import httpx\n\n\ndef get(url):\n # httpx.get(url) used to live here\n"+ " return 'httpx.get(' + url\n"+ )++ assert _scan(tmp_path, files) == []++ def test_importing_the_file_for_another_helper_is_not_reaching(self, tmp_path):+ files = _repo(through=0, direct=0)+ for i in range(6):+ files[f"svc/helper{i}.py"] = "from net.client import other_helper\n\n\ndef f():\n return other_helper()\n"++ assert _scan(tmp_path, files) == []++ def test_importing_the_module_whole_does_reach(self, tmp_path):+ files = _repo(through=0, direct=0)+ for i in range(6):+ files[f"svc/whole{i}.py"] = "from net import client\n\n\ndef f():\n return client.get('u')\n"++ out = _scan(tmp_path, files)+ assert len(out) == 1+ assert out[0].decision.startswith("6 of 6 files")++ def test_an_untyped_library_emits_nothing(self, tmp_path):+ files = _repo(through=6, direct=0)+ files[WRAPPER] = "import somelib\n\n\ndef get(url):\n return somelib.get(url)\n"++ assert _scan(tmp_path, files) == []++ def test_a_barrel_reexport_is_neither_wrapper_nor_direct(self, tmp_path):+ graph, parsed, source_map = _build(tmp_path, _repo(through=6, direct=1))+ # Mark the direct importer's statement as a re-export: the name is+ # forwarded, not used, so it drops out of the direct count.+ raw = next(pf for pf in parsed if pf.file_info.path == "svc/raw0.py")+ raw.imports[0].is_reexport = True++ out = scan_conventions(graph, parsed, source_map, tmp_path)+ assert out[0].decision.endswith("; 0 import it directly.")++ def test_a_go_wrapper_is_counted_by_package(self, tmp_path):+ files = _go_repo(callers=6, direct=1)++ out = _scan(tmp_path, files)+ assert len(out) == 1+ d = out[0]+ assert d.title == "net/http goes through client/client.go"+ assert d.decision == "6 of 7 packages reach net/http through client/client.go; 1 import it directly."+ assert d.consequences == ["raw imports net/http directly"]+ assert d.affected_files == ["client/client.go", "raw/raw.go"]+ assert "call edges" in d.rationale+ assert "svc0/main.go:" in d.context++ def test_a_go_package_importing_the_wrapper_without_calling_it_does_not_reach(self, tmp_path):+ files = _go_repo(callers=0, direct=0)+ for i in range(6):+ files[f"svc{i}/main.go"] = GO_CALLER.replace("client.Get(\"u\")", "client.Other()")++ assert _scan(tmp_path, files) == []++ def test_two_go_files_in_one_package_are_one_wrapper(self, tmp_path):+ files = _go_repo(callers=6, direct=0)+ files["client/more.go"] = GO_CLIENT.replace("Get(u string) (*http.Response, error)", "Post(u string) (*http.Response, error)").replace("http.Get(u)", "http.Post(u, \"\", nil)")++ out = _scan(tmp_path, files)+ assert len(out) == 1+ assert out[0].decision.startswith("6 of 6 packages")+++class TestOnlyAPersonAccepts:+ @pytest.mark.parametrize("through", [MIN_THROUGH, 50, 200])+ def test_no_count_produces_an_active_record(self, tmp_path, through):+ out = _scan(tmp_path, _repo(through=through, direct=0))++ assert out and all(d.status == "proposed" for d in out)++ def test_a_conventions_candidate_governs_nothing_until_accepted(self):+ result = _compute_alignment(+ WRAPPER, [{"id": "c1", "title": f"httpx goes through {WRAPPER}"}], [], {}+ )++ assert result["active_count"] == 0+ assert result["candidate_count"] == 1+++class TestExtractorWiring:+ async def test_extract_all_runs_the_source_and_gates_it(self, tmp_path):+ graph, parsed, source_map = _build(tmp_path, _repo())+ ex = DecisionExtractor(+ repo_path=tmp_path, graph=graph, parsed_files=parsed, source_map=source_map+ )++ report = await ex.extract_all(enabled_sources=["conventions"])++ assert report.by_source == {"conventions": 1}+ assert report.decisions[0].verification == "exact"++ async def test_no_graph_means_no_candidates(self, tmp_path):+ assert await DecisionExtractor(repo_path=tmp_path).scan_conventions() == []+++class TestBoundInstance:+ """The second wrapper shape: a client built once at module level."""++ TS_WRAPPER = 'import axios from "axios";\n\nexport const service = axios.create({ baseURL: "/api" });\n\nexport const TIMEOUT = 5000;\n'++ def _ts_repo(self, users: int, direct: int = 0, readers: int = 0) -> dict[str, str]:+ files = {"src/utils/request.ts": self.TS_WRAPPER}+ for i in range(users):+ files[f"src/api/user{i}.ts"] = 'import { service } from "../utils/request";\n\nexport function load() {\n return service.get("/u");\n}\n'+ for i in range(direct):+ files[f"src/api/raw{i}.ts"] = 'import axios from "axios";\n\nexport function raw() {\n return axios.get("/u");\n}\n'+ for i in range(readers):+ files[f"src/api/reader{i}.ts"] = 'import { TIMEOUT } from "../utils/request";\n\nexport function wait() {\n return TIMEOUT * 2;\n}\n'+ return files++ def test_a_called_instance_is_a_wrapper(self, tmp_path):+ out = _scan(tmp_path, self._ts_repo(users=6, direct=1))++ assert len(out) == 1+ d = out[0]+ assert d.title == "axios goes through src/utils/request.ts"+ assert d.decision.startswith("6 of 7 files reach axios")+ assert d.consequences == ["src/api/raw0.ts imports axios directly"]+ assert "Wrapper instance src/utils/request.ts::service" in d.context+ assert "src/api/user0.ts:4" in d.context++ def test_a_setting_that_is_only_read_is_not_a_wrapper(self, tmp_path):+ # Six files import TIMEOUT and read it; nothing calls through it.+ files = self._ts_repo(users=0, readers=6)+ files["src/utils/request.ts"] = 'import axios from "axios";\n\nexport const TIMEOUT = axios.defaults.timeout;\n'++ assert _scan(tmp_path, files) == []++ def test_readers_do_not_count_toward_the_instance(self, tmp_path):+ out = _scan(tmp_path, self._ts_repo(users=6, readers=6))++ assert len(out) == 1+ assert out[0].decision.startswith("6 of 6 files")++ def test_a_python_client_instance_is_a_wrapper(self, tmp_path):+ files = {+ "net/__init__.py": "",+ "svc/__init__.py": "",+ "net/client.py": "import httpx\n\nclient = httpx.Client(base_url='http://x')\n",+ }+ for i in range(6):+ files[f"svc/user{i}.py"] = "from net.client import client\n\n\ndef load():\n return client.get('/u')\n"++ out = _scan(tmp_path, files)+ assert len(out) == 1+ assert "Wrapper instance net/client.py::client" in out[0].context+ assert out[0].evidence_line == 3diff --git a/tests/unit/analysis/test_decision_policy.py b/tests/unit/analysis/test_decision_policy.pyindex 579503da1..9e7589a01 100644--- a/tests/unit/analysis/test_decision_policy.py+++ b/tests/unit/analysis/test_decision_policy.py@@ -9,6 +9,7 @@ import yamlfrom repowise.core.analysis.decisions.policy import (CAPTURE_SOURCE_KEYS,+ INDEX_SOURCE_KEYS,PRESET_NAMES,SOURCE_SPECS,DiscoveryBudget,@@ -36,6 +37,10 @@ def _write_config(repo: Path, text: str) -> None:# ---------------------------------------------------------------------------+# Sources that shipped off: an upgrade must not switch them on.+_OFF_BY_DEFAULT = frozenset(spec.key for spec in SOURCE_SPECS if not spec.default_enabled)++@pytest.mark.parametrize("config", [None, {}, {"decisions": {}}, {"decisions": None}])def test_absent_config_resolves_to_prior_behaviour(config):"""A repo indexed before the policy existed must not change on upgrade."""@@ -43,12 +48,13 @@ def test_absent_config_resolves_to_prior_behaviour(config):assert policy.enabled is Trueassert policy.llm is True- legacy = [key for key in CAPTURE_SOURCE_KEYS if key != "session_discovery"]+ legacy = [key for key in CAPTURE_SOURCE_KEYS if key not in _OFF_BY_DEFAULT]assert all(policy.source_enabled(key) for key in legacy)- assert all(policy.llm_allowed(key) for key in legacy)+ assert all(policy.llm_allowed(key) for key in legacy if key != "conventions")# A source added after this config shape existed is off until asked for:- # an upgrade must not start a model call nobody enabled.+ # an upgrade must not start capture nobody enabled.assert policy.source_enabled("session_discovery") is False+ assert policy.source_enabled("conventions") is Falseassert policy.preset_name() == "default"@@ -101,7 +107,7 @@ def test_retired_source_keys_say_retired_not_unknown(retired):assert all(resolution.policy.source_enabled(key)for key in CAPTURE_SOURCE_KEYS- if key != "session_discovery"+ if key not in _OFF_BY_DEFAULT)@@ -472,3 +478,30 @@ def test_a_preset_written_today_round_trips_with_discovery_on():stored = {"decisions": {**policy.to_config_block(), "preset": "balanced"}}assert resolve_policy(stored).policy == policy+++# ---------------------------------------------------------------------------+# Conventions+# ---------------------------------------------------------------------------+++def test_conventions_runs_at_index_time_but_is_off_by_default():+ assert "conventions" in INDEX_SOURCE_KEYS+ policy = preset_policy("default")+ assert policy.source_enabled("conventions") is False+ assert "conventions" not in policy.enabled_index_sources()+++def test_full_preset_turns_conventions_on():+ policy = preset_policy("full")+ assert "conventions" in policy.enabled_index_sources()+++def test_conventions_runs_with_no_model_once_it_is_switched_on():+ policy = resolve_policy(+ {"decisions": {"llm": False, "sources": {"conventions": True}}}+ ).policy++ assert policy.source_enabled("conventions") is True+ assert policy.llm_allowed("conventions") is False+ assert "conventions" in policy.enabled_index_sources()diff --git a/tests/unit/analysis/test_decision_provenance.py b/tests/unit/analysis/test_decision_provenance.pyindex 649b884d2..964fbedcf 100644--- a/tests/unit/analysis/test_decision_provenance.py+++ b/tests/unit/analysis/test_decision_provenance.py@@ -67,6 +67,15 @@ def test_git_archaeology_aliases_commit_rank():assert rank_for_source("git_archaeology") == rank_for_source("commit") == 6+def test_conventions_sits_with_commit_and_leaves_the_scale_intact():+ """Counted from the code itself, so it ranks where a commit does."""+ from repowise.core.analysis.decision_provenance import LISTABLE_SOURCES++ assert rank_for_source("conventions") == 6+ assert MAX_SOURCE_RANK == 9+ assert "conventions" in LISTABLE_SOURCES++def test_unknown_source_lowest_rank():assert rank_for_source("something_new") == 1assert rank_for_source(None) == 1diff --git a/tests/unit/analysis/test_decision_sources.py b/tests/unit/analysis/test_decision_sources.pyindex a172b6eba..3a60cba88 100644--- a/tests/unit/analysis/test_decision_sources.py+++ b/tests/unit/analysis/test_decision_sources.py@@ -201,9 +201,11 @@ async def test_extract_all_honors_enabled_sources(tmp_path):def test_enabled_source_names_defaults_and_overrides():- # No config → everything on.- assert enabled_source_names(None) == SOURCE_NAMES- assert enabled_source_names({}) == SOURCE_NAMES+ # No config → every source that shipped on. Conventions ships off until+ # it has been validated on external repositories.+ default_on = tuple(name for name in SOURCE_NAMES if name != "conventions")+ assert enabled_source_names(None) == default_on+ assert enabled_source_names({}) == default_oncfg = {"decisions": {"sources": {"comment": False, "pr": False}}}enabled = enabled_source_names(cfg)@@ -214,7 +216,7 @@ def test_enabled_source_names_defaults_and_overrides():# Stale keys naming a retired source are ignored rather than breaking a# config written before the removal.for retired in RETIRED_SOURCES:- assert enabled_source_names({"decisions": {"sources": {retired: False}}}) == SOURCE_NAMES+ assert enabled_source_names({"decisions": {"sources": {retired: False}}}) == default_on# Malformed sections never break extraction.- assert enabled_source_names({"decisions": "nope"}) == SOURCE_NAMES- assert enabled_source_names({"decisions": {"sources": "nope"}}) == SOURCE_NAMES+ assert enabled_source_names({"decisions": "nope"}) == default_on+ assert enabled_source_names({"decisions": {"sources": "nope"}}) == default_ondiff --git a/tests/unit/cli/test_decision_config_cmd.py b/tests/unit/cli/test_decision_config_cmd.pyindex 611c844dc..13e0d426a 100644--- a/tests/unit/cli/test_decision_config_cmd.py+++ b/tests/unit/cli/test_decision_config_cmd.py@@ -54,6 +54,7 @@ def test_show_json_lists_every_source(repo: Path):"comment","session","session_discovery",+ "conventions","cli",]assert payload["policy"]["preset"] == "default"diff --git a/tests/unit/persistence/test_decision_conventions_persist.py b/tests/unit/persistence/test_decision_conventions_persist.pynew file mode 100644index 000000000..75ab85ad9--- /dev/null+++ b/tests/unit/persistence/test_decision_conventions_persist.py@@ -0,0 +1,144 @@+"""A conventions record keeps its own conformance score and its own identity.++The source measures how many files bypass the wrapper and writes that as the+record's staleness; the git-diff recompute must not overwrite it, and the+semantic dedup must not fold a counted record into prose that sounds alike.+"""++from __future__ import annotations++import json+from datetime import UTC, datetime, timedelta++import pytest+from sqlalchemy import select++from repowise.core.persistence.crud import bulk_upsert_decisions, recompute_decision_staleness+from repowise.core.persistence.models import DecisionRecord, GitMetadata+from tests.unit.persistence.helpers import insert_repo+from tests.unit.persistence.test_decision_semantic_dedup import _decision, _store+++def _convention(title: str = "redis goes through db/client.py", **overrides) -> dict:+ return {+ "title": title,+ "decision": "12 of 13 files reach redis through db/client.py; 1 import it directly.",+ "rationale": "Counted from import edges.",+ "source": "conventions",+ "status": "proposed",+ "evidence_file": "db/client.py",+ "affected_files": ["db/client.py", "jobs/raw.py"],+ "confidence": 0.7,+ "verification": "exact",+ "source_quote": "12 of 13 files reach redis through db/client.py; 1 import it directly.",+ "staleness_score": 0.077,+ **overrides,+ }+++async def _rows(session, repo_id):+ result = await session.execute(+ select(DecisionRecord).where(DecisionRecord.repository_id == repo_id)+ )+ return list(result.scalars().all())+++async def test_the_supplied_score_is_written_on_create(async_session):+ repo = await insert_repo(async_session)++ await bulk_upsert_decisions(async_session, repo.id, [_convention()])++ (rec,) = await _rows(async_session, repo.id)+ assert rec.staleness_score == pytest.approx(0.077)+++async def test_a_re_extraction_moves_the_score_with_the_pattern(async_session):+ repo = await insert_repo(async_session)+ await bulk_upsert_decisions(async_session, repo.id, [_convention()])++ await bulk_upsert_decisions(+ async_session, repo.id, [_convention(staleness_score=0.25)]+ )++ (rec,) = await _rows(async_session, repo.id)+ assert rec.staleness_score == pytest.approx(0.25)+++async def test_a_record_without_a_score_still_starts_at_zero(async_session):+ repo = await insert_repo(async_session)++ await bulk_upsert_decisions(+ async_session,+ repo.id,+ [_decision("Use Redis", source="inline_marker", quote="use Redis for caching")],+ )++ (rec,) = await _rows(async_session, repo.id)+ assert rec.staleness_score == 0.0+++async def test_the_git_recompute_leaves_a_conventions_score_alone(async_session):+ repo = await insert_repo(async_session)+ await bulk_upsert_decisions(async_session, repo.id, [_convention()])+ (rec,) = await _rows(async_session, repo.id)+ rec.created_at = datetime.now(UTC) - timedelta(days=30)+ async_session.add(+ GitMetadata(+ repository_id=repo.id,+ file_path="db/client.py",+ commit_count_90d=3,+ last_commit_at=datetime.now(UTC),+ )+ )+ await async_session.flush()++ updated = await recompute_decision_staleness(+ async_session, repo.id, {"jobs/raw.py": {"last_commit_at": datetime.now(UTC)}}+ )++ refreshed = await async_session.get(DecisionRecord, rec.id)+ assert updated == 0+ assert refreshed.staleness_score == pytest.approx(0.077)+ # The module backfill still applies to it.+ assert json.loads(refreshed.affected_modules_json) == ["db", "jobs"]+++async def test_a_counted_record_does_not_fold_into_prose_that_sounds_alike(async_session):+ repo = await insert_repo(async_session)+ store = _store()+ await bulk_upsert_decisions(+ async_session,+ repo.id,+ [_decision("Use Redis", source="inline_marker", quote="use Redis for caching")],+ vector_store=store,+ )++ # The keyword embedder puts both texts on the same axis, so a prose+ # record with this title would have merged.+ await bulk_upsert_decisions(+ async_session, repo.id, [_convention()], vector_store=store+ )++ rows = await _rows(async_session, repo.id)+ assert sorted(r.source for r in rows) == ["conventions", "inline_marker"]+++async def test_prose_that_sounds_alike_still_folds_without_the_source(async_session):+ """Ablation partner: the skip is keyed on the source, not on the title."""+ repo = await insert_repo(async_session)+ store = _store()+ await bulk_upsert_decisions(+ async_session,+ repo.id,+ [_decision("Use Redis", source="inline_marker", quote="use Redis for caching")],+ vector_store=store,+ )++ await bulk_upsert_decisions(+ async_session,+ repo.id,+ [_decision("Adopt Redis cache", source="adr", quote="adopt Redis cache")],+ vector_store=store,+ )++ assert len(await _rows(async_session, repo.id)) == 1diff --git a/tests/unit/server/test_decision_settings_api.py b/tests/unit/server/test_decision_settings_api.pyindex 4e73c700e..6b10f6813 100644--- a/tests/unit/server/test_decision_settings_api.py+++ b/tests/unit/server/test_decision_settings_api.py@@ -45,6 +45,7 @@ async def test_get_returns_the_full_source_registry(client: AsyncClient):"comment","session","session_discovery",+ "conventions","cli",]assert body["preset"] == "default"diff --git a/website/cli-reference.md b/website/cli-reference.mdindex 39f1dbb45..2c599e82a 100644--- a/website/cli-reference.md+++ b/website/cli-reference.md@@ -756,7 +756,7 @@ repowise decision SUBCOMMAND [OPTIONS]| Flag | Type | Description ||------|------|-------------|| `--status` | choice | Filter by status: `proposed`, `active`, `deprecated`, `superseded`, `all` |-| `--source` | choice | Filter by origin: `adr`, `cli`, `comment`, `commit`, `git_archaeology`, `inline_marker`, `llm_inferred`, `pr`, `session`, `all` |+| `--source` | choice | Filter by origin: `adr`, `cli`, `comment`, `commit`, `conventions`, `git_archaeology`, `inline_marker`, `llm_inferred`, `pr`, `session`, `all` || `--proposed` | flag | Show only proposed decisions || `--stale-only` | flag | Show only decisions with staleness score ≥ 0.5 |