Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(decisions): propose conventions the import graph proves (#2141)

Raghav Chamadiya5f8d5e39c448
diff --git a/docs/layers/DECISIONS.md b/docs/layers/DECISIONS.md
index 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` (deterministic
gates 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 tiers
below that. `session` sits above `adr` because a transcript carries what a person
actually 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 keep
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 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.md
index d09616ac1..9fe0b209a 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -401,6 +401,7 @@ decisions:
enabled: true
llm: false
session_discovery: true # one broad model pass over new transcript prose
+ conventions: false # import patterns the graph proves, no model
discovery: # budget for that one pass, per update
max_sessions: 12 # 1-24
max_input_tokens: 30000 # 2000-60000
@@ -409,7 +410,7 @@ decisions:
Every key is optional. **A config with no `decisions:` block behaves exactly as
it 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 you
ask for it, so upgrading never starts a model call nobody enabled. The same
holds for a config that names a preset *and* lists its sources: that list is
what the preset covered when it was written, so a source added to that preset
diff --git a/packages/core/src/repowise/core/analysis/decisions/conventions.py b/packages/core/src/repowise/core/analysis/decisions/conventions.py
new file mode 100644
index 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.py
index 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 = None
class 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.py
index 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.py
index 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 code
diff --git a/packages/core/src/repowise/core/persistence/crud/decisions.py b/packages/core/src/repowise/core/persistence/crud/decisions.py
index 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":
+ continue
from repowise.core.analysis.decision_extractor import DecisionExtractor
diff --git a/packages/server/src/repowise/server/mcp_server/_why_evidence.py b/packages/server/src/repowise/server/mcp_server/_why_evidence.py
index 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.ts
index 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.tsx
index 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.tsx
index 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.json
index 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.py
new file mode 100644
index 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 == 3
diff --git a/tests/unit/analysis/test_decision_policy.py b/tests/unit/analysis/test_decision_policy.py
index 579503da1..9e7589a01 100644
--- a/tests/unit/analysis/test_decision_policy.py
+++ b/tests/unit/analysis/test_decision_policy.py
@@ -9,6 +9,7 @@ import yaml
from 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 True
assert 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 False
assert 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.py
index 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") == 1
assert rank_for_source(None) == 1
diff --git a/tests/unit/analysis/test_decision_sources.py b/tests/unit/analysis/test_decision_sources.py
index 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_on
cfg = {"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_on
diff --git a/tests/unit/cli/test_decision_config_cmd.py b/tests/unit/cli/test_decision_config_cmd.py
index 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.py
new file mode 100644
index 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)) == 1
diff --git a/tests/unit/server/test_decision_settings_api.py b/tests/unit/server/test_decision_settings_api.py
index 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.md
index 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 |