Skip to content

[#64] Add GrantFox issue batch quality validator - #81

Merged
El-swaggerito merged 1 commit into
Axionvera:mainfrom
Alimzy:feat/issue-quality-validator-64
Jul 28, 2026
Merged

[#64] Add GrantFox issue batch quality validator#81
El-swaggerito merged 1 commit into
Axionvera:mainfrom
Alimzy:feat/issue-quality-validator-64

Conversation

@Alimzy

@Alimzy Alimzy commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a local validator for GrantFox-style advanced issue JSON batches, catching missing fields, unsupported labels, missing ISSUE_STANDARD.md sections, and weak acceptance criteria before any issue is created on GitHub.

Closes #64

Acceptance criteria

  • Issue batch schema validator is implemented -- scripts/validate-issue-batch.mts, validateIssueBatch()
  • Unsupported labels are detected before GitHub issue creation -- checkLabels() cross-references .github/LABELS.yml
  • Missing required fields are reported clearly -- checkRequiredFields(), one violation per missing field with entry index/title
  • Weak acceptance criteria are flagged -- checkBodyStandard(), WEAK_ACCEPTANCE_PHRASES list
  • Tests cover valid and invalid issue batches -- scripts/validate-issue-batch.test.ts, 6 tests
  • Documentation explains the advanced issue standard -- docs/ISSUE_BATCH_VALIDATOR.md

Design notes

  • Placed as a standalone script (scripts/validate-issue-batch.mts), matching the existing scripts/check-package-boundaries.mts convention (dependency-free, runs via tsx, gates before pnpm install even resolves workspace packages) -- not under packages/validators, since that package's own boundary rules (and its actual purpose: Stellar/anchor domain schemas) make it the wrong home for GrantFox meta-tooling.
  • LABELS.yml is hand-parsed (no new yaml dependency) since its format is a simple flat list and the repo has no existing yaml parser dependency.
  • The "campaign issue" checks (label taxonomy, required sections, weak acceptance criteria) only apply to entries carrying all three campaign labels (GrantFox OSS, Maybe Rewarded, Official Campaign | FWC26), per ISSUE_STANDARD.md's own scope ("Anything less is still a valid GitHub issue").

Verification

  • pnpm validate:issues examples/issue-batches/valid-batch.json -- exit 0
  • pnpm validate:issues examples/issue-batches/invalid-batch.json -- exit 1, 16 violations reported clearly
  • The invalid fixture is modeled on this issue's own real-world labels (monorepo, feature, developer-experience) -- none of which exist in .github/LABELS.yml. Running the validator against them catches exactly this class of mistake, the same one AUTOMATION_RUNBOOK.md's troubleshooting table already names as the most common batch failure.
  • npx vitest run scripts/validate-issue-batch.test.ts -- 6/6 passing
  • pnpm typecheck -- 12/12 successful
  • pnpm lint -- clean

Adds scripts/validate-issue-batch.mts, a standalone dependency-free
script (matching check-package-boundaries.mts's convention) that
validates a GrantFox issue batch JSON file against
docs/ISSUE_STANDARD.md and .github/LABELS.yml before any issues are
created via gh issue create.

Checks:
- Required fields (title, labels, body) present and non-empty
- Every label exists in .github/LABELS.yml (the Axionvera#1 failure mode
  AUTOMATION_RUNBOOK.md's troubleshooting table already names)
- Campaign-labelled issues have a scope label, a type label, and at
  most one difficulty label per ISSUE_STANDARD.md
- Campaign-labelled issues include all 8 required ISSUE_STANDARD.md
  sections as markdown headings
- Acceptance-criteria checkboxes aren't vague/unverifiable phrasing

Usage: pnpm validate:issues path/to/batch.json (exit 0/1).

Adds examples/issue-batches/{valid,invalid}-batch.json. The invalid
fixture is modeled on this issue's own real labels (monorepo,
feature, developer-experience), none of which exist in
.github/LABELS.yml -- confirmed by running the validator against it.

Adds scripts/validate-issue-batch.test.ts (6 tests: compliant batch,
unsupported labels, missing fields, missing sections, weak
acceptance criteria, non-campaign issues exempt from section checks).

Adds docs/ISSUE_BATCH_VALIDATOR.md.

Closes Axionvera#64
@El-swaggerito
El-swaggerito merged commit d911217 into Axionvera:main Jul 28, 2026
1 check passed
@grantfox-oss grantfox-oss Bot mentioned this pull request Jul 28, 2026
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add GrantFox issue quality validator

2 participants