feat(cli): add cgc diff against saved index snapshots (#1312) - #1736

Closes #1312.

Implements cgc snapshot save [--name], cgc snapshot list and cgc diff [--against] [--json] [--limit] [--fail-on-changes], so a graph state can be captured before a change and compared afterwards instead of re-querying by hand.

Format decision, JSON schema and exit codes were posted in the issue first, as requested: #1312 (comment)

Snapshot format

A snapshot is a lightweight JSON manifest, not a .cgc bundle, stored at ~/.codegraphcontext/snapshots/<name>.json (format: cgc-snapshot, format_version: 1, checked on read like bundle files):

• cgc diff needs identity + content digest, not the payload, so manifests stay small enough to keep around (14-node probe repo → ~22 KB), and reading one never mutates the database the way loading a bundle would.
• id is the graph's own primary key (CGCBundle._PK_MAP / _UID_PARTS, including uid synthesis for backends that do not persist it), so snapshots agree with cgc bundle export and across Neo4j/Kùzu.
• digest strips volatile properties (Repository.indexed_at), so untouched code diffs to nothing.
• Atomic writes, names restricted to ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$, existing names need --force.

JSON documents and exit codes

• cgc diff --json → cgc-diff v1: base{}, current{}, summary{nodes, edges, total}, nodes{added, removed, changed}, edges{added, removed, changed}; changed rows carry reason (properties | moved | target), before/after and changed_properties[].
• cgc snapshot save --json → cgc-snapshot-save receipt (summary, not the manifest); cgc snapshot list --json → cgc-snapshot-list (unreadable files become an error entry instead of hiding the rest).
• Exit codes: 0 no differences / no gate requested, 1 differences under --fail-on-changes or a snapshot/initialisation error, 2 bad usage (invalid name, negative --limit).

Streams

Product on stdout — cgc diff --json > changes.json parses — init chatter and errors on stderr, following the #1725 split. Human output is ASCII only (+ - ~, ->, |), because a non-ASCII glyph raises UnicodeEncodeError on a cp1252 console the moment output is redirected.

Diff semantics

1. A line shift is a move, not churn. A node uid embeds line_number, so typing a line above a function re-keys it; a naive set diff would report one deletion plus one identical addition. Unambiguous matches pair on a label + name + path + ownership chain signature and report as ~ … (moved, …); ambiguous pairs (two same-named functions in one file) stay add/remove rather than being guessed.
2. Edge rows stay silent when only endpoint uids moved — an edge id embeds both endpoints, so otherwise every file edit triples the output.
3. Retargets fold into one ~ CALLS a -> b (target changed) row only when exactly one removed and one added edge share source/type and the new target already existed in the base graph, so a file that gained refund while losing legacy_checkout does not claim its CONTAINS edge was retargeted.
4. Owner-scoped names qualify (pay.amount), so same-named parameters stay distinguishable — via ownership edges only, so a CALLS edge never re-labels its callee.

Scope

CLI layer only: core/graph_snapshot.py (format/diff/render logic), cli/snapshot_commands.py (paths, orchestration, print() to stdout), Typer wiring in cli/main.py. No MCP tool, UI, database or bundle changes.

Tests

• tests/unit/core/test_graph_snapshot.py — identity, pairing/ambiguity, retarget rules, documents, ASCII rendering, limit truncation.
• tests/integration/test_snapshot_diff_cli.py — index → save → edit → re-index → diff, JSON parse, exit codes, stdout/stderr split (list-argv subprocesses, so it runs on Windows too).
• tests/integration/cli/test_cli_commands.py — three new canonical-matrix entries, with the fake session answering the snapshot queries, so the inventory meta-test covers the new commands.

ruff clean on all new/changed files; tests/unit matches the pre-existing baseline (8 known failures, verified against a864a9f).