feat(enrichment): add exported-API breaking-change analyzer

[e11734937-beep]

Summary

Adds apiBreak, a local (no-network) REES analyzer that flags an exported symbol a PR removes or renames in a package's public entrypoint (index / mod / main / public-api barrels) — a semver-major break that reaches downstream consumers, shipped without a major version bump. Closes #1510.

The no-checkout headless reviewer only sees the diff, so it cannot tell that a barrel dropped a name it used to export. This fills that gap purely from the patch: for each changed public-entrypoint file it collects the exported names on removed (-) lines and on added (+) lines, and reports a name present in the removed set but absent from the added set.

• Conservative / fail-safe: a same-name edit (a signature or value change re-adds the name) is never flagged; only exact whole-name loss is. Non-entrypoint files are out of scope (that is the in-repo caller-impact analyzer's job, per the issue). Deterministic, no network, no token; bounded by entrypoint and finding caps; returns nothing on absent/malformed patches.
• Reports file, old-file line, and the removed/renamed symbol name only — never surrounding code.

Files

• review-enrichment/src/analyzers/api-break.ts — the analyzer (pure diff parsing).
• review-enrichment/src/analyzers/registry.ts, src/types.ts, src/render.ts — descriptor, ApiBreakFinding / BriefFindings key, and the public-safe render section.
• src/review/enrichment-analyzer-names.ts + review-enrichment/test/analyzer-registry.test.ts — canonical name registry entry.
• review-enrichment/analyzer-metadata.json, apps/gittensory-ui/src/lib/rees-analyzers.ts, .env.example — regenerated via npm run rees:metadata.
• review-enrichment/test/api-break.test.ts — units for entrypoint detection, export-name extraction (declarations, export default, aliased/type re-exports, export * as, bare export *), removal / rename / same-name-edit diffing, the caps, the abort path, and the descriptor render.

Validation

• npm run rees:test — build + metadata:check + sourcemaps + 1106 node tests pass (incl. the new apiBreak units).
• npm run typecheck, npm run ui:typecheck, npm run ui:test (64), npm run ui:lint (0 errors), selfhost:env-reference:check, command-reference:check, docs:drift-check — all clean.
• git diff --check clean. No new dependencies. Clean off main, outside the engine tsc/vitest scope.

[superagent-security]

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

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-05 19:59:34 UTC}

10 files · 1 AI reviewer · no blockers · readiness 62/100 · CI green · clean

⏸️ Suggested Action - Manual Review

Review summary
This adds a new local, no-network REES analyzer (apiBreak) that flags exported symbols dropped or renamed in a public-entrypoint file's patch, with correct sign-based diffing logic (removed-name-not-re-added), old-file line tracking that correctly advances only on context/removed lines, and consistent wiring across registry, types, render, UI docs, and regenerated metadata. The regex-based export extraction and hunk-parsing logic in api-break.ts is traced correctly and is conservative by design (single-line-only export lists, no cross-hunk state), and the accompanying test file exercises the entrypoint detection, export-name extraction forms, removal/rename/same-name-edit cases, and both caps.

Nits — 6 non-blocking

• review-enrichment/src/analyzers/registry.ts and apps/gittensory-ui/src/lib/rees-analyzers.ts hardcode the `25`/`25` limits as separate literals instead of importing/referencing MAX_ENTRYPOINTS/MAX_FINDINGS from api-break.ts, so the three copies (analyzer, registry descriptor, UI doc) can silently drift out of sync.
• ENTRYPOINT_BASENAME includes generic stems like `main` and `api`, which could false-positive on internal files that happen to be named that way outside a package root (e.g. a nested `utils/api.ts`); worth confirming this is intentional given the conservative design goal.
• The `+++`/`---` guards inside the +/- branches of removedExports (api-break.ts) are unreachable in practice since GitHub's `file.patch` never includes file-header lines and `inHunk` gates them anyway — harmless but dead defensive code worth a comment or removal.
• Multi-line `export { a, b }` lists spanning more than one diff line are silently unparsed (documented as intentional fail-safe), which is reasonable but could be called out in the rendered brief notes for user awareness of a blind spot.
• Export MAX_ENTRYPOINTS/MAX_FINDINGS from api-break.ts and import them in registry.ts's `limits` field instead of re-typing `25` to keep the three copies in sync.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#1510
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 37 registered-repo PR(s), 17 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	e11734937-beep; Gittensor profile; 37 PR(s), 0 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: e11734937-beep
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 37 PR(s), 0 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (issue #1510, issue #1514)
• Related work: Titles/paths share 5 meaningful terms. (issue #1509, issue #1514)
• Related work: Titles/paths share 5 meaningful terms. (issue #1514, issue #1516)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Await review-lane availability.
• Refresh registry data or choose a registered active repo.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

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

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.19%. Comparing base (bfa9c2d) to head (8375db3).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3619   +/-   ##
=======================================
  Coverage   93.19%   93.19%           
=======================================
  Files         313      313           
  Lines       31874    31874           
  Branches    11666    11666           
=======================================
  Hits        29705    29705           
  Misses       1517     1517           
  Partials      652      652           

Files with missing lines	Coverage Δ
src/review/enrichment-analyzer-names.ts	100.00% <ø> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.