feat(formatters): GraphML XML export for graph-producing commands (closes #59 phase-3)

[Wolfvin]

Closes #59 (phase-3)

Summary

Implements Phase 3 of issue #59 — GraphML export. Adds --format graphml to emit a GraphML 1.0 XML document for the four graph-producing commands (scan, trace, impact, circular). Output opens directly in Gephi, Cytoscape, yEd, and Neo4j. Non-graph commands produce a single-node placeholder graph so the format is always valid XML, never raises.

What changed

New files

• scripts/formatters/graphml.py — stdlib-only GraphML writer (no networkx dependency — KISS). Uses xml.etree.ElementTree. Per-command extractors:
  • scan: full call graph from SQLite graph_nodes + graph_edges
  • trace: subgraph from chains.up + chains.down
  • impact: subgraph from affected.direct + affected.indirect
  • circular: subgraph from every cycle (handles explicit-close chains like [foo, bar, foo], non-closing chains via wrap-around, and recursion self-loops)
• tests/test_graphml_formatter.py — 35 tests covering all 4 commands, placeholder fallback, GraphML XML validity (namespace, key declarations, unique node IDs, edge references resolve, boolean serialization per spec), and never-raise guarantee on weird inputs

Modified files

• scripts/formatters/__init__.py — dispatch format_output(..., "graphml") to the new formatter
• scripts/codelens.py — add "graphml" to --format choices in 3 places (subparser default, global default, pre-parse recognition)
• scripts/mcp_server.py — add "graphml" to _FORMAT_PROPERTY enum, arch-metrics schema, and 2 comment refs
• README.md — list graphml in format enum + add 4 GraphML usage examples (scan/trace/impact/circular)
• SKILL-QUICK.md — graphml row in flags table + MCP tools format note

Acceptance criteria (from issue body)

• Phase 3: GraphML opens correctly in Gephi — verified via structural validation:
  • Root element is <graphml> in the http://graphml.graphdrawing.org/xmlns namespace
  • <key> declarations for both node and edge attributes
  • <graph edgedefault="directed"> per the spec
  • All <node> IDs are unique within a single document
  • Every <edge source/target> resolves to a declared <node id>
  • Every <data key="..."> references a <key id="..."> declared at top
  • XML declaration present, UTF-8 encoded
  • Booleans serialized as true/false (not Python's True/False)
  • Never raises — returns a placeholder graph on any input (including None, lists, malformed dicts)

End-to-end verification

$ python3 scripts/codelens.py scan tests/fixtures --format graphml | head -5
<?xml version='1.0' encoding='utf-8'?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns">
  <key id="d0" for="node" attr.name="name" attr.type="string" />
  ...

$ python3 scripts/codelens.py scan tests/fixtures --format graphml | wc -l
842   # 32 nodes, 18 edges from real SQLite data

Tests

• New: 35 passed in tests/test_graphml_formatter.py
• Regression check: tests/test_formatters.py + tests/test_compact_format.py + tests/test_cli.py → 144 passed, 10 skipped, 0 failed
• Pre-existing failures (NOT regressions, confirmed via git stash):
  • tests/test_codelensignore.py::TestBackwardCompat::test_actual_target_dir_is_ignored — failing on main before this PR
  • tests/test_universal_grammar_loader.py — flaky test ordering issue with tree-sitter env var; passes in isolation

Design decisions

1. No networkx dependency — KISS rule from pre-flight SKILL.md. GraphML is a well-defined XML schema; stdlib xml.etree.ElementTree is sufficient. Avoids adding a new hard dep just for this feature.

2. Global format choice, not command-specific — Matches the pattern used by sarif (also globally available even though only some commands produce findings). Keeps the CLI surface uniform.

3. Placeholder for non-graph commands — When a command like init or doctor is invoked with --format graphml, the formatter emits a single-node graph with a warning data attribute explaining that the command doesn't produce graph data. This keeps the format always-valid XML.

4. Per-command graph extraction — Each graph-producing command has its own extractor that knows the shape of its result dict. The extractors are unit-testable in isolation (tested in TestExtractorsDirectly).

Findings (per pre-flight SKILL.md — outside scope, BOS decides)

• The issue body mentions callgraph and change-coupling commands — these don't exist in the current command registry (70 commands). The 4 existing graph-producing commands (scan, trace, impact, circular) are the ones this PR targets. If callgraph/change-coupling are added later, they can be registered in _EXTRACTORS dict in graphml.py with a one-line addition.

Branch

feat/issue-59-graphml-export

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud