feat(cli): model comparison CLI + comparison docs fixes#158
Merged
villelaitila merged 1 commit intoJun 18, 2026
Conversation
Add a shell entry point for comparing two sgraph models:
python -m sgraph.cli.compare MODEL_A MODEL_B [options]
Modeled on the existing sgraph.cypher CLI (argparse, status to stderr).
Options: -f/--format {text,json}, -o/--output FILE, --rename-detection,
--exclude-attrs a,b,c. Output is either the human-readable
printCompareInfos() summary (text) or pretty-printed JSON listing added,
removed and changed elements and dependencies.
Exit codes follow git diff conventions so the command is usable as a
change gate in scripts/CI:
0 no differences
1 differences found
2 error (bad path, parse failure, usage error)
Also correct the comparison documentation, which described an API that
does not exist (compare() returning a dict, a calculateSimilarity()
method, and an Example 9 that called .get() on the result). The docs now
match the real ModelCompare API: compare()/compareModels() return an
SGraph, and getCompareInfos()/printCompareInfos() extract structured
results.
Implementation is split into a testable run(argv) -> int core and a thin
main(); 7 tests cover both output formats, the three exit codes,
--exclude-attrs and --rename-detection.
Softagram Impact Report for pull/158 (head commit: 910c308)TL;DR Changed code files: 3 | Directly impacted code files: 0⭐ Change Overview
⭐ Details of Dependency Changes
[] 📄 Full report
Impact Report explained. Give feedback on this report to support@softagram.com |
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
2 participants
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
Adds a CLI for comparing two sgraph models from the shell, and fixes the comparison documentation, which described an API that does not exist.
What's new
python -m sgraph.cli.compare MODEL_A MODEL_B [options]— diff two models (MODEL_A = before, MODEL_B = after):-f, --format {text,json}— human-readable summary (reusesModelCompare.printCompareInfos()) or pretty-printed JSON-o, --output FILE— write to a file instead of stdout--rename-detection— collapse an add+remove into a changed element annotated withold_name--exclude-attrs a,b,c— ignore the given attributes during comparisonExit codes follow
git diff(0= no differences,1= differences,2= error), so it works as a change gate in CI.The CLI mirrors the existing
sgraph.cypherCLI conventions (argparse, progress to stderr, results to stdout). No packaging change — it runs viapython -m, like the other tools.Docs
docs/api-reference.mdanddocs/examples.mddocumented an API that does not exist (compare()returning a dict, acalculateSimilarity()method, and an Example 9 that called.get()on the result). They now match the real API:compare()/compareModels()return anSGraph, andgetCompareInfos()/printCompareInfos()extract structured results.README.mdgains a short "Comparing models" section, and the new command is documented in the CLI Tools reference.Testing
tests/cli/test_compare_cli.py— 7 tests: text + JSON output, the three exit codes,--exclude-attrssuppression, and--rename-detectioncollapsing add+remove into a change.flake8 src/sgraph/cli/compare.pyclean (max line length 100).tests/test_release_automation.py(module 'release' has no attribute 'time'), which fail identically onmain.