diff --git a/.github/instructions/.archive/frontmatter.instructions.md b/.github/instructions/.archive/frontmatter.instructions.md index e815260d..08cc5915 100644 --- a/.github/instructions/.archive/frontmatter.instructions.md +++ b/.github/instructions/.archive/frontmatter.instructions.md @@ -1,8 +1,8 @@ --- file_type: "instructions" title: "Frontmatter Instructions" -version: "v1.1" -last_updated: "2025-12-04" +version: "v1.2" +last_updated: "2026-06-19" author: "LightSpeedWP" maintainer: "Ash Shaw" description: "Instructions for creating and validating YAML frontmatter for all LightSpeedWP documentation and code files." @@ -83,9 +83,9 @@ references: - VS Code and Copilot validate automatically if configured (see `.vscode/settings.json`). ```mermaid +graph TD accTitle: Frontmatter validation flow accDescr: Shows how a file with frontmatter moves through schema validation and either passes or returns for correction before automation uses it. -graph TD A[File with Frontmatter] --> B[Schema Validation] B -->|Valid| C[Accepted] B -->|Invalid| D[Error: Fix Required] @@ -357,3 +357,9 @@ Collections already use `tags:`. Add optional `stability:` and `domain:` keys al - [ ] Plans removal after one release cycle --- + +--- + +๐Ÿ“ *Schema validated by LightSpeedWP โ€” always compliant.* + +[๐Ÿ“‹ Coding Standards](https://github.com/lightspeedwp/.github/blob/develop/instructions/coding-standards.instructions.md) ยท [๐Ÿ”— Related Files](https://github.com/lightspeedwp/.github/tree/develop/instructions) diff --git a/.github/instructions/.archive/tests.instructions.md b/.github/instructions/.archive/tests.instructions.md index ee4eb34a..67564236 100644 --- a/.github/instructions/.archive/tests.instructions.md +++ b/.github/instructions/.archive/tests.instructions.md @@ -85,9 +85,9 @@ You are the test style and quality enforcer for LightSpeed projects. Maintain co ## ๐Ÿงช Testing Pyramid ```mermaid +graph TD accTitle: Testing pyramid overview accDescr: Shows how end-to-end, integration, unit, and static analysis layers stack within the testing strategy. -graph TD A[E2E Tests
Playwright] --> B[Integration Tests
Jest + PHPUnit] B --> C[Unit Tests
Jest + PHPUnit + pytest] C --> D[Static Analysis
ESLint + PHPCS + mypy] @@ -96,9 +96,9 @@ graph TD ## ๐Ÿ”„ Test Execution Flow ```mermaid +sequenceDiagram accTitle: Test execution flow accDescr: Shows how a developer runs local tests, receives coverage feedback, and then CI repeats the test stages and quality gate checks. -sequenceDiagram participant Dev as Developer participant Local as Local Tests participant CI as CI Pipeline @@ -177,9 +177,9 @@ sequenceDiagram ## ๐Ÿ“Š Test Coverage Matrix ```mermaid +graph LR accTitle: Test coverage matrix accDescr: Shows how code changes branch into unit, integration, and end-to-end tests before reaching the quality gate. -graph LR A[Code Changes] --> B{Test Type} B --> C[Unit Tests
Fast & Isolated] B --> D[Integration Tests
Component Interaction] @@ -240,5 +240,10 @@ graph LR --- +--- --- + +๐Ÿ“ *Schema validated by LightSpeedWP โ€” always compliant.* + +[๐Ÿ“‹ Coding Standards](https://github.com/lightspeedwp/.github/blob/develop/instructions/coding-standards.instructions.md) ยท [๐Ÿ”— Related Files](https://github.com/lightspeedwp/.github/tree/develop/instructions) diff --git a/.github/reports/mermaid/diagram-validation-2025-12-11.md b/.github/reports/mermaid/diagram-validation-2025-12-11.md index 027d2b6e..64bc22d9 100644 --- a/.github/reports/mermaid/diagram-validation-2025-12-11.md +++ b/.github/reports/mermaid/diagram-validation-2025-12-11.md @@ -2,9 +2,9 @@ file_type: "documentation" title: "Mermaid Diagram Validation Report" description: "Comprehensive validation of all Mermaid diagrams across top-level folders with WCAG AA accessibility and structural checks" -version: "1.1" +version: "1.2" created_date: "2025-12-11" -last_updated: "2026-06-18" +last_updated: "2026-06-19" author: "GitHub Copilot" maintainer: "LightSpeed Team" category: "mermaid" @@ -280,9 +280,9 @@ tags: ["mermaid", "validation", "accessibility", "documentation", "diagrams"] - **Example**: ```mermaid + flowchart TB accTitle: Mermaid validation scope overview accDescr: Shows how the validation report groups README files into a simple top-level flowchart for the scan scope. - flowchart TB A[LightSpeed Org] --> B[Community Health] A --> C[Documentation] A --> D[Scripts & Automation] @@ -340,5 +340,8 @@ All Mermaid diagrams in top-level folders meet validation standards and WCAG AA --- -*Report generated by GitHub Copilot on 2025-12-11* -*Validation performed according to update-mermaid-diagrams.prompt.md* +--- + +๐Ÿ” *Audit report generated {audit_date} by the LightSpeedWP team.* + +[๐Ÿ“‹ Reports Index](https://github.com/lightspeedwp/.github/tree/develop/.github/reports) ยท [๐Ÿ“ž Contact](https://lightspeedwp.agency/contact) diff --git a/CHANGELOG.md b/CHANGELOG.md index a365ffa4..424fe86d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,6 +49,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- **Mermaid validator hardened to reject `accTitle`/`accDescr` placed before diagram type** โ€” Added a guard in `scripts/validation/validate-mermaid-accessibility.js` that rejects any Mermaid block where `accTitle` or `accDescr` appears before the diagram type declaration (e.g. `flowchart TD`). Corrected all 20 affected diagrams across 9 files (`.github/instructions/.archive/frontmatter.instructions.md`, `.github/instructions/.archive/tests.instructions.md`, `.github/reports/mermaid/diagram-validation-2025-12-11.md`, `CONTRIBUTING.md`, `docs/HUSKY_PRECOMMITS.md`, `instructions/automation.instructions.md`, `instructions/documentation-formats.instructions.md`, `instructions/linting.instructions.md`, `instructions/quality-assurance.instructions.md`) to place the diagram type first. 60/60 diagrams are now compliant. + - **Mermaid YAML front-matter converted to inline accessibility syntax** โ€” Replaced all Mermaid `---` YAML front-matter blocks (unsupported by GitHub's renderer) with inline `accTitle` and `accDescr` attributes placed directly after the diagram type declaration. Affected files: `.github/ISSUE_TEMPLATE/README.md`, `.github/README.md`, `.github/prompts/update-mermaid-diagrams.prompt.md`, `.github/reports/audits/2026-06-03-file-organisation-migration-plan-673.md`, `.vscode/README.md`, `docs/AGENT_CREATION.md`, `docs/CANONICAL_CONFIGS_GUIDE.md`. Updated `scripts/validation/validate-mermaid-accessibility.js` to ignore `.claude/**` worktree directories and use a regex for `accDescr {` block detection. Updated `instructions/mermaid.instructions.md` to explicitly forbid YAML front-matter syntax. Closes [#991](https://github.com/lightspeedwp/.github/issues/991). ([#995](https://github.com/lightspeedwp/.github/pull/995)) - **`label-sync.js` crash on YAML-ambiguous hex color values** โ€” YAML parses bare hex strings such as `8957E5` (parsed as scientific notation `895700000`) and `007580` (parsed as integer `7580`) as numbers, causing `labelObj.color.replace is not a function` in the Unified Labeling workflow. Quoted all affected `color:` values in `.github/labels.yml` and added `String()` coercion in `scripts/agents/includes/label-sync.js` as defence-in-depth. ([#995](https://github.com/lightspeedwp/.github/pull/995)) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6b18f91..7438a7c3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,8 @@ file_type: "documentation" title: "Contributing Guidelines" description: "Comprehensive contribution guidelines for LightSpeed community health repository including setup, standards, and workflow" -version: '1.5' -last_updated: '2026-06-18' +version: '1.6' +last_updated: '2026-06-19' owners: ["LightSpeed Team"] tags: ["contributing", "guidelines", "workflow", "standards", "pull-requests"] --- @@ -30,9 +30,9 @@ For details, see the full guidelines below and the [Documentation Index](./docs/ --- ```mermaid +flowchart TD accTitle: Contribution workflow accDescr: Shows the end-to-end contribution path from issue discussion through branch creation, implementation, validation, pull request review, and merge. -flowchart TD A[Open Issue or Feature Request] --> B[Discuss & Plan] B --> C[Create Branch] C --> D[Write Code & Tests] diff --git a/docs/HUSKY_PRECOMMITS.md b/docs/HUSKY_PRECOMMITS.md index 8f41458e..92586791 100644 --- a/docs/HUSKY_PRECOMMITS.md +++ b/docs/HUSKY_PRECOMMITS.md @@ -2,8 +2,8 @@ file_type: documentation title: Husky Pre-commit Hooks description: Using Husky to enforce quality gates (linting/tests) before commits -version: 1.0.2 -last_updated: '2026-06-18' +version: 1.0.3 +last_updated: '2026-06-19' owners: - LightSpeed DevOps tags: @@ -116,9 +116,9 @@ If tests fail, the push is aborted and you must fix the issues before trying aga ## Workflow Overview ```mermaid +flowchart LR accTitle: Husky workflow overview accDescr: Shows how staged files trigger lint-staged during pre-commit, then tests run during pre-push before code reaches the remote repository. -flowchart LR A[Stage Files] --> B[git commit] B --> C{Pre-commit Hook} C -->|Run lint-staged| D{Checks Pass?} @@ -689,3 +689,9 @@ After testing: 5. โœ… Review [HUSKY_PRECOMMITS.md](https://github.com/lightspeedwp/.github/blob/HEAD/docs/HUSKY_PRECOMMITS.md) for detailed documentation --- + +--- + +*Built by ๐Ÿงฑ LightSpeedWP with โ˜•, ๐Ÿš€, and open-source spirit!* + +[๐Ÿ”— Website](https://lightspeedwp.agency) ยท [๐Ÿ“ง Contact](https://lightspeedwp.agency/contact) ยท [๐Ÿ‘ฅ Contributors](https://github.com/lightspeedwp/.github/graphs/contributors) diff --git a/instructions/automation.instructions.md b/instructions/automation.instructions.md index 53a828fb..040f925e 100644 --- a/instructions/automation.instructions.md +++ b/instructions/automation.instructions.md @@ -4,8 +4,8 @@ title: Automation Standards description: Comprehensive standards for GitHub automation agents, workflows, and repository health management scope: repo-local -version: v1.1.2 -last_updated: '2026-06-18' +version: v1.1.3 +last_updated: '2026-06-19' owners: - GitHub Community Health Team tags: @@ -78,9 +78,9 @@ Ensure consistent, reliable, and maintainable automation across GitHub repositor ### System Overview ```mermaid +graph TB accTitle: Automation architecture overview accDescr: Shows how GitHub events trigger workflows, which invoke agents and produce labels, summaries, releases, and metrics. -graph TB subgraph "GitHub Events" A[Issue Created] B[PR Opened] @@ -668,9 +668,9 @@ jobs: ### Automation Pipeline ```mermaid +sequenceDiagram accTitle: Automation pipeline sequence accDescr: Shows the end-to-end automation sequence from a GitHub event through workflow execution, agent processing, API updates, and reporting. -sequenceDiagram participant Event as GitHub Event participant Workflow as Workflow participant Agent as Agent @@ -781,3 +781,9 @@ echo $? - Test with dry-run mode --- + +--- + +๐Ÿ“ *Schema validated by LightSpeedWP โ€” always compliant.* + +[๐Ÿ“‹ Coding Standards](https://github.com/lightspeedwp/.github/blob/develop/instructions/coding-standards.instructions.md) ยท [๐Ÿ”— Related Files](https://github.com/lightspeedwp/.github/tree/develop/instructions) diff --git a/instructions/documentation-formats.instructions.md b/instructions/documentation-formats.instructions.md index 1e2e2a71..2b28f5e2 100644 --- a/instructions/documentation-formats.instructions.md +++ b/instructions/documentation-formats.instructions.md @@ -3,8 +3,8 @@ file_type: "instructions" title: "Documentation Formats Standards" description: "Unified standards for Markdown, YAML frontmatter, and Mermaid diagrams across all GitHub community health documentation" scope: "organization-wide" -version: "v1.1.2" -last_updated: "2026-06-18" +version: "v1.1.3" +last_updated: "2026-06-19" owners: ["GitHub Community Health Team"] tags: - markdown @@ -401,9 +401,9 @@ Mermaid diagrams enhance documentation by visualizing complex relationships, pro #### **Flowchart (Most Common)** ```mermaid +flowchart TD accTitle: Flowchart diagram example accDescr: Shows a simple decision flowchart with yes and no branches ending in separate actions. -flowchart TD A[Start] --> B{Decision?} B -->|Yes| C[Action 1] B -->|No| D[Action 2] @@ -416,9 +416,9 @@ flowchart TD #### **Graph (Relationships)** ```mermaid +graph TB accTitle: Graph diagram example accDescr: Shows a relationship graph connecting issues, pull requests, discussions, and releases. -graph TB A[Issues] --> B[Pull Requests] A --> C[Discussions] B --> D[Releases] @@ -430,9 +430,9 @@ graph TB #### **Architecture Diagram** ```mermaid +graph LR accTitle: Architecture diagram example accDescr: Shows a repository architecture split into internal repository components and external integration points. -graph LR subgraph "Repository" A[Code] --> B[Tests] C[Docs] --> D[Automation] @@ -452,9 +452,9 @@ graph LR #### **Sequence Diagram** ```mermaid +sequenceDiagram accTitle: Sequence diagram example accDescr: Shows a simple request flow from user through GitHub and CI to deployment and back to the user. -sequenceDiagram participant User participant GitHub participant CI @@ -473,9 +473,9 @@ sequenceDiagram #### **State Diagram** ```mermaid +stateDiagram-v2 accTitle: State diagram example accDescr: Shows a linear issue lifecycle from draft to review, approval, and merge. -stateDiagram-v2 [*] --> Draft Draft --> Review: Submit Review --> Approved: Accept @@ -502,9 +502,9 @@ stateDiagram-v2 Use the approved Mermaid palette for any `style` or `classDef` declaration. Keep fill, text, and stroke colours together so GitHub light and dark rendering stay readable. ```mermaid +flowchart TD accTitle: Mermaid colour coding example accDescr: Shows the approved Mermaid palette with explicit fill, text, and stroke values applied to success and error classes. -flowchart TD A[Input] --> B[Process] B --> C{Decision} C -->|Success| D[Output] @@ -544,9 +544,9 @@ flowchart TD The following diagram shows the issue lifecycle: ```mermaid +stateDiagram-v2 accTitle: Issue lifecycle example accDescr: Shows the issue lifecycle from open through in-progress, review, and closed states. -stateDiagram-v2 [*] --> Open Open --> InProgress InProgress --> Review @@ -633,3 +633,9 @@ jobs: - **[community-standards.instructions.md](./community-standards.instructions.md)** โ€” Community health documentation standards --- + +--- + +๐Ÿ“ *Schema validated by LightSpeedWP โ€” always compliant.* + +[๐Ÿ“‹ Coding Standards](https://github.com/lightspeedwp/.github/blob/develop/instructions/coding-standards.instructions.md) ยท [๐Ÿ”— Related Files](https://github.com/lightspeedwp/.github/tree/develop/instructions) diff --git a/instructions/linting.instructions.md b/instructions/linting.instructions.md index 4911629d..cb236975 100644 --- a/instructions/linting.instructions.md +++ b/instructions/linting.instructions.md @@ -5,8 +5,8 @@ description: Master index for all linting instructions in the LightSpeed organis Lists and cross-references all linting instructions, config, and coding standards. scope: organization-wide applyTo: '**/*.{js,ts,php,css,scss,sass,html,json,md,yml,yaml,py,sh}' -version: v2.2 -last_updated: '2026-06-18' +version: v2.3 +last_updated: '2026-06-19' owners: - LightSpeedWP Team tags: @@ -102,9 +102,9 @@ Validate and enforce linting standards for all supported file types (JS, TS, She ## ๐Ÿ”„ Linting Process Flow ```mermaid +graph TD accTitle: Linting process flow accDescr: Shows the linting workflow from code change through pre-commit hooks, local linting, CI/CD pipeline checks, and merge approval. -graph TD A[Code Change] --> B[Pre-commit Hooks] B --> C[Local Linting] C --> D{Lint Passed?} @@ -138,9 +138,9 @@ graph TD ## ๐Ÿ› ๏ธ Linting Toolchain ```mermaid +graph LR accTitle: Linting toolchain overview accDescr: Shows how source code feeds into ESLint, PHPCS, Prettier, Stylelint, and Markdownlint before reaching the CI/CD pipeline. -graph LR A[Source Code] --> B[ESLint] A --> C[PHPCS] A --> D[Prettier] @@ -206,3 +206,9 @@ Linting instructions should evolve with our standards and requirements. When upd - **[quality-assurance.instructions.md](./quality-assurance.instructions.md)** โ€” Testing standards that complement linting --- + +--- + +๐Ÿ“ *Schema validated by LightSpeedWP โ€” always compliant.* + +[๐Ÿ“‹ Coding Standards](https://github.com/lightspeedwp/.github/blob/develop/instructions/coding-standards.instructions.md) ยท [๐Ÿ”— Related Files](https://github.com/lightspeedwp/.github/tree/develop/instructions) diff --git a/instructions/quality-assurance.instructions.md b/instructions/quality-assurance.instructions.md index 268aef9b..d7077b5c 100644 --- a/instructions/quality-assurance.instructions.md +++ b/instructions/quality-assurance.instructions.md @@ -4,8 +4,8 @@ title: Quality Assurance Standards description: Comprehensive testing, validation, and quality assurance standards for all GitHub repository code and automation scope: organization-wide -version: v1.1.1 -last_updated: '2026-06-18' +version: v1.1.2 +last_updated: '2026-06-19' owners: - GitHub Community Health Team tags: @@ -77,9 +77,9 @@ Applies to testing and QA across code, automation, and workflows. Covers strateg When you show the pyramid in Mermaid, use the approved Mermaid palette from `instructions/mermaid.instructions.md` and set `fill`, `color`, and `stroke` together in every `classDef`. ```mermaid +graph TD accTitle: Testing pyramid diagram accDescr: Shows the testing pyramid from end-to-end tests through integration and unit tests to static analysis. -graph TD A[E2E Tests
User Workflows] --> B[Integration Tests
Component Interaction] B --> C[Unit Tests
Pure Functions & Logic] C --> D[Static Analysis
Linting & Type Checking] @@ -374,9 +374,9 @@ describe("Issue Lifecycle E2E", () => { ### Test Execution Flow ```mermaid +sequenceDiagram accTitle: Test execution flow accDescr: Shows how a developer runs tests locally, pushes changes, and then CI executes linting, tests, coverage, and quality gate checks. -sequenceDiagram participant Dev as Developer participant Local as Local Tests participant CI as CI Pipeline @@ -568,3 +568,7 @@ tests/ *This document consolidates quality assurance standards for GitHub community health repositories. All code must be tested and validated before merge.* --- + +๐Ÿ“ *Schema validated by LightSpeedWP โ€” always compliant.* + +[๐Ÿ“‹ Coding Standards](https://github.com/lightspeedwp/.github/blob/develop/instructions/coding-standards.instructions.md) ยท [๐Ÿ”— Related Files](https://github.com/lightspeedwp/.github/tree/develop/instructions) diff --git a/scripts/validation/validate-mermaid-accessibility.js b/scripts/validation/validate-mermaid-accessibility.js index d6520d99..5ac8338c 100644 --- a/scripts/validation/validate-mermaid-accessibility.js +++ b/scripts/validation/validate-mermaid-accessibility.js @@ -101,6 +101,20 @@ function validateAccessibility(content) { return issues; } + // Reject accessibility attributes placed before the diagram type declaration. + // The diagram type (e.g. flowchart TD) must be the very first line; accTitle/accDescr + // that precede it are invisible to screen readers and indicate a mis-ordered block. + if ( + firstMeaningfulLine && + /^\s*(accTitle|accDescr)\s*[:{\s]/.test(firstMeaningfulLine) + ) { + issues.push( + "accTitle/accDescr must appear after the diagram type declaration, not before it. " + + "Move the diagram type (e.g. `flowchart TD`) to the first line.", + ); + return issues; + } + // Check for accTitle as an inline statement after the diagram type line. // Supported forms: "accTitle: text" or (rarely) "accTitle text" const hasAccTitle =