feat: make the validated artifact the canonical CLI contract - #26
Merged
Conversation
Make schema versioning and fail-closed validation reusable by producers and consumers. Add a packaged structural golden artifact and compatibility tests as the first bounded step toward issue #23.
Build and validate local DiffGraph data once before routing the same object to JSON or terminal consumers. Define offline output, conflict, no-change, cancellation, and atomic-write behavior while preserving the legacy HTML path.
Make the default HTML report a self-contained offline consumer of the once-built validated artifact. Keep the former AI report behind an explicit deprecated legacy mode for one compatibility release.
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (8)
🚧 Files skipped from review as they are similar to previous changes (6)
WalkthroughThe CLI now creates one validated, versioned DiffGraph artifact and routes it to canonical JSON, terminal, and HTML outputs. Canonical reports are deterministic, local, and atomically written. AI HTML remains available only through explicit ChangesCanonical DiffGraph artifact
Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related issues
Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@diffgraph/cli.py`:
- Around line 329-336: Update the browser-launch block guarded by no_open in the
CLI to catch OSError from os.startfile and subprocess calls, emit a warning to
stderr, and check returncode for the macOS open and Linux xdg-open commands,
warning when either exits nonzero instead of reporting successful launch.
- Around line 254-270: Add validation alongside the existing option checks in
the CLI command handling around structural_json, output_format, and
format_was_explicit: reject --debug-env when structural_json is set,
output_format is json or terminal, or output_format is explicitly html. Raise a
click.UsageError before debug_environment() can run, while preserving existing
behavior for legacy HTML and non-canonical formats.
In `@diffgraph/contract.py`:
- Around line 33-40: Update ValidatedArtifact.from_value() and the value access
path to prevent post-validation mutation: retain an immutable representation or
a private deep copy, and return defensive copies if the value remains exposed as
a dictionary. Ensure trusted consumers such as TerminalFormatter cannot observe
changes made through the original artifact or artifact.value.
In `@diffgraph/formatters/terminal.py`:
- Around line 316-317: Update analyze_local_diff to include accurate lines_added
and lines_removed values for each changed file so the terminal formatter’s
existing fallback reports real statistics instead of zeroes. Add an integration
test covering the producer output and verifying these fields are emitted
correctly.
In `@README.md`:
- Line 58: Update the README option description for --api-key to mark it as
legacy-only, explicitly stating that it applies only when using --format
legacy-html.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 89cf217d-bd18-441f-a58a-8b6ef3d02a36
📒 Files selected for processing (14)
README.mddiffgraph/artifact.pydiffgraph/cli.pydiffgraph/contract.pydiffgraph/formatters/html.pydiffgraph/formatters/terminal.pydiffgraph/schema/diffgraph-v2.structural.example.jsondiffgraph/structural.pysetup.pytests/test_artifact_dispatch.pytests/test_contract.pytests/test_html_formatter.pytests/test_structural.pytests/test_terminal_formatter.py
Keep canonical artifact output isolated from environment diagnostics, preserve successful HTML generation when browser launch fails, and populate deterministic file line statistics. Clarify that API credentials belong only to the deprecated legacy renderer and cover each behavior with regression tests.
This was referenced Aug 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
legacy-htmlfor one compatibility releaseContract behavior
schema_versionmust useMAJOR.MINOR2.xartifacts are accepted only when valid against the packaged consumer schemaVerification
python3 -m pytest -q— 94 passedpython3 -m compileall -q diffgraph tests mcp_server.py build.pygit diff --checkFollow-up compatibility
Companion extension compatibility PR: WildestAI/wildest-vscode-ext#24. It vendors this exact golden fixture and exercises the same version policy in extension CI. The broader JSON-backed Webview migration remains scoped to
wildest-vscode-ext#17.Closes #23
Summary by CodeRabbit
New Features
Improvements
Documentation