codmap 0.0.3__py3-none-any.whl

codemap/integrations/registry.py

@@ -0,0 +1,69 @@
+"""Integration registry — register tools, resolve a capability to a live one.
+
+DESIGN §13.1. The registry is where the licensing policy is machine-enforced: an
+**adapter** (which absorbs the tool's output into our artifact) must be permissive-
+licensed; a **router** (which only forwards) may be any license. Registration of a
+non-permissive adapter is a programming error and raises.
+
+Resolution is **capability-first** (the chosen UX, DESIGN §13.1 decision): a caller
+asks for a capability ("semantic-search", "resolve-into-deps"), and the registry
+returns an integration that (a) provides it, (b) is opted-in via config, and (c) is
+actually installed. The concrete tool stays hidden behind the capability.
+"""
+
+from __future__ import annotations
+
+from .base import Integration, IntegrationMode, is_permissive
+from .gate import IntegrationConfig, load_config
+
+_REGISTRY: dict[str, Integration] = {}
+
+
+def register(integration: Integration) -> Integration:
+    """Register an integration, enforcing the DESIGN §13.1 licensing policy.
+
+    Raises ``ValueError`` if an adapter is not permissive-licensed (adapters absorb
+    output into our artifact → MIT/Apache only; a non-commercial tool can only be a
+    router). Idempotent-friendly: re-registering the same name overwrites.
+    """
+    if (integration.mode is IntegrationMode.ADAPTER
+            and not is_permissive(integration.license)):
+        raise ValueError(
+            f"adapter '{integration.name}' has non-permissive license "
+            f"{integration.license!r}: a tool whose output we absorb must be "
+            f"MIT/Apache-class (DESIGN §13.1); use router mode instead."
+        )
+    _REGISTRY[integration.name] = integration
+    return integration
+
+
+def unregister(name: str) -> None:
+    _REGISTRY.pop(name, None)
+
+
+def get(name: str) -> Integration | None:
+    return _REGISTRY.get(name)
+
+
+def all_integrations() -> list[Integration]:
+    return [_REGISTRY[n] for n in sorted(_REGISTRY)]
+
+
+def resolve(capability: str, *, config: IntegrationConfig | None = None,
+            root: str = ".", mode: IntegrationMode | None = None) -> Integration | None:
+    """Return an enabled + installed integration providing ``capability``, or None.
+
+    Capability-first dispatch: the tool is picked for the caller. Requires all three
+    gates — provides the capability, opted-in (``config.enabled``), and
+    ``is_available()`` — so the core degrades cleanly when nothing satisfies them.
+    ``mode`` narrows to one coupling mode (e.g. ADAPTER when the caller must enrich
+    the output, not just forward it). Deterministic tie-break by name.
+    """
+    cfg = config if config is not None else load_config(root)
+    for integ in all_integrations():  # sorted by name → deterministic pick
+        if (capability in integ.capabilities
+                and (mode is None or integ.mode is mode)
+                and cfg.is_enabled(integ.name)
+                and integ.is_available()):
+            return integ
+    return None

codemap/integrations/transport.py

