codetruth 0.2.0__py3-none-any.whl

codetruth/core/evidence.py

@@ -0,0 +1,306 @@
+"""Layer 4 — evidence assembly and the 4-way classification.
+
+The logic inversion lives here: a symbol is only `safe_to_delete` when the
+system FAILS to find any usage path — no strong edge, no weak edge, no
+framework marker, no dynamic access in its module, and no public-API
+exposure that static analysis can't rule out.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Optional
+
+from .graph import CodeGraph
+from .models import (Action, Edge, EdgeKind, EdgeStrength, EvidenceRecord,
+                     Marker, MarkerKind, RiskLevel, Status, Symbol, SymbolType)
+
+MAX_EVIDENCE_ITEMS = 8
+
+# How strongly one weak inbound edge argues *against* deletion, by kind.
+# Attribute name-matches are the noisiest signal (a bare `.name` matches every
+# symbol called `name`); a string-literal or reflection reference is far more
+# likely to be a real dynamic use. These weights spread the otherwise-flat
+# uncertain_dynamic_risk bucket so an agent can triage it.
+_WEAK_WEIGHT = {
+    EdgeKind.ATTRIBUTE: 0.15,
+    EdgeKind.REFERENCE: 0.30,
+    EdgeKind.CALL: 0.30,
+    EdgeKind.IMPORT: 0.40,
+    EdgeKind.STRING_REF: 0.50,
+    EdgeKind.DYNAMIC: 0.50,
+    EdgeKind.INHERIT: 0.60,
+}
+
+
+def _rank_score(status: Status, weak: list[Edge], cautions: list,
+                runtime_zero: list, in_dynamic_module: bool,
+                strong_test: list, is_public_api: bool,
+                treat_public_as_api: bool, sym: Symbol) -> float:
+    """Ordering key in [0, 1]; higher = review/delete first. Deterministic
+    heuristic, not a calibrated probability (PLAN.md §4)."""
+    if status is Status.DEFINITELY_USED:
+        return 0.0
+    if status is Status.SAFE_TO_DELETE:
+        # Runtime tracing that observed zero calls is the strongest signal.
+        return 1.0 if runtime_zero else 0.95
+    if status is Status.LIKELY_DEAD:
+        c = 0.75
+        if is_public_api and treat_public_as_api:
+            c -= 0.10   # could be imported by an external consumer
+        if sym.type is SymbolType.MODULE:
+            c -= 0.10   # could be an external entry point (cron/script)
+        if strong_test:
+            c -= 0.10   # its own test suite still references it
+        return round(max(0.50, c), 3)
+    # UNCERTAIN_DYNAMIC_RISK: rank by how much weak evidence exists.
+    pressure = sum(_WEAK_WEIGHT.get(e.kind, 0.30) for e in weak)
+    pressure += 0.40 * len(cautions)
+    if in_dynamic_module:
+        pressure += 0.50
+    if strong_test:
+        pressure += 0.20
+    return round(max(0.10, min(0.45, 0.45 / (1.0 + pressure))), 3)
+
+
+def _edge_is_from_test(edge: Edge, symbols_by_id: dict[str, Symbol]) -> bool:
+    src = symbols_by_id.get(edge.src)
+    if src is not None:
+        return src.is_test
+    # Pseudo-source ("file:...") — treat config references as non-test.
+    return False
+
+
+def _compute_live(symbols: list[Symbol], graph: CodeGraph,
+                  markers_by_symbol: dict[str, list[Marker]],
+                  treat_public_as_api: bool,
+                  reachability: str = "default") -> set[str]:
+    """Reachability: the set of symbols provably executable from a live root.
+
+    Default mode roots: modules (their top-level code runs on import),
+    framework/test/runtime entrypoints, and — in library mode — every public
+    symbol (an external consumer could call it).
+
+    Strict mode ("useless clump" detection) roots are ONLY real entry points:
+    framework routes/commands, __main__ modules, tests, runtime observations,
+    and entrypoints declared in .codetruth.toml. Code that is internally
+    well-connected but never reached from any entry point — an orphaned
+    island — then surfaces in the review queue. Modules are not automatic
+    roots in strict mode; a module is live only if something live imports it
+    or a rule marked it (e.g. a __main__ guard).
+
+    Liveness propagates along STRONG edges only; a strong reference from
+    unreachable code proves nothing, which is exactly the dead-cluster case.
+    Weak edges never propagate liveness; they feed the uncertainty tier
+    directly regardless of their source, which stays conservative.
+    """
+    strict = reachability == "strict"
+    live: set[str] = set()
+    for s in symbols:
+        if any(m.kind in (MarkerKind.ENTRYPOINT, MarkerKind.RUNTIME_USED)
+               for m in markers_by_symbol.get(s.id, ())):
+            live.add(s.id)
+        elif not strict and s.type is SymbolType.MODULE:
+            live.add(s.id)
+        elif not strict and treat_public_as_api and s.is_public:
+            live.add(s.id)
+
+    stack = list(live)
+    while stack:
+        src = stack.pop()
+        if src not in graph.g:
+            continue
+        for _src, dst, data in graph.g.out_edges(src, data=True):
+            if data["edge"].strength is EdgeStrength.STRONG and dst not in live:
+                live.add(dst)
+                stack.append(dst)
+    return live
+
+
+def _dead_clusters(symbols: list[Symbol], graph: CodeGraph,
+                   live: set[str]) -> dict[str, list[str]]:
+    """Group unreachable symbols into connected clumps. Two dead symbols
+    joined by a strong edge belong to the same island; reporting them as a
+    unit ('delete as a group') is far more actionable than scattered rows."""
+    dead = {s.id for s in symbols
+            if s.id not in live and s.type is not SymbolType.MODULE}
+    if not dead:
+        return {}
+    adjacency: dict[str, set[str]] = defaultdict(set)
+    for e in graph.edges:
+        if e.strength is EdgeStrength.STRONG and e.src in dead and e.dst in dead:
+            adjacency[e.src].add(e.dst)
+            adjacency[e.dst].add(e.src)
+    clusters: dict[str, list[str]] = {}
+    seen: set[str] = set()
+    for start in adjacency:
+        if start in seen:
+            continue
+        component, stack = set(), [start]
+        while stack:
+            node = stack.pop()
+            if node in component:
+                continue
+            component.add(node)
+            stack.extend(adjacency[node] - component)
+        seen |= component
+        if len(component) > 1:
+            members = sorted(component)
+            for node in component:
+                clusters[node] = members
+    return clusters
+
+
+def build_records(symbols: list[Symbol], graph: CodeGraph,
+                  markers: list[Marker],
+                  treat_public_as_api: bool = True,
+                  reachability: str = "default") -> list[EvidenceRecord]:
+    symbols_by_id = {s.id: s for s in symbols}
+    markers_by_symbol: dict[str, list[Marker]] = defaultdict(list)
+    dynamic_modules: set[str] = set()
+    for m in markers:
+        markers_by_symbol[m.symbol].append(m)
+        if m.kind is MarkerKind.DYNAMIC_MODULE:
+            dynamic_modules.add(m.symbol)
+
+    live = _compute_live(symbols, graph, markers_by_symbol,
+                         treat_public_as_api, reachability)
+    clusters = _dead_clusters(symbols, graph, live)
+
+    records = []
+    for sym in symbols:
+        records.append(_classify(sym, graph, markers_by_symbol.get(sym.id, []),
+                                 dynamic_modules, symbols_by_id,
+                                 treat_public_as_api, live,
+                                 clusters.get(sym.id), reachability))
+    return records
+
+
+def _classify(sym: Symbol, graph: CodeGraph, sym_markers: list[Marker],
+              dynamic_modules: set[str], symbols_by_id: dict[str, Symbol],
+              treat_public_as_api: bool, live: set[str],
+              cluster: Optional[list[str]] = None,
+              reachability: str = "default") -> EvidenceRecord:
+    strong, weak = graph.inbound_split(sym.id)
+    strong_nontest = [e for e in strong if not _edge_is_from_test(e, symbols_by_id)]
+    strong_test = [e for e in strong if _edge_is_from_test(e, symbols_by_id)]
+    # A strong reference only proves use when its source is itself reachable.
+    # Unknown sources (not in the symbol table) are treated as live — never
+    # assume deadness about code we can't see.
+    strong_live = [e for e in strong_nontest
+                   if e.src in live or e.src not in symbols_by_id]
+    strong_deadsrc = [e for e in strong_nontest
+                      if e.src in symbols_by_id and e.src not in live]
+
+    entry = [m for m in sym_markers if m.kind in (MarkerKind.ENTRYPOINT,
+                                                  MarkerKind.RUNTIME_USED)]
+    cautions = [m for m in sym_markers if m.kind is MarkerKind.CAUTION]
+    runtime_zero = [m for m in sym_markers if m.kind is MarkerKind.RUNTIME_ZERO]
+    in_dynamic_module = sym.module in dynamic_modules
+
+    for_del: list[str] = []
+    against: list[str] = []
+
+    # ---- evidence both ways, assembled regardless of final status ----------
+    if entry:
+        against.extend(m.reason for m in entry[:MAX_EVIDENCE_ITEMS])
+    if strong_live:
+        against.append(f"{len(strong_live)} strong reference(s), e.g. "
+                       + strong_live[0].describe())
+    if strong_deadsrc and not strong_live:
+        srcs = sorted({e.src for e in strong_deadsrc})
+        against.append(
+            f"{len(strong_deadsrc)} strong reference(s) exist, but only from "
+            f"code that is itself unreachable ({', '.join(srcs[:4])}) — "
+            "deleting this symbol alone would break that dead code; delete "
+            "the cluster together")
+    if strong_test and not strong_nontest:
+        against.append(f"{len(strong_test)} reference(s) from tests only, e.g. "
+                       + strong_test[0].describe())
+    for e in weak[:MAX_EVIDENCE_ITEMS]:
+        against.append("Possible dynamic usage: " + e.describe())
+    if len(weak) > MAX_EVIDENCE_ITEMS:
+        against.append(f"...and {len(weak) - MAX_EVIDENCE_ITEMS} more weak reference(s)")
+    for m in cautions[:MAX_EVIDENCE_ITEMS]:
+        against.append(m.reason)
+    if in_dynamic_module:
+        against.append(f"module {sym.module} contains non-literal dynamic access "
+                       "(getattr/eval/import_module) — usage cannot be ruled out")
+
+    if not strong:
+        for_del.append("No strong references (calls/imports/inheritance) found "
+                       "in the repository")
+    elif not strong_live and not strong_test and strong_deadsrc:
+        for_del.append("Every strong reference originates from unreachable "
+                       "(dead) code — no live usage path exists")
+    if cluster:
+        others = [c for c in cluster if c != sym.id]
+        for_del.append(
+            f"Part of an unreachable {len(cluster)}-symbol cluster with "
+            f"{', '.join(others[:6])}{'…' if len(others) > 6 else ''} — the "
+            "clump can be reviewed and deleted as a group")
+    if reachability == "strict" and sym.id not in live \
+            and sym.type is not SymbolType.MODULE and not entry:
+        for_del.append("Strict mode: not reachable from any entry point "
+                       "(route, command, __main__, test, declared entrypoint)")
+    if not weak:
+        for_del.append("No string-literal, reflection, or attribute-name "
+                       "references detected")
+    if not entry:
+        for_del.append("Not matched by any framework/entry-point rule")
+    if not strong_test and not sym.is_test:
+        for_del.append("Not referenced by the test suite")
+    for m in runtime_zero:
+        for_del.append(m.reason)
+
+    is_public_api = sym.is_public and sym.type is not SymbolType.MODULE
+    if is_public_api and treat_public_as_api:
+        against.append("Symbol is public — may be consumed outside this "
+                       "repository (pass treat_public_as_api=False for "
+                       "application code)")
+
+    # ---- decision ladder (conservative by construction) --------------------
+    if entry:
+        status = Status.DEFINITELY_USED
+    elif strong_live:
+        status = Status.DEFINITELY_USED
+    elif strong_test:
+        # Only its own tests keep it alive.
+        status = Status.UNCERTAIN_DYNAMIC_RISK if weak else Status.LIKELY_DEAD
+    elif weak:
+        status = Status.UNCERTAIN_DYNAMIC_RISK
+    elif cautions or in_dynamic_module:
+        status = Status.UNCERTAIN_DYNAMIC_RISK
+    elif strong_deadsrc:
+        # Dead-cluster interior: no live path reaches it, but deleting it
+        # alone would break its (dead) referrers. Never safe standalone —
+        # the advice is to review and delete the cluster as a group.
+        status = Status.LIKELY_DEAD
+    elif sym.type is SymbolType.MODULE:
+        # An unimported module might still be an external entry point
+        # (cron, script, service runner) — never provably dead statically.
+        status = Status.LIKELY_DEAD
+        against.append("Modules can be executed directly or referenced "
+                       "externally — static analysis cannot prove otherwise")
+    elif is_public_api and treat_public_as_api:
+        status = Status.LIKELY_DEAD
+    else:
+        status = Status.SAFE_TO_DELETE
+
+    risk, action = {
+        Status.DEFINITELY_USED: (RiskLevel.LOW, Action.KEEP),
+        Status.SAFE_TO_DELETE: (RiskLevel.LOW, Action.DELETE),
+        Status.LIKELY_DEAD: (RiskLevel.MEDIUM, Action.REVIEW_REQUIRED),
+        Status.UNCERTAIN_DYNAMIC_RISK: (RiskLevel.HIGH, Action.REVIEW_REQUIRED),
+    }[status]
+
+    rank = _rank_score(status, weak, cautions, runtime_zero, in_dynamic_module,
+                       strong_test, is_public_api, treat_public_as_api, sym)
+
+    return EvidenceRecord(
+        symbol=sym.id, name=sym.name, type=sym.type, file=sym.file,
+        line=sym.line, status=status, risk_level=risk,
+        recommended_action=action, evidence_for_deletion=for_del,
+        evidence_against_deletion=against, inbound_strong=len(strong),
+        inbound_weak=len(weak), exported=sym.exported, rank_score=rank,
+        cluster=list(cluster) if cluster else None,
+    )

codetruth/core/graph.py

@@ -0,0 +1,44 @@
+"""Layer 2 container: directed multigraph of symbols with strong/weak edges."""
+from __future__ import annotations
+
+import networkx as nx
+
+from .models import Edge, EdgeStrength, Symbol
+
+
+class CodeGraph:
+    """Wraps a networkx MultiDiGraph. Nodes are symbol ids (plus pseudo-nodes
+    like 'file:config.yaml' for edges sourced from non-code files)."""
+
+    def __init__(self) -> None:
+        self.g = nx.MultiDiGraph()
+        self.edges: list[Edge] = []
+
+    def add_symbol(self, sym: Symbol) -> None:
+        self.g.add_node(sym.id, symbol=sym)
+
+    def add_edge(self, edge: Edge) -> None:
+        # Self-references (recursion, a class referring to itself) are not
+        # evidence of external use — drop them at insertion time.
+        if edge.src == edge.dst:
+            return
+        self.edges.append(edge)
+        self.g.add_edge(edge.src, edge.dst, edge=edge)
+
+    def inbound(self, symbol_id: str) -> list[Edge]:
+        """Inbound edges, excluding edges whose source is nested inside the
+        target (a method referencing its own class proves nothing)."""
+        if symbol_id not in self.g:
+            return []
+        result = []
+        for src, _dst, data in self.g.in_edges(symbol_id, data=True):
+            if src.startswith(symbol_id + ".") or src.startswith(symbol_id + ":"):
+                continue
+            result.append(data["edge"])
+        return result
+
+    def inbound_split(self, symbol_id: str) -> tuple[list[Edge], list[Edge]]:
+        strong, weak = [], []
+        for e in self.inbound(symbol_id):
+            (strong if e.strength is EdgeStrength.STRONG else weak).append(e)
+        return strong, weak

codetruth/core/models.py

@@ -0,0 +1,193 @@
+"""Core data models shared by every layer and every language plugin."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class SymbolType(str, Enum):
+    MODULE = "module"
+    CLASS = "class"
+    FUNCTION = "function"
+    METHOD = "method"
+    VARIABLE = "variable"
+
+
+class EdgeKind(str, Enum):
+    CALL = "call"
+    IMPORT = "import"
+    INHERIT = "inherit"
+    ATTRIBUTE = "attribute"
+    REFERENCE = "reference"
+    STRING_REF = "string_ref"
+    DYNAMIC = "dynamic"
+
+
+class EdgeStrength(str, Enum):
+    STRONG = "strong"
+    WEAK = "weak"
+
+
+class Status(str, Enum):
+    SAFE_TO_DELETE = "safe_to_delete"
+    LIKELY_DEAD = "likely_dead"
+    UNCERTAIN_DYNAMIC_RISK = "uncertain_dynamic_risk"
+    DEFINITELY_USED = "definitely_used"
+
+
+class RiskLevel(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class Action(str, Enum):
+    DELETE = "delete"
+    REVIEW_REQUIRED = "review_required"
+    KEEP = "keep"
+
+
+class MarkerKind(str, Enum):
+    # Proof of use: framework entry point, dunder, test, runtime observation.
+    ENTRYPOINT = "entrypoint"
+    RUNTIME_USED = "runtime_used"
+    # Not proof of use, but a reason deletion is riskier than the graph shows.
+    CAUTION = "caution"
+    # Module contains non-literal reflection/eval — nothing in it is provably dead.
+    DYNAMIC_MODULE = "dynamic_module"
+    # Runtime tracking registered the symbol and observed zero calls.
+    RUNTIME_ZERO = "runtime_zero"
+
+
+@dataclass
+class Symbol:
+    """One node in the graph. id format: 'pkg.mod:Qual.name' ('pkg.mod' for modules)."""
+    id: str
+    name: str
+    qualname: str
+    type: SymbolType
+    file: str          # repo-relative path, forward slashes
+    line: int
+    end_line: int
+    module: str        # dotted module name the symbol lives in
+    parent: Optional[str] = None   # enclosing symbol id (module id for top-level)
+    exported: bool = False         # in __all__, or public top-level when no __all__
+    is_public: bool = False        # top-level or method, name has no leading underscore
+    is_test: bool = False          # defined in a test file
+    decorators: list[str] = field(default_factory=list)
+    bases: list[str] = field(default_factory=list)  # dotted base names (classes only)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id, "name": self.name, "qualname": self.qualname,
+            "type": self.type.value, "file": self.file, "line": self.line,
+            "end_line": self.end_line, "module": self.module, "parent": self.parent,
+            "exported": self.exported, "is_public": self.is_public,
+            "is_test": self.is_test, "decorators": self.decorators, "bases": self.bases,
+        }
+
+
+@dataclass
+class Edge:
+    """A directed usage edge: src uses dst. Strength is assigned at creation time."""
+    src: str           # symbol id, or pseudo-node like 'file:config/app.yaml'
+    dst: str           # symbol id
+    kind: EdgeKind
+    strength: EdgeStrength
+    file: str
+    line: int
+    detail: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "src": self.src, "dst": self.dst, "kind": self.kind.value,
+            "strength": self.strength.value, "file": self.file,
+            "line": self.line, "detail": self.detail,
+        }
+
+    def describe(self) -> str:
+        base = f"{self.kind.value} from {self.src} ({self.file}:{self.line})"
+        return f"{base} — {self.detail}" if self.detail else base
+
+
+@dataclass
+class Marker:
+    """A rule-produced fact about a symbol that isn't a graph edge."""
+    symbol: str
+    kind: MarkerKind
+    reason: str
+    rule: str = ""
+    file: str = ""
+    line: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "symbol": self.symbol, "kind": self.kind.value, "reason": self.reason,
+            "rule": self.rule, "file": self.file, "line": self.line,
+        }
+
+
+@dataclass
+class EvidenceRecord:
+    """Layer 4 output: the structured record an agent reads before deciding."""
+    symbol: str
+    name: str
+    type: SymbolType
+    file: str
+    line: int
+    status: Status
+    risk_level: RiskLevel
+    recommended_action: Action
+    evidence_for_deletion: list[str] = field(default_factory=list)
+    evidence_against_deletion: list[str] = field(default_factory=list)
+    inbound_strong: int = 0
+    inbound_weak: int = 0
+    exported: bool = False
+    # Deterministic ordering heuristic for the review queue, in [0, 1]:
+    # higher = weaker evidence of use = review/delete first. NOT a calibrated
+    # probability (see PLAN.md §4) — it exists only to rank candidates within
+    # a status so the strongest deletion targets surface first.
+    rank_score: float = 0.0
+    # Advisory description of what a deletion would involve (exact span,
+    # orphaned imports, __all__ entry). Attached to safe_to_delete records;
+    # never applied by the tool.
+    deletion_plan: Optional[dict] = None
+    # Ids of the unreachable clump this symbol belongs to (itself included)
+    # when it is part of a dead cluster — reviewable/deletable as a group.
+    cluster: Optional[list[str]] = None
+
+    def to_dict(self) -> dict:
+        d = {
+            "symbol": self.symbol, "name": self.name, "type": self.type.value,
+            "file": self.file, "line": self.line, "status": self.status.value,
+            "risk_level": self.risk_level.value,
+            "recommended_action": self.recommended_action.value,
+            "rank_score": self.rank_score,
+            "evidence_for_deletion": self.evidence_for_deletion,
+            "evidence_against_deletion": self.evidence_against_deletion,
+            "inbound_strong": self.inbound_strong, "inbound_weak": self.inbound_weak,
+            "exported": self.exported,
+        }
+        if self.deletion_plan is not None:
+            d["deletion_plan"] = self.deletion_plan
+        if self.cluster:
+            d["cluster"] = self.cluster
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "EvidenceRecord":
+        return cls(
+            symbol=d["symbol"], name=d["name"], type=SymbolType(d["type"]),
+            file=d["file"], line=d["line"], status=Status(d["status"]),
+            risk_level=RiskLevel(d["risk_level"]),
+            recommended_action=Action(d["recommended_action"]),
+            evidence_for_deletion=list(d.get("evidence_for_deletion", [])),
+            evidence_against_deletion=list(d.get("evidence_against_deletion", [])),
+            inbound_strong=d.get("inbound_strong", 0),
+            inbound_weak=d.get("inbound_weak", 0),
+            exported=d.get("exported", False),
+            rank_score=d.get("rank_score", 0.0),
+            deletion_plan=d.get("deletion_plan"),
+            cluster=d.get("cluster"),
+        )

