docs: fix the docs that drifted from the code, add an architecture map and Vietnamese translations - #21
Merged
Conversation
The tool is used by an automotive team that reads Vietnamese, and the two docs a newcomer actually needs — what the tool does, and how it is put together — were English only. Both translations state up front that the English files are authoritative, so a stale translation can never quietly become the thing someone trusts. The English README and architecture doc link across to them.
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
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.
Why
The README described a tool that had moved on without it, and the one document a
newcomer most needs — how the pieces fit together — did not exist at all.
What changed
README corrections, each checked against the code rather than assumed:
Export report…/Ctrl+E, including theguarantee that it is built from the complete scan and not from what is on
screen.
view_model.py,syntax.py,review.pyandgitsource.py—view_model.pyis the seam that keeps the report and theviewer from disagreeing, and it was not named once.
a2l_rules.py, skipped the shadow step, and askedfor "a test" where the rule checklist requires two — the pattern alone, and
the same pattern beside a real change.
--reviewdid not say the badge hides changes already signed off.docs/architecture.md— new: why the core is stdlib-only, what each of thetwo diff passes decides, why the verdict lives in one function, what the result
dict guarantees downstream, and a "change X, touch Y" table.
docs/vi/— Vietnamese README and architecture doc, for the team that readsVietnamese. Both say up front that the English files are authoritative, so a
stale translation cannot quietly become the thing someone trusts.
Stale facts fixed everywhere they appeared:
build.ps1has no-Exeswitch(the default builds the exe;
-Pyz/-PyzOnlyadd or isolate the zipapp), thesmoke-render command in
CLAUDE.mdnamed a script that is not in the repo, andthe zipapp is ~110 KB — measured, not the 78–80 KB that README,
CLAUDE.mdandbuild.ps1all claimed.Checks
python -m unittest discover -s tests— 378 tests, OK.build.ps1comment.