Skip to content

Add explain command to preview structure resolution#143

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

Add explain command to preview structure resolution#143
httpdss wants to merge 2 commits intomainfrom
codex/implement-feature-from-issue-136

Conversation

@httpdss
Copy link
Copy Markdown
Owner

@httpdss httpdss commented May 8, 2026

Motivation

  • Provide a safe, no-side-effect way to inspect how a structure definition will resolve before generation, separate from generate --dry-run which simulates file operations and diffs.

Description

  • Add a new CLI command explain implemented in structkit/commands/explain.py that resolves structure definitions and reports files, folders, nested folders[].struct traversal, declared variables and resolved values, hooks (rendered but not executed), remote file references (detected but not fetched), and configured conflict behavior.
  • Register the command in the main CLI by adding ExplainCommand to get_parser() in structkit/main.py.
  • Support both text and JSON output via --json/-o json, accept --vars, --mappings-file, and --file-strategy, and use the same Jinja2 rendering environment/filters for variable resolution and with rendering.
  • Update documentation (docs/cli-reference.md, README.md) with explain usage, examples, and guidance on how it differs from generate --dry-run.
  • Add unit tests in tests/test_explain_command.py to cover CLI registration, nested structures, remote references, rendered hooks/variables, conflict behavior for existing files, text and JSON outputs, and ensure no side effects (no fetches, no subprocess runs).

Testing

  • Ran pytest tests/test_explain_command.py and the new tests passed.
  • Ran the full test suite with pytest, resulting in all tests passing (158 passed).
  • Performed static checks by compiling modules with python -m compileall structkit tests/test_explain_command.py which succeeded.
  • Exercised the CLI manually with python -m structkit.main explain project/python --json to verify JSON output, which produced the expected explanation output.

Codex Task

@httpdss httpdss added minor enhancement New feature or request labels May 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant