epic(enrichment): REES modular analyzer runtime roadmap

[JSONbored]

REES modular analyzer/runtime roadmap

REES is now a production review-enrichment service with many analyzers, not just the original supply-chain/security set. The next bottleneck is no longer "add another analyzer". It is the runtime shape: analyzer PRs conflict because they touch the same central files, and full analyzer runs still spend too much duplicated CPU/network budget.

This epic now tracks the maintainer-only foundation work needed to make REES modular, budget-aware, resource-efficient, and safe to operate in self-hosted maintainer stacks.

Parent: #1029

Current state

• REES lives under review-enrichment/ and is called by the engine from src/review/enrichment-wire.ts.
• fix(rees): return degraded history before caller timeout #1805 fixed the recent history timeout path so REES can return partial/degraded context before the engine transport timeout expires.
• The service is now more reliable for timeout/degraded responses, but it is not yet structurally performance optimized.
• Analyzer implementation is still centralized across registry, types, rendering, engine allow-lists, UI metadata, docs, and shared tests.
• Several analyzers independently parse the same PR data or call the same external services.

Goals

• Make analyzers modular so contributor and maintainer PRs stop conflicting in the same core files.
• Allow self-host operators to enable/disable analyzers individually or by profile.
• Make every analyzer budget-aware and fail-open with useful degraded status.
• Reduce duplicated parsing, external fanout, and resource usage.
• Improve safe Sentry/context attribution without leaking secrets, tokens, request bodies, diffs, raw prompts, comments, or private configs.
• Preserve engine compatibility while making REES easier to evolve.

Maintainer-only foundation issues

These are intentionally maintainer-only, assigned to JSONbored, and should not carry gittensor:* labels.

• refactor(rees): introduce modular analyzer manifests #1809 - refactor(rees): introduce modular analyzer manifests
• perf(rees): add shared analysis context and request caches #1810 - perf(rees): add shared analysis context and request caches
• perf(rees): add cost-aware analyzer scheduling and profiles #1811 - perf(rees): add cost-aware analyzer scheduling and profiles
• fix(rees): standardize bounded external fetches #1812 - fix(rees): standardize bounded external fetches
• feat(rees): generate analyzer config and self-host profiles #1813 - feat(rees): generate analyzer config and self-host profiles
• feat(rees): add performance guardrails and regression telemetry #1814 - feat(rees): add performance guardrails and regression telemetry

Recommended sequence

1. Start with refactor(rees): introduce modular analyzer manifests #1809. This creates the analyzer manifest/descriptor pattern and reduces future merge conflicts.
2. Do perf(rees): add shared analysis context and request caches #1810 and fix(rees): standardize bounded external fetches #1812 next. Shared context/caches and bounded fetches are the core performance substrate.
3. Do perf(rees): add cost-aware analyzer scheduling and profiles #1811 after the shared context exists. Scheduling is much easier when analyzers declare cost and limits.
4. Do feat(rees): generate analyzer config and self-host profiles #1813 after manifests/profiles are stable so self-host docs and UI metadata can be generated from runtime truth.
5. Do feat(rees): add performance guardrails and regression telemetry #1814 across the sequence as the regression guardrail, with final tests proving REES returns partial/degraded output before caller timeouts.

Analyzer contribution rules after this epic starts

• New analyzers should live mostly under review-enrichment/src/analyzers/<name>/.
• Each analyzer should declare name, category, cost class, default enabled state, external requirements, limits, timeout behavior, renderer, and docs metadata.
• Analyzer PRs should avoid hand-editing central registry/render/config surfaces once generated or manifest-backed surfaces exist.
• Every analyzer must have clear skip predicates, bounded fanout, safe diagnostics, and focused tests.
• External-call analyzers must use the shared bounded fetch/client layer unless an exception is documented.
• Output must remain public-safe and review-useful: file/package/line/count/reason context is fine; raw payloads and private data are not.

Performance/resource requirements

• REES must reserve enough response time to return before the engine transport timeout.
• Slow analyzers should degrade individually instead of causing whole-request failure.
• Cheap local analyzers should run first and should not wait behind GitHub/registry work.
• Dependency and registry analyzers should skip early when no relevant files changed.
• GitHub-heavy analyzers should have strict file/commit/PR lookup caps and short subcall timeouts.
• Safe telemetry should include analyzer, requested analyzers, repo, PR number, head SHA prefix, release, timeout budget, elapsed time, phase/subcall, partial status, analyzer status, file/commit/PR lookup counts, endpoint category, request id, and trace id.

Existing analyzer backlog

The existing analyzer feature backlog is still useful, but new implementation should wait for or adapt to the modular manifest pattern to avoid more merge conflicts.

Open analyzer issues already split from this epic include:

• feat(enrichment): Cross-file caller-impact / dead-symbol analyzer #1509 - Cross-file caller-impact / dead-symbol analyzer
• feat(enrichment): Exported-API breaking-change detector #1510 - Exported-API breaking-change detector
• feat(enrichment): Package maintenance-health / deprecated-dep scorer #1511 - Package maintenance-health / deprecated-dep scorer
• feat(enrichment): Churn-hotspot + bug-density scorer #1513 - Churn-hotspot + bug-density scorer
• feat(enrichment): Revert-recurrence detector #1514 - Revert-recurrence detector
• feat(enrichment): Changed-line coverage-delta #1516 - Changed-line coverage-delta
• feat(enrichment): Doc-comment-vs-signature drift #1519 - Doc-comment-vs-signature drift
• feat(enrichment): Full-file / near-verbatim duplication scan #1520 - Full-file / near-verbatim duplication scan

Speculative/later analyzer ideas remain:

• Uncaught-rejection / floating-promise + error-swallow analyzer.
• SQL migration safety analyzer.
• Deprecated-API and framework anti-pattern cross-checker.
• Accessibility and i18n regression detector.
• Public-API undocumented-export scan.
• Blame-to-PR regression linker.
• Flaky-test history annotator.
• Enum/literal-union exhaustiveness drift.
• License compatibility deep-resolver.

Non-goals for the foundation pass

• Do not build a hosted website scanner before the runtime is modular and bounded.
• Do not add large new analyzers until the manifest/context/scheduler work is in place.
• Do not make REES rely on forwarded GitHub tokens by default.
• Do not expand Sentry context with sensitive payloads.

Definition of done for this epic

• Analyzer PRs can be implemented with minimal central-file conflicts.
• Self-host operators can select individual analyzers or profiles with clear resource expectations.
• REES returns useful partial/degraded context before caller timeouts.
• External fanout is capped, attributed, and test-covered.
• Sentry failures are immediately attributable to analyzer, phase/subcall, endpoint category, budget, elapsed time, and safe request identity.