feat(enrichment): add maintenance-health dependency analyzer (#1511)

[jonathanchang31]

Summary

Adds a new REES analyzer for issue #1511 that flags direct dependency additions or upgrades with maintenance-risk signals from public registries.
The analyzer currently reports:

• deprecated npm or PyPI packages
• yanked PyPI releases
• stale releases with no recent publish activity
• sole-maintainer packages

It is wired into the REES findings contract, analyzer registry, and rendered external review brief. Focused tests were added for npm and PyPI paths, fail-safe behavior, and rendered output.

Related Issue

Closes: #1511

Change Type

• New feature
• Bug fix
• Tests
• Documentation
• Refactor
• Breaking change

Real Behavior Proof

Added behavior

• A direct npm dependency with a deprecation notice, old release date, and one maintainer is reported as a maintenance-health finding.
• A yanked PyPI release is reported as a maintenance-health finding.
• Healthy dependencies and unsupported ecosystems are skipped.
• Registry fetch failures fail safe and do not block the brief.

Validation

npm --prefix review-enrichment test

Checklist

• Linked issue is valid and in scope
• Change stays within allowed repo paths
• Added focused tests for new behavior
• Verified fail-safe behavior on fetch errors
• Kept output public-safe

Notes

• Scope is intentionally narrow and low-noise.
• The analyzer currently covers npm and PyPI direct dependency changes only.
• Findings are additive and fail-safe, consistent with existing REES analyzer behavior.

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-06-29 21:42:31 UTC}

6 files · 1 AI reviewer · 1 blocker · readiness 55/100 · CI green · dirty

⏸️ Suggested Action - Manual Review

• The AI review flagged a possible must-fix defect below the automatic close-confidence floor, so the gate is held for a human reviewer instead of passed automatically.

Review summary
The change wires a new maintenance-health analyzer into REES, adds rendering and contract support, and covers the happy-path npm/PyPI cases plus fail-open behavior. The registry lookup and brief integration are mostly coherent, but the staleness signal is computed from inconsistent sources and will produce wrong findings for real packages: npm can hide stale release history behind metadata modification time, while PyPI only checks the selected version instead of project activity.

Blockers

• review-enrichment/src/analyzers/maintenance-health.ts:76 uses npm `time.modified` as the release-activity date, so a package with no releases for 3+ years but a recent metadata/deprecation edit will not emit the intended `stale-release` finding; compute the max timestamp across version entries instead of preferring `modified`.
• review-enrichment/src/analyzers/maintenance-health.ts:149 sets PyPI `lastReleaseDate` from only `releases[version]`, so adding an old pinned version of an actively maintained project will incorrectly emit `stale-release`; scan all release upload times for project-level recent publish activity, matching the npm behavior tested at `review-enrichment/test/maintenance-health.test.ts:92`.

Nits — 7 non-blocking

• nit: review-enrichment/src/analyzers/maintenance-health.ts:89 should validate that `data.versions?.[version]` exists before reporting package-level signals, otherwise a malformed or range-like extracted version can still produce stale/maintainer findings for a version the registry does not contain.
• nit: review-enrichment/src/analyzers/maintenance-health.ts:161 performs up to 25 registry calls sequentially, which can consume the whole analyzer budget on ordinary dependency bumps; consider bounded parallelism or a smaller lookup cap if this starts degrading briefs.
• In `latestNpmActivityDate`, remove the `modified` fast path and derive the latest date from actual version keys only, with a test where `modified` is recent but every version timestamp is stale.
• In `fetchPypiSignals`, compute `lastReleaseDate` from all arrays in `data.releases`, while still computing `yanked` from the selected `version` release files.
• Add a PyPI counterpart to the existing active-package npm test so an old selected version with a recent newer release does not produce `stale-release`.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.
• AI reviewers agree on a likely critical defect: review-enrichment/src/analyzers/maintenance-health.ts:76 uses npm `time.modified` as the release-activity date, so a package with no releases for 3+ years but a recent metadata/deprecation edit will not emit the intended `stale-release` finding; compute the max timestamp across version entries instead of preferring `modified`. — Resolve the flagged defect, or override if the AI reviewers are mistaken, then re-run the gate.

Concerns raised — review before merging

• review-enrichment/src/analyzers/maintenance-health.ts:76 uses npm `time.modified` as the release-activity date, so a package with no releases for 3+ years but a recent metadata/deprecation edit will not emit the intended `stale-release` finding; compute the max timestamp across version entries instead of preferring `modified`.

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	✅ No-issue rationale	PR body explains why no issue is linked.
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 (size label size:L; no linked issue context).
Validation posture	❌ 5/25	Preflight is holding this PR; address the blocker before review.
Contributor workload	✅ 10/10	Author activity: 123 registered-repo PR(s), 67 merged, 11 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	jonathanchang31; Gittensor profile; 123 PR(s), 11 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Review context

• Author: jonathanchang31
• 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: 123 PR(s), 11 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (PR #1750)
• Related work: Titles/paths share 6 meaningful terms. (PR #1763)
• Related work: Titles/paths share 6 meaningful terms. (PR #1764)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Fix the blocker.
• Triage stale or unlinked PRs.
• Refresh registry data or choose a registered active repo.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.
• 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

[loopover-orb]

Important

🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪🟪

🔍 Gittensory is reviewing…

AI analysis is in progress. This comment will update when the review is complete.

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

[JSONbored]

Blockers identified by gittensory orb review agent, and also a merge conflict with the README:

This branch has conflicts that must be resolved
Use the [web editor](https://github.com/JSONbored/gittensory/pull/1751/conflicts) or the command line to resolve conflicts before continuing.

review-enrichment/README.md

Closing.