@@ -0,0 +1,46 @@
+"""Transport helpers for adapters/routers that call an external tool (DESIGN §13).
+
+Modes 3–4 call a **user-installed** tool as a subprocess (or MCP client) — codemap
+bundles nothing (DESIGN §13.1 п.1: calling ≠ distributing). These helpers keep that
+call uniform: locate the binary, run it, parse JSON. Failures return None rather
+than raising, so a flaky external tool degrades to "capability unavailable", never a
+crash of the core.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from typing import Any
+
+
+def which(binary: str) -> str | None:
+    """Absolute path to a user-installed binary on PATH, or None."""
+    return shutil.which(binary)
+
+
+def run_json(cmd: list[str], *, timeout: float = 120.0,
+             input_text: str | None = None, cwd: str | None = None) -> Any | None:
+    """Run ``cmd``, parse stdout as JSON, return it (or None on any failure).
+
+    A non-zero exit, timeout, missing binary, or non-JSON stdout all yield None —
+    the caller treats that as "the external tool couldn't answer" and falls back to
+    the deterministic core. ``cwd`` runs the tool in a specific directory (some
+    tools, e.g. a per-repo index, key off the working dir).
+    """
+    if not cmd or which(cmd[0]) is None:
+        return None
+    try:
+        proc = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=timeout,
+            input=input_text, cwd=cwd,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if proc.returncode != 0:
+        return None
+    try:
+        return json.loads(proc.stdout)
+    except (ValueError, TypeError):
+        return None

codemap/model.py

@@ -0,0 +1,178 @@
+"""Neutral code-graph model (DESIGN §2).
+
+Language-neutral core: a node is ``kind + attrs``; edges are typed. Python-isms
+live in ``extras`` provided by the extractor, never baked into the core. The JSON
+form (DESIGN §2.2) is the canonical store: deterministic (sorted, no timestamps)
+so it diffs cleanly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+# Bump on any change to the JSON schema (invariant, like bquant's CACHE_SCHEMA_VERSION).
+# 0.2: M1.5 — inherits / decorated_by edges; attribute annotations, is_dataclass and
+#      dynamic-registration keys in node extras (closes gap-doc CM-01/02/06/07/08).
+# 0.3: M4 — best-effort `calls` edges (resolution-labeled); per-function extras
+#      `calls` coverage, `control` skeleton, structured `params`/`returns` for
+#      type-flow (partially closes CM-03/09/10/11/12).
+# 0.4: M6 — repo scope / impact (multi-root). Nodes carry provenance
+#      (`extras.root`: core | tests | examples | research | scripts | docs);
+#      `doc` node kind + `references` edge (consumer/doc → core symbol) let
+#      blast-radius reach beyond the package (closes gap-doc F1).
+# 0.5: M7 — registry-aware call bridging. `calls` edges gain resolution
+#      `registry` (literal key → exact impl) and `registry-candidate` (factory/
+#      getter → all family impls, honest over-approximation) so the call chain
+#      reconnects at factory/registry dispatch seams (closes gap-doc F5).
+# 0.6: M9 — registry-family Protocol links. `implements` edge (concrete impl →
+#      the Protocol it structurally satisfies, matched via the registry family)
+#      makes the family queryable and diagrammable though it's never inherited
+#      (closes gap-doc F4).
+# 0.7: M11 — call-site argument contract. `calls` edges carry `callsites`
+#      (how many call expressions collapsed into this edge) and the observed
+#      argument shape (`posargs` / `kwargs` / `splat`) so signature-change
+#      reasoning is possible (closes gap-doc F7).
+# 0.8: M12 — string-key dataflow. `column` node per string subscript key
+#      (`column:macd_hist`) with `writes`/`reads` edges (function → column) so
+#      "who produces/consumes this DataFrame column" is queryable (closes
+#      gap-doc F6). Over-set of columns (dict keys land here too — honest).
+# 0.9: M14 — dataflow access-form (soundness/F15). `column` node carries
+#      `extras.subscripted` (bool — key was ever accessed as `x['k']`, not only a
+#      dict-literal payload key); `reads`/`writes` edges carry `extras.access`
+#      (`subscript` | `dict-literal`). B1 dogfood found 71% of column nodes were
+#      dict-literal-only payload keys (result dicts, config, rcParams) — the
+#      `subscripted` flag lets aggregates surface the ~29% real column-like set
+#      while per-key queries and the F6 producer edge stay intact.
+# 0.10: R1-C4 — per-function complexity metrics. `extras.complexity` on function
+#      nodes carries `cc` (McCabe cyclomatic), `volume` (Halstead), `sloc` (physical
+#      span) and `mi` (Maintainability Index, 0–100). Computed in the behavioral AST
+#      pass (source-only, stdlib-only, deterministic); Query.hotspots blends them with
+#      structural coupling so "complex by McCabe" ranks alongside "big by connectivity".
+# 0.11: R1-C20 — attribute-access edges. `accesses` edge (function → the `attribute`
+#      node it reads/writes), `extras.access` (`read` | `write`) + `extras.resolution`
+#      (`self` | `class` | `construct` | `deep`). Emitted by the `extract/attrflow.py`
+#      pass (fast `ast` for self./ClassName./construction-kwargs, deep `jedi` for typed
+#      `obj.field`). Wired into impact/references_to so a field's blast-radius is real;
+#      an attribute with no modelled accessor reports risk `unknown` (lower bound), never
+#      `none` (closes the issue #1 honesty gap — see gaps/attribute_impact_gap_2026-08-22).
+# 0.12: R1-C25 — build provenance. New top-level ``provenance`` block: tool identity
+#       (name/version/commit — commit absent, never guessed, when installed from a
+#       wheel), ``tier`` (fast|deep), input ``scope_id`` (M19.A) and the source vcs
+#       commit + dirty flag. **Timestamp-free and path-free by construction** — the
+#       clock and the absolute `cwd` stay in the `*.meta.json` sidecar, so the graph
+#       remains byte-identical across two builds of a frozen tree and safe to publish.
+#       ``codemap_schema`` is now *read* on load: a mismatch raises a diagnostic instead
+#       of being silently accepted (gaps/graph_provenance_2026-08-25 — the same tree
+#       built four commits apart gave 30 vs 38 edges under one declared schema).
+SCHEMA_VERSION = "0.12"
+
+# Closed vocabulary of edge types (R1-C7). Node ``kind`` is deliberately an OPEN set
+# (DESIGN §2 — new entity kinds may appear), but edges are TYPED: every relationship
+# codemap emits is one of these, each with a fixed meaning. This is the machine-
+# checkable contract — a new relationship must be added here (and documented) rather
+# than emitted silently; ``tests/test_r1c7_edge_vocab.py`` fails if a graph carries a
+# type not in this set (or if a declared type stops appearing on the dogfood target).
+EDGE_TYPES = frozenset({
+    "contains",       # parent → member (module→class/func, class→method)
+    "imports",        # module → module it imports (internal, resolved to canonical)
+    "export",         # package → symbol it re-exports (extras.public marks __all__)
+    "inherits",       # class → base class (extras.external for out-of-package bases)
+    "decorated_by",   # symbol → the decorator applied to it
+    "calls",          # caller function → callee (extras.resolution: how it resolved)
+    "references",     # consumer/doc/dispatch site → the core symbol it names
+    "implements",     # concrete class → the Protocol it structurally satisfies (M9)
+    "reads",          # function → string-keyed column it reads (extras.access)
+    "writes",         # function → string-keyed column it writes (extras.access)
+    "accesses",       # function → attribute node it reads/writes (extras.access, R1-C20)
+})
+
+
+@dataclass
+class Node:
+    """A code entity. ``id`` is its canonical definition path (DESIGN §2.1)."""
+
+    id: str
+    kind: str  # module | class | function | attribute | doc | column (open set — DESIGN §2)
+    file: str | None = None
+    lineno: int | None = None
+    endlineno: int | None = None
+    signature: str | None = None
+    docstring: str | None = None
+    visibility: str = "public"  # public | private
+    decorators: list[str] = field(default_factory=list)
+    is_deprecated: bool = False
+    extras: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Edge:
+    """A typed relationship between two nodes (by id)."""
+
+    type: str  # one of EDGE_TYPES (closed vocabulary, R1-C7): contains | imports |
+    #            export | inherits | decorated_by | calls | references | implements |
+    #            reads | writes | accesses  (§2)
+    source: str
+    target: str
+    extras: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Graph:
+    """The code graph: nodes + edges over a single target package."""
+
+    target: str
+    nodes: dict[str, Node] = field(default_factory=dict)
+    edges: list[Edge] = field(default_factory=list)
+    #: R1-C25 — what produced this graph (see ``codemap/provenance.py``). Serialized.
+    provenance: dict[str, Any] = field(default_factory=dict)
+    #: The ``codemap_schema`` this graph was *loaded* from, or None for a fresh build.
+    #: Not serialized and not part of equality — it describes the file, not the graph.
+    loaded_schema: str | None = field(default=None, compare=False, repr=False)
+
+    def add_node(self, node: Node) -> None:
+        self.nodes[node.id] = node
+
+    def add_edge(self, edge: Edge) -> None:
+        self.edges.append(edge)
+
+    # -- canonical serialization (deterministic — DESIGN §2.2) --------------
+
+    def to_dict(self) -> dict[str, Any]:
+        import json as _json
+        nodes = [asdict(self.nodes[nid]) for nid in sorted(self.nodes)]
+        # Sort by the full edge content, not just (type, source, target): two edges
+        # can share that triple but differ in `extras` (e.g. a behavioral `calls` and
+        # a registry-dispatch `calls`). Including a stable render of `extras` in the
+        # key makes the order **insertion-independent**, so an incremental rebuild
+        # (R1-C9), which splices edges in a different order, serializes identically to
+        # a full build.
+        edges = sorted(
+            (asdict(e) for e in self.edges),
+            key=lambda e: (e["type"], e["source"], e["target"],
+                           _json.dumps(e["extras"], sort_keys=True, ensure_ascii=False)),
+        )
+        return {
+            "codemap_schema": SCHEMA_VERSION,
+            "target": self.target,
+            # R1-C25: always emitted, even empty — a stable shape diffs cleanly, and an
+            # empty block is itself the honest statement "this build recorded nothing".
+            "provenance": self.provenance,
+            "nodes": nodes,
+            "edges": edges,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Graph":
+        g = cls(target=data["target"])
+        g.provenance = data.get("provenance") or {}
+        # Read the schema the file declares (R1-C25/D3). It used to be written and never
+        # read, so a graph predating an extraction change was consumed without a word.
+        # "" (not None) when the file declared nothing: None must keep meaning
+        # "this graph was never loaded from a file", so a fresh build stays quiet.
+        g.loaded_schema = data.get("codemap_schema", "")
+        for n in data["nodes"]:
+            g.add_node(Node(**n))
+        for e in data["edges"]:
+            g.add_edge(Edge(**e))
+        return g

codemap/provenance.py

@@ -0,0 +1,248 @@
+"""Build provenance — what produced this graph, and from what (R1-C25).
+
+``graph.json`` is a claim: *this is the shape of that source tree, as read by this
+tool*. Until now it recorded the claim and dropped both qualifiers — four top-level
+keys, no tool identity, no input identity, and a ``codemap_schema`` that was written
+and never read. One frozen tree built by two codemap versions four commits apart gave
+30 edges vs 38 and 12 vs 7 ``high`` dead-code verdicts, with **both files declaring
+schema 0.11** — correctly, because only open ``extras`` had changed. Provenance is not
+schema (gaps/graph_provenance_2026-08-25.md).
+
+Two rules shape everything here:
+
+- **No clock.** The canonical graph is timestamp-free so two builds of a frozen tree
+  are byte-identical; a timestamp would destroy exactly the property this block exists
+  to make checkable. Wall-clock stays in the ``*.meta.json`` sidecar.
+- **No absolute paths.** The graph is the half that travels — into a ticket, a sibling
+  repo, an agent's context. A personal path in it is a leak (AGENTS.md), so paths here
+  are repo-relative or a bare name, never a location.
+
+Design: ``docs/design/graph_provenance.md`` (D1–D7).
+"""
+
+from __future__ import annotations
+
+import subprocess
+from functools import lru_cache
+from pathlib import Path
+
+#: What the tool calls itself — the command, the import, the repository. This is the
+#: identity recorded in every graph, so it stays put: changing it would make every
+#: existing 0.12 graph incomparable with a new one over a packaging detail.
+TOOL_NAME = "codemap"
+
+#: What the tool is *distributed* as. Different from `TOOL_NAME` because `codemap` was
+#: already taken on PyPI. Only the version lookup uses it; if these are ever confused,
+#: `version()` raises PackageNotFoundError and the version silently vanishes from
+#: provenance — the failure this split exists to prevent (the wheel CI job asserts it).
+DIST_NAME = "codmap"
+
+#: Schema comparison outcomes (D3).
+MATCH, OLDER, NEWER, UNKNOWN = "match", "older", "newer", "unknown"
+
+
+# -- tool identity (D2) -------------------------------------------------------
+
+@lru_cache(maxsize=1)
+def _tool_version() -> str | None:
+    from importlib.metadata import PackageNotFoundError, version
+    try:
+        return version(DIST_NAME)
+    except (PackageNotFoundError, ImportError):
+        return None
+
+
+@lru_cache(maxsize=8)
+def _commit_of(root: Path) -> str | None:
+    """Short HEAD of the checkout at ``root``, or None when it is not one."""
+    if not (Path(root) / ".git").exists():
+        return None
+    try:
+        out = subprocess.run(("git", "-C", str(root), "rev-parse", "--short", "HEAD"),
+                             capture_output=True, text=True, check=True)
+    except (OSError, subprocess.CalledProcessError):
+        return None
+    return out.stdout.strip() or None
+
+
+def _tool_commit() -> str | None:
+    """Short commit of codemap's **own** checkout, when it runs from a source tree.
+
+    Absent — not ``"unknown"``, not a guess — when installed from a wheel. The package
+    version alone is not an identity: every graph in the R1-C20…R1-C22 series was built
+    by version ``0.0.2``, which is why this field exists at all.
+    """
+    return _commit_of(Path(__file__).resolve().parent.parent)
+
+
+@lru_cache(maxsize=8)
+def _is_dirty(root: Path) -> bool | None:
+    """Does the checkout at ``root`` have uncommitted changes? None when not a checkout."""
+    if not (Path(root) / ".git").exists():
+        return None
+    try:
+        out = subprocess.run(("git", "-C", str(root), "status", "--porcelain"),
+                             capture_output=True, text=True, check=True)
+    except (OSError, subprocess.CalledProcessError):
+        return None
+    return bool(out.stdout.strip())
+
+
+def tool_identity() -> dict:
+    """``{name, version?, commit?, dirty?}`` — only the fields we actually know.
+
+    ``dirty`` mirrors what ``source`` records about the target, and for the same reason:
+    two builds from the same commit with different working trees are two different tools.
+    Measured the hard way — comparing a worktree at HEAD against a dirty checkout of the
+    same HEAD, both reported the identical commit and were plainly not the same builder.
+    """
+    root = Path(__file__).resolve().parent.parent
+    ident: dict = {"name": TOOL_NAME}
+    version, commit, dirty = _tool_version(), _tool_commit(), _is_dirty(root)
+    if version:
+        ident["version"] = version
+    if commit:
+        ident["commit"] = commit
+    if dirty is not None:
+        ident["dirty"] = dirty
+    return ident
+
+
+# -- the block ----------------------------------------------------------------
+
+def canonicalize(value):
+    """Sort every dict key, recursively — the block must serialize identically twice."""
+    if isinstance(value, dict):
+        return {k: canonicalize(value[k]) for k in sorted(value)}
+    if isinstance(value, list):
+        return [canonicalize(v) for v in value]
+    return value
+
+
+def relative_root(root: str | Path | None, path: str | Path) -> str:
+    """``path`` relative to ``root``, or its bare name — never an absolute path (D5)."""
+    p = Path(path)
+    if root is not None:
+        try:
+            return Path(p).resolve().relative_to(Path(root).resolve()).as_posix() or "."
+        except (ValueError, OSError):
+            pass
+    return p.name or "."
+
+
+def build_provenance(*, tier: str, scope: dict | None = None,
+                     roots: dict | None = None, inputs: dict | None = None) -> dict:
+    """Assemble the ``provenance`` block. Deterministic; no clock, no absolute path."""
+    prov: dict = {"tool": tool_identity(), "tier": tier}
+    if inputs:
+        # R1-C23/D2: what the extractor read, and what it could not. Belongs with the
+        # identity rather than in the sidecar — a consumer holding only the graph is
+        # exactly the one who must be told the tree was read incompletely.
+        prov["inputs"] = inputs
+    if scope:
+        if scope.get("scope_id"):
+            prov["scope_id"] = scope["scope_id"]
+        git = scope.get("git") or {}
+        if git.get("mode") == "git" and git.get("commit"):
+            source = {"vcs": "git", "commit": git["commit"][:12],
+                      "dirty": bool(git.get("dirty"))}
+            if git.get("ref"):
+                source["ref"] = git["ref"]
+            prov["source"] = source
+    if roots:
+        prov["roots"] = roots
+    block = canonicalize(prov)
+    leaked = absolute_paths(block)
+    if leaked:
+        raise ValueError(f"provenance must stay path-free, got {leaked[0]!r}")
+    return block
+
+
+def absolute_paths(value, _path=()) -> list[str]:
+    """Every string in ``value`` that looks like an absolute filesystem path (D5)."""
+    found: list[str] = []
+    if isinstance(value, dict):
+        for k in sorted(value):
+            found += absolute_paths(value[k], _path + (k,))
+    elif isinstance(value, list):
+        for i, v in enumerate(value):
+            found += absolute_paths(v, _path + (str(i),))
+    elif isinstance(value, str):
+        if value.startswith("/") or value.startswith("\\\\") or (
+                len(value) > 2 and value[1] == ":" and value[2] in "\\/"):
+            found.append(value)
+    return found
+
+
+# -- schema comparison (D3) ---------------------------------------------------
+
+def _parts(v: str) -> tuple[int, ...] | None:
+    try:
+        return tuple(int(p) for p in str(v).split("."))
+    except (TypeError, ValueError):
+        return None
+
+
+def schema_status(loaded: str | None, running: str) -> str:
+    """``match`` | ``older`` | ``newer`` | ``unknown`` — how a stored graph compares."""
+    if loaded is None:
+        return UNKNOWN
+    if loaded == running:
+        return MATCH
+    a, b = _parts(loaded), _parts(running)
+    if a is None or b is None:
+        return UNKNOWN
+    return OLDER if a < b else NEWER
+
+
+# -- comparability of two graphs (D4) -----------------------------------------
+
+def _tool_str(prov: dict) -> str:
+    t = (prov or {}).get("tool") or {}
+    bits = [t.get("name") or "?"]
+    if t.get("version"):
+        bits.append(t["version"])
+    if t.get("commit"):
+        bits.append(f"@{t['commit']}")
+    return " ".join(bits)
+
+
+def describe(prov: dict | None) -> str:
+    """One-line human rendering of a provenance block (``unrecorded`` when absent)."""
+    if not prov:
+        return "unrecorded (built before schema 0.12)"
+    bits = [_tool_str(prov), f"tier={prov.get('tier', '?')}"]
+    src = prov.get("source") or {}
+    if src.get("commit"):
+        bits.append(f"source={src['commit']}{'+dirty' if src.get('dirty') else ''}")
+    if prov.get("scope_id"):
+        bits.append(f"scope={prov['scope_id'][7:19]}")
+    return ", ".join(bits)
+
+
+def comparability(old: dict | None, new: dict | None) -> dict:
+    """Are two graphs a before/after of the *code*, or of the *tool*? (D4)
+
+    Never a refusal — comparing across an upgrade is a legitimate thing to want. What
+    was missing is being told: on the R1-C25 evidence pair, ``diff`` said "no breaking
+    changes" (true, and useless) about two graphs that disagreed on which functions
+    were dead.
+    """
+    differences: list[str] = []
+    if not old or not new:
+        differences.append("one of the graphs records no provenance "
+                           "(built before schema 0.12) — the pair cannot be verified")
+    else:
+        if _tool_str(old) != _tool_str(new):
+            differences.append(f"different tool: {_tool_str(old)} → {_tool_str(new)}")
+        if old.get("tier") != new.get("tier"):
+            differences.append(f"different tier: {old.get('tier')} → {new.get('tier')}")
+        old_roots, new_roots = old.get("roots"), new.get("roots")
+        if old_roots != new_roots:
+            differences.append(f"different scope roots: {old_roots} → {new_roots}")
+    return {
+        "comparable": not differences,
+        "differences": differences,
+        "old": describe(old),
+        "new": describe(new),
+    }