feat(export): contextix export --format mermaid|json

[tmchow]

Summary

Adds a new contextix export command that renders a subgraph around an entity as JSON (default) or a Mermaid flowchart. Wires into the existing extractSubgraph BFS; no changes to the graph types or store.

contextix export --format mermaid --entity "Jerome Powell" --hops 2
contextix export --format json --entity "Fed Funds Rate" --hops 1

Closes #14.

Acceptance (from the issue)

• --format accepts json (default) and mermaid. Unknown values exit 1 with a clear message; cypher / d2 are left for future formats.
• --entity <name> + --hops <N> scope the export. extractSubgraph does BFS up to N hops (default 2) bounded by --max-nodes (default 200).
• Output goes to stdout -- user can pipe to a file (> foo.mmd) or another tool.

Files

• New: src/export/mermaid.ts (57 lines) -- pure function that turns a SubGraph into a Mermaid flowchart string.
• Modified: src/index.ts -- new program.command("export") block registered alongside the existing commands.

No changes to src/graph/types.ts, src/graph/query.ts, or the data file format.

Mermaid renderer details

• Graph node ids (e.g. ent_person_jerome_powell) are not valid Mermaid identifiers. The renderer builds a per-subgraph alias map that sanitizes ids to [A-Za-z0-9_] with _N disambiguation on collision.
• Node labels use entity.name or event.title so the diagram reads like the underlying graph instead of exposing raw ids.
• Edge labels carry the relation type (involves, influences, ...).
• Labels are wrapped in "..." (Mermaid's double-quoted label syntax); embedded double quotes escape to ".

Testing

Built and smoke-checked against data/seed-graph.json:

$ npm run build
... tsup ⚡️ Build success in 18ms

$ node dist/index.js export --format mermaid --entity "Jerome Powell" --hops 2 --data-dir /tmp/contextix-test
graph LR
  evt_macro_a1b2c3["Fed holds rates steady at 4.25-4.50%"]
  evt_macro_d4e5f6["March CPI comes in at 2.4% YoY, below expectations"]
  evt_macro_p7q8r9["US unemployment claims rise to 245K"]
  ent_person_jerome_powell["Jerome Powell"]
  ent_org_federal_reserve["Federal Reserve"]
  ent_policy_fed_funds_rate["Federal Funds Rate"]
  ent_org_federal_reserve -->|involves| evt_macro_a1b2c3
  ent_person_jerome_powell -->|involves| evt_macro_a1b2c3
  evt_macro_a1b2c3 -->|involves| ent_policy_fed_funds_rate
  evt_macro_d4e5f6 -->|influences| evt_macro_a1b2c3
  evt_macro_p7q8r9 -->|influences| evt_macro_a1b2c3

$ node dist/index.js export --format json --entity "Jerome Powell" --hops 1 --data-dir /tmp/contextix-test
{ "query": "Jerome Powell", "radius": 1, "nodes": [...], "edges": [...] }

$ node dist/index.js export
export: --entity <name> is required
(exit 1)

$ node dist/index.js export --entity "Test" --format yaml --data-dir /tmp/contextix-test
export: unsupported --format "yaml" (supported: json, mermaid)
(exit 1)

Closes #14

---

This contribution was developed with AI assistance (Claude Code).

[kiyeonjeon21]

Thanks @tmchow — really clean first PR. The alias map for Mermaid ids handles the : problem elegantly, and keeping the else-if chain open for cypher / d2 later was the right call. Merged.