Repository navigation
docs: simplify guides and document CLI flags - #49
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3ef4e0e2ff
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| A generated rename is applied only after a one-to-one mapping is inferred and rechecked against the shadow. Function callees require matching generated checksum roots. Literal contents are never rewritten. | ||
| - Unexplained differences remain real; scan/read/compare failures produce errors. | ||
| - Verdicts: `identical`, `comment-only`, `ignorable-only`, `real-change`, `added`, `deleted`, `error`. | ||
| - `diff_engine._status_of` owns verdict decisions; `scanner.FOLDABLE` permits only comment/noise folding. Filters never change raw verdicts, counts or exports. |
There was a problem hiding this comment.
Qualify this contract as applying to UI/view filters. The documented --exclude filter is passed to scanner.scan, where matching paths are skipped entirely, so it intentionally changes verdict counts and JSON/SARIF exports. Leaving “Filters” unqualified documents an invariant that the CLI violates and can mislead maintainers implementing or testing exclusion behavior.
AGENTS.md reference: AGENTS.md:L21-L21
Useful? React with 👍 / 👎.
| | `--json` / `--sarif` | Export comparison results for pipelines | | ||
|
|
||
| `--exit-zero` suppresses only file-difference failures, never consistency failures or incomplete scans. `--check-current` returns `0` for a policy pass, `1` for failed rules and `2` for incomplete input/scanning or unchecked items under delivery policy. | ||
| CURRENT consistency findings are terminal-only; JSON/SARIF exports contain comparison results and old/new advisories. |
There was a problem hiding this comment.
State that only JSON contains the old/new advisories. When a pipeline requests SARIF, serialize.build_sarif() emits only actionable per-file findings and has no advisory field, whereas the JSON document stores advisories under consistency; the current wording incorrectly promises SARIF consumers data they cannot receive.
Useful? React with 👍 / 👎.
longvo92
changed the title
What
Shorten the English/Vietnamese README, user guides, architecture guides and supporting READMEs using DBC Compare Tool's writing style. Copy its documentation rules into AGENTS.md while retaining this project's Python 3.8, stdlib, comparison-safety and delivery constraints.
Document all 24 current CLI flags/aliases with their purpose, defaults, mode restrictions and examples. Link both READMEs to the complete flag reference.
Why
Make setup and review tasks easier to find, remove repeated explanations and keep architecture focused on the current design. Clarify report/export behavior, consistency policies and --exit-zero without hiding coverage or export limitations.
Validation