Add report documentation quality checker#222
Conversation
pranavisrikanth
requested review from
6igby,
du-dhartley and
liyunze-coding
as code owners
![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: c59d4f3c38
ℹ️ 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".
| missing_sections = [ | ||
| section for section in REQUIRED_SECTIONS if section not in content | ||
| ] |
There was a problem hiding this comment.
Make the section check validate actual heading lines instead of using substring containment. As written, any occurrence of ## Purpose-like text (for example in a code block, quoted example, or metadata) will satisfy the requirement even if the real section header is missing, so this checker can report false passes and weaken documentation quality enforcement.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Updated in the latest commit. The checker now validates against actual markdown heading lines instead of generic substring matches to reduce false positives.
du-dhartley
left a comment
du-dhartley
left a comment
There was a problem hiding this comment.
@pranavisrikanth I've approved this PR, but documentation elsewhere will need to be updated so that future contributors are aware that this tool exists and can be used. It would be more beneficial if usage of this was automated somehow but there's no evidence that this was planned.
Please merge this PR, but also establish a place where documentation can be updated to point contributors to this tool.
2 participants
Summary
This PR adds a lightweight Python utility script to support documentation quality validation for AutoAudit GRC/reporting artefacts.
The script checks markdown files for required sections and helps future contributors maintain more consistent report documentation structure.
Type of Change
Affected Components
/backend-api/frontend/engine(collectors / policies)/security/infrastructure/.github/workflows/docsMotivation
Recent GRC/report generation work highlighted the need for more consistent documentation structure across reporting artefacts. This utility provides a simple validation mechanism for required markdown sections.
Testing Done
Tested manually by running:
python tools/check_report_doc_quality.py README.md