codetruth/core/plugin.py

@@ -0,0 +1,88 @@
+"""Language-plugin and rule interfaces. The core engine only talks to these."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .graph import CodeGraph
+from .models import Edge, Marker, Symbol
+
+if TYPE_CHECKING:
+    pass
+
+
+@dataclass
+class RuleContext:
+    """Everything a Layer 3 rule may inspect, plus sinks for its findings."""
+    repo_path: Path
+    modules: list[Any]           # language-specific ModuleInfo objects
+    index: Any                   # language-specific symbol index
+    graph: CodeGraph
+    markers: list[Marker]
+    config_files: list[Path] = field(default_factory=list)
+
+    def add_edge(self, edge: Edge) -> None:
+        self.graph.add_edge(edge)
+
+    def add_marker(self, marker: Marker) -> None:
+        self.markers.append(marker)
+
+
+class Rule(ABC):
+    """One Layer 3 pattern detector. Emits weak edges and/or markers."""
+    id: str = "rule"
+
+    @abstractmethod
+    def apply(self, ctx: RuleContext) -> None: ...
+
+
+class LanguagePlugin(ABC):
+    """A language implementation: extraction (L1), edges (L2), rules (L3)."""
+    name: str = ""
+
+    @abstractmethod
+    def extract(self, repo_path: Path,
+                ignores: tuple[str, ...] = ()) -> tuple[list[Any], list[str]]:
+        """Return (modules, warnings). Each module carries its symbols.
+        `ignores` are user-configured path globs to skip entirely."""
+
+    @abstractmethod
+    def build_index(self, modules: list[Any]) -> Any: ...
+
+    @abstractmethod
+    def build_edges(self, repo_path: Path, modules: list[Any], index: Any,
+                    graph: CodeGraph, markers: list[Marker]) -> None: ...
+
+    @abstractmethod
+    def rules(self) -> list[Rule]: ...
+
+    @abstractmethod
+    def symbols(self, modules: list[Any]) -> list[Symbol]: ...
+
+
+_PLUGINS: dict[str, LanguagePlugin] = {}
+
+
+def register_plugin(plugin: LanguagePlugin) -> None:
+    _PLUGINS[plugin.name] = plugin
+
+
+def get_plugin(name: str) -> LanguagePlugin:
+    if name not in _PLUGINS:
+        # Lazy-load built-in plugins on first request.
+        if name == "python":
+            from ..languages.python.plugin import PythonPlugin
+            register_plugin(PythonPlugin())
+        elif name in ("javascript", "typescript", "js", "ts"):
+            from ..languages.javascript.plugin import JavaScriptPlugin
+            plugin = JavaScriptPlugin()
+            for alias in ("javascript", "typescript", "js", "ts"):
+                _PLUGINS[alias] = plugin
+        elif name == "go":
+            raise NotImplementedError(
+                "The 'go' plugin is a stub — python and javascript ship today.")
+        else:
+            raise ValueError(f"Unknown language plugin: {name!r}")
+    return _PLUGINS[name]