system-diff 0.1.0__py3-none-any.whl

system_diff/__init__.py

@@ -0,0 +1,8 @@
+"""system-diff: draws a system from its code, and what each change does to it.
+
+    from system_diff import config, extract, diff, graph
+    cfg = config.load(root=Path("."))
+    bp = extract.extract(DirSource(Path(".")), cfg)
+    svg = graph.system_svg(bp, cfg)
+"""
+__version__ = "0.1.0"

system_diff/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

system_diff/agent.py

@@ -0,0 +1,197 @@
+"""Claude Code: `system-diff hook`, which its Stop hook runs after every turn, and `system-diff setup claude`, which wires
+system-diff in: the hook, a short skill telling the agent when to show the system diff, and the MCP server.
+
+The hook never blocks and never fails a turn: it says in one line what changed in the system since the checkpoint, or
+nothing when nothing structural did. Everything setup changes is printed, and `--undo` takes it back.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from .compare import compare
+from .sources import git
+
+NAME = "system-diff"
+SKILL_MARK = "<!-- written by system-diff setup claude -->"
+SKILL = f"""---
+name: system-diff
+description: Shows the person what a code change does to the system's structure (parts, endpoints, connections, settings, tables, outside systems). Use after changing code that may change the structure, before asking them to review, or when they ask what changed.
+---
+{SKILL_MARK}
+
+# Showing the system diff
+
+After a change that may touch the system's structure:
+
+1. Call the `system_diff` MCP tool, or run `system-diff diff --base checkpoint --head . --out .git/system-diff/latest`.
+2. Tell the person, in two or three plain sentences built only from its plan, what changed in the system and why it
+   matters: an endpoint added or removed, a new connection between parts, a new outside system, changed stored data,
+   or code changed without tests.
+3. Point them at the picture: the path the tool returns, or `system-diff watch` for a page that redraws as you work.
+4. When they say they have seen it, call the `checkpoint` tool (or run `system-diff checkpoint`), so the next diff
+   shows only what is new to them.
+
+Never mention a part, endpoint, table or system that is not in the plan. For a picture of something else (a process,
+a sequence of calls), use the `draw` tool.
+"""
+
+
+def _is_repo(path: Path) -> bool:
+    try:
+        return git("rev-parse", "--is-inside-work-tree", cwd=path).strip() == "true"
+    except (OSError, subprocess.CalledProcessError):
+        return False
+
+
+def hook_message(root: Path) -> Optional[str]:
+    """One line on what changed in the system since the checkpoint; None when nothing structural did."""
+    c = compare(root, "checkpoint", ".")
+    if not c.diff["changes"]:
+        return None
+    return f"System diff since {c.base}: {c.diff['headline']} (`system-diff watch` shows the picture.)"
+
+
+def run_hook(stdin_text: str, emit: Callable[[str], None] = print) -> int:
+    """What the Stop hook runs. Always exits 0: a hook that fails must not get in the agent's way."""
+    try:
+        payload = json.loads(stdin_text) if stdin_text.strip() else {}
+    except ValueError:
+        payload = {}
+    cwd = Path(payload.get("cwd") or os.getcwd())
+    if not _is_repo(cwd):
+        return 0
+    try:
+        root = Path(git("rev-parse", "--show-toplevel", cwd=cwd).strip())
+        message = hook_message(root)
+    except (OSError, subprocess.CalledProcessError, ValueError, KeyError):
+        return 0
+    if message:
+        emit(json.dumps({"systemMessage": message}))
+    return 0
+
+
+# ── setup ────────────────────────────────────────────────────────────────────
+
+SCOPES = ("user", "project", "local")
+
+
+def hook_command() -> str:
+    """How Claude Code should run system-diff: by name when it is on PATH, else this Python by its full path."""
+    if shutil.which(NAME):
+        return f"{NAME} hook"
+    exe = sys.executable
+    return f'"{exe}" -m system_diff hook' if " " in exe else f"{exe} -m system_diff hook"
+
+
+def _paths(scope: str, root: Path) -> tuple:
+    home = Path.home() / ".claude"
+    settings = {"user": home / "settings.json", "project": root / ".claude" / "settings.json",
+                "local": root / ".claude" / "settings.local.json"}[scope]
+    skills = home / "skills" if scope == "user" else root / ".claude" / "skills"
+    return settings, skills / NAME / "SKILL.md"
+
+
+def _ours(entry: Dict[str, Any]) -> bool:
+    return any("system-diff hook" in h.get("command", "") or "system_diff hook" in h.get("command", "")
+               for h in entry.get("hooks", []))
+
+
+def _load(path: Path) -> Dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8") or "{}")
+    except ValueError as exc:
+        raise SystemExit(f"{path} is not valid JSON ({exc}); fix it, then run setup again") from exc
+    if not isinstance(data, dict):
+        raise SystemExit(f"{path} is not a JSON object; fix it, then run setup again")
+    return data
+
+
+def _save(path: Path, data: Dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8", newline="\n") as f:
+        f.write(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+
+
+def _claude(args: List[str]) -> subprocess.CompletedProcess:
+    return subprocess.run(["claude", *args], capture_output=True, text=True)
+
+
+def setup_claude(root: Path, scope: str = "user", undo: bool = False, out: Callable[[str], None] = print) -> int:
+    """Add (or with `undo`, remove) the Stop hook, the skill and the MCP server, printing each change."""
+    if scope not in SCOPES:
+        raise SystemExit(f"--scope is one of {', '.join(SCOPES)}")
+    settings_path, skill_path = _paths(scope, root)
+    settings = _load(settings_path)
+    stop = settings.setdefault("hooks", {}).setdefault("Stop", [])
+    ours = [e for e in stop if _ours(e)]
+    has_claude = shutil.which("claude") is not None
+    if undo:
+        if ours:
+            settings["hooks"]["Stop"] = [e for e in stop if not _ours(e)]
+            if not settings["hooks"]["Stop"]:
+                del settings["hooks"]["Stop"]
+            if not settings["hooks"]:
+                del settings["hooks"]
+            _save(settings_path, settings)
+            out(f"removed the Stop hook from {settings_path}")
+        if skill_path.is_file() and SKILL_MARK in skill_path.read_text(encoding="utf-8"):
+            skill_path.unlink()
+            if not any(skill_path.parent.iterdir()):
+                skill_path.parent.rmdir()
+            out(f"removed the skill {skill_path}")
+        if has_claude and _claude(["mcp", "get", NAME]).returncode == 0:
+            got = _claude(["mcp", "remove", NAME, "--scope", scope])
+            out(f"removed the MCP server ({scope} scope)" if got.returncode == 0 else
+                f"could not remove the MCP server: {(got.stderr or got.stdout).strip()[:200]}")
+        out("system-diff is no longer wired into Claude Code" + ("" if scope == "user" else f" ({scope} scope)"))
+        return 0
+
+    if ours:
+        out(f"the Stop hook is already in {settings_path}")
+    else:
+        # A timeout (seconds) so a stuck git can never hold up the end of a turn; Claude Code's default is 600.
+        stop.append({"hooks": [{"type": "command", "command": hook_command(), "timeout": 30}]})
+        _save(settings_path, settings)
+        out(f"added a Stop hook to {settings_path}: after each turn, one line on what changed in the system")
+    skill_path.parent.mkdir(parents=True, exist_ok=True)
+    if skill_path.is_file() and skill_path.read_text(encoding="utf-8") == SKILL:
+        out(f"the skill is already at {skill_path}")
+    elif skill_path.is_file() and SKILL_MARK not in skill_path.read_text(encoding="utf-8"):
+        out(f"left {skill_path} alone: someone else wrote it")
+    else:
+        with open(skill_path, "w", encoding="utf-8", newline="\n") as f:
+            f.write(SKILL)
+        out(f"wrote the skill {skill_path}: when and how to show the system diff")
+    if not has_claude:
+        out("Claude Code's `claude` command is not on PATH, so the MCP server was not registered; "
+            "run setup again where it is")
+        return 0
+    try:
+        import mcp  # noqa: F401  (the extra the server needs)
+    except ImportError:
+        out('the MCP server needs its extra: pip install "system-diff[mcp]", then run setup again')
+        return 0
+    if _claude(["mcp", "get", NAME]).returncode == 0:
+        out("the MCP server is already registered")
+    else:
+        server = hook_command()[: -len(" hook")]
+        got = _claude(["mcp", "add", "--scope", scope, "--transport", "stdio", NAME, "--", *_split(server), "mcp"])
+        out(f"registered the MCP server ({scope} scope): system_map, system_diff, draw, checkpoint"
+            if got.returncode == 0 else f"could not register the MCP server: {(got.stderr or got.stdout).strip()[:200]}")
+    return 0
+
+
+def _split(command: str) -> List[str]:
+    """`"C:/Program Files/py/python.exe" -m system_diff` -> its words, the quoted path as one."""
+    if command.startswith('"'):
+        exe, rest = command[1:].split('"', 1)
+        return [exe, *rest.split()]
+    return command.split()

system_diff/cli.py

@@ -0,0 +1,214 @@
+"""system-diff: the system's structure at a git ref, the typed diff between two refs, and pictures of both.
+
+    system-diff map  [--ref REF | --dir DIR] [--out DIR]            -> system.json, system.svg
+    system-diff diff --base A [--head B|.] [--out DIR] [--narrate]  -> diff.json, diff.svg, plan.txt, headline.txt
+    system-diff readme [--json system.json] [--stale PNGS]          -> the README's generated system map
+    system-diff draw SPEC.json...                                   -> a hand-made picture beside each spec
+    system-diff png [--host HOST] FILE.svg...                       -> FILE.png beside each SVG
+    system-diff summarize --diff diff.json                          -> the plain-words summary alone
+    system-diff checkpoint [--ref REF]                              -> mark what you have seen
+    system-diff watch [--base checkpoint] [--port 8765]             -> a live page of the diff since then
+    system-diff setup claude [--scope user|project|local] [--undo]  -> the hook, a skill and the MCP server
+    system-diff mcp                                                 -> the MCP server (stdio)
+
+Deterministic: everything is read from git objects (no checkout) or a directory, with the standard library only.
+`--head .` is the working tree, uncommitted and untracked files included; `--base checkpoint` is what you last marked
+as seen (HEAD until you mark something).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__, compare, config, graph, narrate, pictures, png, readme
+from .extract import extract
+from .sources import DirSource, GitSource, repo_root
+
+
+def _write(path: Path, text: str, check: bool) -> bool:
+    """Write (or, with --check, only compare); True when the file is or would be different."""
+    if check:
+        return not path.is_file() or path.read_text(encoding="utf-8") != text
+    pictures.write_if_changed(path, text)
+    return False
+
+
+def _map(args, root: Path) -> int:
+    if args.dir:
+        on_disk = config.load(root=Path(args.dir), path=args.config)
+        source = DirSource(Path(args.dir), config.segment_rx(on_disk["code"]["skip"]))
+    else:
+        source = GitSource(args.ref or "HEAD", root)
+    cfg = config.load(source, root, args.config)
+    bp = extract(source, cfg)
+    out = Path(args.out)
+    if not args.check:
+        out.mkdir(parents=True, exist_ok=True)
+    stale = _write(out / "system.json", json.dumps(bp, indent=1, ensure_ascii=False) + "\n", args.check)
+    stale |= _write(out / "system.svg", graph.system_svg(bp, cfg), args.check)
+    if args.check:
+        print(f"system map {'is out of date' if stale else 'is current'}: {out}/system.svg")
+        return 1 if stale else 0
+    print(f"system map of {bp['ref']}: {len(bp['components'])} parts, {len(bp['externals'])} outside systems, "
+          f"{len(bp['routes'])} routes, {len(bp['tables'])} tables -> {out}/system.svg")
+    return 0
+
+
+def _diff(args, root: Path) -> int:
+    c = compare.compare(root, args.base, args.head, args.config)
+    d = c.diff
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "diff.json").write_text(json.dumps(d, indent=1, ensure_ascii=False) + "\n", encoding="utf-8", newline="\n")
+    (out / "plan.txt").write_text(d["plan"] + "\n", encoding="utf-8", newline="\n")
+    (out / "headline.txt").write_text(d["headline"] + "\n", encoding="utf-8", newline="\n")
+    svg = graph.diff_svg(d, c.before, c.after, c.cfg)
+    if svg:
+        pictures.write_if_changed(out / "diff.svg", svg)
+    elif (out / "diff.svg").is_file():
+        (out / "diff.svg").unlink()  # an older run's picture must not pass for this one
+    story = narrate.narrate(d, d["commits"], root, c.cfg) if args.narrate else None
+    (out / "narrative.md").write_text((story or "") + "\n", encoding="utf-8", newline="\n")
+    print(d["headline"])
+    return 0
+
+
+def _checkpoint(args, root: Path) -> int:
+    sha = compare.checkpoint(root, args.ref)
+    print(f"checkpoint: {args.ref or 'the working tree'} ({sha[:9]}) is what you have seen; "
+          "`system-diff diff --base checkpoint --head .` now shows only what comes after it")
+    return 0
+
+
+def _readme(args, root: Path) -> int:
+    cfg = config.load(root=root, path=args.config)
+    dormant = json.loads(Path(args.json).read_text(encoding="utf-8")).get("dormant", {}) if args.json else {}
+    path = Path(args.readme or (root / cfg["readme"]["file"]))
+    stale = [x for x in args.stale.split(",") if x]
+    if args.check:
+        r = cfg["readme"]
+        text = path.read_text(encoding="utf-8")
+        if r["begin"] not in text or r["end"] not in text:
+            print(f"{path} has no system map section")
+            return 1
+        start, end = text.index(r["begin"]), text.index(r["end"]) + len(r["end"])
+        current = text[start:end] == readme.readme_section(dormant, cfg, stale)
+        print("README system map " + ("is current" if current else "is out of date"))
+        return 0 if current else 1
+    changed = readme.update_readme(path, dormant, cfg, stale)
+    print("README system map " + ("updated" if changed else "already current"))
+    return 0
+
+
+def _summarize(args, root: Path) -> int:
+    cfg = config.load(root=root, path=args.config)
+    d = json.loads(Path(args.diff).read_text(encoding="utf-8"))
+    story = narrate.narrate(d, d.get("commits", ""), root, cfg)
+    print("BEGIN SUMMARY")
+    print(story or "")
+    print("END SUMMARY")
+    return 0 if story else 1
+
+
+def parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="system-diff", description=__doc__.split("\n")[0],
+                                 formatter_class=argparse.RawDescriptionHelpFormatter,
+                                 epilog="\n".join(__doc__.split("\n")[2:]))
+    ap.add_argument("--version", action="version", version=f"system-diff {__version__}")
+    ap.add_argument("--repo", help="the repository (default: the one holding the current directory)")
+    ap.add_argument("--config", help="a TOML or JSON config (default: system-diff.toml, or pyproject.toml's "
+                                     "[tool.system-diff])")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    m = sub.add_parser("map", help="the system as it is: system.json and system.svg")
+    m.add_argument("--ref", help="a commit, branch or tag (default HEAD)")
+    m.add_argument("--dir", help="a directory instead of a commit, e.g. . for the working tree")
+    m.add_argument("--out", default=".")
+    m.add_argument("--check", action="store_true", help="write nothing; exit 1 if the files are out of date")
+    d = sub.add_parser("diff", help="what a change does to the system")
+    d.add_argument("--base", required=True, help="a commit, or checkpoint (what you last marked as seen)")
+    d.add_argument("--head", default="HEAD", help="a commit, or . for the working tree (default HEAD)")
+    d.add_argument("--out", default=".")
+    d.add_argument("--narrate", action="store_true", help="add a plain-words summary from your LLM (narrative.md)")
+    r = sub.add_parser("readme", help="rewrite the README's system-map section")
+    r.add_argument("--json", default="", help="system.json, for the outside systems that are not drawn")
+    r.add_argument("--readme", default="")
+    r.add_argument("--stale", default="", help="comma-separated pictures that could not be redrawn")
+    r.add_argument("--check", action="store_true", help="write nothing; exit 1 if the section is out of date")
+    dr = sub.add_parser("draw", help="draw hand-made pictures from JSON specs")
+    dr.add_argument("specs", nargs="+")
+    p = sub.add_parser("png", help="SVG to PNG with headless Chromium")
+    p.add_argument("--host", help="an SSH host with Docker, when this machine has neither Docker nor Playwright")
+    p.add_argument("svgs", nargs="+")
+    s = sub.add_parser("summarize", help="the plain-words summary of a diff.json")
+    s.add_argument("--diff", required=True)
+    c = sub.add_parser("checkpoint", help="mark what you have seen: later diffs from `checkpoint` start here")
+    c.add_argument("--ref", help="a commit to mark instead of the working tree")
+    w = sub.add_parser("watch", help="a live local page of the diff since the checkpoint")
+    w.add_argument("--base", default="checkpoint")
+    w.add_argument("--port", type=int, default=8765)
+    w.add_argument("--interval", type=float, default=2.0, help="seconds between looks at the files")
+    sub.add_parser("mcp", help="run as an MCP server over stdio (needs the [mcp] extra)")
+    sub.add_parser("hook", help="what Claude Code's Stop hook runs: one line on what changed since the checkpoint")
+    st = sub.add_parser("setup", help="wire system-diff into an AI coding tool")
+    st.add_argument("tool", choices=["claude"])
+    st.add_argument("--scope", default="user", choices=["user", "project", "local"],
+                    help="user: every project (default); project: this repository, shared; local: this repository, you")
+    st.add_argument("--undo", action="store_true", help="remove what setup added")
+    return ap
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = parser().parse_args(argv)
+    root = repo_root(Path(args.repo) if args.repo else None)
+    if args.cmd == "map":
+        return _map(args, root)
+    if args.cmd == "diff":
+        return _diff(args, root)
+    if args.cmd == "readme":
+        return _readme(args, root)
+    if args.cmd == "summarize":
+        return _summarize(args, root)
+    if args.cmd == "checkpoint":
+        return _checkpoint(args, root)
+    if args.cmd == "watch":
+        from . import watch
+        watch.serve(root, args.base, args.port, args.config, args.interval)
+        return 0
+    if args.cmd == "hook":
+        from . import agent
+        return agent.run_hook(sys.stdin.read() if not sys.stdin.isatty() else "")
+    if args.cmd == "setup":
+        from . import agent
+        return agent.setup_claude(root, args.scope, args.undo)
+    if args.cmd == "mcp":
+        try:
+            from . import mcp_server
+        except ImportError:
+            print('system-diff: the MCP server needs its extra: pip install "system-diff[mcp]"', file=sys.stderr)
+            return 1
+        mcp_server.main()
+        return 0
+    if args.cmd == "draw":
+        try:
+            for out in pictures.draw_files([Path(x) for x in args.specs]):
+                print(f"drew {out}")
+        except ValueError as exc:
+            print(f"system-diff: {exc}", file=sys.stderr)
+            return 1
+        return 0
+    if args.cmd == "png":
+        try:
+            for out in png.render([Path(x) for x in args.svgs], host=args.host):
+                print(f"rendered {out}")
+        except (RuntimeError, ValueError) as exc:
+            print(f"system-diff: {exc}", file=sys.stderr)
+            return 1
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

system_diff/compare.py

@@ -0,0 +1,105 @@
+"""What changed in the system between two points, where a point is a commit, the working tree, or the CHECKPOINT: the
+last state a person marked as seen (`system-diff checkpoint`, or "Mark as seen" on the live page).
+
+The working tree is read as a SNAPSHOT: a commit made with a temporary index, so untracked files count (ignored ones do
+not) and nothing the person uses changes: not their index, not HEAD, not a branch. A checkpoint is such a snapshot kept
+under refs/system-diff/checkpoint, so it lives in this clone only and is never pushed.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from . import config
+from .diff import diff, numstat
+from .extract import Code, extract
+from .sources import GitSource, git
+
+CHECKPOINT_REF = "refs/system-diff/checkpoint"
+WORKTREE = (".", "worktree")
+_IDENTITY = {"GIT_AUTHOR_NAME": "system-diff", "GIT_AUTHOR_EMAIL": "system-diff@localhost",
+             "GIT_COMMITTER_NAME": "system-diff", "GIT_COMMITTER_EMAIL": "system-diff@localhost"}
+
+
+def _git_env(root: Path, env: Dict[str, str], *args: str) -> str:
+    return subprocess.run(["git", *args], cwd=root, env=env, check=True, capture_output=True, text=True,
+                          encoding="utf-8", errors="replace").stdout.strip()
+
+
+def _head(root: Path) -> Optional[str]:
+    try:
+        return git("rev-parse", "--verify", "-q", "HEAD", cwd=root).strip() or None
+    except subprocess.CalledProcessError:
+        return None  # a repository with no commit yet
+
+
+def worktree_tree(root: Path) -> str:
+    """The working tree's git tree id: cheap, and the same until a file changes."""
+    with tempfile.TemporaryDirectory() as tmp:
+        env = {**os.environ, "GIT_INDEX_FILE": str(Path(tmp) / "index")}
+        if _head(root):
+            _git_env(root, env, "read-tree", "HEAD")
+        _git_env(root, env, "add", "-A")
+        return _git_env(root, env, "write-tree")
+
+
+def snapshot(root: Path) -> str:
+    """The working tree as a commit (parent HEAD), made without touching the index, HEAD or any branch."""
+    tree = worktree_tree(root)
+    head = _head(root)
+    env = {**os.environ, **_IDENTITY}
+    return _git_env(root, env, "commit-tree", tree, *(["-p", head] if head else []), "-m", "system-diff snapshot")
+
+
+def checkpoint(root: Path, ref: Optional[str] = None) -> str:
+    """Mark `ref` (default: the working tree as it is now) as seen. Returns the commit it points at."""
+    sha = git("rev-parse", "--verify", f"{ref}^{{commit}}", cwd=root).strip() if ref else snapshot(root)
+    git("update-ref", CHECKPOINT_REF, sha, cwd=root)
+    return sha
+
+
+def checkpoint_sha(root: Path) -> Optional[str]:
+    try:
+        return git("rev-parse", "--verify", "-q", CHECKPOINT_REF, cwd=root).strip() or None
+    except subprocess.CalledProcessError:
+        return None
+
+
+def resolve(root: Path, point: str) -> tuple:
+    """(commit, label) for a point: `checkpoint` (else HEAD, when nothing was marked yet), `.` for the working tree,
+    or any commit."""
+    if point == "checkpoint":
+        sha = checkpoint_sha(root)
+        return (sha, "checkpoint") if sha else (_head(root) or snapshot(root), "HEAD (no checkpoint yet)")
+    if point in WORKTREE:
+        return snapshot(root), "working tree"
+    return git("rev-parse", "--verify", f"{point}^{{commit}}", cwd=root).strip(), point
+
+
+@dataclass
+class Comparison:
+    diff: Dict[str, Any]
+    before: Dict[str, Any]
+    after: Dict[str, Any]
+    cfg: Dict[str, Any]
+    base: str
+    head: str
+
+
+def compare(root: Path, base: str = "checkpoint", head: str = ".", config_path: Optional[str] = None) -> Comparison:
+    """The typed diff from `base` to `head`, both read with the head's config so a part keeps one name."""
+    (a_sha, a_label), (b_sha, b_label) = resolve(root, base), resolve(root, head)
+    head_src = GitSource(b_sha, root)
+    cfg = config.load(head_src, root, config_path)
+    a, b = extract(GitSource(a_sha, root), cfg), extract(head_src, cfg)
+    for side, point, label in ((a, base, a_label), (b, head, b_label)):
+        if point == "checkpoint" or point in WORKTREE:
+            side["ref"] = label  # a snapshot's commit id means nothing to a person
+    d = diff(a, b, numstat(root, a_sha, b_sha, cfg), cfg.get("deploy", []), Code(cfg))
+    tip = "HEAD" if head in WORKTREE else b_sha
+    d["commits"] = git("log", "--format=%s%n%n%b", f"{a_sha}..{tip}", cwd=root)[:6000] if a_sha != b_sha else ""
+    return Comparison(d, a, b, cfg, a_label, b_label)

system_diff/config.py

@@ -0,0 +1,106 @@
+"""What a project tells system-diff about itself: where its code is, what its parts are called, how to draw them.
+
+Read from the first of: the file given with --config (TOML or JSON); `system-diff.toml` at the repository root (in the
+commit being read, else on disk); `[tool.system-diff]` in pyproject.toml. Every key is optional. With none at all, each
+directory of code is a part named by its path, which is a fair first picture of most repositories.
+"""
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, Dict, Iterable, Optional
+
+FILE = "system-diff.toml"
+
+DEFAULTS: Dict[str, Any] = {
+    "code": {
+        "roots": [""],                       # path prefixes that hold code; "" is the whole repository
+        "extensions": [".py", ".ts", ".tsx", ".js", ".jsx"],
+        "skip": ["node_modules", "__pycache__", "dist", "build", ".venv*", "venv", ".git"],
+        "aliases": {},                       # import prefix -> repository path, e.g. {"@/": "web/src/"}
+        "python_paths": ["", "src/"],        # where `import a.b` is looked up
+        "group": {"default": 2},             # a part nobody declared is named by its first N path segments
+        "strip": None,                       # suffixes dropped from such a name; None: the code extensions
+    },
+    "components": [],    # [{id, label, kind, layer, container, paths, hub, quiet}]
+    "externals": [],     # [{id, label, shape, env}]: an outside system, known by the settings that reach it
+    "api": [],           # [{prefix, component}]: who serves a URL the front end calls
+    "containers": {},    # container name -> label
+    "internal_env": {},  # setting -> container it points at
+    "migrations": {},    # {glob, schemas: [[from, to, schema]], store}
+    "tests": [],         # globs of test files
+    "deploy": [],        # globs of files whose change changes what is deployed
+    "compose": "docker-compose.yml",
+    "config_files": ["docker-compose*.yml", "docker-compose*.yaml", "compose*.yml", "compose*.yaml", ".env.*example"],
+    "picture": {
+        "columns": [["ui", "What people use"], ["interface", "Entry points"], ["logic", "Logic"],
+                    ["data", "Data access"], ["store", "Stored data"], ["external", "Outside the system"]],
+        "ui_containers": ["web"],            # parts deployed here are what people use
+        "main_containers": [],               # containers not named on their parts' boxes
+        "legend": {"new": "new", "legacy": "legacy, still running", "undeclared": "not named in system-diff.toml"},
+        "hub_note": "used across the code",
+        "min_flow": 1,                       # import sites before a connection is drawn
+        "top_flows": 2,                      # connections drawn from each part, strongest first
+        "max_ext_edges": 1,                  # users drawn per outside system; its box counts the rest
+    },
+    "readme": {
+        "file": "README.md",
+        "image": "docs/diagrams/system.png",
+        "begin": "<!-- system-map:begin -->",
+        "end": "<!-- system-map:end -->",
+        "stale": ("> ⚠️ **Older than the code:** {pictures}. The last run could not redraw {it}; the next run that "
+                  "can render does, and removes this note. The `.svg` beside each picture is current and opens in a "
+                  "browser.\n\n"),
+        "how": ("Regenerated by `system-diff` from the code: the parts and their columns from `system-diff.toml`, the "
+                "connections from imports, API calls and the settings each part reads, the outside systems from the "
+                "settings a deploy configuration sets, and the tables from the migrations. Parts used everywhere are "
+                "drawn without the arrows into them, and each part keeps only its strongest connections; "
+                "`system-diff map` writes all of them to `system.json`.{dormant}"),
+        "dormant": "\n\nRead by the code but set by no deploy configuration, so not drawn: {names}.",
+    },
+    "narrate": {
+        "settings": [],                      # more Claude Code settings files, highest precedence last
+    },
+}
+
+
+def merge(base: Dict[str, Any], over: Dict[str, Any]) -> Dict[str, Any]:
+    """`over` on top of `base`: tables merge key by key, anything else is replaced."""
+    out = deepcopy(base)
+    for k, v in (over or {}).items():
+        out[k] = merge(out[k], v) if isinstance(v, dict) and isinstance(out.get(k), dict) else deepcopy(v)
+    return out
+
+
+def parse(text: str, name: str) -> Dict[str, Any]:
+    if not text.strip():
+        return {}
+    if name.endswith(".json"):
+        return json.loads(text)
+    data = tomllib.loads(text)
+    return data.get("tool", {}).get("system-diff", {}) if name.endswith("pyproject.toml") else data
+
+
+def load(source=None, root: Optional[Path] = None, path: Optional[str] = None) -> Dict[str, Any]:
+    """The project's settings over the defaults. `source` is what is being read (a commit or a directory): its own
+    system-diff.toml wins over the one on disk, so an old commit is described by the file it had."""
+    if path:
+        p = Path(path)
+        return merge(DEFAULTS, parse(p.read_text(encoding="utf-8"), p.name))
+    for name in (FILE, "pyproject.toml"):
+        text = source.read(name) if source is not None and name in source.files else ""
+        if not text and root is not None and (root / name).is_file():
+            text = (root / name).read_text(encoding="utf-8")
+        got = parse(text, name) if text else {}
+        if got:
+            return merge(DEFAULTS, got)
+    return deepcopy(DEFAULTS)
+
+
+def segment_rx(names: Iterable[str]) -> re.Pattern:
+    """A path containing a directory named like one of `names` (`*` within a name)."""
+    alts = "|".join(re.escape(n).replace(r"\*", "[^/]*") for n in names)
+    return re.compile(rf"(^|/)({alts})(/|$)") if alts else re.compile(r"(?!)")