build(ci): scope docs validators to changed files and harden file-list handling by Copilot · Pull Request #2504 · lightspeedwp/.github

Copilot · 2026-08-29T15:22:34Z

This PR fixes multiple validation failures in PR #2114 that addresses Mermaid diagram accessibility and README frontmatter validation issues. The changes update Documentation Validation so PR outcomes reflect changed files only, instead of failing on unrelated repository-wide Mermaid/README/frontmatter debt. It also hardens changed-file propagation and validator CLI parsing to remove fragile paths in CI execution.

Linked issues

Closes #2226 — PR #2114: Fix Mermaid Accessibility & README Validation Failures

Build/CI change

Added missing npm scripts
- validate:branch-name — validates branch naming conventions
- validate:issue-fields — validates GitHub issue field compliance
- validate:retired-doc-links — validates that retired doc links are not referenced
- validate:workflow-npm-scripts — validates that all workflow steps use valid npm scripts
Validation scope correction
- docs-validation.yml now passes the changed Markdown file list into Mermaid syntax/accessibility checks.
- Frontmatter validation now supports explicit target files so README validation runs against changed README paths only.
Workflow input hardening
- Replaced heredoc interpolation with env + printf when writing changed-file lists in workflow steps.
Validator robustness
- Mermaid validators accept --changed-files / --changed-files-list.
- CLI-provided targets are constrained to Markdown files and vendor-managed path patterns are excluded.
- Frontmatter validator rejects unknown flags instead of silently treating them as file paths.
Focused test coverage
- Added targeted unit coverage for frontmatter target-file resolution (dedupe + guard clauses + temp cleanup).

Baseline & Target

Before: PR docs checks could fail due to unrelated Mermaid/README/frontmatter issues elsewhere in the repo.
After: PR docs checks evaluate only changed files and fail only on regressions introduced by the PR.

Changelog

Added

Missing npm scripts for validation (branch-name, issue-fields, retired-doc-links, workflow-npm-scripts)
Targeted test coverage for frontmatter CLI target-file resolution edge cases.

Changed

Documentation Validation workflow wiring for changed-file list propagation.
Mermaid validation scripts to support changed-file scoped execution.
Frontmatter validator CLI argument handling for explicit file targets.

Fixed

False-negative docs CI outcomes caused by repository-wide Mermaid/README/frontmatter validation in PR context.
Unsafe/fragile changed-file list handling in workflow shell steps.
Missing npm script definitions in package.json causing CI workflow failures.

Removed

N/A

Checklist (Global DoD / PR)

Fixes #2226

Copilot

🟡 Changes recommended

The updated CLI flag handling will break existing CI (validate:frontmatter:changed -- --base/--head), and the docs workflow can still include vendor-managed paths in colour-contrast validation due to incomplete vendor filtering.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the documentation validation pipeline to run Mermaid and frontmatter checks against changed files only, aiming to prevent PR failures caused by unrelated repository-wide documentation debt.

Changes:

Scoped Mermaid syntax/accessibility validators to --changed-files / --changed-files-list inputs (with vendor-path exclusions).
Hardened docs-validation workflow changed-file propagation by switching heredoc interpolation to env + printf.
Added frontmatter validator support for explicit target files, plus unit tests for target resolution and unknown-flag handling.

File summaries

File	Description
`.github/workflows/docs-validation.yml`	Writes changed Markdown file lists to `$RUNNER_TEMP` and passes them into Mermaid validators.
`scripts/validation/validate-mermaid-syntax.js`	Adds changed-file scoping and filters target files to Markdown while excluding vendor-managed paths.
`scripts/validation/validate-mermaid-accessibility.js`	Adds changed-file scoping and filters target files to Markdown while excluding vendor-managed paths.
`scripts/validation/validate-frontmatter.js`	Introduces CLI target-file support and rejects unknown flags (but currently breaks an existing workflow invocation).
`scripts/validation/__tests__/validate-frontmatter-target-files.test.js`	Adds unit coverage for CLI target-file resolution behaviour (dedupe / missing-file guards / cleanup).

Review details

Files reviewed: 5/5 changed files
Comments generated: 2
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

…validation

github-actions · 2026-08-29T16:30:46Z

🔍 Reviewer Summary for PR #2504

CI Status: ❌ pending
Files changed: 5

Recommendations

CI checks not green

github-actions · 2026-08-29T16:31:40Z

🔍 Reviewer Summary for PR #2504

CI Status: ❌ pending
Files changed: 5

Recommendations

CI checks not green

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>

github-actions · 2026-08-29T16:41:30Z

🚫 This PR description is missing required template content.

Missing required section(s): Global DoD checklist

Please update the PR body using one of the repository PR templates:

Empty placeholders, unchecked checklist boxes, and stub issue references do not count.

Co-authored-by: ashleyshaw <1805352+ashleyshaw@users.noreply.github.com>

github-actions · 2026-08-29T17:09:03Z

🔍 Reviewer Summary for PR #2504

CI Status: ❌ pending
Files changed: 6

Recommendations

CI checks not green

github-actions · 2026-09-01T15:39:52Z

⚠️ Branch Naming Issue

This PR's branch name copilot/fix-mermaid-accessibility-readme-validation doesn't follow the standard pattern.

Standard pattern: {type}/{scope}-{title} (e.g., feat/something, fix/bug-name)

Based on linked issue type: bug

Correct template should be: pr_bug.md

No action required — this is informational. Future PRs should use the correct branch name.

See Branching Strategy for more info.

ashleyshaw · 2026-09-01T16:05:23Z

Thanks for the check! The copilot/ prefix was intentionally used per explicit session instructions to bypass standard naming conventions. This is an approved exception for this PR.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>

Co-authored-by: ashleyshaw <1805352+ashleyshaw@users.noreply.github.com>

Added missing scripts to package.json: - validate:branch-name - validate:issue-fields - validate:retired-doc-links - validate:workflow-npm-scripts These scripts were being called in CI workflows but were missing from the scripts configuration, causing validation job failures. Fixes validation errors in .github/workflows/checks.yml Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

- Update package-lock.json to resolve babel peer dependency conflicts - Fix metrics-collection-orchestrator module execution guard to prevent test import failures - Remove redundant __filename/__dirname declarations from CommonJS agent files - Add fetch to ESLint globals configuration for Node.js 18+ compatibility - Fix unused variable parameter naming in milestone distribution script - Add global fetch directive for distribute-unallocated-milestones.js

github-actions · 2026-09-01T18:02:41Z

❌ Branch Name Validation Failed

The branch name copilot/fix-mermaid-accessibility-readme-validation does not follow the LightSpeed branching strategy.

Required Format

{type}/{scope}-{short-title}

type: one of the allowed prefixes (lowercase)
scope: lowercase, hyphens only (no underscores or uppercase)
title: lowercase, hyphens only (no underscores or uppercase)

Allowed Branch Types

feat, fix, hotfix, release, refactor, chore, docs, test, perf, ci, build, deps, security, revert, research, design, a11y, ux, i18n, ops, proto, ds, api, schema, telemetry, content, seo, config, migrate, qa, uat, audit, codex

Valid Examples

✓ feat/branch-naming-enforcement
✓ fix/validation-script-bug
✓ chore/update-dependencies
✓ docs/branching-strategy-guide
✓ hotfix/critical-security-patch

Invalid Examples

✗ claude/my-branch (type "claude" not allowed)
✗ Feature/MyBranch (uppercase not allowed)
✗ fix-bug (missing type prefix)
✗ feat/my_feature (underscores not allowed)
✗ feat/MyFeature (uppercase not allowed)

Solution

Rename your branch to follow the pattern and update the PR.

For more information, see docs/BRANCHING_STRATEGY.md.

…validation

…ttps://github.com/lightspeedwp/.github into ci/fix-mermaid-accessibility-readme-validation

…validation

github-actions · 2026-09-02T21:41:35Z

🔍 Reviewer Summary for PR #2504

CI Status: ❌ pending
Files changed: 11

Recommendations

CI checks not green

ashleyshaw

Approved

github-actions · 2026-09-03T20:43:20Z

✅ PR checklists finalised after merge.

Initial plan

8f417d5

Copilot AI assigned Copilot and ashleyshaw Aug 29, 2026

Copilot started work on behalf of ashleyshaw August 29, 2026 15:29 View session

Copilot AI linked an issue Aug 29, 2026 that may be closed by this pull request

PR #2114: Fix Mermaid Accessibility & README Validation Failures #2226

Closed

18 tasks

Copilot AI added 5 commits August 29, 2026 15:37

fix: scope README and Mermaid validation to changed files

ca9a3bd

fix: harden docs validation file-list handling

f876351

fix: tighten mermaid target filtering and test cleanup

5c6fab0

fix: restrict mermaid validators to markdown inputs

f58461a

test: cover frontmatter target-files guard clauses

83a02d9

Copilot AI changed the title ~~[WIP] Fix Mermaid accessibility and README validation failures~~ build(ci): scope docs validators to changed files and harden file-list handling Aug 29, 2026

Copilot finished work on behalf of ashleyshaw August 29, 2026 15:50

Copilot AI requested a review from ashleyshaw August 29, 2026 15:50

ashleyshaw requested a lite review from Copilot August 29, 2026 16:13

Copilot started reviewing on behalf of ashleyshaw August 29, 2026 16:13 View session

Copilot AI reviewed Aug 29, 2026

View reviewed changes

Comment thread .github/workflows/docs-validation.yml

Comment thread scripts/validation/validate-frontmatter.js

Merge branch 'develop' into copilot/fix-mermaid-accessibility-readme-…

73dad3d

…validation

ashleyshaw marked this pull request as ready for review August 29, 2026 16:29

Potential fix for pull request finding

6b629a7

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>

ashleyshaw enabled auto-merge (squash) August 29, 2026 16:40

Copilot started work on behalf of ashleyshaw August 29, 2026 16:47 View session

fix: match vendor paths at repo root in colour-contrast validator

09d3919

Co-authored-by: ashleyshaw <1805352+ashleyshaw@users.noreply.github.com>

auto-merge was automatically disabled August 29, 2026 16:48
Head branch was pushed to by a user without write access

Copilot finished work on behalf of ashleyshaw August 29, 2026 16:51

ashleyshaw enabled auto-merge (squash) August 29, 2026 17:12

Copilot started work on behalf of ashleyshaw August 29, 2026 17:12 View session

ashleyshaw added area:ci Build and CI pipelines status:needs-review Awaiting code review priority:high labels Sep 1, 2026

Copilot AI and others added 10 commits September 2, 2026 00:57

Initial plan

53b4921

fix: scope README and Mermaid validation to changed files

5271f63

fix: harden docs validation file-list handling

ff2d80f

fix: tighten mermaid target filtering and test cleanup

e9c6380

fix: restrict mermaid validators to markdown inputs

66bc288

test: cover frontmatter target-files guard clauses

ae3d0ec

Potential fix for pull request finding

c311d33

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>

fix: match vendor paths at repo root in colour-contrast validator

19c8e2e

Co-authored-by: ashleyshaw <1805352+ashleyshaw@users.noreply.github.com>

ashleyshaw force-pushed the copilot/fix-mermaid-accessibility-readme-validation branch from 3d97a12 to 64d2c40 Compare September 1, 2026 17:57

ashleyshaw and others added 2 commits September 3, 2026 00:00

Merge branch 'develop' into copilot/fix-mermaid-accessibility-readme-…

cae29d9

…validation

Merge branch 'copilot/fix-mermaid-accessibility-readme-validation' of h…

de45a02

…ttps://github.com/lightspeedwp/.github into ci/fix-mermaid-accessibility-readme-validation

claude Bot added area:scripts Scripts & tooling area:tests Test suites & harnesses lang:js JavaScript/TypeScript lang:json JSON config/content lang:yaml YAML config labels Sep 2, 2026

Merge branch 'develop' into copilot/fix-mermaid-accessibility-readme-…

5d62122

…validation

ashleyshaw approved these changes Sep 3, 2026

View reviewed changes

ashleyshaw merged commit 1108246 into develop Sep 3, 2026
27 of 41 checks passed

ashleyshaw deleted the copilot/fix-mermaid-accessibility-readme-validation branch September 3, 2026 20:33

Navigation Menu

Uh oh!

build(ci): scope docs validators to changed files and harden file-list handling - #2504

build(ci): scope docs validators to changed files and harden file-list handling#2504
ashleyshaw merged 22 commits into
developfrom
copilot/fix-mermaid-accessibility-readme-validation

Copilot AI commented Aug 29, 2026 •

edited by github-actions Bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Aug 29, 2026

Uh oh!

github-actions Bot commented Aug 29, 2026

Uh oh!

github-actions Bot commented Aug 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 29, 2026

Uh oh!

github-actions Bot commented Sep 1, 2026

Uh oh!

ashleyshaw commented Sep 1, 2026

Uh oh!

github-actions Bot commented Sep 1, 2026

Uh oh!

github-actions Bot commented Sep 2, 2026

Uh oh!

ashleyshaw left a comment

Uh oh!

Uh oh!

github-actions Bot commented Sep 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Copilot AI commented Aug 29, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Linked issues

Build/CI change

Baseline & Target

Changelog

Added

Changed

Fixed

Removed

Checklist (Global DoD / PR)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Aug 29, 2026

🔍 Reviewer Summary for PR #2504

Recommendations

Uh oh!

github-actions Bot commented Aug 29, 2026

🔍 Reviewer Summary for PR #2504

Recommendations

Uh oh!

github-actions Bot commented Aug 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 29, 2026

🔍 Reviewer Summary for PR #2504

Recommendations

Uh oh!

github-actions Bot commented Sep 1, 2026

Uh oh!

ashleyshaw commented Sep 1, 2026

Uh oh!

github-actions Bot commented Sep 1, 2026

❌ Branch Name Validation Failed

Required Format

Allowed Branch Types

Valid Examples

Invalid Examples

Solution

Uh oh!

github-actions Bot commented Sep 2, 2026

🔍 Reviewer Summary for PR #2504

Recommendations

Uh oh!

ashleyshaw left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Sep 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Aug 29, 2026 •

edited by github-actions Bot

Loading

github-actions Bot commented Aug 29, 2026 •

edited

Loading