Description

Extends the check-template-and-add-labels CI job with semantic validators that enforce the Definition of Ready For Review (docs/readme/ready-for-review.md) at the PR level, replacing the previous structural-only check.

What changed:

• New module shared/markdown-tokenizer.ts — a zero-dependency, single-pass GFM tokenizer (state machine) that correctly handles fenced code blocks, HTML comments, ATX headings, and GFM checkboxes in precedence order. This prevents content injection: a Fixes: #123 line or a CHANGELOG entry: inside a Gherkin block can no longer bypass the semantic validators.
• New module shared/pr-template-checks.ts with six pure validators (description non-empty, changelog entry present, issue linkage, manual testing steps filled, screenshots/evidence provided, author checklist fully checked). The validation plan is now metadata-driven: mms-check directives embedded in pull-request-template.md declare which validator applies to each section; a buildValidationPlan parser reads them at module load and dispatches each section to a VALIDATORS registry. Adding or reordering a plain-text section needs zero code changes — only a new kind of check requires a new registry entry.
• PR_TEMPLATE_SECTION_TITLES (structural presence list) and AUTHOR_CHECKLIST_MIN_ITEMS (minimum required checklist rows) are now derived at module load from the same template file — no hardcoded constants. The checklist count enforces that authors cannot bypass the requirement by deleting unchecked rows.
• pull-request-template.md is the single source of truth for validation rules. It now embeds <!-- mms-check: type=X required=true --> directives (invisible in rendered markdown) directly under each author-validated section heading, with a legend comment at the top explaining the vocabulary.
• New module shared/pr-template-comment.ts that creates, updates, or deletes a single sticky bot comment listing every missing item, so authors get consolidated actionable feedback.
• Updated check-template-and-add-labels.ts to call the validators, apply draft-aware exit (informational core.warning + exit 0 for drafts, blocking core.setFailed + exit 1 for non-drafts), and resolve the January-2024 TODO that kept the structural mismatch non-failing.
• Extended workflow triggers with ready_for_review, converted_to_draft, and synchronize so the required status flips immediately when an author changes draft state or pushes new commits.
• READMEs added for markdown-tokenizer, pr-template-checks, and pr-template-comment documenting API, parsing workflow (Mermaid diagram), directive vocabulary, and how to add new validators.

Changelog

CHANGELOG entry: null

Related issues

Refs: MCWP-603

Manual testing steps

Feature: semantic PR template validators

  Scenario: validators pass on a complete PR body
    Background: `gh` CLI authenticated (`gh auth status`) and the repo checked out on this branch.

    Given the branch is checked out locally
    When the reviewer runs the local validator script (see code below) against this PR's body
    Then the script exits 0 and prints "All checks pass"

Local validator script (copy and run in your local terminal, at project root)

gh pr view 30541 --json body -q .body > /tmp/pr-body.txt
cat > .github/scripts/check-pr-local.ts << 'EOF'
import { runAllChecks } from './shared/pr-template-checks';
import * as fs from 'fs';
const body = fs.readFileSync('/tmp/pr-body.txt', 'utf8');
const failures = runAllChecks(body, false);
if (failures.length === 0) { console.log('All checks pass'); }
else { failures.forEach((f: { reason: string }) => console.log('FAIL', f.reason)); process.exit(1); }
EOF
cd .github/scripts && yarn ts-node check-pr-local.ts ; rm check-pr-local.ts

Screenshots/Recordings

Before

N/A

After

Proof of manual testing passed:

Example of sticky PR comment the check would send on a PR marked ready for review but with no changelog line:

PR template — items to address before "Ready for review"

This check is blocking. Address every item below, then push to re-run.

• Changelog section is missing the CHANGELOG entry: line. Add CHANGELOG entry: <description>, CHANGELOG entry: null, or apply the no-changelog label.

See docs/readme/ready-for-review.md for the full Definition of Ready for Review.

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.