simple_graphify - Cookbook

Recipe: Onboard onto an unfamiliar library

simple_graphify build D:/prod/simple_sql
# open graphify-out/GRAPH_REPORT.md -> God Nodes section
simple_graphify explain SIMPLE_SQL_DATABASE

The god nodes are the integration hubs; explain on the top one shows the whole shape: what it inherits, what it drives (weighted), and everything that depends on it. Real output for simple_sql showed the facade funneling all SQLite access through a single SQLITE_DATABASE supplier edge — the engine isolation was visible in one command.

Recipe: Impact analysis before a refactor

simple_graphify explain HTTP_COOKIE_JAR
# read the Incoming section: every client that will feel the change

Incoming uses/creates edges with weights tell you which callers are heavy consumers and which touch the class once.

Recipe: "How do these two subsystems even relate?"

simple_graphify path SIMPLE_SCHOLAR SIMPLE_SQL_DATABASE

The hop chain names the classes that join the two, with the edge kind and confidence at every step. Cross-check inferred hops against source before acting on them.

Recipe: Map a whole ecosystem (and keep it honest)

simple_graphify build D:/prod --exclude "gobo-gobo-25.09,_non-eiffel,simple_gobo"

Exclude vendored compiler/library source trees, or their classes (BOOLEAN, ANY, ARRAYED_LIST) become false god nodes with thousands of edges. Symptom to watch for: base-library class names at the top of the god list. Measured on a 112-library ecosystem: 40 s, 5,917 nodes, 28,410 edges, 875 communities.

Recipe: Contract-coverage audit

simple_graphify report | grep -A 30 "Contract Coverage"

The report ranks classes by contract clauses and lists contract-free classes as hardening candidates — a ready-made worklist for /eiffel.harden. (Ecosystem measurement: 72% of 2,332 classes carry contracts.)

Recipe: Claude Code, graph-first

simple_graphify build .
simple_graphify install

From the next session, structural questions ("what depends on X?", "how is Y wired?") route through the graph instead of file search. The skill also teaches Claude to record its own inferred connections:

echo '{"edges":[{"from":"class:RETRY_POLICY","to":"doc:docs/resilience.md",
  "kind":"references","why":"design rationale"}]}' > edges.json
simple_graphify annotate edges.json

Keep edges.json files in the repo; re-apply them after rebuilds.

Recipe: Render the graph as SVG

dot -Tsvg graphify-out/graph.dot -o graph.svg      # requires Graphviz
# or just open graphify-out/graph.html - no dependencies at all

Troubleshooting

Symptom	Cause & fix
"GRAPH NOT LOADED"	No graph.json in ./graphify-out or . — run `build` first or pass `--graph FILE`.
Base-library classes as god nodes	Vendored source tree in the walk — add `--exclude`.
"Syntax error" lines during build	Gobo rejecting an odd file; the fallback parser takes over and the build continues. Check the report's warnings.
Node not found in `explain`	Use the label (`SIMPLE_HTTP`) or full id (`class:SIMPLE_HTTP`); the error lists closest labels.
Duplicate class warnings	Same class name in multiple libraries (every `TEST_APP`); first registration wins — expected at ecosystem scale.
One giant community	Shared test-scaffolding names glue libraries; query within a library or exclude test clusters for a cleaner map.