Skip to content

Add graph command to visualize structure dependencies#142

Draft
httpdss wants to merge 2 commits intomainfrom
codex/implement-feature-from-issue-138
Draft

Add graph command to visualize structure dependencies#142
httpdss wants to merge 2 commits intomainfrom
codex/implement-feature-from-issue-138

Conversation

@httpdss
Copy link
Copy Markdown
Owner

@httpdss httpdss commented May 8, 2026

Motivation

  • Provide a way to inspect how folders[].struct references compose structures so users can reason about nested dependencies, detect missing references, and identify cycles.
  • Support both human-readable and machine-consumable outputs (text tree, JSON, Mermaid) so the data can be used in docs, CI, and tooling.

Description

  • Add a new GraphCommand implemented in structkit/commands/graph.py that resolves structure paths, extracts folders[].struct dependencies, detects cycles, and records missing references.
  • Support CLI options --all, --format {text,json,mermaid}, and -s/--structures-path, and hook the command into the main parser via structkit/main.py.
  • Implement renderers for text tree, JSON (format_json), and Mermaid (format_mermaid) including Mermaid classes for missing references and cycles, and safe node id/label escaping.
  • Add comprehensive tests in tests/test_graph_command.py and update docs (README.md, docs/usage.md, docs/cli-reference.md) with usage examples.

Testing

  • Ran pytest tests/test_graph_command.py, which passed (all tests green).
  • Ran the full test suite with pytest, which passed (163 passed).
  • Exercised the CLI manually with python -m structkit.main graph --help, python -m structkit.main graph terraform/apps/generic --format mermaid, and python -m structkit.main graph --all --format json, all producing the expected outputs.

Codex Task

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant