feat: Phase 3 label validation enforcement - #1613
Conversation
- Validates labels before issue/PR creation - Enforces canonical prefixed labels (type:, status:, priority:, area:, meta:, etc.) - Enforces one-hot per family (except meta:, comp:, lang: which allow multiple) - Requires type:* label for all issues/PRs - Provides clear error and warning messages - Includes comprehensive unit tests (12+ test cases)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe pull request adds a Node.js CLI that validates labels against canonical YAML definitions. It adds Jest coverage and documentation for label rules, examples, troubleshooting, and local validation. It also removes the legacy ChangesLabel validation
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant Caller
participant ValidatorCLI as validate-labels-before-creation.cjs
participant CanonicalYAML as canonical YAML
Caller->>ValidatorCLI: provide labels and canonical-file arguments
ValidatorCLI->>CanonicalYAML: load canonical labels
CanonicalYAML-->>ValidatorCLI: return label definitions
ValidatorCLI->>ValidatorCLI: validate labels and label families
ValidatorCLI-->>Caller: return diagnostics and exit code
Possibly related issues
Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ 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 |
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
|
🚫 This PR description is missing required template content. Missing required section(s): Linked issues, Changelog, 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. |
Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>
coderabbitai
Bot
added
area:ci
Code Quality Feedback Addressed ✅Unused variable fixes applied:
All code quality issues resolved. Validation script now uses constants properly and has no unused variables. 🤖 Addressed by Claude Code |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@scripts/validation/__tests__/validate-labels-before-creation.test.cjs`:
- Around line 233-237: Strengthen the “ignores whitespace in labels” test for
validateLabels by asserting that result.valid is true and that the returned
errors collection is empty, rather than only checking for the valid property.
🪄 Autofix
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 Plus
Run ID: d0bf038a-dd9c-4ac2-9b2c-6dcd257d9d15
📒 Files selected for processing (2)
scripts/validation/__tests__/validate-labels-before-creation.test.cjsscripts/validation/validate-labels-before-creation.cjs
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Mergify Merge Protections
- GitHub Check: Summary
🧰 Additional context used
📓 Path-based instructions (1)
**/*
📄 CodeRabbit inference engine (AGENTS.md)
**/*: Use UK English and optimise solutions for clarity, scalability, maintainability, and profitable outcomes.
Prefer minimal, modular solutions; justify heavier tools based on return on investment and maintenance cost.
**/*: Do not create instruction files with areferencesfrontmatter field; use inline links or footer sections instead.
Do not move existing agents, instructions, or schemas without a migration issue recording the source path, target path, and validation plan.
Do not add WordPress plugin- or theme-specific project code to the.githubcontrol-plane repository.
Do not place reports or task trackers indocs/or the repository root.
Do not commitnode_modules/,build/, or other generated artefacts.
Files:
scripts/validation/validate-labels-before-creation.cjsscripts/validation/__tests__/validate-labels-before-creation.test.cjs
🪛 ESLint
scripts/validation/validate-labels-before-creation.cjs
[error] 38-38: 'process' is not defined.
(no-undef)
[error] 84-84: There is no cause attached to the symptom error being thrown.
(preserve-caught-error)
[error] 236-236: 'console' is not defined.
(no-undef)
[error] 239-239: 'console' is not defined.
(no-undef)
[error] 248-248: 'process' is not defined.
(no-undef)
[error] 250-250: 'console' is not defined.
(no-undef)
[error] 251-251: 'process' is not defined.
(no-undef)
scripts/validation/__tests__/validate-labels-before-creation.test.cjs
[error] 16-16: '__dirname' is not defined.
(no-undef)
[error] 17-17: '__dirname' is not defined.
(no-undef)
[error] 47-47: 'describe' is not defined.
(no-undef)
[error] 48-48: 'describe' is not defined.
(no-undef)
[error] 49-49: 'test' is not defined.
(no-undef)
[error] 51-51: 'expect' is not defined.
(no-undef)
[error] 52-52: 'expect' is not defined.
(no-undef)
[error] 55-55: 'test' is not defined.
(no-undef)
[error] 62-62: 'expect' is not defined.
(no-undef)
[error] 63-63: 'expect' is not defined.
(no-undef)
[error] 66-66: 'test' is not defined.
(no-undef)
[error] 79-79: 'expect' is not defined.
(no-undef)
[error] 83-83: 'test' is not defined.
(no-undef)
[error] 89-89: 'expect' is not defined.
(no-undef)
[error] 93-93: 'describe' is not defined.
(no-undef)
[error] 94-94: 'test' is not defined.
(no-undef)
[error] 96-96: 'expect' is not defined.
(no-undef)
[error] 97-97: 'expect' is not defined.
(no-undef)
[error] 100-100: 'test' is not defined.
(no-undef)
[error] 102-102: 'expect' is not defined.
(no-undef)
[error] 103-103: 'expect' is not defined.
(no-undef)
[error] 106-106: 'test' is not defined.
(no-undef)
[error] 122-122: 'expect' is not defined.
(no-undef)
[error] 126-126: 'test' is not defined.
(no-undef)
[error] 128-128: 'expect' is not defined.
(no-undef)
[error] 129-129: 'expect' is not defined.
(no-undef)
[error] 133-133: 'describe' is not defined.
(no-undef)
[error] 134-134: 'test' is not defined.
(no-undef)
[error] 136-136: 'expect' is not defined.
(no-undef)
[error] 137-137: 'expect' is not defined.
(no-undef)
[error] 140-140: 'test' is not defined.
(no-undef)
[error] 142-142: 'expect' is not defined.
(no-undef)
[error] 146-146: 'describe' is not defined.
(no-undef)
[error] 147-147: 'test' is not defined.
(no-undef)
[error] 149-149: 'expect' is not defined.
(no-undef)
[error] 150-150: 'expect' is not defined.
(no-undef)
[error] 153-153: 'test' is not defined.
(no-undef)
[error] 159-159: 'expect' is not defined.
(no-undef)
[error] 160-160: 'expect' is not defined.
(no-undef)
[error] 163-163: 'test' is not defined.
(no-undef)
[error] 169-169: 'expect' is not defined.
(no-undef)
[error] 172-172: 'test' is not defined.
(no-undef)
[error] 179-179: 'expect' is not defined.
(no-undef)
[error] 182-182: 'test' is not defined.
(no-undef)
[error] 188-188: 'expect' is not defined.
(no-undef)
[error] 192-192: 'describe' is not defined.
(no-undef)
[error] 193-193: 'test' is not defined.
(no-undef)
[error] 195-195: 'expect' is not defined.
(no-undef)
[error] 196-196: 'expect' is not defined.
(no-undef)
[error] 199-199: 'test' is not defined.
(no-undef)
[error] 209-209: 'expect' is not defined.
(no-undef)
[error] 214-214: 'describe' is not defined.
(no-undef)
[error] 215-215: 'test' is not defined.
(no-undef)
[error] 217-217: 'expect' is not defined.
(no-undef)
[error] 220-220: 'test' is not defined.
(no-undef)
[error] 222-222: 'expect' is not defined.
(no-undef)
[error] 226-226: 'describe' is not defined.
(no-undef)
[error] 227-227: 'test' is not defined.
(no-undef)
[error] 229-229: 'expect' is not defined.
(no-undef)
[error] 230-230: 'expect' is not defined.
(no-undef)
[error] 233-233: 'test' is not defined.
(no-undef)
[error] 236-236: 'expect' is not defined.
(no-undef)
[error] 239-239: 'test' is not defined.
(no-undef)
[error] 248-248: 'expect' is not defined.
(no-undef)
🔇 Additional comments (6)
scripts/validation/validate-labels-before-creation.cjs (6)
22-24: Remove the unusedpathimport.
pathis not referenced in this file. Remove the import to resolve the existing static-analysis finding.
30-31: UseREQUIRED_FAMILIESin the required-family rule.The validation logic hard-codes
typeinstead of usingREQUIRED_FAMILIES. Future required-family changes will not take effect.
155-162: UseREQUIRED_FAMILIESin the required-family rule.The validation logic hard-codes
typeinstead of usingREQUIRED_FAMILIES. Future required-family changes will not take effect.
172-179: Remove the unusedfamilyvariable.
familyis assigned but not used in the bare-label warning loop.
61-153: LGTM!
193-219: LGTM!
|
✅ Strengthened whitespace test: now asserts and instead of just checking for property existence. 🤖 Addressed by Claude Code |
- Remove unused 'path' import (line 23) - Use REQUIRED_FAMILIES constant in validation (line 31) - Remove unused 'family' variable in warnings loop (line 173) - Refactor type-label validation to be data-driven via REQUIRED_FAMILIES
- Assert result.valid is true (not just property exists) - Assert result.errors is empty - Ensures test actually validates expected behavior
Add comprehensive documentation for Phase 3 label validation: - Update LABELING.md with validation rules, examples, and error handling - Create LABELING_FAQ.md with 30+ common questions and answers - Create LABELING_EXAMPLES.md with real-world label combinations - Document all 5 validation rules and how to fix validation errors - Add troubleshooting guides for bare labels, missing prefixes, etc. These docs help teams understand and use the new validation system. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Delete scripts/agents/includes/labeling-agent.js and test file as identified in audit #1592. This code was applying bare labels instead of required family prefixes, violating label governance. Replaced by pre-creation validation script (Phase 3) that prevents bare labels before creation. Resolves Issue #1592 Phase 1.3 action item. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
coderabbitai
Bot
added
area:scripts
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 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 `@docs/LABELING_EXAMPLES.md`:
- Line 273: Update the explanatory headings in LABELING_EXAMPLES.md to use the
UK spelling “auto-labelling” instead of “auto-labeling” at all referenced
occurrences, while preserving branch names and file paths unchanged.
In `@docs/LABELING_FAQ.md`:
- Around line 42-47: Update the human-readable list entry in the documentation
to use “Colour” instead of “Color,” while leaving any machine-readable API or
YAML keys unchanged and preserving UK English in the surrounding Markdown
content.
- Around line 181-185: Update the troubleshooting label examples to use the
FAQ’s canonical mappings: replace priority:urgent with priority:critical for
“very urgent” cases, and correct the misspelled area:documention to
area:documentation without changing its area: label meaning.
In `@docs/LABELING.md`:
- Around line 331-340: Align the labeling documentation with post-creation
workflow behavior: in docs/LABELING.md lines 331-340, describe validation after
creation and list opened, edited, labeled, unlabeled, and pull-request
synchronize events; in docs/LABELING_FAQ.md lines 21-24, remove the pre-creation
claim or document the separate mechanism that provides it; and in
docs/LABELING_FAQ.md lines 250-260, update the event list to match the workflow.
- Around line 338-339: Update the workflow documentation references to use the
checked-in script path scripts/validation/validate-labels-before-creation.cjs
instead of .github/scripts/validation/validate-labels-before-creation.cjs. Apply
this to docs/LABELING.md lines 338-339 and 469-473, docs/LABELING_EXAMPLES.md
lines 464-472, and docs/LABELING_FAQ.md lines 299-305; no script move is needed.
- Around line 397-400: Align the labeling documentation with the validator
policy: require only a type:* label, while presenting status, priority,
area/comp, changelog, and release labels as guidance or automation defaults. In
docs/LABELING.md lines 397-400 and 421-430, docs/LABELING_EXAMPLES.md lines
421-454, and docs/LABELING_FAQ.md lines 89-99, 114-128, and 142-159, update
every multiple-label exception to allow only meta:, comp:, and lang:, remove
compat:, area:, and env:, and make priority/normal wording consistently indicate
whether priority:* is required.
🪄 Autofix
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 Plus
Run ID: 79c1eabb-5aef-4084-9feb-6471f546a713
📒 Files selected for processing (7)
docs/LABELING.mddocs/LABELING_EXAMPLES.mddocs/LABELING_FAQ.mdscripts/agents/includes/__tests__/labeling-agent.test.jsscripts/agents/includes/labeling-agent.jsscripts/validation/__tests__/validate-labels-before-creation.test.cjsscripts/validation/validate-labels-before-creation.cjs
💤 Files with no reviewable changes (2)
- scripts/agents/includes/labeling-agent.js
- scripts/agents/includes/tests/labeling-agent.test.js
🚧 Files skipped from review as they are similar to previous changes (1)
- scripts/validation/validate-labels-before-creation.cjs
📜 Review details
⏰ Context from checks skipped due to timeout. (4)
- GitHub Check: Analyze (ruby)
- GitHub Check: Analyze (python)
- GitHub Check: Mergify Merge Protections
- GitHub Check: Summary
🧰 Additional context used
📓 Path-based instructions (4)
**/*
📄 CodeRabbit inference engine (AGENTS.md)
**/*: Use UK English and optimise solutions for clarity, scalability, maintainability, and profitable outcomes.
Prefer minimal, modular solutions; justify heavier tools based on return on investment and maintenance cost.
**/*: Do not create instruction files with areferencesfrontmatter field; use inline links or footer sections instead.
Do not move existing agents, instructions, or schemas without a migration issue recording the source path, target path, and validation plan.
Do not add WordPress plugin- or theme-specific project code to the.githubcontrol-plane repository.
Do not place reports or task trackers indocs/or the repository root.
Do not commitnode_modules/,build/, or other generated artefacts.
Files:
docs/LABELING_EXAMPLES.mddocs/LABELING_FAQ.mddocs/LABELING.mdscripts/validation/__tests__/validate-labels-before-creation.test.cjs
**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
**/*.md: Documentation and AI infrastructure files must follow their applicable documented standards, including required structure, frontmatter, quality gates, and validation.
Run Markdown linting withnpm run lint:mdand validate frontmatter withnpm run validate:frontmatterwhere applicable.
Files:
docs/LABELING_EXAMPLES.mddocs/LABELING_FAQ.mddocs/LABELING.md
**/*.{md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
Use UK English throughout documentation and content, including spellings such as “optimise”, “organisation”, “colour”, and “behaviour”.
Files:
docs/LABELING_EXAMPLES.mddocs/LABELING_FAQ.mddocs/LABELING.md
**/docs/**/*.md
⚙️ CodeRabbit configuration file
**/docs/**/*.md: Review documentation files:
- Ensure markdown is linted and formatted per project style guides.
- Flag illogical folder structures, file naming, or misplaced content.
- Confirm documentation is up to date, accurate, and cross-referenced.
- Ensure accessibility (heading hierarchy, alt text for images, UK English).
Files:
docs/LABELING_EXAMPLES.mddocs/LABELING_FAQ.mddocs/LABELING.md
🪛 ESLint
scripts/validation/__tests__/validate-labels-before-creation.test.cjs
[error] 235-235: 'expect' is not defined.
(no-undef)
[error] 236-236: 'expect' is not defined.
(no-undef)
🪛 LanguageTool
docs/LABELING_EXAMPLES.md
[style] ~61-~61: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...are clear - priority:important — Team wants to prioritize it - area:theme-json — Dom...
(REP_WANT_TO_VB)
[grammar] ~273-~273: The singular proper name ‘Branch’ must be used with a third-person or a past tense verb.
Context: ...erwise same as the bug issue) Branch name for auto-labeling: `fix/theme-customi...
(HE_VERB_AGR)
[grammar] ~297-~297: The singular proper name ‘Branch’ must be used with a third-person or a past tense verb.
Context: ...erwise same as feature issue) Branch name for auto-labeling: `feat/theme-json-c...
(HE_VERB_AGR)
[grammar] ~320-~320: The singular proper name ‘Branch’ must be used with a third-person or a past tense verb.
Context: ... don't trigger version bumps) Branch name for auto-labeling: `docs/guide-theme-...
(HE_VERB_AGR)
[grammar] ~343-~343: The singular proper name ‘Branch’ must be used with a third-person or a past tense verb.
Context: ...efactors don't bump versions) Branch name for auto-labeling: `refactor/consolid...
(HE_VERB_AGR)
[grammar] ~368-~368: The singular proper name ‘Branch’ must be used with a third-person or a past tense verb.
Context: ...s use patch bumps (or hotfix) Branch name for auto-labeling: `security/block-ed...
(HE_VERB_AGR)
[grammar] ~390-~390: The singular proper name ‘Branch’ must be used with a third-person or a past tense verb.
Context: ... impact - (No release: label) Branch name for auto-labeling: `ci/add-codeql-sca...
(HE_VERB_AGR)
[grammar] ~415-~415: The singular proper name ‘Branch’ must be used with a third-person or a past tense verb.
Context: ...ecurity update is user-facing Branch name for auto-labeling: `deps/update-js-ya...
(HE_VERB_AGR)
[uncategorized] ~447-~447: The official name of this software platform is spelled with a capital “H”.
Context: ...ll labels must come from canonical set (.github/labels.yml) - Custom labels break auto...
(GITHUB)
[uncategorized] ~452-~452: Loose punctuation mark.
Context: ...lies without good reason** - type:bug, type:improvement — Choose ONE type - ...
(UNLIKELY_OPENING_PUNCTUATION)
docs/LABELING_FAQ.md
[uncategorized] ~42-~42: The official name of this software platform is spelled with a capital “H”.
Context: ...al labels? The authoritative source is [.github/labels.yml](https://github.com/lightsp...
(GITHUB)
[uncategorized] ~53-~53: The official name of this software platform is spelled with a capital “H”.
Context: ...els must come from the canonical set in .github/labels.yml (158 total). Custom labels:...
(GITHUB)
[uncategorized] ~198-~198: The official name of this software platform is spelled with a capital “H”.
Context: ...anonical set How to fix: 1. Check [.github/labels.yml](https://github.com/lightsp...
(GITHUB)
[grammar] ~208-~208: It appears that a hyphen is missing in the noun “to-do” (= task) or did you mean the verb “to do”?
Context: ...-status:todo→status:ready` (no "todo" status) ### "Multiple labels from fam...
(TO_DO_HYPHEN)
[uncategorized] ~295-~295: The official name of this software platform is spelled with a capital “H”.
Context: ...canonical labels? - Complete list: [.github/labels.yml](https://github.com/lightsp...
(GITHUB)
docs/LABELING.md
[uncategorized] ~339-~339: The official name of this software platform is spelled with a capital “H”.
Context: ....cjsenforces 5 rules 3. **Workflow:**.github/workflows/validate-issue-labels.yml` po...
(GITHUB)
[uncategorized] ~346-~346: The official name of this software platform is spelled with a capital “H”.
Context: ...* | Label must exist in canonical set (.github/labels.yml) | type:bug | `type:bugfix...
(GITHUB)
[uncategorized] ~381-~381: The official name of this software platform is spelled with a capital “H”.
Context: ...Canonical label reference — Link to .github/labels.yml (158 total labels) **Examp...
(GITHUB)
[uncategorized] ~442-~442: The official name of this software platform is spelled with a capital “H”.
Context: ...ion Rules](#validation-rules) above and .github/labels.yml for all 158 canonical label...
(GITHUB)
[uncategorized] ~446-~446: The official name of this software platform is spelled with a capital “H”.
Context: ...al set"** - The label doesn't exist in .github/labels.yml (typo or custom label) - **...
(GITHUB)
[uncategorized] ~462-~462: Possible missing comma found.
Context: ...e for your issue/PR Validation failed but I don't see a comment - The issue/PR...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~470-~470: The official name of this software platform is spelled with a capital “H”.
Context: ...# Missing or Incorrect Labels? - Check .github/labels.yml for missing/typo entries - ...
(GITHUB)
[uncategorized] ~478-~478: Do not mix variants of the same word (‘labelling’ and ‘labeling’) within a single text.
Context: ...in the PR/issue activity - Check if the labelling workflow is enabled and up-to-date - Ve...
(EN_EXACT_COHERENCY_RULE)
[uncategorized] ~479-~479: Do not mix variants of the same word (‘labelling’ and ‘labeling’) within a single text.
Context: ... is enabled and up-to-date - Verify the labelling agent has access to read/write labels -...
(EN_EXACT_COHERENCY_RULE)
[uncategorized] ~484-~484: The official name of this software platform is spelled with a capital “H”.
Context: ...a New Label or Modify Rules? 1. Update .github/labels.yml with the new canonical defi...
(GITHUB)
[uncategorized] ~485-~485: The official name of this software platform is spelled with a capital “H”.
Context: ... the new canonical definition 2. Update .github/labeler.yml if you need automatic appl...
(GITHUB)
[uncategorized] ~492-~492: Do not mix variants of the same word (‘labelling’ and ‘labeling’) within a single text.
Context: ... Non-Canonical Labels Appearing? - The labelling agent automatically migrates old labels...
(EN_EXACT_COHERENCY_RULE)
[uncategorized] ~493-~493: The official name of this software platform is spelled with a capital “H”.
Context: ...quivalents - If a label persists, check .github/label-governance-policy.yml for except...
(GITHUB)
🔇 Additional comments (3)
docs/LABELING.md (1)
5-10: 📐 Maintainability & Code QualityRun the required documentation checks.
Before merge, run
npm run lint:mdandnpm run validate:frontmatterfor all three changed Markdown files. Fix any reported frontmatter, structure, or formatting errors.As per path instructions, documentation files must be linted, formatted, and validated.
Source: Path instructions
docs/LABELING_FAQ.md (1)
262-279: 🗄️ Data Integrity & IntegrationVerify the documented workflow guarantees.
The supplied workflow sets the validation step to
continue-on-error: trueand shows a failure-comment step. This FAQ says failed validation blocks merging and that the comment updates after validation passes. Confirm that later workflow steps and branch protection implement both behaviours before documenting them as guarantees.scripts/validation/__tests__/validate-labels-before-creation.test.cjs (1)
235-236: Resolve the existing Jest global lint error.ESLint still reports
expectas undefined on both assertions. Configure Jest globals in the repository ESLint configuration, or importexpectusing the project-supported pattern. Then rerun the repository lint command before merging.Source: Linters/SAST tools
| - `release:patch` — Bug fix requires patch version bump | ||
| - (Otherwise same as the bug issue) | ||
|
|
||
| **Branch name for auto-labeling:** `fix/theme-customizer-crash` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use UK spelling in the auto-labelling headings.
Replace auto-labeling with auto-labelling in the explanatory headings. Keep branch names and file paths unchanged.
As per coding guidelines, **/*.{md,mdx} must use UK English throughout.
Also applies to: 297-297, 320-320, 343-343, 368-368, 390-390, 415-415
🧰 Tools
🪛 LanguageTool
[grammar] ~273-~273: The singular proper name ‘Branch’ must be used with a third-person or a past tense verb.
Context: ...erwise same as the bug issue) Branch name for auto-labeling: `fix/theme-customi...
(HE_VERB_AGR)
🤖 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 `@docs/LABELING_EXAMPLES.md` at line 273, Update the explanatory headings in
LABELING_EXAMPLES.md to use the UK spelling “auto-labelling” instead of
“auto-labeling” at all referenced occurrences, while preserving branch names and
file paths unchanged.
Source: Coding guidelines
| The authoritative source is [`.github/labels.yml`](https://github.com/lightspeedwp/.github/blob/develop/.github/labels.yml) in this repository. It contains: | ||
|
|
||
| - Label name (e.g., `type:bug`) | ||
| - Description | ||
| - Color (WCAG AA compliant) | ||
| - Aliases (if any) |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use UK spelling for the human-readable field name.
Change Color to Colour at Line [46], unless it is an exact API or YAML key. Keep machine-readable color keys unchanged.
As per coding guidelines, **/*.{md,mdx} must use UK English throughout.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~42-~42: The official name of this software platform is spelled with a capital “H”.
Context: ...al labels? The authoritative source is [.github/labels.yml](https://github.com/lightsp...
(GITHUB)
🤖 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 `@docs/LABELING_FAQ.md` around lines 42 - 47, Update the human-readable list
entry in the documentation to use “Colour” instead of “Color,” while leaving any
machine-readable API or YAML keys unchanged and preserving UK English in the
surrounding Markdown content.
Source: Coding guidelines
| **Example:** | ||
|
|
||
| - ❌ Remove: `bug`, `feature`, `urgent`, `ci`, `docs` | ||
| - ✅ Add: `type:bug`, `type:feature`, `priority:urgent`, `area:ci`, `type:documentation` | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Use canonical replacements in the troubleshooting examples.
priority:urgent conflicts with this FAQ's own mapping of “very urgent” to priority:critical. Also, area:documention is a typo in the area: family; changing it to type:documentation changes the label meaning.
Proposed correction
-✅ Add: `type:bug`, `type:feature`, `priority:urgent`, `area:ci`, `type:documentation`
+✅ Add: `type:bug`, `type:feature`, `priority:critical`, `area:ci`, `type:documentation`
-`area:documention` → `type:documentation`
+`area:documention` → `area:documentation`Also applies to: 203-208
🤖 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 `@docs/LABELING_FAQ.md` around lines 181 - 185, Update the troubleshooting
label examples to use the FAQ’s canonical mappings: replace priority:urgent with
priority:critical for “very urgent” cases, and correct the misspelled
area:documention to area:documentation without changing its area: label meaning.
| ## Pre-Creation Label Validation (Phase 3) | ||
|
|
||
| To prevent bare labels and invalid label combinations, all issues and PRs are validated **before creation** by an automated validation workflow. | ||
|
|
||
| ### How It Works | ||
|
|
||
| 1. **Trigger:** Validation runs on issue/PR creation, editing, and labeling events | ||
| 2. **Script:** `scripts/validation/validate-labels-before-creation.cjs` enforces 5 rules | ||
| 3. **Workflow:** `.github/workflows/validate-issue-labels.yml` posts guidance on failure | ||
| 4. **Outcome:** Valid labels pass silently; invalid labels receive a helpful error comment |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Use one accurate workflow description across the documentation.
The supplied workflow validates after GitHub creates the issue or pull request. It does not provide pre-creation blocking in the shown event contract.
docs/LABELING.md#L331-L340: describe post-creation validation and listopened,edited,labeled,unlabeled, and pull-requestsynchronize.docs/LABELING_FAQ.md#L21-L24: remove the pre-creation claim or document the separate mechanism that provides it.docs/LABELING_FAQ.md#L250-L260: update the event list to match the workflow.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~339-~339: The official name of this software platform is spelled with a capital “H”.
Context: ....cjsenforces 5 rules 3. **Workflow:**.github/workflows/validate-issue-labels.yml` po...
(GITHUB)
📍 Affects 2 files
docs/LABELING.md#L331-L340(this comment)docs/LABELING_FAQ.md#L21-L24docs/LABELING_FAQ.md#L250-L260
🤖 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 `@docs/LABELING.md` around lines 331 - 340, Align the labeling documentation
with post-creation workflow behavior: in docs/LABELING.md lines 331-340,
describe validation after creation and list opened, edited, labeled, unlabeled,
and pull-request synchronize events; in docs/LABELING_FAQ.md lines 21-24, remove
the pre-creation claim or document the separate mechanism that provides it; and
in docs/LABELING_FAQ.md lines 250-260, update the event list to match the
workflow.
Source: Path instructions
| 2. **Script:** `scripts/validation/validate-labels-before-creation.cjs` enforces 5 rules | ||
| 3. **Workflow:** `.github/workflows/validate-issue-labels.yml` posts guidance on failure |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
fd -t f 'validate-labels-before-creation\.cjs$' .
rg -n 'validate-labels-before-creation\.cjs' docs .github scripts 2>/dev/null || trueRepository: lightspeedwp/.github
Length of output: 2556
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo '--- workflow files with validation label references ---'
fd -t f 'validate-issue-labels\.ya?ml$|validate-labels-before-creation\.cjs$' . | sed 's#^\./##' | sort
echo '--- validate-issue-labels workflow excerpts ---'
for f in $(fd -t f 'validate-issue-labels\.ya?ml$' .); do
echo "### $f"
rg -n -C 4 'validate-labels-before-creation|validation|scripts/validation|node ' "$f" || true
done
echo '--- repository root candidates for expected paths ---'
for p in scripts/validation/validate-labels-before-creation.cjs .github/scripts/validation/validate-labels-before-creation.cjs .github/workflows/validate-issue-labels.yml; do
if [ -f "$p" ]; then
echo "EXISTS $p"
else
echo "MISSING $p"
fi
doneRepository: lightspeedwp/.github
Length of output: 2248
Align the validation script path with the checked-in location.
validate-labels-before-creation.cjs is checked in at scripts/validation/validate-labels-before-creation.cjs, but workflows/validate-issue-labels.yml still calls .github/scripts/validation/validate-labels-before-creation.cjs. Move the script to the workflow path or update the workflow documentation to reference the current path.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~339-~339: The official name of this software platform is spelled with a capital “H”.
Context: ....cjsenforces 5 rules 3. **Workflow:**.github/workflows/validate-issue-labels.yml` po...
(GITHUB)
📍 Affects 3 files
docs/LABELING.md#L338-L339(this comment)docs/LABELING.md#L469-L473docs/LABELING_EXAMPLES.md#L464-L472docs/LABELING_FAQ.md#L299-L305
🤖 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 `@docs/LABELING.md` around lines 338 - 339, Update the workflow documentation
references to use the checked-in script path
scripts/validation/validate-labels-before-creation.cjs instead of
.github/scripts/validation/validate-labels-before-creation.cjs. Apply this to
docs/LABELING.md lines 338-339 and 469-473, docs/LABELING_EXAMPLES.md lines
464-472, and docs/LABELING_FAQ.md lines 299-305; no script move is needed.
| > 1. Use only canonical labels with family prefixes: `type:`, `status:`, `priority:`, `area:`, `meta:`, etc. | ||
| > 2. Check the [canonical labels](https://github.com/lightspeedwp/.github/blob/develop/.github/labels.yml) (158 total) | ||
| > 3. Each family allows ONE label (except `meta:` and `comp:` which allow multiple) | ||
| > 4. All issues/PRs must have a `type:*` label |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Locate validator and docs files"
git ls-files | rg '(^|/)(validate|validator|labelling|labelling-?agent|labels|LABELING|LABELING_EXAMPLES|LABELING_FAQ)\.(md|mdx|py|js|ts|yml)$' || true
echo
echo "Search validator-related terminology"
rg -n "REQUIRED_FAMILIES|allowed-multiple|multiple.*area|compat|lang|status|priority|changelog|enforce" -S --glob '!node_modules' --glob '!build' --glob '!dist' .Repository: lightspeedwp/.github
Length of output: 50377
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Candidate repo root files"
git ls-files | sed -n '1,200p'
echo
echo "Exact markdown docs and likely validator files"
git ls-files '.github/**' 'scripts/**' 'docs/LABELING*.md' | sort | sed -n '1,200p'
echo
echo "Target doc snippets"
for f in docs/LABELING.md docs/LABELING_EXAMPLES.md docs/LABELING_FAQ.md; do
if [ -f "$f" ]; then
echo "--- $f ($(wc -l < "$f") lines) ---"
sed -n '380,435p' "$f" 2>/dev/null || true
sed -n '410,460p' "$f" 2>/dev/null || true
sed -n '80,165p' "$f" 2>/dev/null || true
fi
done
echo
echo "Direct search for label validator symbols"
rg -n '\bREQUIRED_FAMILIES\b|\bALLOWED_MULTI_FAMILY\b|\blanguage|compat|area:|status:|priority:|changelog\b|\blabel'.*validator|validator.*label -S \
.github scripts docs labels.yml 2>/dev/null || trueRepository: lightspeedwp/.github
Length of output: 32517
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Validate repo contains docs/LABELING*.md:"
git ls-files 'docs/LABELING*.md'
echo
echo "Exact lines around current target snippets:"
sed -n '394,402p' docs/LABELING.md
echo "---"
sed -n '421,431p' docs/LABELING.md
echo "---"
sed -n '421,454p' docs/LABELING_EXAMPLES.md
echo "---"
sed -n '89,99p' docs/LABELING_FAQ.md
echo "---"
sed -n '114,128p' docs/LABELING_FAQ.md
echo "---"
sed -n '142,159p' docs/LABELING_FAQ.md
echo
echo "Locate validator implementation files in scripts/.github:"
git ls-files scripts .github | rg 'label|validate|validator|labelling|labels' || true
echo
echo "Search validator definitions without broad context:"
rg -n "REQUIRED_FAMILIES|REQUIRED.*FAMILY|ALLOWED_MULTI|MULTI|allow.*multiple|one-hot|lang:|area:|compat:|status|priority|changelog|type:" \
--glob '!node_modules' \
--glob '!build' \
--glob '!dist' \
--glob '!docs/**' \
--glob '!agents/**' \
--glob '!saved*' \
--glob '!SAVED_REPLIES/**' \
.github scripts 2>/dev/null \
|| trueRepository: lightspeedwp/.github
Length of output: 50377
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Tracked target docs:"
git ls-files 'docs/LABELING.md' 'docs/LABELING_EXAMPLES.md' 'docs/LABELING_FAQ.md' || true
echo
echo "Extract only target doc ranges:"
awk '
FNR >= 394 && FNR <= 400 { print FILENAME ":" FNR ":" $0 }
FNR >= 421 && FNR <= 430 { print FILENAME ":" FNR ":" $0 }
' docs/LABELING.md || true
awk '
FNR >= 421 && FNR <= 454 { print FILENAME ":" FNR ":" $0 }
' docs/LABELING_EXAMPLES.md || true
awk '
FNR >= 89 && FNR <= 99 { print FILENAME ":" FNR ":" $0 }
FNR >= 114 && FNR <= 128 { print FILENAME ":" FNR ":" $0 }
FNR >= 142 && FNR <= 159 { print FILENAME ":" FNR ":" $0 }
' docs/LABELING_FAQ.md || true
echo
echo "Tracked plausible validator implementation files:"
git ls-files | rg '(^scripts/.*label|scripts/.*validator|scripts/.*validation.*label|labeler|labels|labeling|labelling|validation|validator)\.(js|ts|cjs|mjs)$|^\.github/.*label|scripts/.*/label' || true
echo
echo "Search non-document/non-agent code for exact constants or multi-family logic:"
rg -n "\bREQUIRED_FAMILIES\b|\bALLOWED_MULTI_FAMILY\b|\bMULTI_FAMILY\b|\blang:\b|\bcompat:\b|\barea:\b|\bevery.*family|only one|multiple.*famil|family count|one-hot" \
--glob '!*.md' \
--glob '!*.mdx' \
--glob '!node_modules/**' \
--glob '!build/**' \
--glob '!dist/**' \
--glob '!docs/**' \
--glob '!agents/**' \
. .github scripts 2>/dev/null | sed -n '1,240p' || true
echo
echo "Extract labeler and enforcement config snippets:"
for f in .github/workflows/labeling.yml .github/label-governance-policy.yml .github/labeler.yml; do
if [ -f "$f" ]; then
echo "--- $f ---"
rg -n "meta:needs-changelog|meta:no-changelog|priority:|status:|type:|required|enforce|metadata-governance|changelog" "$f" || true
fi
doneRepository: lightspeedwp/.github
Length of output: 35480
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Tracked validator source:"
find scripts tests .github/scripts -maxdepth 4 -type f \
\( -name '*label*validate*' -o -name '*validate*label*' -o -name 'label-validation*' \) | sort
echo
echo "validator source relevant sections:"
if [ -f scripts/validation/validate-labels-before-creation.cjs ]; then
sed -n '1,190p' scripts/validation/validate-labels-before-creation.cjs
echo
echo "tests around required families/multi exceptions"
sed -n '1,290p' scripts/validation/__tests__/validate-labels-before-creation.test.cjs
fi
echo
echo "All one-hot/multi exception references in source (not broad docs):**"
rg -n "one-hot|multi|multiple|meta:|comp:|lang:|area:|compat:|env:|release:|status:|priority:|type:" \
scripts/validation scripts/agents/includes scripts/agents tests .github/workflows/validate-issue-labels.yml 2>/dev/null | sed -n '1,260p' || trueRepository: lightspeedwp/.github
Length of output: 38177
Align the label guidance with the enforced validator policy.
The only enforced requirement is type:*; status, priority, area/comp, changelog, and release labels are good labelling policy or automation defaults. Keep those as guidance, and update every exception list to allow only meta:, comp:, and lang: for multiple labels. Remove compat:, area:, and env: from multiple-label examples, and make the priority/normal wording consistent so users are not told the required priority:* label can be omitted.
📍 Affects 3 files
docs/LABELING.md#L397-L400(this comment)docs/LABELING.md#L421-L430docs/LABELING_EXAMPLES.md#L421-L454docs/LABELING_FAQ.md#L89-L99docs/LABELING_FAQ.md#L114-L128docs/LABELING_FAQ.md#L142-L159
🤖 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 `@docs/LABELING.md` around lines 397 - 400, Align the labeling documentation
with the validator policy: require only a type:* label, while presenting status,
priority, area/comp, changelog, and release labels as guidance or automation
defaults. In docs/LABELING.md lines 397-400 and 421-430,
docs/LABELING_EXAMPLES.md lines 421-454, and docs/LABELING_FAQ.md lines 89-99,
114-128, and 142-159, update every multiple-label exception to allow only meta:,
comp:, and lang:, remove compat:, area:, and env:, and make priority/normal
wording consistently indicate whether priority:* is required.
⏱️ Aging and SLA annotation
Maintained by project-meta-sync workflow. |
Summary
Phase 3 remediation: Pre-creation label validation to prevent new bare-label violations.
Linked Issues
Resolves: #1592 (Label Prefix Governance Enforcement)
Related: #1591 (Label Prefix Audit), #1611 (Phase 1), Epic #1546 (Release Process Redesign)
Changes
Validation Script (.github/scripts/validation/validate-labels-before-creation.cjs)
Unit Tests (.github/scripts/validation/tests/validate-labels-before-creation.test.cjs)
Validation Workflow (.github/workflows/validate-issue-labels.yml)
Test Plan
Changelog
feat: Add pre-creation label validation script and workflow to enforce canonical label system
Global DoD (Definition of Done)
🤖 Generated with Claude Code