Improve framework Clean Repos CI trust

[aileen]

Summary

• fixes TypeScript package coverage measurement for @tryghost/errors and @tryghost/prometheus-metrics so thresholds measure real source files
• removes the job-manager unhandled-error suppression by fixing the worker fixture, then exposes explicit pnpm lint and All tests pass in CI
• adds AGENTS.md, a symlinked CLAUDE.md, fills root README install/usage gaps, and overrides vulnerable transitive js-yaml to the patched 3.x release
• preserves the legacy SES ServiceUrl parser behavior and adds explicit CodeQL rationale for compatibility/test-fixture findings

ref GVA-823

Clean Repos ledger slice

• CI trust remediation: done in this PR; local coverage artifact audit checked 42 package Cobertura files with no zero-file or under-threshold packages
• Required check: target-repo workflow now emits All tests pass; GitHub ruleset/protection still needs updating after this lands on main
• Renovate config: verified existing renovate.json extends github>tryghost/renovate-config and validates
• pnpm migration: verified repo-pinned pnpm@11.9.0; frozen install passes
• Oxlint/oxfmt: explicit root pnpm lint added to CI and local lint/format checks pass
• README: done in this PR
• AGENTS: done in this PR, with CLAUDE.md symlinked to AGENTS.md
• Supporting docs: not applicable for this slice; package READMEs remain the detailed docs surface
• Diagrams: not applicable; no flow or architecture diagram needed for the current cleanup
• GitHub description: already matches repo-meta description

Verification

• corepack pnpm install --frozen-lockfile
• corepack pnpm lint
• corepack pnpm format:check
• corepack pnpm --filter @tryghost/errors test
• corepack pnpm --filter @tryghost/prometheus-metrics test
• corepack pnpm --filter @tryghost/job-manager test
• corepack pnpm --filter @tryghost/nodemailer test
• corepack pnpm --filter @tryghost/security test
• corepack pnpm --filter @tryghost/express-test test
• corepack pnpm --filter @tryghost/mw-vhost test
• corepack pnpm test:ci
• corepack pnpm audit --audit-level moderate
• corepack pnpm dlx --package renovate renovate-config-validator renovate.json

Follow-up after merge

• update the default-branch ruleset/protection to require All tests pass instead of All tests passed
• verify GitHub Dependabot and CodeQL alert state after the branch is scanned on main
• update cleanrepos repo-meta/ledger without promoting framework.yaml to confirmed

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 21 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 33df5f47-0e80-458c-8238-5b4dabcf96fb

📥 Commits

Reviewing files that changed from the base of the PR and between 0dcfe3b and 606f6b6.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (14)

• .github/workflows/test.yml
• AGENTS.md
• CLAUDE.md
• README.md
• packages/errors/vitest.config.ts
• packages/express-test/example/app.js
• packages/job-manager/test/jobs/timed-job.js
• packages/job-manager/vitest.config.ts
• packages/mw-vhost/test/vhost.test.js
• packages/nodemailer/lib/nodemailer.js
• packages/prometheus-metrics/vitest.config.ts
• packages/security/lib/tokens.js
• pnpm-workspace.yaml
• vitest.config.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch aileen/gva-823-clean-repos-framework

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.24%. Comparing base (0dcfe3b) to head (606f6b6).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #772      +/-   ##
==========================================
+ Coverage   98.07%   98.24%   +0.17%     
==========================================
  Files          86       93       +7     
  Lines        2804     3138     +334     
  Branches      519      570      +51     
==========================================
+ Hits         2750     3083     +333     
  Misses         12       12              
- Partials       42       43       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR improves CI “clean repo” trust signals and documentation for the Framework monorepo by tightening CI behavior (lint + explicit “All tests pass” gate), fixing Vitest coverage scoping for TS packages, and documenting/justifying legacy and test-fixture patterns (incl. CodeQL rationale) while patching a vulnerable transitive dependency via pnpm overrides.

Changes:

• Fix Vitest coverage measurement so TypeScript packages with src/ are measured correctly; adjust shared root coverage excludes accordingly.
• Make CI more explicit and trustworthy: add pnpm lint, set minimal workflow permissions, and rename the required-check aggregator to All tests pass; remove job-manager unhandled-error suppression by fixing worker fixtures.
• Add/expand repo-level docs (README.md, AGENTS.md) and pin js-yaml via pnpm override/lockfile update; add CodeQL suppression rationale for compatibility/test fixtures.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
vitest.config.ts	Updates shared coverage exclude rules so src/ isn’t erroneously excluded from coverage accounting.
README.md	Adds install/usage guidance and clarifies repo workflows and commands.
pnpm-workspace.yaml	Adds a pnpm override to force patched js-yaml for vulnerable transitive consumers.
pnpm-lock.yaml	Lockfile update to reflect the js-yaml override and resolved versions.
packages/security/lib/tokens.js	Adds CodeQL rationale comment for reset-token hashing behavior.
packages/prometheus-metrics/vitest.config.ts	Ensures package coverage config properly scopes to src/** (and clears inherited excludes).
packages/nodemailer/lib/nodemailer.js	Documents and suppresses CodeQL findings for legacy SES ServiceUrl parsing compatibility.
packages/mw-vhost/test/vhost.test.js	Adds CodeQL rationale comment for hostname-regexp-related test behavior.
packages/job-manager/vitest.config.ts	Removes unhandled-error suppression to keep unhandled errors fatal for this package.
packages/job-manager/test/jobs/timed-job.js	Fixes worker fixture timing handling to avoid leaking unhandled rejections.
packages/express-test/example/app.js	Adds CodeQL rationale comment for intentionally insecure test-fixture session setup.
packages/errors/vitest.config.ts	Ensures package coverage config properly scopes to src/** (and clears inherited excludes).
AGENTS.md	Adds agent-facing repo notes: structure, commands, CI expectations, and coverage conventions.
.github/workflows/test.yml	Adds minimal permissions, runs pnpm lint, and renames the aggregator check to All tests pass.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.