codmap 0.0.3__py3-none-any.whl

codemap/scope.py

@@ -0,0 +1,212 @@
+"""Input scope manifest — M19.A (design: ``docs/design/scope.md``).
+
+A deterministic identity of the **input** that produced a graph. codemap is already
+deterministic on its *output* (canonical ``graph.json``); this is the symmetric thing
+for the *input*: resolve a scope (build args / spec) to a **sorted file list**,
+content-hash each file (sha-256), build a **profile**, and compute a **scope_id**.
+
+Operates **in place over the real tree** (the live path — enables watch/incremental
+downstream). When the root is a git repo, enumeration prefers ``git ls-files`` (the
+gitignore-correct set — no venv/build/cache, for free) and records git provenance;
+identity (``scope_id``) is always our sha-256, independent of git and of dirty state.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import subprocess
+from pathlib import Path
+
+# What codemap actually consumes as input (source + docs it indexes as references).
+DEFAULT_INCLUDE = ("*.py", "*.md")
+# fs-mode default excludes (git mode gets these for free via .gitignore).
+DEFAULT_EXCLUDE_DIRS = frozenset({
+    "__pycache__", ".git", ".venv", "venv", "node_modules", "build", "dist",
+    ".eggs", ".mypy_cache", ".pytest_cache", ".ruff_cache", ".tox",
+})
+_LARGEST_N = 10
+# consumer dir name → role; anything else keeps its own basename as the role.
+_KNOWN_ROLES = frozenset({"tests", "examples", "research", "scripts", "docs", "benchmarks"})
+
+
+def _git(root: Path, *args: str) -> str | None:
+    """Run ``git -C root …``; return stdout (stripped) or None on any failure."""
+    try:
+        out = subprocess.run(("git", "-C", str(root), *args),
+                             capture_output=True, text=True, check=True)
+    except (OSError, subprocess.CalledProcessError):
+        return None
+    return out.stdout
+
+
+def _match_include(name: str, include: tuple[str, ...]) -> bool:
+    from fnmatch import fnmatch
+    return any(fnmatch(name, pat) for pat in include)
+
+
+def _role_of(rel: str, roots: list[tuple[str, str]]) -> str:
+    """Assign a relative path to a role by its longest matching root prefix."""
+    parts = rel.split("/")
+    best_role, best_len = "core", -1
+    for rpath, role in roots:
+        rp = rpath.split("/") if rpath else []
+        if parts[:len(rp)] == rp and len(rp) > best_len:
+            best_role, best_len = role, len(rp)
+    return best_role
+
+
+def _roots_spec(root: Path, core: Path, consumers, docs) -> list[tuple[str, str]]:
+    """[(rel-path-from-root, role)] for core + consumers + docs (longest-match order)."""
+    out: list[tuple[str, str]] = [(_rel(root, core), "core")]
+    for c in consumers:
+        p = Path(c).resolve()
+        out.append((_rel(root, p), p.name if p.name in _KNOWN_ROLES else p.name))
+    for d in docs:
+        p = Path(d).resolve()
+        out.append((_rel(root, p), "docs"))
+    return out
+
+
+def _rel(root: Path, p: Path) -> str:
+    try:
+        return p.resolve().relative_to(root).as_posix()
+    except ValueError:
+        return p.resolve().as_posix()
+
+
+def _pick_root(core: Path, consumers, docs) -> tuple[Path, str]:
+    """Choose the scope root (paths are stored relative to it) and enumeration mode.
+
+    Prefer the git top-level (→ git mode); else the common ancestor of the inputs
+    (→ fs mode). Returns (root, mode).
+    """
+    core = core.resolve()
+    top = _git(core if core.is_dir() else core.parent, "rev-parse", "--show-toplevel")
+    if top:
+        return Path(top.strip()), "git"
+    paths = [core] + [Path(p).resolve() for p in (*consumers, *docs)]
+    base = Path(os.path.commonpath([str(p) for p in paths])) if len(paths) > 1 else core.parent
+    return base, "fs"
+
+
+def _enumerate_git(root: Path, roots: list[tuple[str, str]]) -> tuple[list[str], dict]:
+    """git ls-files over the scope pathspecs → (rel paths, {path: git_blob})."""
+    specs = [rp for rp, _ in roots if rp]
+    out = _git(root, "ls-files", "-s", "--", *specs) or ""
+    paths, blobs = [], {}
+    for line in out.splitlines():
+        # "<mode> <blob> <stage>\t<path>"
+        meta, _, path = line.partition("\t")
+        if not path:
+            continue
+        cols = meta.split()
+        if len(cols) >= 2:
+            blobs[path] = cols[1]
+        paths.append(path)
+    return paths, blobs
+
+
+def _enumerate_fs(root: Path, roots, include, exclude_dirs) -> list[str]:
+    paths = []
+    for rp, _role in roots:
+        base = (root / rp) if rp else root
+        if not base.exists():
+            continue
+        for dirpath, dirnames, filenames in os.walk(base):
+            dirnames[:] = [d for d in dirnames if d not in exclude_dirs]
+            for fn in filenames:
+                if _match_include(fn, include):
+                    paths.append(Path(dirpath, fn).resolve().relative_to(root).as_posix())
+    return paths
+
+
+def resolve_scope(
+    core: str | Path,
+    *,
+    consumers: tuple[str | Path, ...] = (),
+    docs: tuple[str | Path, ...] = (),
+    include: tuple[str, ...] = DEFAULT_INCLUDE,
+    exclude_dirs=DEFAULT_EXCLUDE_DIRS,
+    use_git: bool = True,
+) -> dict:
+    """Resolve a scope to ``{scope_id, profile, git, files}`` (design §1)."""
+    core = Path(core).resolve()
+    root, mode = _pick_root(core, consumers, docs)
+    if not use_git:
+        mode = "fs"
+    roots = _roots_spec(root, core, consumers, docs)
+
+    if mode == "git":
+        rels, blobs = _enumerate_git(root, roots)
+        rels = [r for r in rels if _match_include(Path(r).name, include)]
+    else:
+        rels, blobs = _enumerate_fs(root, roots, include, exclude_dirs), {}
+
+    files = []
+    for rel in sorted(set(rels)):
+        fpath = root / rel
+        try:
+            data = fpath.read_bytes()
+        except OSError:
+            continue
+        rec = {"path": rel, "sha256": hashlib.sha256(data).hexdigest(),
+               "bytes": len(data), "role": _role_of(rel, roots),
+               "loc": data.count(b"\n") + (1 if data and not data.endswith(b"\n") else 0)}
+        if rel in blobs:
+            rec["git_blob"] = blobs[rel]
+        files.append(rec)
+
+    scope_id = "sha256:" + hashlib.sha256(
+        "\n".join(f"{f['path']}\t{f['sha256']}" for f in files).encode("utf-8")
+    ).hexdigest()
+
+    return {
+        "scope_id": scope_id,
+        "root": str(root),
+        "profile": _profile(files),
+        "git": _git_block(root, roots, mode) if mode == "git" else {"mode": "fs"},
+        # files carry loc for the profile; drop it from the persisted per-file record
+        "files": [{k: v for k, v in f.items() if k != "loc"} for f in files],
+    }
+
+
+def _profile(files: list[dict]) -> dict:
+    by_role: dict[str, dict] = {}
+    by_ext: dict[str, dict] = {}
+    for f in files:
+        for bucket, key in ((by_role, f["role"]), (by_ext, Path(f["path"]).suffix or "—")):
+            b = bucket.setdefault(key, {"files": 0, "bytes": 0, "loc": 0})
+            b["files"] += 1
+            b["bytes"] += f["bytes"]
+            b["loc"] += f["loc"]
+    largest = sorted(files, key=lambda f: (-f["bytes"], f["path"]))[:_LARGEST_N]
+    return {
+        "file_count": len(files),
+        "total_bytes": sum(f["bytes"] for f in files),
+        "loc_total": sum(f["loc"] for f in files),
+        "by_role": dict(sorted(by_role.items())),
+        "by_ext": dict(sorted(by_ext.items())),
+        "largest": [{"path": f["path"], "bytes": f["bytes"]} for f in largest],
+    }
+
+
+def _git_block(root: Path, roots: list[tuple[str, str]], mode: str) -> dict:
+    commit = (_git(root, "rev-parse", "HEAD") or "").strip()
+    ref = (_git(root, "rev-parse", "--abbrev-ref", "HEAD") or "").strip()
+    specs = [rp for rp, _ in roots if rp]
+    status = _git(root, "status", "--porcelain", "--", *specs) or ""
+    dirty_files = sorted(line[3:].strip() for line in status.splitlines() if line.strip())
+    return {"mode": mode, "commit": commit, "ref": ref,
+            "dirty": bool(dirty_files), "dirty_files": dirty_files}
+
+
+def diff_scopes(a: dict, b: dict) -> dict:
+    """Added / removed / changed files between two scope manifests (by path+sha256)."""
+    am = {f["path"]: f["sha256"] for f in a.get("files", [])}
+    bm = {f["path"]: f["sha256"] for f in b.get("files", [])}
+    added = sorted(set(bm) - set(am))
+    removed = sorted(set(am) - set(bm))
+    changed = sorted(p for p in set(am) & set(bm) if am[p] != bm[p])
+    return {"added": added, "removed": removed, "changed": changed,
+            "same_scope_id": a.get("scope_id") == b.get("scope_id")}

codemap/serve/__init__.py

@@ -0,0 +1,26 @@
+"""Serve layer: views/reports over the canonical graph (DESIGN §4)."""
+
+from codemap.serve.api_surface import render_api_surface
+from codemap.serve.architecture import build_architecture, render_architecture
+from codemap.serve.audit import render_behavior, render_dead_code, render_dependencies
+from codemap.serve.impact import render_impact
+from codemap.serve.mermaid import render_mermaid
+from codemap.serve.rag import build_chunks, render_rag
+from codemap.serve.session import Session, build_query_result
+from codemap.serve.vault import build_vault
+
+__all__ = [
+    "Session",
+    "build_query_result",
+    "render_api_surface",
+    "render_dependencies",
+    "render_dead_code",
+    "render_behavior",
+    "render_architecture",
+    "build_architecture",
+    "render_impact",
+    "render_mermaid",
+    "render_rag",
+    "build_chunks",
+    "build_vault",
+]

codemap/serve/_scip_pb2.py

@@ -0,0 +1,100 @@
+# vendored SCIP protobuf bindings — generated from sourcegraph/scip scip.proto
+# (regenerate: protoc --python_out=. scip.proto). The runtime-version guard was
+# lowered to 5.26.0 so the optional `scip` extra works on protobuf>=5.26.
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: scip.proto
+# Protobuf Python Version: 7.35.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    5,
+    26,
+    0,
+    '',
+    'scip.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\nscip.proto\x12\x04scip\"\x7f\n\x05Index\x12 \n\x08metadata\x18\x01 \x01(\x0b\x32\x0e.scip.Metadata\x12!\n\tdocuments\x18\x02 \x03(\x0b\x32\x0e.scip.Document\x12\x31\n\x10\x65xternal_symbols\x18\x03 \x03(\x0b\x32\x17.scip.SymbolInformation\"\x9f\x01\n\x08Metadata\x12&\n\x07version\x18\x01 \x01(\x0e\x32\x15.scip.ProtocolVersion\x12!\n\ttool_info\x18\x02 \x01(\x0b\x32\x0e.scip.ToolInfo\x12\x14\n\x0cproject_root\x18\x03 \x01(\t\x12\x32\n\x16text_document_encoding\x18\x04 \x01(\x0e\x32\x12.scip.TextEncoding\"<\n\x08ToolInfo\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x0f\n\x07version\x18\x02 \x01(\t\x12\x11\n\targuments\x18\x03 \x03(\t\"\xc5\x01\n\x08\x44ocument\x12\x10\n\x08language\x18\x04 \x01(\t\x12\x15\n\rrelative_path\x18\x01 \x01(\t\x12%\n\x0boccurrences\x18\x02 \x03(\x0b\x32\x10.scip.Occurrence\x12(\n\x07symbols\x18\x03 \x03(\x0b\x32\x17.scip.SymbolInformation\x12\x0c\n\x04text\x18\x05 \x01(\t\x12\x31\n\x11position_encoding\x18\x06 \x01(\x0e\x32\x16.scip.PositionEncoding\"_\n\x06Symbol\x12\x0e\n\x06scheme\x18\x01 \x01(\t\x12\x1e\n\x07package\x18\x02 \x01(\x0b\x32\r.scip.Package\x12%\n\x0b\x64\x65scriptors\x18\x03 \x03(\x0b\x32\x10.scip.Descriptor\"9\n\x07Package\x12\x0f\n\x07manager\x18\x01 \x01(\t\x12\x0c\n\x04name\x18\x02 \x01(\t\x12\x0f\n\x07version\x18\x03 \x01(\t\"\x82\x02\n\nDescriptor\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x15\n\rdisambiguator\x18\x02 \x01(\t\x12\'\n\x06suffix\x18\x03 \x01(\x0e\x32\x17.scip.Descriptor.Suffix\"\xa5\x01\n\x06Suffix\x12\x15\n\x11UnspecifiedSuffix\x10\x00\x12\r\n\tNamespace\x10\x01\x12\x0f\n\x07Package\x10\x01\x1a\x02\x08\x01\x12\x08\n\x04Type\x10\x02\x12\x08\n\x04Term\x10\x03\x12\n\n\x06Method\x10\x04\x12\x11\n\rTypeParameter\x10\x05\x12\r\n\tParameter\x10\x06\x12\x08\n\x04Meta\x10\x07\x12\t\n\x05Local\x10\x08\x12\t\n\x05Macro\x10\t\x1a\x02\x10\x01\"d\n\tSignature\x12\x10\n\x08language\x18\x04 \x01(\t\x12\x0c\n\x04text\x18\x05 \x01(\t\x12%\n\x0boccurrences\x18\x02 \x03(\x0b\x32\x10.scip.OccurrenceJ\x04\x08\x01\x10\x02J\x04\x08\x03\x10\x04J\x04\x08\x06\x10\x07\"\xf1\x0b\n\x11SymbolInformation\x12\x0e\n\x06symbol\x18\x01 \x01(\t\x12\x15\n\rdocumentation\x18\x03 \x03(\t\x12)\n\rrelationships\x18\x04 \x03(\x0b\x32\x12.scip.Relationship\x12*\n\x04kind\x18\x05 \x01(\x0e\x32\x1c.scip.SymbolInformation.Kind\x12\x14\n\x0c\x64isplay_name\x18\x06 \x01(\t\x12\x30\n\x17signature_documentation\x18\x07 \x01(\x0b\x32\x0f.scip.Signature\x12\x18\n\x10\x65nclosing_symbol\x18\x08 \x01(\t\"\xfb\t\n\x04Kind\x12\x13\n\x0fUnspecifiedKind\x10\x00\x12\x12\n\x0e\x41\x62stractMethod\x10\x42\x12\x0c\n\x08\x41\x63\x63\x65ssor\x10H\x12\t\n\x05\x41rray\x10\x01\x12\r\n\tAssertion\x10\x02\x12\x12\n\x0e\x41ssociatedType\x10\x03\x12\r\n\tAttribute\x10\x04\x12\t\n\x05\x41xiom\x10\x05\x12\x0b\n\x07\x42oolean\x10\x06\x12\t\n\x05\x43lass\x10\x07\x12\x0b\n\x07\x43oncept\x10V\x12\x0c\n\x08\x43onstant\x10\x08\x12\x0f\n\x0b\x43onstructor\x10\t\x12\x0c\n\x08\x43ontract\x10>\x12\x0e\n\nDataFamily\x10\n\x12\x0c\n\x08\x44\x65legate\x10I\x12\x08\n\x04\x45num\x10\x0b\x12\x0e\n\nEnumMember\x10\x0c\x12\t\n\x05\x45rror\x10?\x12\t\n\x05\x45vent\x10\r\x12\r\n\tExtension\x10T\x12\x08\n\x04\x46\x61\x63t\x10\x0e\x12\t\n\x05\x46ield\x10\x0f\x12\x08\n\x04\x46ile\x10\x10\x12\x0c\n\x08\x46unction\x10\x11\x12\n\n\x06Getter\x10\x12\x12\x0b\n\x07Grammar\x10\x13\x12\x0c\n\x08Instance\x10\x14\x12\r\n\tInterface\x10\x15\x12\x07\n\x03Key\x10\x16\x12\x08\n\x04Lang\x10\x17\x12\t\n\x05Lemma\x10\x18\x12\x0b\n\x07Library\x10@\x12\t\n\x05Macro\x10\x19\x12\n\n\x06Method\x10\x1a\x12\x0f\n\x0bMethodAlias\x10J\x12\x12\n\x0eMethodReceiver\x10\x1b\x12\x17\n\x13MethodSpecification\x10\x43\x12\x0b\n\x07Message\x10\x1c\x12\t\n\x05Mixin\x10U\x12\x0c\n\x08Modifier\x10\x41\x12\n\n\x06Module\x10\x1d\x12\r\n\tNamespace\x10\x1e\x12\x08\n\x04Null\x10\x1f\x12\n\n\x06Number\x10 \x12\n\n\x06Object\x10!\x12\x0c\n\x08Operator\x10\"\x12\x0b\n\x07Package\x10#\x12\x11\n\rPackageObject\x10$\x12\r\n\tParameter\x10%\x12\x12\n\x0eParameterLabel\x10&\x12\x0b\n\x07Pattern\x10\'\x12\r\n\tPredicate\x10(\x12\x0c\n\x08Property\x10)\x12\x0c\n\x08Protocol\x10*\x12\x12\n\x0eProtocolMethod\x10\x44\x12\x15\n\x11PureVirtualMethod\x10\x45\x12\x0f\n\x0bQuasiquoter\x10+\x12\x11\n\rSelfParameter\x10,\x12\n\n\x06Setter\x10-\x12\r\n\tSignature\x10.\x12\x12\n\x0eSingletonClass\x10K\x12\x13\n\x0fSingletonMethod\x10L\x12\x14\n\x10StaticDataMember\x10M\x12\x0f\n\x0bStaticEvent\x10N\x12\x0f\n\x0bStaticField\x10O\x12\x10\n\x0cStaticMethod\x10P\x12\x12\n\x0eStaticProperty\x10Q\x12\x12\n\x0eStaticVariable\x10R\x12\n\n\x06String\x10\x30\x12\n\n\x06Struct\x10\x31\x12\r\n\tSubscript\x10/\x12\n\n\x06Tactic\x10\x32\x12\x0b\n\x07Theorem\x10\x33\x12\x11\n\rThisParameter\x10\x34\x12\t\n\x05Trait\x10\x35\x12\x0f\n\x0bTraitMethod\x10\x46\x12\x08\n\x04Type\x10\x36\x12\r\n\tTypeAlias\x10\x37\x12\r\n\tTypeClass\x10\x38\x12\x13\n\x0fTypeClassMethod\x10G\x12\x0e\n\nTypeFamily\x10\x39\x12\x11\n\rTypeParameter\x10:\x12\t\n\x05Union\x10;\x12\t\n\x05Value\x10<\x12\x0c\n\x08Variable\x10=\"\x82\x01\n\x0cRelationship\x12\x0e\n\x06symbol\x18\x01 \x01(\t\x12\x14\n\x0cis_reference\x18\x02 \x01(\x08\x12\x19\n\x11is_implementation\x18\x03 \x01(\x08\x12\x1a\n\x12is_type_definition\x18\x04 \x01(\x08\x12\x15\n\ris_definition\x18\x05 \x01(\x08\"O\n\x0fSingleLineRange\x12\x0c\n\x04line\x18\x01 \x01(\x05\x12\x17\n\x0fstart_character\x18\x02 \x01(\x05\x12\x15\n\rend_character\x18\x03 \x01(\x05\"f\n\x0eMultiLineRange\x12\x12\n\nstart_line\x18\x01 \x01(\x05\x12\x17\n\x0fstart_character\x18\x02 \x01(\x05\x12\x10\n\x08\x65nd_line\x18\x03 \x01(\x05\x12\x15\n\rend_character\x18\x04 \x01(\x05\"\xd8\x03\n\nOccurrence\x12\x11\n\x05range\x18\x01 \x03(\x05\x42\x02\x18\x01\x12\x32\n\x11single_line_range\x18\x08 \x01(\x0b\x32\x15.scip.SingleLineRangeH\x00\x12\x30\n\x10multi_line_range\x18\t \x01(\x0b\x32\x14.scip.MultiLineRangeH\x00\x12\x0e\n\x06symbol\x18\x02 \x01(\t\x12\x14\n\x0csymbol_roles\x18\x03 \x01(\x05\x12\x1e\n\x16override_documentation\x18\x04 \x03(\t\x12%\n\x0bsyntax_kind\x18\x05 \x01(\x0e\x32\x10.scip.SyntaxKind\x12%\n\x0b\x64iagnostics\x18\x06 \x03(\x0b\x32\x10.scip.Diagnostic\x12\x1b\n\x0f\x65nclosing_range\x18\x07 \x03(\x05\x42\x02\x18\x01\x12<\n\x1bsingle_line_enclosing_range\x18\n \x01(\x0b\x32\x15.scip.SingleLineRangeH\x01\x12:\n\x1amulti_line_enclosing_range\x18\x0b \x01(\x0b\x32\x14.scip.MultiLineRangeH\x01\x42\r\n\x0btyped_rangeB\x17\n\x15typed_enclosing_range\"\x80\x01\n\nDiagnostic\x12 \n\x08severity\x18\x01 \x01(\x0e\x32\x0e.scip.Severity\x12\x0c\n\x04\x63ode\x18\x02 \x01(\t\x12\x0f\n\x07message\x18\x03 \x01(\t\x12\x0e\n\x06source\x18\x04 \x01(\t\x12!\n\x04tags\x18\x05 \x03(\x0e\x32\x13.scip.DiagnosticTag*1\n\x0fProtocolVersion\x12\x1e\n\x1aUnspecifiedProtocolVersion\x10\x00*@\n\x0cTextEncoding\x12\x1b\n\x17UnspecifiedTextEncoding\x10\x00\x12\x08\n\x04UTF8\x10\x01\x12\t\n\x05UTF16\x10\x02*\xa4\x01\n\x10PositionEncoding\x12\x1f\n\x1bUnspecifiedPositionEncoding\x10\x00\x12#\n\x1fUTF8CodeUnitOffsetFromLineStart\x10\x01\x12$\n UTF16CodeUnitOffsetFromLineStart\x10\x02\x12$\n UTF32CodeUnitOffsetFromLineStart\x10\x03*\x94\x01\n\nSymbolRole\x12\x19\n\x15UnspecifiedSymbolRole\x10\x00\x12\x0e\n\nDefinition\x10\x01\x12\n\n\x06Import\x10\x02\x12\x0f\n\x0bWriteAccess\x10\x04\x12\x0e\n\nReadAccess\x10\x08\x12\r\n\tGenerated\x10\x10\x12\x08\n\x04Test\x10 \x12\x15\n\x11\x46orwardDefinition\x10@*\xea\x06\n\nSyntaxKind\x12\x19\n\x15UnspecifiedSyntaxKind\x10\x00\x12\x0b\n\x07\x43omment\x10\x01\x12\x18\n\x14PunctuationDelimiter\x10\x02\x12\x16\n\x12PunctuationBracket\x10\x03\x12\x0b\n\x07Keyword\x10\x04\x12\x19\n\x11IdentifierKeyword\x10\x04\x1a\x02\x08\x01\x12\x16\n\x12IdentifierOperator\x10\x05\x12\x0e\n\nIdentifier\x10\x06\x12\x15\n\x11IdentifierBuiltin\x10\x07\x12\x12\n\x0eIdentifierNull\x10\x08\x12\x16\n\x12IdentifierConstant\x10\t\x12\x1b\n\x17IdentifierMutableGlobal\x10\n\x12\x17\n\x13IdentifierParameter\x10\x0b\x12\x13\n\x0fIdentifierLocal\x10\x0c\x12\x16\n\x12IdentifierShadowed\x10\r\x12\x17\n\x13IdentifierNamespace\x10\x0e\x12\x18\n\x10IdentifierModule\x10\x0e\x1a\x02\x08\x01\x12\x16\n\x12IdentifierFunction\x10\x0f\x12 \n\x1cIdentifierFunctionDefinition\x10\x10\x12\x13\n\x0fIdentifierMacro\x10\x11\x12\x1d\n\x19IdentifierMacroDefinition\x10\x12\x12\x12\n\x0eIdentifierType\x10\x13\x12\x19\n\x15IdentifierBuiltinType\x10\x14\x12\x17\n\x13IdentifierAttribute\x10\x15\x12\x0f\n\x0bRegexEscape\x10\x16\x12\x11\n\rRegexRepeated\x10\x17\x12\x11\n\rRegexWildcard\x10\x18\x12\x12\n\x0eRegexDelimiter\x10\x19\x12\r\n\tRegexJoin\x10\x1a\x12\x11\n\rStringLiteral\x10\x1b\x12\x17\n\x13StringLiteralEscape\x10\x1c\x12\x18\n\x14StringLiteralSpecial\x10\x1d\x12\x14\n\x10StringLiteralKey\x10\x1e\x12\x14\n\x10\x43haracterLiteral\x10\x1f\x12\x12\n\x0eNumericLiteral\x10 \x12\x12\n\x0e\x42ooleanLiteral\x10!\x12\x07\n\x03Tag\x10\"\x12\x10\n\x0cTagAttribute\x10#\x12\x10\n\x0cTagDelimiter\x10$\x1a\x02\x10\x01*V\n\x08Severity\x12\x17\n\x13UnspecifiedSeverity\x10\x00\x12\t\n\x05\x45rror\x10\x01\x12\x0b\n\x07Warning\x10\x02\x12\x0f\n\x0bInformation\x10\x03\x12\x08\n\x04Hint\x10\x04*N\n\rDiagnosticTag\x12\x1c\n\x18UnspecifiedDiagnosticTag\x10\x00\x12\x0f\n\x0bUnnecessary\x10\x01\x12\x0e\n\nDeprecated\x10\x02*\xa5\n\n\x08Language\x12\x17\n\x13UnspecifiedLanguage\x10\x00\x12\x08\n\x04\x41\x42\x41P\x10<\x12\x08\n\x04\x41pex\x10`\x12\x07\n\x03\x41PL\x10\x31\x12\x07\n\x03\x41\x64\x61\x10\'\x12\x08\n\x04\x41gda\x10-\x12\x0c\n\x08\x41sciiDoc\x10V\x12\x0c\n\x08\x41ssembly\x10:\x12\x07\n\x03\x41wk\x10\x42\x12\x07\n\x03\x42\x61t\x10\x44\x12\n\n\x06\x42ibTeX\x10Q\x12\x05\n\x01\x43\x10\"\x12\t\n\x05\x43OBOL\x10;\x12\x07\n\x03\x43PP\x10#\x12\x07\n\x03\x43SS\x10\x1a\x12\n\n\x06\x43Sharp\x10\x01\x12\x0b\n\x07\x43lojure\x10\x08\x12\x10\n\x0c\x43offeescript\x10\x15\x12\x0e\n\nCommonLisp\x10\t\x12\x07\n\x03\x43oq\x10/\x12\x08\n\x04\x43UDA\x10\x61\x12\x08\n\x04\x44\x61rt\x10\x03\x12\n\n\x06\x44\x65lphi\x10\x39\x12\x08\n\x04\x44iff\x10X\x12\x0e\n\nDockerfile\x10P\x12\n\n\x06\x44yalog\x10\x32\x12\n\n\x06\x45lixir\x10\x11\x12\n\n\x06\x45rlang\x10\x12\x12\n\n\x06\x46Sharp\x10*\x12\x08\n\x04\x46ish\x10\x41\x12\x08\n\x04\x46low\x10\x18\x12\x0b\n\x07\x46ortran\x10\x38\x12\x0e\n\nGit_Commit\x10[\x12\x0e\n\nGit_Config\x10Y\x12\x0e\n\nGit_Rebase\x10\\\x12\x06\n\x02Go\x10!\x12\x0b\n\x07GraphQL\x10\x62\x12\n\n\x06Groovy\x10\x07\x12\x08\n\x04HTML\x10\x1e\x12\x08\n\x04Hack\x10\x14\x12\x0e\n\nHandlebars\x10Z\x12\x0b\n\x07Haskell\x10,\x12\t\n\x05Idris\x10.\x12\x07\n\x03Ini\x10H\x12\x05\n\x01J\x10\x33\x12\x08\n\x04JSON\x10K\x12\x08\n\x04Java\x10\x06\x12\x0e\n\nJavaScript\x10\x16\x12\x13\n\x0fJavaScriptReact\x10]\x12\x0b\n\x07Jsonnet\x10L\x12\t\n\x05Julia\x10\x37\x12\x0c\n\x08Justfile\x10m\x12\n\n\x06Kotlin\x10\x04\x12\t\n\x05LaTeX\x10S\x12\x08\n\x04Lean\x10\x30\x12\x08\n\x04Less\x10\x1b\x12\x07\n\x03Lua\x10\x0c\x12\x08\n\x04Luau\x10l\x12\x0c\n\x08Makefile\x10O\x12\x0c\n\x08Markdown\x10T\x12\n\n\x06Matlab\x10\x34\x12\n\n\x06Nickel\x10n\x12\x07\n\x03Nix\x10M\x12\t\n\x05OCaml\x10)\x12\x0f\n\x0bObjective_C\x10$\x12\x11\n\rObjective_CPP\x10%\x12\x08\n\x04Odin\x10o\x12\n\n\x06Pascal\x10\x63\x12\x07\n\x03PHP\x10\x13\x12\t\n\x05PLSQL\x10\x46\x12\x08\n\x04Perl\x10\r\x12\x0e\n\nPowerShell\x10\x43\x12\n\n\x06Prolog\x10G\x12\x0c\n\x08Protobuf\x10\x64\x12\n\n\x06Python\x10\x0f\x12\x05\n\x01R\x10\x36\x12\n\n\x06Racket\x10\x0b\x12\x08\n\x04Raku\x10\x0e\x12\t\n\x05Razor\x10>\x12\t\n\x05Repro\x10\x66\x12\x08\n\x04ReST\x10U\x12\x08\n\x04Ruby\x10\x10\x12\x08\n\x04Rust\x10(\x12\x07\n\x03SAS\x10=\x12\x08\n\x04SCSS\x10\x1d\x12\x07\n\x03SML\x10+\x12\x07\n\x03SQL\x10\x45\x12\x08\n\x04Sass\x10\x1c\x12\t\n\x05Scala\x10\x05\x12\n\n\x06Scheme\x10\n\x12\x0f\n\x0bShellScript\x10@\x12\x0b\n\x07Skylark\x10N\x12\t\n\x05Slang\x10k\x12\x0c\n\x08Solidity\x10_\x12\n\n\x06Svelte\x10j\x12\t\n\x05Swift\x10\x02\x12\x07\n\x03Tcl\x10\x65\x12\x08\n\x04TOML\x10I\x12\x07\n\x03TeX\x10R\x12\n\n\x06Thrift\x10g\x12\x0e\n\nTypeScript\x10\x17\x12\x13\n\x0fTypeScriptReact\x10^\x12\x0b\n\x07Verilog\x10h\x12\x08\n\x04VHDL\x10i\x12\x0f\n\x0bVisualBasic\x10?\x12\x07\n\x03Vue\x10\x19\x12\x0b\n\x07Wolfram\x10\x35\x12\x07\n\x03XML\x10\x1f\x12\x07\n\x03XSL\x10 \x12\x08\n\x04YAML\x10J\x12\x07\n\x03Zig\x10&BN\n\x12org.scip_code.scipB\tScipProtoP\x01Z+github.com/scip-code/scip/bindings/go/scip/b\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'scip_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\n\022org.scip_code.scipB\tScipProtoP\001Z+github.com/scip-code/scip/bindings/go/scip/'
+  _globals['_SYNTAXKIND']._loaded_options = None
+  _globals['_SYNTAXKIND']._serialized_options = b'\020\001'
+  _globals['_SYNTAXKIND'].values_by_name["IdentifierKeyword"]._loaded_options = None
+  _globals['_SYNTAXKIND'].values_by_name["IdentifierKeyword"]._serialized_options = b'\010\001'
+  _globals['_SYNTAXKIND'].values_by_name["IdentifierModule"]._loaded_options = None
+  _globals['_SYNTAXKIND'].values_by_name["IdentifierModule"]._serialized_options = b'\010\001'
+  _globals['_DESCRIPTOR_SUFFIX']._loaded_options = None
+  _globals['_DESCRIPTOR_SUFFIX']._serialized_options = b'\020\001'
+  _globals['_DESCRIPTOR_SUFFIX'].values_by_name["Package"]._loaded_options = None
+  _globals['_DESCRIPTOR_SUFFIX'].values_by_name["Package"]._serialized_options = b'\010\001'
+  _globals['_OCCURRENCE'].fields_by_name['range']._loaded_options = None
+  _globals['_OCCURRENCE'].fields_by_name['range']._serialized_options = b'\030\001'
+  _globals['_OCCURRENCE'].fields_by_name['enclosing_range']._loaded_options = None
+  _globals['_OCCURRENCE'].fields_by_name['enclosing_range']._serialized_options = b'\030\001'
+  _globals['_PROTOCOLVERSION']._serialized_start=3540
+  _globals['_PROTOCOLVERSION']._serialized_end=3589
+  _globals['_TEXTENCODING']._serialized_start=3591
+  _globals['_TEXTENCODING']._serialized_end=3655
+  _globals['_POSITIONENCODING']._serialized_start=3658
+  _globals['_POSITIONENCODING']._serialized_end=3822
+  _globals['_SYMBOLROLE']._serialized_start=3825
+  _globals['_SYMBOLROLE']._serialized_end=3973
+  _globals['_SYNTAXKIND']._serialized_start=3976
+  _globals['_SYNTAXKIND']._serialized_end=4850
+  _globals['_SEVERITY']._serialized_start=4852
+  _globals['_SEVERITY']._serialized_end=4938
+  _globals['_DIAGNOSTICTAG']._serialized_start=4940
+  _globals['_DIAGNOSTICTAG']._serialized_end=5018
+  _globals['_LANGUAGE']._serialized_start=5021
+  _globals['_LANGUAGE']._serialized_end=6338
+  _globals['_INDEX']._serialized_start=20
+  _globals['_INDEX']._serialized_end=147
+  _globals['_METADATA']._serialized_start=150
+  _globals['_METADATA']._serialized_end=309
+  _globals['_TOOLINFO']._serialized_start=311
+  _globals['_TOOLINFO']._serialized_end=371
+  _globals['_DOCUMENT']._serialized_start=374
+  _globals['_DOCUMENT']._serialized_end=571
+  _globals['_SYMBOL']._serialized_start=573
+  _globals['_SYMBOL']._serialized_end=668
+  _globals['_PACKAGE']._serialized_start=670
+  _globals['_PACKAGE']._serialized_end=727
+  _globals['_DESCRIPTOR']._serialized_start=730
+  _globals['_DESCRIPTOR']._serialized_end=988
+  _globals['_DESCRIPTOR_SUFFIX']._serialized_start=823
+  _globals['_DESCRIPTOR_SUFFIX']._serialized_end=988
+  _globals['_SIGNATURE']._serialized_start=990
+  _globals['_SIGNATURE']._serialized_end=1090
+  _globals['_SYMBOLINFORMATION']._serialized_start=1093
+  _globals['_SYMBOLINFORMATION']._serialized_end=2614
+  _globals['_SYMBOLINFORMATION_KIND']._serialized_start=1339
+  _globals['_SYMBOLINFORMATION_KIND']._serialized_end=2614
+  _globals['_RELATIONSHIP']._serialized_start=2617
+  _globals['_RELATIONSHIP']._serialized_end=2747
+  _globals['_SINGLELINERANGE']._serialized_start=2749
+  _globals['_SINGLELINERANGE']._serialized_end=2828
+  _globals['_MULTILINERANGE']._serialized_start=2830
+  _globals['_MULTILINERANGE']._serialized_end=2932
+  _globals['_OCCURRENCE']._serialized_start=2935
+  _globals['_OCCURRENCE']._serialized_end=3407
+  _globals['_DIAGNOSTIC']._serialized_start=3410
+  _globals['_DIAGNOSTIC']._serialized_end=3538
+# @@protoc_insertion_point(module_scope)

codemap/serve/api_surface.py

@@ -0,0 +1,60 @@
+"""API-surface report — view D (DESIGN §4.1-D), the M0 deliverable.
+
+The public surface of the target: public symbols grouped by module, with
+signatures, first docstring line and a deprecated marker. Reads the canonical
+graph; renders Markdown.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from codemap.model import Graph
+
+_SYMBOL_KINDS = {"class", "function", "attribute"}
+
+
+def render_api_surface(graph: Graph) -> str:
+    """Render the public API surface of ``graph`` as Markdown."""
+    by_module: dict[str, list] = defaultdict(list)
+    for node in graph.nodes.values():
+        if node.visibility != "public" or node.kind not in _SYMBOL_KINDS:
+            continue
+        module = node.id.rsplit(".", 1)[0]
+        by_module[module].append(node)
+
+    lines = [f"# API surface — `{graph.target}`", ""]
+    public_modules = sorted(
+        n.id for n in graph.nodes.values() if n.kind == "module" and n.visibility == "public"
+    )
+    total = sum(len(v) for v in by_module.values())
+    lines.append(f"_{total} public symbols across {len(public_modules)} modules._")
+    lines.append("")
+
+    for module in public_modules:
+        symbols = sorted(by_module.get(module, []), key=lambda n: n.id)
+        if not symbols:
+            continue
+        lines.append(f"## `{module}`")
+        lines.append("")
+        for node in symbols:
+            name = node.id.rsplit(".", 1)[1]
+            head = node.signature or name
+            marker = " **⚠ deprecated**" if node.is_deprecated else ""
+            lines.append(f"- **`{head}`** ({node.kind}){marker}")
+            doc = _first_line(node.docstring)
+            if doc:
+                lines.append(f"  - {doc}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _first_line(docstring: str | None) -> str | None:
+    if not docstring:
+        return None
+    for line in docstring.strip().splitlines():
+        line = line.strip()
+        if line:
+            return line
+    return None

codemap/serve/apidiff.py

@@ -0,0 +1,83 @@
+"""Render the two-graph API diff (R1-C5) — structured + markdown.
+
+The engine lives in ``codemap.apidiff``; this is the presentation shared by the
+``diff`` CLI command and the ``diff`` serve op. Breaking changes lead (that is what
+fails a release gate); removed public symbols are listed with them, since a deleted
+symbol is itself breaking.
+"""
+
+from __future__ import annotations
+
+from codemap.apidiff import ApiDiff, BREAKING, INFO, WARNING, diff_api
+from codemap.model import Graph
+
+_CAP = 40
+
+
+def build_apidiff(old: Graph, new: Graph) -> dict:
+    """Structured API diff: {old_target, new_target, ...ApiDiff.to_dict()}."""
+    d = diff_api(old, new).to_dict()
+    d["old_target"] = old.target
+    d["new_target"] = new.target
+    # a removed public symbol is itself a breaking change — fold into the count.
+    d["summary"]["breaking_total"] = d["summary"]["breaking"] + d["summary"]["removed"]
+    d["ok"] = d["summary"]["breaking_total"] == 0
+    # R1-C25/D4: the envelope says whether the pair is a before/after of the code at all.
+    from codemap.provenance import comparability
+    d["provenance"] = comparability(old.provenance, new.provenance)
+    return d
+
+
+def _bullets(items, cap=_CAP):
+    for x in items[:cap]:
+        yield f"- `{x}`"
+    if len(items) > cap:
+        yield f"- _… {len(items) - cap} more_"
+
+
+def render_apidiff(old: Graph, new: Graph) -> str:
+    d = build_apidiff(old, new)
+    s = d["summary"]
+    out = [f"# API diff — `{old.target}` → `{new.target}`", ""]
+    verdict = ("✅ **No breaking changes.**" if d["ok"]
+               else f"❌ **{s['breaking_total']} breaking change(s).**")
+    out.append(f"{verdict} {s['added']} added, {s['removed']} removed, "
+               f"{s['changed_symbols']} changed.")
+    out.append("")
+    # R1-C25/D4: a verdict about the code is only a verdict about the code when both
+    # graphs came from the same tool. Say so above the verdict, not in a footnote.
+    prov = d.get("provenance") or {}
+    if prov and not prov.get("comparable", True):
+        out.append("> ⚠️ These graphs are not directly comparable: "
+                   + "; ".join(prov["differences"])
+                   + f". Old: {prov['old']} | new: {prov['new']}. "
+                     "Differences below may be tool changes, not code changes.")
+        out.append("")
+
+    removed = d["removed"]
+    if removed:
+        out.append(f"## Removed public symbols — breaking ({len(removed)})")
+        out.extend(_bullets(removed))
+        out.append("")
+
+    by_sev = {BREAKING: [], WARNING: [], INFO: []}
+    for c in d["changes"]:
+        by_sev[c["severity"]].append(c)
+    labels = {BREAKING: "Breaking signature changes", WARNING: "Warnings (review)",
+              INFO: "Compatible changes"}
+    for sev in (BREAKING, WARNING, INFO):
+        rows = by_sev[sev]
+        if not rows:
+            continue
+        out.append(f"## {labels[sev]} ({len(rows)})")
+        for c in rows[:_CAP]:
+            out.append(f"- `{c['symbol']}` — {c['detail']}")
+        if len(rows) > _CAP:
+            out.append(f"- _… {len(rows) - _CAP} more_")
+        out.append("")
+
+    if d["added"]:
+        out.append(f"## Added public symbols ({len(d['added'])})")
+        out.extend(_bullets(d["added"]))
+        out.append("")
+    return "\n".join(out).rstrip() + "\n"

codemap/serve/architecture.py

@@ -0,0 +1,101 @@
+"""Architecture overview — the whole-system shape in one view (M16 / A9).
+
+The A9 dogfood found every local view existed (symbol, diff, column) but no
+*global* one: an architect asking "what shape is this system?" had only
+``report dependencies`` (import cycles + in-degree). This synthesises the pieces
+already in the graph — import cycles, **layers** + direction/violations (F18),
+**coupling** Ca/Ce/instability (F19), **god-objects & call-hubs** (F20) — into one
+report. No schema change: pure aggregation over the import graph / calls / contains
+/ provenance.
+"""
+
+from __future__ import annotations
+
+from codemap.diagnostics import render_lines
+from codemap.query import Query
+
+
+def build_architecture(query: Query) -> dict:
+    """Structured whole-system overview (cycles + layers + coupling + hotspots)."""
+    return {
+        "target": query.graph.target,
+        "cycles": query.import_cycles(),
+        "layers": query.layers(),
+        "coupling": query.coupling(),
+        "hotspots": query.hotspots(),
+    }
+
+
+def render_architecture(query: Query) -> str:
+    """Human markdown for the architecture overview (highest-signal first)."""
+    a = build_architecture(query)
+    ig = query.import_graph
+    core_mods = [m for m in ig.nodes if query.root_of(m) == "core"]
+    out = [f"# Architecture overview — `{a['target']}`", ""]
+    out.append(f"_{len(core_mods)} core modules, {ig.number_of_edges()} import edges._")
+    out.append("")
+    # R1-C21: with an empty import graph, "no layer violations" and "acyclic" below are
+    # *vacuous*, not clean. Each check states its own consequence (issue #8).
+    out.extend(render_lines(query.graph))
+
+    # -- layers -------------------------------------------------------------
+    lay = a["layers"]
+    out.append(f"## Layers ({len(lay['layers'])})")
+    out.append("")
+    for name, mods in lay["layers"].items():
+        out.append(f"- **{name}** — {len(mods)} module(s)")
+    out.append("")
+    out.append("### Inter-layer dependencies")
+    out.append("")
+    out.extend([f"- {edge} ({n})" for edge, n in lay["edges"].items()] or ["_none._"])
+    out.append("")
+    if lay["violations"]:
+        out.append("### ⚠ Layer violations (mutual dependency)")
+        out.append("")
+        out.extend(f"- {a} ↔ {b}" for a, b in lay["violations"])
+    else:
+        out.append("_No layer violations (no mutually-dependent layer pair)._")
+    out.append("")
+
+    # -- cycles -------------------------------------------------------------
+    out.append(f"## Import cycles: {len(a['cycles'])}")
+    out.append("")
+    out.extend([f"- {' → '.join(c)} → {c[0]}" for c in
+                sorted(a["cycles"], key=lambda c: (len(c), c))]
+               or ["_none — import graph is acyclic._"])
+    out.append("")
+
+    # -- coupling -----------------------------------------------------------
+    out.append("## Coupling (top by afferent Ca)")
+    out.append("")
+    out.append("_Ca = depended-on-by, Ce = depends-on, I = Ce/(Ca+Ce): 0 stable → 1 unstable._")
+    out.append("")
+    for r in a["coupling"][:12]:
+        out.append(f"- `{r['module']}` — Ca {r['ca']}, Ce {r['ce']}, I {r['instability']:.2f}")
+    out.append("")
+
+    # -- hotspots -----------------------------------------------------------
+    hs = a["hotspots"]
+    out.append(f"## God-object candidates (≥ methods): {len(hs['god_classes'])}")
+    out.append("")
+    out.append("_methods = concentration of behaviour; ΣCC / maxCC = McCabe complexity across them._")
+    out.append("")
+    out.extend([f"- `{g['class']}` — {g['methods']} methods, ΣCC {g['total_cc']}, maxCC {g['max_cc']}"
+                for g in hs["god_classes"]] or ["_none above threshold._"])
+    out.append("")
+    complex_fns = hs.get("complex_functions", [])
+    out.append(f"## Most complex functions (cyclomatic ≥ threshold): {len(complex_fns)}")
+    out.append("")
+    out.append("_CC = McCabe cyclomatic; MI = Maintainability Index (0–100, higher is better)._")
+    out.append("")
+    out.extend([f"- `{f['id']}` — CC {f['cc']}, MI {f['mi']} ({f['sloc']} sloc)"
+                for f in complex_fns] or ["_none above threshold._"])
+    out.append("")
+    out.append("## Call-graph hubs (in+out degree)")
+    out.append("")
+    out.append("_`pervasive` = logging/util that hubs by nature — expected noise, not risk._")
+    out.append("")
+    for h in hs["call_hubs"][:12]:
+        tag = " _(pervasive)_" if h["pervasive"] else ""
+        out.append(f"- `{h['id']}` — {h['degree']}{tag}")
+    return "\n".join(out).rstrip() + "\n"