Wave 5: Mermaid Accessibility Compliance + README Frontmatter Updates#696
Conversation
|
Caution Review failedThe pull request is closed. Warning Ignoring CodeRabbit configuration file changes. For security, only the configuration from the base branch is applied for open source repositories. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (14)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThis PR adds three README validation CLIs (Mermaid syntax, Mermaid accessibility, README links), publishes accessibility and completion reports (24 diagrams → 100% compliant), updates Mermaid accTitle/accDescr metadata across READMEs, and adds Issue ChangesWave 5 Audit Completion & Link Validation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 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 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces Mermaid diagram validation and accessibility compliance auditing by adding new reporting files, audit spreadsheets, and two Node.js validation scripts (validate-mermaid-accessibility.js and validate-mermaid-syntax.js). It also updates several README files to include accessibility attributes (accTitle and accDescr) in their Mermaid diagrams. The review feedback focuses on improving the robustness of the validation scripts, including supporting Windows-style line endings (\r\n), making the accDescr block closing check more precise, refining diagram type detection to avoid false positives from comments or node text, and adding checks for mismatched parentheses.
| if (inAccDescrBlock && line.includes("}")) { | ||
| inAccDescrBlock = false; | ||
| } |
There was a problem hiding this comment.
Checking line.includes("}") to close the accDescr block is fragile. If a line inside the description block contains a } character, or if the block is unclosed but a subsequent flowchart node contains a } (e.g., B{Decision}), the block will be considered closed prematurely, and the validator will fail to detect the unclosed block.
Since the closing brace of a multi-line accDescr block in Mermaid is placed on its own line, we should check if the trimmed line is exactly "}".
| if (inAccDescrBlock && line.includes("}")) { | |
| inAccDescrBlock = false; | |
| } | |
| if (inAccDescrBlock && line === "}") { | |
| inAccDescrBlock = false; | |
| } |
| if (inAccDescrBlock && line.includes("}")) { | ||
| inAccDescrBlock = false; | ||
| } |
There was a problem hiding this comment.
Checking line.includes("}") to close the accDescr block is fragile. If a line inside the description block contains a } character, or if the block is unclosed but a subsequent flowchart node contains a } (e.g., B{Decision}), the block will be considered closed prematurely, and the validator will fail to detect the unclosed block.
Since the closing brace of a multi-line accDescr block in Mermaid is placed on its own line, we should check if the trimmed line is exactly "}".
| if (inAccDescrBlock && line.includes("}")) { | |
| inAccDescrBlock = false; | |
| } | |
| if (inAccDescrBlock && line === "}") { | |
| inAccDescrBlock = false; | |
| } |
| const openBrackets = (cleanContent.match(/\[/g) || []).length; | ||
| const closeBrackets = (cleanContent.match(/]/g) || []).length; | ||
| if (openBrackets !== closeBrackets) { | ||
| errors.push( | ||
| `Mismatched brackets: ${openBrackets} open, ${closeBrackets} close`, | ||
| ); | ||
| } |
There was a problem hiding this comment.
In addition to braces and brackets, Mermaid diagrams (especially flowcharts) frequently use parentheses () for round nodes (e.g., A(Round Node)). Adding a check for mismatched parentheses would make the syntax validation more comprehensive.
const openBrackets = (cleanContent.match(/\[/g) || []).length;
const closeBrackets = (cleanContent.match(/]/g) || []).length;
if (openBrackets !== closeBrackets) {
errors.push(
"Mismatched brackets: " + openBrackets + " open, " + closeBrackets + " close",
);
}
const openParens = (cleanContent.match(/\(/g) || []).length;
const closeParens = (cleanContent.match(/\)/g) || []).length;
if (openParens !== closeParens) {
errors.push(
"Mismatched parentheses: " + openParens + " open, " + closeParens + " close",
);
}|
|
||
| function extractMermaidDiagrams(content) { | ||
| const diagrams = []; | ||
| const regex = /```mermaid\n([\s\S]*?)```/g; |
There was a problem hiding this comment.
The regular expression /```mermaid\n/ expects a Unix-style newline (\n). If any README files use Windows-style line endings (\r\n), the Mermaid diagrams in those files will not be detected.
We should make the newline check optional for \r to ensure cross-platform compatibility.
| const regex = /```mermaid\n([\s\S]*?)```/g; | |
| const regex = /```mermaid\r?\n([\s\S]*?)```/g; |
|
|
||
| function extractMermaidDiagrams(content) { | ||
| const diagrams = []; | ||
| const regex = /```mermaid\n([\s\S]*?)```/g; |
There was a problem hiding this comment.
The regular expression /```mermaid\n/ expects a Unix-style newline (\n). If any README files use Windows-style line endings (\r\n), the Mermaid diagrams in those files will not be detected.
We should make the newline check optional for \r to ensure cross-platform compatibility.
| const regex = /```mermaid\n([\s\S]*?)```/g; | |
| const regex = /```mermaid\r?\n([\s\S]*?)```/g; |
| function getDiagramType(content) { | ||
| for (const [type, pattern] of Object.entries(DIAGRAM_TYPES)) { | ||
| if (pattern.test(content)) { | ||
| return type; | ||
| } | ||
| } | ||
| // Try to extract type from first line | ||
| const firstLine = content.split("\n")[0].trim(); | ||
| const match = firstLine.match(/^(\w+)/); | ||
| return match ? match[1] : "unknown"; | ||
| } |
There was a problem hiding this comment.
The getDiagramType function uses multiline regular expressions to scan the entire diagram content. This can lead to false positives if a diagram type keyword (like graph or flowchart) appears inside a comment (e.g., %% flowchart diagram) or within node text.
Instead, we should find the first non-empty, non-comment line and extract the diagram type from it.
function getDiagramType(content) {
const lines = content.split("\n");
for (const line of lines) {
const trimmed = line.trim();
if (trimmed === "" || trimmed.startsWith("%%")) {
continue;
}
for (const type of Object.keys(DIAGRAM_TYPES)) {
if (new RegExp(`^${type}\\b`).test(trimmed)) {
return type;
}
}
if (/^stateDiagram-v2\b/.test(trimmed)) {
return "stateDiagram";
}
const match = trimmed.match(/^(\w+)/);
return match ? match[1] : "unknown";
}
return "unknown";
}| function getDiagramType(content) { | ||
| const types = { | ||
| graph: /^\s*graph\b/m, | ||
| flowchart: /^\s*flowchart\b/m, | ||
| sequenceDiagram: /^\s*sequenceDiagram\b/m, | ||
| stateDiagram: /^\s*(stateDiagram|stateDiagram-v2)\b/m, | ||
| erDiagram: /^\s*erDiagram\b/m, | ||
| gantt: /^\s*gantt\b/m, | ||
| pie: /^\s*pie\b/m, | ||
| }; | ||
|
|
||
| for (const [type, pattern] of Object.entries(types)) { | ||
| if (pattern.test(content)) { | ||
| return type; | ||
| } | ||
| } | ||
|
|
||
| const firstLine = content.split("\n")[0].trim(); | ||
| const match = firstLine.match(/^(\w+)/); | ||
| return match ? match[1] : "unknown"; | ||
| } |
There was a problem hiding this comment.
The getDiagramType function uses multiline regular expressions to scan the entire diagram content. This can lead to false positives if a diagram type keyword (like graph or flowchart) appears inside a comment (e.g., %% flowchart diagram) or within node text.
Instead, we should find the first non-empty, non-comment line and extract the diagram type from it.
function getDiagramType(content) {
const types = ["graph", "flowchart", "sequenceDiagram", "stateDiagram", "erDiagram", "gantt", "pie"];
const lines = content.split("\n");
for (const line of lines) {
const trimmed = line.trim();
if (trimmed === "" || trimmed.startsWith("%%")) {
continue;
}
for (const type of types) {
if (new RegExp(`^${type}\\b`).test(trimmed)) {
return type;
}
}
if (/^stateDiagram-v2\b/.test(trimmed)) {
return "stateDiagram";
}
const match = trimmed.match(/^(\w+)/);
return match ? match[1] : "unknown";
}
return "unknown";
}![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: c415a94815
ℹ️ 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".
| ### .github/README.md — Diagram #1 (flowchart) | ||
|
|
||
| - Missing accTitle attribute | ||
| - Missing accDescr attribute |
There was a problem hiding this comment.
The added accessibility validator still scans .github/README.md, and after this patch node scripts/validation/validate-mermaid-accessibility.js exits 1 because the four Mermaid diagrams in that file still have no accTitle/accDescr. This means the change does not achieve the advertised 100% compliance and any CI or maintainer running the new validator will still fail until those remaining diagrams are updated or the scan scope is intentionally narrowed.
Useful? React with 👍 / 👎.
| @@ -0,0 +1,323 @@ | |||
| #!/usr/bin/env node | |||
There was a problem hiding this comment.
The commit adds validate-mermaid-accessibility.js and validate-mermaid-syntax.js, but package.json still has no validate:mermaid-accessibility or validate:mermaid-syntax entries, so the documented/test-plan commands npm run validate:mermaid-* fail with “Missing script”. Add the scripts to package.json or update the documented invocation so contributors and CI can run these validators consistently.
Useful? React with 👍 / 👎.
coderabbitai
Bot
added
priority:normal
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/projects/README.md (1)
41-107:⚠️ Potential issue | 🟠 Major | ⚡ Quick winFix Mermaid block: it currently includes Markdown prose, so the diagram may fail to render (and the new
accTitle/accDescrwon’t get applied).
The ```mermaid fence starts at line 41 and isn’t closed until line 107, but lines like**\active/`** - Current Active Projects`, the bullet list, and the “File Naming Convention” section are regular Markdown inside the Mermaid code block—those aren’t valid Mermaid statements. Close the Mermaid fence before the prose (keep only Mermaid syntax inside the fence).🤖 Prompt for 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. In @.github/projects/README.md around lines 41 - 107, The Mermaid code block currently contains non-Mermaid Markdown (prose and lists) which breaks rendering; close the ```mermaid fence immediately after the valid Mermaid diagram (the graph with nodes like accTitle, accDescr, A[📂 .github/reports], B[🤖 Agents], etc.) and move the prose (the **`active/`**/`completed/` sections and "File Naming Convention" paragraph) outside that fenced block so the diagram only includes proper Mermaid syntax and the accTitle/accDescr nodes are applied correctly.
🤖 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 @.github/reports/mermaid-validation-report.md:
- Line 79: The report contains Markdown path entries like
"scripts/agents/**tests**/README.md" where `**tests**` is being interpreted as
bold; update these entries to use a literal directory name by replacing
`**tests**` with `__tests__` (e.g., "scripts/agents/__tests__/README.md") or by
escaping the underscores (e.g., "scripts/agents/\_\_tests\_\_/README.md")
wherever the same pattern appears (notably the lines around the shown diff and
line 81) so the renderer shows the real path instead of bold text.
In @.github/reports/wave-5-4-readme-discovery-audit.md:
- Around line 25-30: The audit contains inconsistent README totals (e.g., "57"
vs "52" README.md files and "No action needed: 44") — update the report so all
derived counts are computed once and propagated consistently: recalculate the
master total of README.md files and then update every related summary line (the
lines listing "Mermaid diagrams", "files requiring validation", "files with no
Mermaid diagrams", and any "No action needed" statements) so they sum correctly;
search for the alternate totals referenced in the comment (52-53, 198-199,
274-275) and replace those mismatched numbers with values derived from the
single canonical calculation to ensure the audit math is consistent end-to-end.
In `@scripts/validation/validate-mermaid-accessibility.js`:
- Around line 190-197: The compliance-rate calculation can produce NaN when
report.totalDiagrams is 0; change the inline expression to compute a guarded
value first (e.g., const complianceRate = report.totalDiagrams ?
(report.accessibleDiagrams / report.totalDiagrams) * 100 : 0) and then use
complianceRate.toFixed(1) + '%' in the console.log and file-write spots where
the current expression appears (the print at the shown block using
report.totalDiagrams/report.accessibleDiagrams and the second occurrence around
lines 241-244); update both occurrences to use the same guarded variable to
avoid NaN.
In `@scripts/validation/validate-mermaid-syntax.js`:
- Around line 193-200: The success-rate computation can produce NaN when
report.totalDiagrams is 0; before formatting the percentage in the console log
(the lines that reference report.totalDiagrams / report.validDiagrams and the
similar block at the other occurrence), compute a guarded value like const
successRate = report.totalDiagrams ? (report.validDiagrams /
report.totalDiagrams) * 100 : 0 and use successRate.toFixed(1) for display, and
apply the same guard for any other percentage calculations around the
console/logging code that reference report.totalDiagrams, report.validDiagrams,
or report.errorDiagrams.
---
Outside diff comments:
In @.github/projects/README.md:
- Around line 41-107: The Mermaid code block currently contains non-Mermaid
Markdown (prose and lists) which breaks rendering; close the ```mermaid fence
immediately after the valid Mermaid diagram (the graph with nodes like accTitle,
accDescr, A[📂 .github/reports], B[🤖 Agents], etc.) and move the prose (the
**`active/`**/`completed/` sections and "File Naming Convention" paragraph)
outside that fenced block so the diagram only includes proper Mermaid syntax and
the accTitle/accDescr nodes are applied correctly.
🪄 Autofix (Beta)
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: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 9b5b7ddf-6cdf-4335-bcd7-1767ed779256
⛔ Files ignored due to path filters (2)
.github/reports/mermaid-diagram-accessibility-spreadsheet.csvis excluded by!**/*.csv.github/reports/mermaid-diagram-audit-spreadsheet.csvis excluded by!**/*.csv
📒 Files selected for processing (9)
.github/ISSUE_TEMPLATE/README.md.github/projects/README.md.github/reports/mermaid-accessibility-report.md.github/reports/mermaid-diagram-audit.md.github/reports/mermaid-validation-report.md.github/reports/wave-5-4-readme-discovery-audit.md.vscode/README.mdscripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.js
📜 Review details
🧰 Additional context used
📓 Path-based instructions (7)
**/.github/ISSUE_TEMPLATE/*.md
⚙️ CodeRabbit configuration file
**/.github/ISSUE_TEMPLATE/*.md: Review issue template files:
- Ensure valid markdown syntax, logical structure, and clear instructions.
- Validate YAML frontmatter for required fields (title, description, labels).
- Check for accessibility (clear headings, no ambiguous language).
- Confirm templates reference related documentation.
Files:
.github/ISSUE_TEMPLATE/README.md
**/*.{js,ts,jsx,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
Follow ESLint/Prettier standards for JavaScript/TypeScript
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.js
**/*.{php,js,ts}
📄 CodeRabbit inference engine (CLAUDE.md)
Validate all input, escape all output, use nonces, never commit secrets
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.js
**/*.{html,htm,php,js,jsx,ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
WCAG 2.2 AA minimum accessibility standard; use semantic HTML, keyboard support, sufficient contrast
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.js
**/*.{js,ts,jsx,tsx,html,htm,php}
📄 CodeRabbit inference engine (CLAUDE.md)
Avoid unnecessary JavaScript, defer/lazy-load where possible, prefer native blocks
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.js
**/*.{php,js,ts,css,scss,html}
📄 CodeRabbit inference engine (AGENTS.md)
Follow WordPress Coding Standards (CSS, HTML, JavaScript, PHP) and inline-documentation standards at all times
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.js
**/*.{js,ts}
⚙️ CodeRabbit configuration file
**/*.{js,ts}: Review JavaScript/TypeScript:
- Ensure code is linted and follows project style guides.
- Check for dead code, unused variables, and clear function naming.
- Validate accessibility and performance optimisations.
- Ensure tests are isolated and do not depend on external state.
- Check for descriptive test names and clear test structure.
Files:
scripts/validation/validate-mermaid-accessibility.jsscripts/validation/validate-mermaid-syntax.js
🪛 LanguageTool
.github/reports/mermaid-accessibility-report.md
[uncategorized] ~41-~41: The official name of this software platform is spelled with a capital “H”.
Context: ... scripts/README.md - tests/README.md - .github/README.md - .github/ISSUE_TEMPLATE/READ...
(GITHUB)
[uncategorized] ~42-~42: The official name of this software platform is spelled with a capital “H”.
Context: ... tests/README.md - .github/README.md - .github/ISSUE_TEMPLATE/README.md - .github/proj...
(GITHUB)
[uncategorized] ~43-~43: The official name of this software platform is spelled with a capital “H”.
Context: ...d - .github/ISSUE_TEMPLATE/README.md - .github/projects/README.md - .vscode/README.md ...
(GITHUB)
[uncategorized] ~62-~62: The official name of this software platform is spelled with a capital “H”.
Context: ...missing accessibility attributes: ### .github/README.md — Diagram #1 (flowchart) - M...
(GITHUB)
[uncategorized] ~67-~67: The official name of this software platform is spelled with a capital “H”.
Context: ...bute - Missing accDescr attribute ### .github/README.md — Diagram #2 (sequenceDiagram...
(GITHUB)
[uncategorized] ~72-~72: The official name of this software platform is spelled with a capital “H”.
Context: ...bute - Missing accDescr attribute ### .github/README.md — Diagram #3 (graph) - Missi...
(GITHUB)
[uncategorized] ~77-~77: The official name of this software platform is spelled with a capital “H”.
Context: ...bute - Missing accDescr attribute ### .github/README.md — Diagram #4 (flowchart) - M...
(GITHUB)
[uncategorized] ~82-~82: The official name of this software platform is spelled with a capital “H”.
Context: ...bute - Missing accDescr attribute ### .github/ISSUE_TEMPLATE/README.md — Diagram #1 (...
(GITHUB)
[uncategorized] ~87-~87: The official name of this software platform is spelled with a capital “H”.
Context: ...bute - Missing accDescr attribute ### .github/projects/README.md — Diagram #1 (graph)...
(GITHUB)
.github/reports/mermaid-validation-report.md
[uncategorized] ~36-~36: The official name of this software platform is spelled with a capital “H”.
Context: ...s rate**: 100.0% ## Files Analyzed - .github/DISCUSSION_TEMPLATE/README.md - .github...
(GITHUB)
[uncategorized] ~37-~37: The official name of this software platform is spelled with a capital “H”.
Context: ...github/DISCUSSION_TEMPLATE/README.md - .github/ISSUE_TEMPLATE/README.md - .github/PULL...
(GITHUB)
[uncategorized] ~38-~38: The official name of this software platform is spelled with a capital “H”.
Context: ...d - .github/ISSUE_TEMPLATE/README.md - .github/PULL_REQUEST_TEMPLATE/README.md - .gith...
(GITHUB)
[uncategorized] ~39-~39: The official name of this software platform is spelled with a capital “H”.
Context: ...thub/PULL_REQUEST_TEMPLATE/README.md - .github/README.md - .github/SAVED_REPLIES/READM...
(GITHUB)
[uncategorized] ~40-~40: The official name of this software platform is spelled with a capital “H”.
Context: ...MPLATE/README.md - .github/README.md - .github/SAVED_REPLIES/README.md - .github/agent...
(GITHUB)
[uncategorized] ~41-~41: The official name of this software platform is spelled with a capital “H”.
Context: ...md - .github/SAVED_REPLIES/README.md - .github/agents/README.md - .github/instructions...
(GITHUB)
[uncategorized] ~42-~42: The official name of this software platform is spelled with a capital “H”.
Context: ...README.md - .github/agents/README.md - .github/instructions/.archive/README.md - .gith...
(GITHUB)
[uncategorized] ~43-~43: The official name of this software platform is spelled with a capital “H”.
Context: ...thub/instructions/.archive/README.md - .github/instructions/README.md - .github/metric...
(GITHUB)
[uncategorized] ~44-~44: The official name of this software platform is spelled with a capital “H”.
Context: ....md - .github/instructions/README.md - .github/metrics/README.md - .github/projects/RE...
(GITHUB)
[uncategorized] ~45-~45: The official name of this software platform is spelled with a capital “H”.
Context: ...EADME.md - .github/metrics/README.md - .github/projects/README.md - .github/projects/a...
(GITHUB)
[uncategorized] ~46-~46: The official name of this software platform is spelled with a capital “H”.
Context: ...ADME.md - .github/projects/README.md - .github/projects/archived/adoption-workstream-2...
(GITHUB)
[uncategorized] ~47-~47: The official name of this software platform is spelled with a capital “H”.
Context: ...tion-workstream-2026-05-26/README.md - .github/projects/archived/agent-skill-memory-pl...
(GITHUB)
[uncategorized] ~48-~48: The official name of this software platform is spelled with a capital “H”.
Context: ...ill-memory-platform/issues/README.md - .github/projects/archived/label-governance-stab...
(GITHUB)
[uncategorized] ~49-~49: The official name of this software platform is spelled with a capital “H”.
Context: ...e-stabilisation-2026-05-27/README.md - .github/projects/archived/label-governance-stab...
(GITHUB)
[uncategorized] ~50-~50: The official name of this software platform is spelled with a capital “H”.
Context: ...lisation-2026-05-27/issues/README.md - .github/projects/archived/portable-ai-plugin-re...
(GITHUB)
[uncategorized] ~51-~51: The official name of this software platform is spelled with a capital “H”.
Context: ...-plugin-restructure/issues/README.md - .github/projects/completed/github-workflow-cons...
(GITHUB)
[uncategorized] ~52-~52: The official name of this software platform is spelled with a capital “H”.
Context: ...w-consolidation-2026-05-28/README.md - .github/projects/completed/github-workflow-cons...
(GITHUB)
[uncategorized] ~53-~53: The official name of this software platform is spelled with a capital “H”.
Context: ...lidation-2026-05-28/issues/README.md - .github/prompts/README.md - .github/reports/REA...
(GITHUB)
[uncategorized] ~54-~54: The official name of this software platform is spelled with a capital “H”.
Context: ...EADME.md - .github/prompts/README.md - .github/reports/README.md - .github/schemas/REA...
(GITHUB)
[uncategorized] ~55-~55: The official name of this software platform is spelled with a capital “H”.
Context: ...EADME.md - .github/reports/README.md - .github/schemas/README.md - .github/workflows/R...
(GITHUB)
[uncategorized] ~56-~56: The official name of this software platform is spelled with a capital “H”.
Context: ...EADME.md - .github/schemas/README.md - .github/workflows/README.md - .vscode/README.md...
(GITHUB)
.github/reports/wave-5-4-readme-discovery-audit.md
[uncategorized] ~25-~25: The official name of this software platform is spelled with a capital “H”.
Context: ...README.md files** across the LightSpeed .github repository. Of these: - **24 Mermaid ...
(GITHUB)
[uncategorized] ~45-~45: The official name of this software platform is spelled with a capital “H”.
Context: ....md| 3 | 🟡 MEDIUM | Needs audit | | .github README |.github/README.md` | 4 | 🟡 M...
(GITHUB)
[uncategorized] ~45-~45: The official name of this software platform is spelled with a capital “H”.
Context: ...DIUM | Needs audit | | .github README | .github/README.md | 4 | 🟡 MEDIUM | Needs audi...
(GITHUB)
[uncategorized] ~46-~46: The official name of this software platform is spelled with a capital “H”.
Context: ....md| 4 | 🟡 MEDIUM | Needs audit | | .github ISSUE_TEMPLATE README |.github/ISSUE_...
(GITHUB)
[uncategorized] ~46-~46: The official name of this software platform is spelled with a capital “H”.
Context: ...dit | | .github ISSUE_TEMPLATE README | .github/ISSUE_TEMPLATE/README.md | 1 | 🟢 LOW ...
(GITHUB)
[uncategorized] ~47-~47: The official name of this software platform is spelled with a capital “H”.
Context: ...DME.md| 1 | 🟢 LOW | Needs audit | | .github projects README |.github/projects/REA...
(GITHUB)
[uncategorized] ~47-~47: The official name of this software platform is spelled with a capital “H”.
Context: ...eds audit | | .github projects README | .github/projects/README.md | 1 | 🟢 LOW | Need...
(GITHUB)
[uncategorized] ~59-~59: The official name of this software platform is spelled with a capital “H”.
Context: ...on | .github/README.md | .github control plane |
(GITHUB)
[uncategorized] ~59-~59: The official name of this software platform is spelled with a capital “H”.
Context: ...aid diagrams | | .github/README.md | .github control plane |
(GITHUB)
[uncategorized] ~61-~61: The official name of this software platform is spelled with a capital “H”.
Context: ...Documentation index | ✅ No diagrams | | .github/projects/README.md | Project templates...
(GITHUB)
[uncategorized] ~78-~78: The official name of this software platform is spelled with a capital “H”.
Context: ...d| Portable hooks | ✅ No diagrams | |.github/workflows/README.md` | GitHub workflow ...
(GITHUB)
[uncategorized] ~79-~79: The official name of this software platform is spelled with a capital “H”.
Context: ...orkflow definitions | ✅ No diagrams | | .github/agents/README.md | Agent specification...
(GITHUB)
[uncategorized] ~80-~80: The official name of this software platform is spelled with a capital “H”.
Context: ...gent specifications | ✅ No diagrams | | .github/instructions/README.md | Repo-local in...
(GITHUB)
[uncategorized] ~112-~112: The official name of this software platform is spelled with a capital “H”.
Context: ... | --- | --- | --- | | Issue Template | .github/ISSUE_TEMPLATE/README.md |
(GITHUB)
[uncategorized] ~113-~113: The official name of this software platform is spelled with a capital “H”.
Context: ...ins 1 Mermaid diagram | | PR Template | .github/PULL_REQUEST_TEMPLATE/README.md | ✅ No...
(GITHUB)
[uncategorized] ~114-~114: The official name of this software platform is spelled with a capital “H”.
Context: ...✅ No diagrams | | Discussion Template | .github/DISCUSSION_TEMPLATE/README.md | ✅ No d...
(GITHUB)
[uncategorized] ~115-~115: The official name of this software platform is spelled with a capital “H”.
Context: ...md| ✅ No diagrams | | Saved Replies |.github/SAVED_REPLIES/README.md` | ✅ No diagram...
(GITHUB)
[uncategorized] ~116-~116: The official name of this software platform is spelled with a capital “H”.
Context: ...EADME.md| ✅ No diagrams | | Metrics |.github/metrics/README.md` | ✅ No diagrams | #...
(GITHUB)
[uncategorized] ~122-~122: The official name of this software platform is spelled with a capital “H”.
Context: ...tatus | | --- | --- | --- | | Schemas (.github) | .github/schemas/README.md | ✅ No d...
(GITHUB)
[uncategorized] ~122-~122: The official name of this software platform is spelled with a capital “H”.
Context: ...--- | --- | --- | | Schemas (.github) | .github/schemas/README.md | ✅ No diagrams | | ...
(GITHUB)
[uncategorized] ~124-~124: The official name of this software platform is spelled with a capital “H”.
Context: ...EADME.md| ✅ No diagrams | | Prompts (.github) |.github/prompts/README.md` | ✅ No d...
(GITHUB)
[uncategorized] ~124-~124: The official name of this software platform is spelled with a capital “H”.
Context: ...| ✅ No diagrams | | Prompts (.github) | .github/prompts/README.md | ✅ No diagrams | #...
(GITHUB)
[uncategorized] ~148-~148: The official name of this software platform is spelled with a capital “H”.
Context: ...- | --- | --- | | Adoption Workstream | `.github/projects/archived/adoption-workstream-2...
(GITHUB)
[uncategorized] ~149-~149: The official name of this software platform is spelled with a capital “H”.
Context: ... ✅ No diagrams | | Agent Skill Memory | `.github/projects/archived/agent-skill-memory-pl...
(GITHUB)
[uncategorized] ~150-~150: The official name of this software platform is spelled with a capital “H”.
Context: ... diagrams | | Label Governance (main) | `.github/projects/archived/label-governance-stab...
(GITHUB)
[uncategorized] ~151-~151: The official name of this software platform is spelled with a capital “H”.
Context: ...iagrams | | Label Governance (issues) | `.github/projects/archived/label-governance-stab...
(GITHUB)
[uncategorized] ~152-~152: The official name of this software platform is spelled with a capital “H”.
Context: ... ✅ No diagrams | | Portable AI Plugin | `.github/projects/archived/portable-ai-plugin-re...
(GITHUB)
[uncategorized] ~153-~153: The official name of this software platform is spelled with a capital “H”.
Context: ...o diagrams | | Workflow Consolidation | `.github/projects/completed/github-workflow-cons...
(GITHUB)
[uncategorized] ~154-~154: The official name of this software platform is spelled with a capital “H”.
Context: ...s | | Workflow Consolidation (issues) | `.github/projects/completed/github-workflow-cons...
(GITHUB)
[uncategorized] ~160-~160: The official name of this software platform is spelled with a capital “H”.
Context: ...tatus | | --- | --- | --- | | Reports | .github/reports/README.md | ✅ No diagrams | | ...
(GITHUB)
[uncategorized] ~169-~169: The official name of this software platform is spelled with a capital “H”.
Context: ... | | --- | --- | --- | | Instructions | .github/instructions/.archive/README.md | ✅ No...
(GITHUB)
[uncategorized] ~227-~227: The official name of this software platform is spelled with a capital “H”.
Context: ....github/README.md`** (4 diagrams) - .github control plane documentation - **Prio...
(GITHUB)
.github/reports/mermaid-diagram-audit.md
[uncategorized] ~33-~33: The official name of this software platform is spelled with a capital “H”.
Context: ... Mermaid diagrams across the LightSpeed .github repository pass syntax validation. | ...
(GITHUB)
[uncategorized] ~83-~83: The official name of this software platform is spelled with a capital “H”.
Context: ...✅ Valid | Test coverage diagram | ### .github/README.md (4 diagrams) — 🟡 MEDIUM PRIO...
(GITHUB)
[uncategorized] ~92-~92: The official name of this software platform is spelled with a capital “H”.
Context: ...aph | ✅ Valid | Automation flow | ### .github/ISSUE_TEMPLATE/README.md (1 diagram) — ...
(GITHUB)
[uncategorized] ~98-~98: The official name of this software platform is spelled with a capital “H”.
Context: ...h | ✅ Valid | Issue triage flow | ### .github/projects/README.md (1 diagram) — 🟢 LOW...
(GITHUB)
🪛 OpenGrep (1.22.0)
scripts/validation/validate-mermaid-accessibility.js
[ERROR] 50-50: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.
(coderabbit.command-injection.exec-js)
scripts/validation/validate-mermaid-syntax.js
[ERROR] 61-61: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.
(coderabbit.command-injection.exec-js)
🔇 Additional comments (4)
.github/ISSUE_TEMPLATE/README.md (1)
42-45: LGTM!.vscode/README.md (1)
25-28: LGTM!.github/reports/mermaid-accessibility-report.md (1)
1-112: LGTM!.github/reports/mermaid-diagram-audit.md (1)
1-183: LGTM!
- Fix Mermaid fence in .github/projects/README.md: close fence after valid diagram, move prose outside - Add NaN guards to both validation scripts (successRate/complianceRate calculations) - Replace **tests** with __tests__ in mermaid-validation-report.md paths - Reconcile README inventory counts: fix inconsistent totals (57 vs 52 vs 44) - Update inventory header from '52 files' to '57 files' - Update 'No action needed' count from 44 to 49 files https://claude.ai/code/session_01EbzWFAdwUYXyZYkFpF1KYs
There was a problem hiding this comment.
Pull request overview
This PR targets Mermaid WCAG compliance by adding missing accTitle/accDescr attributes to non-compliant diagrams across repo READMEs, and introduces validation tooling (syntax, accessibility, README link checks) plus generated audit artefacts to support ongoing enforcement.
Changes:
- Updated Mermaid diagrams in multiple README files to include accessibility attributes (
accTitle,accDescr). - Added new Node validation scripts (Mermaid accessibility/syntax + README link checking) and exposed them via
package.jsonscripts. - Added Mermaid audit artefacts/reports and an Issue #670 task tracker document.
Reviewed changes
Copilot reviewed 28 out of 28 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/validation/validate-readme-links.js |
New README link validator (currently contains an absolute-path resolution bug). |
scripts/validation/validate-mermaid-syntax.js |
New Mermaid syntax validator (uses Mermaid CLI; current CLI invocation is not Windows-safe). |
scripts/validation/validate-mermaid-accessibility.js |
New Mermaid a11y validator and report/spreadsheet generator (output paths don’t follow reporting conventions). |
README.md |
Adds/normalises Mermaid accTitle/accDescr in several diagrams. |
package.json |
Adds validate:mermaid-* and validate:readme-links npm scripts. |
.vscode/README.md |
Adds Mermaid accessibility attributes to the workspace diagram. |
.github/reports/wave-5-4-readme-discovery-audit.md |
Adds discovery audit report (contains an internal metric inconsistency). |
.github/reports/mermaid-validation-report.md |
Adds generated Mermaid syntax validation report artefact. |
.github/reports/mermaid-diagram-audit.md |
Adds Mermaid diagram audit report artefact. |
.github/reports/mermaid-diagram-audit-spreadsheet.csv |
Adds Mermaid syntax audit CSV artefact. |
.github/reports/mermaid-diagram-accessibility-spreadsheet.csv |
Adds Mermaid accessibility audit CSV artefact. |
.github/reports/mermaid-accessibility-report.md |
Adds Mermaid accessibility report artefact (contains incorrect rendered paths). |
.github/README.md |
Adds Mermaid accessibility attributes to multiple diagrams. |
.github/projects/README.md |
Adds Mermaid accessibility attributes to the reports structure diagram and removes invalid Mermaid lines. |
.github/projects/active/issue-670-readme-refresh-tasks.md |
Adds Issue #670 tracker (frontmatter currently fails schema validation; includes US spelling). |
.github/ISSUE_TEMPLATE/README.md |
Adds Mermaid accessibility attributes to the issue workflow diagram. |
| const tmpFile = path.join( | ||
| path.dirname(fileURLToPath(import.meta.url)), | ||
| `tmp-validate-${Date.now()}.mmd`, | ||
| ); | ||
|
|
||
| fs.writeFileSync(tmpFile, content); | ||
|
|
||
| try { | ||
| await execAsync(`mmdc -i "${tmpFile}" -o /dev/null 2>&1`, { | ||
| timeout: 5000, | ||
| }); | ||
| fs.unlinkSync(tmpFile); | ||
| } catch (cliError) { | ||
| fs.unlinkSync(tmpFile); | ||
| if (cliError.stderr && cliError.stderr.includes("syntax")) { | ||
| errors.push(`Mermaid syntax error: ${cliError.stderr.split("\n")[0]}`); | ||
| } else if (cliError.message) { | ||
| errors.push(`Validation error: ${cliError.message.split("\n")[0]}`); | ||
| } | ||
| } | ||
| } catch (err) { |
| // Create audit report file with frontmatter | ||
| const reportPath = path.join( | ||
| ROOT, | ||
| ".github/reports/mermaid-validation-report.md", | ||
| ); |
| fs.writeFileSync( | ||
| path.join(ROOT, ".github/reports/mermaid-accessibility-report.md"), | ||
| reportContent, | ||
| ); | ||
| console.log( | ||
| "\n✅ Accessibility report saved to .github/reports/mermaid-accessibility-report.md", | ||
| ); | ||
|
|
||
| // Create/update comprehensive audit spreadsheet | ||
| const spreadsheetContent = csvRows.join("\n"); | ||
| fs.writeFileSync( | ||
| path.join( | ||
| ROOT, | ||
| ".github/reports/mermaid-diagram-accessibility-spreadsheet.csv", | ||
| ), | ||
| spreadsheetContent, |
- Create accessibility validation script checking for accTitle and accDescr - Audit shows 70.8% compliance (17 of 24 diagrams accessible) - Identify 7 non-compliant diagrams in .github control plane files - Generate accessibility audit report with detailed findings - Create accessibility spreadsheet for tracking missing attributes Compliant files (all 7 diagrams accessible): - README.md (7/7) - profile/README.md (4/4) - scripts/README.md (3/3) - tests/README.md (3/3) Non-compliant files requiring accessibility fixes: - .github/README.md (4 diagrams missing accTitle/accDescr) - .github/ISSUE_TEMPLATE/README.md (1 diagram) - .github/projects/README.md (1 diagram) - .vscode/README.md (1 diagram) https://claude.ai/code/session_01EbzWFAdwUYXyZYkFpF1KYs
- Add accTitle and accDescr attributes to all 4 non-compliant diagrams in .github/README.md - Implement review suggestions for validation scripts: - Support Windows line endings in diagram regex (add \r? to \n) - Improve getDiagramType to skip comments and find first non-comment line - Fix accDescr block closing check to match exactly on closing brace - Add parenthesis validation for comprehensive syntax checking - Add npm scripts to package.json for running Mermaid validators - Validation confirms 100% compliance: 24/24 diagrams now accessible - Update accessibility report and spreadsheet with final results Resolves: #669 https://claude.ai/code/session_01EbzWFAdwUYXyZYkFpF1KYs
Add comprehensive task tracking document for updating and refreshing all 57 README files across the repository with current information, fixing broken links, and ensuring consistent formatting. https://claude.ai/code/session_01EbzWFAdwUYXyZYkFpF1KYs
Create validate-readme-links.js to identify broken links across all 57 README files. Script validates: - Internal relative links (./path) - Absolute paths (/path) - Anchor links (#section) - External URLs (HTTP/HTTPS) Adds npm script: npm run validate:readme-links https://claude.ai/code/session_01EbzWFAdwUYXyZYkFpF1KYs
…ter and fix broken links - Remove deprecated 'references' frontmatter field from scripts/README.md - Add proper frontmatter with title, file_type, last_updated to both files - Fix broken documentation links in scripts/README.md (AUTOMATION_GOVERNANCE → AUTOMATION) - Remove non-existent README file links from tests/ subdirectories - Update References sections with correct paths and descriptions - Update last_updated dates to 2026-05-31 https://claude.ai/code/session_01EbzWFAdwUYXyZYkFpF1KYs
Removed deprecated auto_review configuration section that was causing unrecognized properties warnings. CodeRabbit no longer supports this configuration in the current schema. Related: Issue #670 (Wave 5 Documentation Audit)
ashleyshaw
force-pushed
the
claude/fervent-davinci-JiqKn
branch
from
83d96fa to
354cdaa
Compare
ashleyshaw
changed the title
🔍 Reviewer Summary for PR #696CI Status: ✅ Recommendations
|
- Fix inconsistent README file count in wave-5-4-readme-discovery-audit.md (57 files throughout, update status to 'Compliant') - Add NaN guards to validate-mermaid-accessibility.js to prevent division by zero - Ensure safe calculation of compliance rate when no diagrams found
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>
| domain: documentation | ||
| status: active | ||
| stability: stable |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>
| reviews: | ||
| # === Review Behaviour === | ||
| profile: "chill" # Reduce noise; prefer high-signal comments only | ||
| request_changes_workflow: true | ||
| high_level_summary: true | ||
| review_status: true | ||
| review_details: true | ||
| collapse_walkthrough: true | ||
| poem: false | ||
|
|
||
| # === Auto Review Settings === | ||
| auto_review: | ||
| enabled: true | ||
| drafts: false | ||
| base_branches: | ||
| - "main" | ||
| - "develop" | ||
|
|
||
| # === Path Filters (Exclude from Review) === |
| fs.writeFileSync( | ||
| path.join(ROOT, ".github/reports/mermaid-accessibility-report.md"), | ||
| reportContent, | ||
| ); | ||
| console.log( | ||
| "\n✅ Accessibility report saved to .github/reports/mermaid-accessibility-report.md", | ||
| ); | ||
|
|
||
| // Create/update comprehensive audit spreadsheet | ||
| const spreadsheetContent = csvRows.join("\n"); | ||
| fs.writeFileSync( | ||
| path.join( | ||
| ROOT, | ||
| ".github/reports/mermaid-diagram-accessibility-spreadsheet.csv", | ||
| ), | ||
| spreadsheetContent, | ||
| ); |
There was a problem hiding this comment.
Updated in commit 4e676fdb. The validator now reuses existing report timestamp fields (created_date, last_updated, Generated, and Date) when regenerating .github/reports/mermaid-accessibility-report.md, so repeated runs no longer introduce runtime-date-only diffs.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>
github-actions
Bot
added
area:dependencies
Summary
Comprehensive Wave 5 updates combining Mermaid accessibility compliance (Issue #669) and README frontmatter standardization (Issue #670 Phase 2). All 24 Mermaid diagrams now achieve 100% WCAG 2.2 AA compliance with proper accessibility attributes. 12 critical README files updated with standardized frontmatter and improved documentation links.
Issues Resolved
Changes
Mermaid Accessibility (#669)
7 Diagrams Fixed:
.github/ISSUE_TEMPLATE/README.md— Issue template workflow diagram.github/projects/README.md— Reports directory structure diagram.github/README.md— 4 diagrams (ecosystem, automation, repository, integration).vscode/README.md— VS Code workspace configuration diagramValidation Scripts Enhanced:
\r?\npattern)Build Automation:
validate:mermaid-accessibilitynpm scriptvalidate:mermaid-syntaxnpm scriptREADME Frontmatter Standardization (#670 Phase 2)
12 Files Updated:
scripts/README.md,tests/README.mdagents/,instructions/,plugins/,skills/,workflows/,cookbook/,hooks/READMEs.githublevel:agents/README.md,instructions/README.md,workflows/README.mdStandardized Format:
Link Validation Progress:
Documentation Updates
Next Steps
Phases 3-5 will address:
Test Plan
npm run validate:mermaid-syntaxpassesnpm run validate:mermaid-accessibilitypassesnpm run validate:frontmatterpasseshttps://claude.ai/code/session_01EbzWFAdwUYXyZYkFpF1KYs