simple_graphify - API Reference

SIMPLE_GRAPHIFY (facade)

The one class most consumers need. Create with make.

build (a_root, a_out_dir: STRING; a_deep, a_include_docs, a_full_deps: BOOLEAN): BOOLEAN

Builds the graph from directory a_root and writes all four artifacts to a_out_dir (empty string = <root>/graphify-out). True when Eiffel content was found and artifacts written; on False, last_error explains. require root_not_empty; ensure error_on_failure.

set_exclusions (a_csv: STRING)

Directory names (comma-separated) pruned from the next build's walk, matched case-insensitively at any depth.

load (a_graph_path: STRING): BOOLEAN | load_default (a_dir: STRING): BOOLEAN

Loads a graph.json. load_default probes <dir>/graphify-out/graph.json then <dir>/graph.json.

query (a_question: STRING; a_hops, a_limit: INTEGER): STRING

Markdown subgraph answering a_question. require graph_loaded: has_graph, hops_non_negative, limit_positive; ensure result_not_empty.

explain (a_name: STRING): STRING

Full record of one node: description, location, degree, community, god rank, metrics, all edges. Resolution: exact id → exact label → unique substring (ambiguity lists candidates).

path_between (a_from, a_to: STRING): STRING

Undirected shortest connection with per-hop edge kind and confidence; reports "no path" or same-node cases explicitly.

stats: STRING | report: STRING

Statistics summary; full GRAPH_REPORT.md regenerated from the loaded graph.

annotate (a_edges_path, a_graph_path: STRING): STRING

Merges edges from a JSON file ({"edges":[{"from","to","kind","why"}]}) into the stored graph as confidence inferred, re-analyzes, rewrites the file. Unknown endpoints are rejected and listed; last_error set when nothing merges.

install_skill (a_project_dir, a_exe_path: STRING): BOOLEAN

Writes the Claude Code skill into <project>/.claude/skills/graphify-eiffel/SKILL.md with a_exe_path substituted.

graph: GRAPHIFY_GRAPH | has_graph: BOOLEAN | last_error, last_summary, last_out_dir: STRING

Current graph and status of the last operation.

GRAPHIFY_GRAPH (model)

nodes: HASH_TABLE [GRAPHIFY_NODE, STRING] | edges: ARRAYED_LIST [GRAPHIFY_EDGE]

Nodes keyed by id; edges unique per (from, to, kind) — duplicates merge into weight.

node_by_id / has_node / node_count / edge_count

edges_from (a_id) / edges_to (a_id): ARRAYED_LIST [GRAPHIFY_EDGE]

connect (a_from, a_to, a_kind, a_confidence: STRING; a_line: INTEGER; a_why: STRING)

Convenience edge builder; self-loops are silently dropped, duplicates merge.

shortest_path (a_from, a_to: STRING): ARRAYED_LIST [STRING]

Undirected Dijkstra via SIMPLE_GRAPH; empty when disconnected. require both nodes present.

sorted_node_ids / sorted_edges

Deterministic orderings used by serialization (ids ascending; edges by from/to/kind).

communities: ARRAYED_LIST [GRAPHIFY_COMMUNITY] | god_node_ids | surprising | warnings

GRAPHIFY_NODE

id, kind, label, file_path, description: STRING | line, community, degree: INTEGER

flags: ARRAYED_LIST [STRING] | metrics: HASH_TABLE [INTEGER, STRING] | metric (a_name): INTEGER

Node kinds: library, cluster, class, feature, document, rationale. Class metrics: features, queries, commands, attributes, preconditions, postconditions, has_invariant, creators, loc. Flags: deferred, expanded, frozen, external, attribute, once.

GRAPHIFY_EDGE

from_id, to_id, kind, confidence, why: STRING | weight, line: INTEGER | key: STRING

Kinds: contains, depends_on, inherits, uses, creates, references, mentions. Confidence invariant-checked to extracted | inferred | ambiguous. No self-loops (class invariant).

Pipeline classes

Class	Role
`GRAPHIFY_BUILDER`	Orchestrates a build: walk → scanners → analyzer. `set_excluded` before `build`.
`GRAPHIFY_FS`	Recursive walker; collects .ecf/.e/.md, prunes EIFGENs, hidden, _deprecated, bin, graphify-out + custom exclusions.
`GRAPHIFY_ECF_SCANNER`	Pass 1a: library nodes, depends_on edges, cluster topology, containment map (tolerant tag/attribute scan, namespace-proof).
`GRAPHIFY_CLASS_SCANNER`	Pass 1b/1c: class nodes from simple_eiffel_parser; comment-aware supplier scan (uses/creates/mentions); NOTE:/WHY:/TODO: rationale nodes; deep-mode feature nodes; contract metrics from source.
`GRAPHIFY_DOC_SCANNER`	Pass 2: markdown nodes + references edges to known classes/libraries.
`GRAPHIFY_ANALYZER`	Pass 3: degrees, label-propagation communities (topology edges only), library-majority labels, god nodes, surprising cross-community links.
`GRAPHIFY_JSON_IO`	`serialized (graph): STRING` (hand-emitted, stable order) and `loaded (text): detachable GRAPHIFY_GRAPH` (via simple_json).
`GRAPHIFY_QUERY`	Scoring, neighborhood expansion, markdown rendering for query/explain/path/stats.
`GRAPHIFY_REPORT` / `GRAPHIFY_HTML` / `GRAPHIFY_DOT`	GRAPH_REPORT.md, self-contained graph.html, Graphviz DOT (via simple_graphviz).
`GRAPHIFY_SKILL_WRITER`	Claude Code skill payload + installer.
`GRAPHIFY_UTIL`	Mixin: UTF-8 conversion, path normalization, JSON escaping, merge sort, ALL_CAPS token scanning.

graph.json schema (v1.0)

{
  "schema_version": "1.0",
  "generator": "simple_graphify 1.0.0",
  "root": "D:/prod/simple_http",
  "generated_at": "2026-07-18T14:03:22",
  "mode": "standard",
  "stats": { "nodes": 214, "edges": 897, "communities": 9,
             "files_scanned": 87, "classes": 61, "documents": 12 },
  "nodes": [ { "id": "class:SIMPLE_HTTP", "kind": "class", "label": "SIMPLE_HTTP",
               "file": "src/simple_http.e", "line": 14, "community": 1, "degree": 37,
               "flags": [], "description": "...",
               "metrics": { "features": 42, "preconditions": 30, "loc": 1180 } } ],
  "edges": [ { "from": "class:SIMPLE_HTTP", "to": "class:SIMPLE_HTTP_RESPONSE",
               "kind": "uses", "confidence": "extracted", "weight": 11,
               "line": 210, "why": "supplier reference" } ],
  "communities": [ { "id": 1, "label": "simple_http", "size": 38,
                     "members_sample": ["class:SIMPLE_HTTP"] } ],
  "god_nodes": ["class:SIMPLE_HTTP"],
  "surprising": [ { "from": "doc:docs/design.md", "to": "class:HTTP_COOKIE_JAR",
                    "kind": "references", "reason": "bridges ..." } ]
}

Ordering is fully deterministic: nodes by id, edges by (from, to, kind), metrics keys sorted, member samples sorted and capped at 8.