feat(github-app): wire check-run annotations for Context check

[kiannidev]

Summary

• Adds buildCheckRunAnnotations in src/rules/advisory.ts to map duplicate-overlap, missing-test, and public finding hotspots onto changed PR files with sanitized messages, severity→level mapping, and a 50-annotation cap plus omitted-count rollup in formatCheckRunOutput.
• Wires output.annotations[] through createOrUpdateCheckRun / createOrUpdateNamedCheckRun for the Gittensory Context check only; Gate stays text-only.
• Loads cached PR files in processGitHubWebhook so Context check runs can annotate changed paths.
• Adds unit coverage in test/unit/rules.test.ts and test/unit/github-app.test.ts for builder behavior, sanitizer boundaries, cap/rollup, and Context-vs-Gate wiring.

Closes #575

Scope

• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; global coverage stays at or above 97% for lines, statements, functions, and branches (aim for 98%+ branch coverage locally so CI variance does not fail near the threshold)
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm run audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• npm run validate was run locally (covers typecheck + test:coverage); branch coverage met the 97% threshold.
• Remaining CI checks (actionlint, test:workers, build:mcp, test:mcp-pack, ui:*, audit) are left for CI to run.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (not applicable — check-run output wiring only; existing GitHub App permission paths unchanged)
• API/OpenAPI/MCP behavior is updated and tested where needed. (no public API/OpenAPI/MCP surface change)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (not applicable — backend only)
• Visible UI changes include screenshots or a short recording. (not applicable — no UI changes)
• Public docs/changelogs are updated where needed. (not applicable)

Notes

• Parent epic: feat(github-app): per-file/line check-run annotations #537
• Annotations respect checkRunDetailLevel; minimal detail level publishes no inline annotations.
• Gate check output is intentionally unchanged and remains text-only.

[ghost]

Note

Gittensory Gate skipped

PR closed before full evaluation. No late first comment was created.

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#607 is no longer open.	No action.

---

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[ghost]

reviewbot · advisory review

Reviewed 5 changed file(s) — two independent AI reviewers.

Suggested action: ✅ Safe to merge — the reviewer found no blocking issues.

Reviewer A · gpt-oss-120b — recommends ✅ merge
The PR adds full support for check‑run annotations in the Context check, introducing new types, annotation building logic, and wiring it through the queue and GitHub app code. The changes compile, are well‑tested, and respect GitHub limits.

Suggestions

• Add a comment documenting the new annotation limit constant and its relation to the GitHub API limit.
• Consider adding a TypeScript JSDoc comment for buildCheckRunAnnotations to clarify its parameters and return shape.
• Verify that listPullRequestFiles is exported from the module and returns PullRequestFileRecord[] as expected.

Worth double-checking

• If listPullRequestFiles does not match the expected signature or returns unexpected data, the annotation context could be incomplete.
• Future callers of formatCheckRunOutput must remember to pass the annotation context; missing it will silently drop annotations.

Reviewer B · nemotron-3-120b-a12b — review unavailable

[ghost]

gittensory · advisory review

Reviewed 3 changed file(s) — two independent AI reviewers.

Suggested action: ✅ Safe to merge — both reviewers found no blocking issues.

Reviewer A · gpt-oss-120b — recommends ✅ merge
The PR extends the GitHub check‑run creation to support file‑level annotations for the Context check by adding an optional annotation context parameter and wiring it through the queue processor. The changes are scoped, type‑safe, and include a new test verifying the new behavior.

Suggestions

• Add a comment or documentation note indicating that the annotationContext parameter is optional and describing its shape.
• Consider adding a test case where no files are returned to ensure the function still works without annotations.
• Verify that all other call sites of createOrUpdateCheckRun compile with the new optional parameter (they should, but a quick type‑check is advisable).

Worth double-checking

• If formatCheckRunOutput does not correctly handle undefined annotationContext, existing check‑run creation could break.
• listPullRequestFiles may throw or return unexpected data; ensure error handling does not affect the main flow.

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
The PR wires check‑run annotations for the Context check by threading an optional annotationContext through createOrUpdateCheckRun, updating the call site in the queue processor, and adding a test that verifies annotations appear on the Context check but not the Gate check. The changes are focused and follow the existing patterns.

Suggestions

• Confirm that formatCheckRunOutput in src/rules/advisory.ts has been updated to accept an optional annotationContext parameter and returns a CheckRunOutput that can include annotations.
• Verify that CheckRunAnnotationContext and CheckRunOutput are properly exported from ../rules/advisory so the new imports succeed.
• Ensure the test helper createOrUpdateGateCheckRun used in the new test is defined (or replace it with the appropriate call) to avoid test runtime errors.

Worth double-checking

• If the advisory module was not updated to match the new formatCheckRunOutput signature, the call will throw a TypeError at runtime.
• If the exported types are missing, the TypeScript compilation will fail.
• The test may fail if the helper function createOrUpdateGateCheckRun is not available in the test file.

[JSONbored]

Please fix failing CI.