codmap 0.0.3__py3-none-any.whl

codemap/serve/audit.py

@@ -0,0 +1,176 @@
+"""Audit reports — consumer C (DESIGN §1-C): dependencies/cycles, dead code."""
+
+from __future__ import annotations
+
+from codemap.diagnostics import render_lines
+from codemap.query import Query
+from codemap.tomlio import read_toml
+
+
+def render_dependencies(query: Query) -> str:
+    g = query.import_graph
+    lines = [f"# Module dependencies — `{query.graph.target}`", ""]
+    lines.append(f"_{g.number_of_nodes()} modules, {g.number_of_edges()} import edges._")
+    lines.append("")
+    # R1-C21: name what the graph cannot support before listing conclusions drawn from
+    # it; each check supplies its own consequence, or none (issue #8).
+    lines.extend(render_lines(query.graph))
+
+    cycles = query.import_cycles()
+    lines.append(f"## Import cycles: {len(cycles)}")
+    lines.append("")
+    if cycles:
+        for cyc in sorted(cycles, key=lambda c: (len(c), c)):
+            lines.append(f"- {' → '.join(cyc)} → {cyc[0]}")
+    else:
+        lines.append("_none — import graph is acyclic._")
+    lines.append("")
+
+    lines.append("## Most-depended-on modules (top 15)")
+    lines.append("")
+    ranked = sorted(g.nodes, key=lambda m: g.in_degree(m), reverse=True)
+    for mid in ranked[:15]:
+        deg = g.in_degree(mid)
+        if deg == 0:
+            break
+        lines.append(f"- `{mid}` — imported by {deg}")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def load_dead_code_whitelist(root: str | None) -> tuple[tuple[str, ...], str | None]:
+    """Read ``[dead_code].whitelist`` (exact ids / globs) from codemap.toml under ``root``.
+
+    Returns ``(whitelist, error)``. Empty on an absent file — and *also* empty on a file
+    that would not parse, because a bad whitelist must never break a report — but the two
+    are no longer the same answer (R1-C27): the reason comes back so the report can say
+    that nothing was suppressed because nothing could be read.
+    """
+    from pathlib import Path
+    if not root:
+        return (), None
+    data, error = read_toml(Path(root) / "codemap.toml")
+    if error:
+        return (), error
+    return tuple(data.get("dead_code", {}).get("whitelist", []) or []), None
+
+
+def render_dead_code(query: Query, *, whitelist: tuple[str, ...] = (),
+                     min_confidence: str | None = None,
+                     whitelist_error: str | None = None) -> str:
+    by_root = query.orphan_modules_by_root()
+    core_orphans = by_root.get("core", [])
+    consumer = {r: v for r, v in by_root.items() if r != "core"}
+    dead = query.dead_code(whitelist=whitelist, min_confidence=min_confidence)
+    lines = [f"# Dead-code candidates — `{query.graph.target}`", ""]
+    lines.append(
+        "_Static heuristics only — dynamic imports, CLI entry points, test targets "
+        "and partial call resolution (~1/4 of sites, gaps/ CM-09) are blind spots. "
+        "**Candidates, not proof.**_"
+    )
+    lines.append("")
+    # R1-C27: an unreadable codemap.toml suppresses nothing, and a list below that is
+    # longer than the user expects is otherwise indistinguishable from a whitelist that
+    # did not match. Say it before the findings, like every other blind spot here.
+    if whitelist_error:
+        lines.append(f"> ⚠️ **Whitelist not read — nothing is suppressed.** {whitelist_error}")
+        lines.append("")
+    # R1-C21: name what the graph cannot support before listing conclusions drawn from
+    # it; each check supplies its own consequence, or none (issue #8).
+    lines.extend(render_lines(query.graph))
+    # F8: on a repo-scoped graph, consumer roots are orphan by nature (nobody
+    # imports an entrypoint). Only core orphans are candidate dead code.
+    lines.append(f"## Orphan modules — core (no incoming imports): {len(core_orphans)}")
+    lines.append("")
+    lines.extend([f"- `{mid}`" for mid in core_orphans] or ["_none._"])
+    if consumer:
+        total = sum(len(v) for v in consumer.values())
+        breakdown = ", ".join(f"{r} {len(v)}" for r, v in sorted(consumer.items()))
+        lines.append("")
+        lines.append(f"## Consumer entrypoints (orphan by nature, not dead code): {total}")
+        lines.append("")
+        lines.append(
+            f"_{breakdown} — tests/examples/scripts/research are never imported; "
+            "expected orphan. Excluded from dead-code candidates (F8)._"
+        )
+    # R1-C8: uncalled private functions, graded by confidence with a provenance reason.
+    lines.append("")
+    filt = f" (min-confidence: {min_confidence})" if min_confidence else ""
+    wl = f", {len(whitelist)} whitelisted pattern(s)" if whitelist else ""
+    lines.append(f"## Uncalled private functions: {len(dead)}{filt}{wl}")
+    lines.append("")
+    lines.append("_Private functions with no incoming resolved call, graded by how sure. "
+                 "**high** = no inbound edge or hook; **medium** = a decorator/registry "
+                 "may invoke it implicitly; **low** = something references it (likely alive)._")
+    lines.append("")
+    if not dead:
+        lines.append("_none._")
+    for level in ("high", "medium", "low"):
+        rows = [c for c in dead if c["confidence"] == level]
+        if not rows:
+            continue
+        lines.append(f"### {level} ({len(rows)})")
+        lines.append("")
+        for c in rows:
+            reason = "; ".join(c["reasons"])
+            lines.append(f"- `{c['id']}` — {reason}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_behavior(query: Query) -> str:
+    """Consumer A/C: honest call-graph coverage + type-flow spot-check (M4)."""
+    graph = query.graph
+    funcs = [n for n in graph.nodes.values() if n.kind == "function"]
+    with_cov = [n for n in funcs if "calls" in n.extras]
+    agg = {"out": 0, "resolved": 0, "external": 0, "unresolved": 0, "dynamic": 0}
+    for n in with_cov:
+        for k, v in n.extras["calls"].items():
+            agg[k] += v
+    total = agg["out"] or 1
+    lines = [f"# Behavioral layer — `{graph.target}`", ""]
+    lines.append(
+        "_Best-effort static call-graph (DESIGN §7). Calls on local variables need "
+        "type inference and are left unresolved on purpose (gaps/ CM-09/10)._"
+    )
+    lines.append("")
+    lines.append(f"## Call-site resolution ({agg['out']} sites in {len(with_cov)} functions)")
+    lines.append("")
+    lines.append(f"- resolved to internal edges: **{agg['resolved']}** ({100*agg['resolved']/total:.1f}%)")
+    lines.append(f"- external / builtin (flagged): {agg['external']} ({100*agg['external']/total:.1f}%)")
+    lines.append(f"- dynamic string-keyed: {agg['dynamic']} ({100*agg['dynamic']/total:.1f}%)")
+    lines.append(f"- unresolved (local vars — parked): {agg['unresolved']} ({100*agg['unresolved']/total:.1f}%)")
+    lines.append("")
+    by_res: dict[str, int] = {}
+    for e in graph.edges:
+        if e.type == "calls":
+            by_res[e.extras.get("resolution", "?")] = by_res.get(e.extras.get("resolution", "?"), 0) + 1
+    calls_edges = sum(by_res.values())
+    lines.append(f"_Emitted {calls_edges} `calls` edges (deduped caller→callee)._")
+    bridged = by_res.get("registry", 0) + by_res.get("registry-candidate", 0)
+    if bridged:
+        lines.append("")
+        lines.append(
+            f"## Registry-bridged dispatch (M7): {bridged} edges "
+            f"({by_res.get('registry', 0)} exact, {by_res.get('registry-candidate', 0)} candidate)"
+        )
+        lines.append("")
+        lines.append(
+            "_Factory/registry seams (`create_x`, `Registry.get`) bridged to registered "
+            "impls via the M1.5 table. **Candidate** edges are an over-approximation "
+            "(dispatches to one of a family) — real for navigation, not for exact counts._"
+        )
+
+    # -- complexity (R1-C4) -------------------------------------------------
+    scored = [(n, n.extras["complexity"]) for n in funcs if "complexity" in n.extras]
+    if scored:
+        ccs = [m["cc"] for _, m in scored]
+        avg_cc = sum(ccs) / len(ccs)
+        top = sorted(scored, key=lambda x: (-x[1]["cc"], x[0].id))[:10]
+        lines.append("")
+        lines.append(f"## Complexity ({len(scored)} functions, mean CC {avg_cc:.1f})")
+        lines.append("")
+        lines.append("_CC = McCabe cyclomatic; MI = Maintainability Index (0–100, higher is better)._")
+        lines.append("")
+        for n, m in top:
+            lines.append(f"- `{n.id}` — CC {m['cc']}, MI {m['mi']} ({m['sloc']} sloc)")
+    return "\n".join(lines).rstrip() + "\n"

codemap/serve/check.py

@@ -0,0 +1,80 @@
+"""Render the architecture-contract check (R1-C3) — structured + markdown.
+
+The gate itself lives in ``codemap.arch``; this is the presentation layer shared by
+the ``check`` CLI command and the ``check`` serve op. A clean run is deliberately
+quiet (one line); a failing run names every offending import edge so the fix is
+mechanical.
+"""
+
+from __future__ import annotations
+
+from codemap.arch import ArchitectureContract, Violation
+
+_EDGE_CAP = 25   # offending edges listed per rule before "+N more"
+
+
+def build_check(query, contract: ArchitectureContract, violations: list[Violation]) -> dict:
+    """Structured result: ok flag + violations with their concrete edges.
+
+    ``ok`` answers *may the pipeline proceed?*, so an unreadable ``codemap.toml`` makes it
+    false with no violations listed — there are none to list, because no rule ever ran
+    (R1-C27). ``contract_error`` says why. This is the JSON-first surface, so it carried
+    the same lie as the markdown one and is fixed in the same place.
+    """
+    return {
+        "target": query.graph.target,
+        "contract_empty": contract.is_empty(),
+        "contract_error": contract.error,
+        "ok": not violations and contract.error is None,
+        "violations": [
+            {"rule": v.rule, "summary": v.summary,
+             "edges": [list(e) for e in v.edges],
+             "modules": list(v.modules)}
+            for v in violations
+        ],
+    }
+
+
+def render_check(query, contract: ArchitectureContract, violations: list[Violation]) -> str:
+    target = query.graph.target
+    # R1-C27: ask `error` before `is_empty()`. A contract that would not parse used to be
+    # reported as a contract that does not exist, which is how one missing `]` turned a
+    # failing gate green. Nothing was enforced either way — but only one of the two is the
+    # user's decision, and the caller exits non-zero on this one.
+    if contract.error:
+        return (f"# Architecture check — `{target}`\n\n"
+                f"❌ **Contract not read — nothing was enforced.** {contract.error}\n\n"
+                "_Fix `codemap.toml` (or remove it) and run again. This is a failure, not "
+                "an absent contract: rules may exist that no rule-check ran against._\n")
+    if contract.is_empty():
+        return (f"# Architecture check — `{target}`\n\n"
+                "_No `[architecture]` contract found in codemap.toml — nothing to enforce._\n")
+    if not violations:
+        rules = []
+        if contract.layers:
+            rules.append(f"layered ({len(contract.layers)})")
+        if contract.independent:
+            rules.append(f"independent ({len(contract.independent)})")
+        if contract.forbidden:
+            rules.append(f"forbidden ({len(contract.forbidden)})")
+        if contract.no_cycles:
+            rules.append("no_cycles")
+        if contract.exhaustive:
+            rules.append("exhaustive")
+        return (f"# Architecture check — `{target}`\n\n"
+                f"✅ **Contract satisfied.** Rules enforced: {', '.join(rules)}.\n")
+
+    out = [f"# Architecture check — `{target}`", "",
+           f"❌ **{len(violations)} rule(s) broken.**", ""]
+    for v in violations:
+        out.append(f"## `{v.rule}` — {v.summary}")
+        out.append("")
+        if v.edges:
+            for u, w in v.edges[:_EDGE_CAP]:
+                out.append(f"- `{u}` → `{w}`")
+            if len(v.edges) > _EDGE_CAP:
+                out.append(f"- _… {len(v.edges) - _EDGE_CAP} more_")
+        for m in v.modules:
+            out.append(f"- {m}")
+        out.append("")
+    return "\n".join(out).rstrip() + "\n"

codemap/serve/ctags.py

@@ -0,0 +1,203 @@
+"""ctags export — codemap's graph as a universal-ctags ``tags`` file (R1-C2).
+
+The ``tags`` file is the lowest common denominator of code navigation: vim, Emacs,
+``readtags`` and countless editors do go-to-definition by binary-searching a sorted
+``tags`` file. codemap already knows every definition's name, file, line and scope,
+so emitting this format is near-free interop — the "floor" of capability codemap
+comfortably clears (research/00_landscape.md ranks ctags a *learn/emit* peer that
+survives on simplicity where heavier graph indexers churned).
+
+**Format.** Extended (exuberant/universal-ctags) format, one line per definition::
+
+    {name}<Tab>{file}<Tab>{address};"<Tab>{kind}<Tab>{ext fields}
+
+The address is a search pattern ``/^<source line>$/`` when the source is readable
+(robust to line drift — the whole point of ctags patterns), else a bare line number
+(always available from the graph). Extension fields carry ``line:``, ``scope`` (e.g.
+``class:Foo``), ``typeref`` / ``signature`` (functions), ``access`` (public/private)
+and ``end:`` — all facts codemap already holds, no guessing.
+
+**Honest scope.** Definitions only (classes / functions / methods / attributes);
+codemap tracks no token positions, so this is a *tags* file, not a references index
+(that is SCIP's job, R1-C1). Modules are files, not tags, so they are skipped — as
+universal-ctags itself does. Output is byte-stable: pseudo-tags declare it sorted,
+and real tags are sorted by name (then file, then address) for binary search.
+"""
+
+from __future__ import annotations
+
+import os
+
+from codemap.model import Graph
+from codemap.query import Query
+
+# universal-ctags Python kind letters. Modules are not tagged (a module is a file).
+# Methods (function whose parent is a class) use 'm'; module/function-level defs 'f'.
+_CLASS, _FUNC, _METHOD, _VAR = "c", "f", "m", "v"
+
+# Long kind names for the scope field key (``class:Foo`` / ``function:bar``).
+_SCOPE_KIND = {"class": "class", "function": "function"}
+
+# Node kinds that become tags (module/doc/column are skipped).
+_TAGGABLE = {"class", "function", "attribute"}
+
+
+def _kind_letter(kind: str, parent_kind: str | None) -> str:
+    if kind == "class":
+        return _CLASS
+    if kind == "function":
+        return _METHOD if parent_kind == "class" else _FUNC
+    return _VAR  # attribute
+
+
+def _parent_id(nid: str) -> str | None:
+    return nid.rsplit(".", 1)[0] if "." in nid else None
+
+
+def _module_prefix(nodes: dict, nid: str) -> str | None:
+    """Return the id of the nearest module ancestor of ``nid`` (for scope stripping)."""
+    parts = nid.split(".")
+    for i in range(len(parts) - 1, 0, -1):
+        pid = ".".join(parts[:i])
+        node = nodes.get(pid)
+        if node and node.kind == "module":
+            return pid
+    return None
+
+
+def _scope_field(nodes: dict, nid: str) -> str | None:
+    """Build the ``<scopekind>:<name>`` field, or None for a top-level (module-scoped) def."""
+    parent = _parent_id(nid)
+    if parent is None:
+        return None
+    pnode = nodes.get(parent)
+    if pnode is None or pnode.kind == "module":
+        return None  # top-level def — universal-ctags omits module scope
+    scopekind = _SCOPE_KIND.get(pnode.kind, pnode.kind)
+    mod = _module_prefix(nodes, parent)
+    name = parent[len(mod) + 1:] if mod and parent.startswith(mod + ".") else parent
+    return f"{scopekind}:{name}"
+
+
+def _param_list(signature: str) -> str | None:
+    """Extract the parenthesised parameter list from a signature (paren-balanced)."""
+    start = signature.find("(")
+    if start == -1:
+        return None
+    depth = 0
+    for i in range(start, len(signature)):
+        c = signature[i]
+        if c == "(":
+            depth += 1
+        elif c == ")":
+            depth -= 1
+            if depth == 0:
+                return signature[start:i + 1]
+    return None
+
+
+def _return_type(signature: str) -> str | None:
+    arrow = signature.rfind("->")
+    if arrow == -1:
+        return None
+    ret = signature[arrow + 2:].strip()
+    return ret or None
+
+
+def _escape_pattern(line: str) -> str:
+    """Escape a source line for a ctags ``/^…$/`` search address.
+
+    Backslash first, then the pattern delimiter and regex end-anchor so a literal
+    ``/`` or ``$`` in the line does not break or mis-anchor the match.
+    """
+    return line.replace("\\", "\\\\").replace("/", "\\/").replace("$", "\\$")
+
+
+def _tab_sanitize(field: str) -> str:
+    """Tabs/newlines are field separators — never let them into a field value."""
+    return field.replace("\t", " ").replace("\r", " ").replace("\n", " ")
+
+
+class _SourceLines:
+    """Lazily read source files (relative to ``root``) to build search-pattern addresses."""
+
+    def __init__(self, root: str | None):
+        self.root = root
+        self._cache: dict[str, list[str] | None] = {}
+
+    def line(self, rel_path: str, lineno: int) -> str | None:
+        if self.root is None or not lineno:
+            return None
+        lines = self._cache.get(rel_path, "unset")
+        if lines == "unset":
+            try:
+                with open(os.path.join(self.root, rel_path), encoding="utf-8") as fh:
+                    lines = fh.read().split("\n")
+            except (OSError, UnicodeDecodeError):
+                lines = None
+            self._cache[rel_path] = lines
+        if not lines or lineno > len(lines):
+            return None
+        return lines[lineno - 1]
+
+
+def _address(src: _SourceLines, file: str, lineno: int) -> str:
+    """Search-pattern address if the source line is readable, else a bare line number."""
+    text = src.line(file, lineno)
+    if text is not None:
+        return f"/^{_escape_pattern(text)}$/"
+    return str(lineno)
+
+
+def build_ctags(
+    query: Query,
+    *,
+    source_root: str | None = None,
+    tool_version: str = "0.0.1",
+) -> str:
+    """Render the graph as a sorted universal-ctags ``tags`` file (text)."""
+    graph: Graph = query.graph
+    nodes = graph.nodes
+    src = _SourceLines(source_root)
+
+    rows: list[tuple[str, str, str]] = []  # (name, file, full line) — sort key is (name, file, addr)
+    for nid in nodes:
+        node = nodes[nid]
+        if node.kind not in _TAGGABLE or not node.file or not node.lineno:
+            continue
+        name = nid.rsplit(".", 1)[-1]
+        parent = _parent_id(nid)
+        parent_kind = nodes[parent].kind if parent and parent in nodes else None
+
+        address = _address(src, node.file, node.lineno)
+        fields = [_kind_letter(node.kind, parent_kind), f"line:{node.lineno}"]
+        scope = _scope_field(nodes, nid)
+        if scope:
+            fields.append(scope)
+        if node.kind == "function" and node.signature:
+            params = _param_list(node.signature)
+            if params:
+                fields.append(f"signature:{params}")
+            ret = _return_type(node.signature)
+            if ret:
+                fields.append(f"typeref:typename:{ret}")
+        fields.append(f"access:{node.visibility}")
+        if node.endlineno and node.endlineno != node.lineno:
+            fields.append(f"end:{node.endlineno}")
+
+        fields = [_tab_sanitize(f) for f in fields]
+        line = f"{name}\t{node.file}\t{address};\"\t" + "\t".join(fields)
+        rows.append((name, node.file, line))
+
+    # Sorted by name (byte order), then file, then the whole line — binary-searchable.
+    rows.sort(key=lambda r: (r[0], r[1], r[2]))
+
+    header = [
+        "!_TAG_FILE_FORMAT\t2\t/extended format; --format=1 will not append ;\" to lines/",
+        "!_TAG_FILE_SORTED\t1\t/0=unsorted, 1=sorted, 2=foldcase/",
+        "!_TAG_PROGRAM_NAME\tcodemap\t//",
+        "!_TAG_PROGRAM_URL\thttps://github.com/kogriv/codemap\t/graph-native tags/",
+        f"!_TAG_PROGRAM_VERSION\t{_tab_sanitize(tool_version)}\t//",
+    ]
+    body = [r[2] for r in rows]
+    return "\n".join(header + body) + "\n"

codemap/serve/impact.py

@@ -0,0 +1,84 @@
+"""Impact / blast-radius report — consumer C (DESIGN §10.12, M6).
+
+"Can I change / remove X, and what breaks?" — the question the single-package
+graph could not answer (the blast radius lives in tests/docs/examples, outside
+the package; dogfood F1). Needs a repo-scoped graph (``extract_repo``); on a
+core-only graph it simply reports in-package references.
+"""
+
+from __future__ import annotations
+
+from codemap.query import Query
+
+
+def render_impact(query: Query, symbol: str, *, depth: int = 2) -> str:
+    """Markdown blast-radius for the symbol matching ``symbol`` (short or full)."""
+    ids = query.impact_targets(symbol)  # F23: short name / full id / re-export
+    lines = [f"# Impact — `{symbol}`", ""]
+    lines.append(
+        "_Best-effort static blast radius: who references the symbol (and its "
+        "members), grouped by repo root. Call resolution is partial (gaps/ CM-09), "
+        "so this is a **lower bound** — pair with grep before deleting._"
+    )
+    lines.append("")
+    if not ids:
+        lines.append(f"_No definition found for `{symbol}`._")
+        return "\n".join(lines) + "\n"
+
+    for sid in ids:
+        rep = query.impact(sid, depth=depth)
+        refs = rep["refs"]
+        by_root = rep["by_root"]
+        lines.append(f"## `{sid}`")
+        lines.append("")
+        if not refs:
+            lines.append("_No inbound references — isolated in the analysed roots._")
+            lines.append("")
+            continue
+        total = len(refs)
+        roots = ", ".join(f"{r} ({sum(by_root[r].values())})" for r in sorted(by_root))
+        lines.append(f"**{total} references across roots:** {roots}")
+        # R1-C19: risk triage + depth histogram (transitive reach at a glance).
+        hist = ", ".join(f"d{d}×{rep['by_distance'][d]}" for d in sorted(rep["by_distance"]))
+        lines.append(
+            f"**Risk: {rep['risk'].upper()}** — depth reached {rep['max_distance']}"
+            + (f"; distances: {hist}" if hist else "")
+            + " _(heuristic: breadth × reach × root-spread)_"
+        )
+        lines.append("")
+        # per-root breakdown, direct refs first.
+        for root in sorted(by_root):
+            counts = ", ".join(f"{t}×{c}" for t, c in sorted(by_root[root].items()))
+            lines.append(f"### {root} — {counts}")
+            direct = sorted(
+                {r["source"] for r in refs if r["root"] == root and r["distance"] == 1}
+            )
+            for src in direct[:40]:
+                lines.append(f"- `{src}`")
+            if len(direct) > 40:
+                lines.append(f"- _… {len(direct) - 40} more_")
+            indirect = {r["source"] for r in refs if r["root"] == root and r["distance"] > 1}
+            if indirect:
+                lines.append(f"- _+{len(indirect)} transitive (distance >1)_")
+            lines.append("")
+
+        # F7: argument contract of the call-sites — what a signature change touches.
+        contract = query.call_contract(sid)
+        if contract:
+            sites = sum(c["callsites"] for c in contract)
+            lines.append(f"### Call-site contract ({sites} sites — for signature change)")
+            lines.append("")
+            for c in contract:
+                pos = "/".join(map(str, c["posargs"])) or "0"
+                kw = ", ".join(c["kwargs"]) or "—"
+                splat = " +splat" if c["splat"] else ""
+                lines.append(
+                    f"- `{c['caller']}` ×{c['callsites']} — {pos} positional, kwargs: {kw}{splat}"
+                )
+            lines.append("")
+            lines.append(
+                "_Positional counts / kwarg names observed at the call-sites (resolved "
+                "edges only). Use to see which sites break under an arity/keyword change._"
+            )
+            lines.append("")
+    return "\n".join(lines).rstrip() + "\n"