Add e18e replacement suggestions, supply-chain combination flags, and maintenance drift tiers

[JosephMaynard]

Ports the worthwhile analysis from the retired Dependency Radar SaaS into the CLI as one PR. The SaaS composite risk score is deliberately not ported — the individual signals below are surfaced as explainable findings instead of a 0–100 number.

Replacement suggestions (e18e)

• Every scanned package is matched offline against the vendored module-replacements catalogue, part of the e18e ecosystem performance initiative (MIT, pinned to v3.0.0, 792 entries).
• Vendored at build time via scripts/build-replacements.ts → src/generated/replacements.ts (same pattern as the SPDX data; refresh with npm run update:replacements). Zero runtime dependencies, works with --offline.
• Surfaced in dependencies[id].replacement, the report's Upgrade & Change Impact detail panel (with credit and links to e18e / module-replacements), explain <pkg> output, and info-level modernization findings for direct dependencies only.
• The header Replacements stat, the Has replacement suggestion filter, and the detail section are all hidden unless the scan actually matched something.
• Sample data now includes a recommendation on the chalk stand-in (util.styleText, picocolors, ansis) so npm run dev:report shows the feature.

Supply-chain combination flags

Install lifecycle scripts paired with a mutable or unverifiable source now produce dedicated findings that explain why the pairing matters:

Combination	Severity
Install scripts + git dependency	error
Install scripts + non-registry tarball	error
Install scripts + unexpected registry host	error
Install scripts + missing lockfile integrity	warning

Shared logic in src/supplyChainCombos.ts feeds findings, report key points, overall dependency risk (error combos escalate to red), and a new opt-in supply-chain-combo --fail-on rule.

Maintenance drift tiers + upgrade risk

• New slowing status: 12+ months without any registry write.
• Dual-signal escalation using the repository pushed_at timestamp already returned by the existing bounded ecosyste.ms lookups (no new hosts): registry and repo must both be quiet before a package is called stale (12mo/6mo) or unmaintained (24mo/12mo). An actively developed package that just stopped publishing stays slowing.
• Single-signal fallback keeps the existing 18/36-month behaviour, so --offline and degraded scans are unchanged.
• Derived upgrade.risk band (high/medium/low/unknown) from outdated status and blockers, recomputed after registry enrichment.

Housekeeping

• Report schema bumped to 1.7 (purely additive; 1.6 baselines remain valid for compare).
• README documents all three features, the new status tiers, and the new CI rule.
• Committed dist/ includes a catch-up rebuild: Harden Dependency Radar for v1.0.0 #86 changed src/ but shipped without rebuilding dist/, so part of this diff is that drift.
• No release/tag — more PRs to come before the next version.

Testing

• 186 unit tests pass (new suites for combos and upgrade risk; extended maintenance, findings, and failOn tests).
• tsc clean; report-ui typecheck shows only the 3 errors that pre-exist on master.
• End-to-end offline scan of test-repos/cal.diy: 301 replacement matches, 16 modernization findings, upgrade-risk bands populated, output validates against schema 1.7, and the generated HTML contains the new UI elements.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added fully offline replacement suggestions with a Replacements stat chip, Has replacement suggestion filtering, and explain output (direct dependencies only).
  • Added per-dependency Upgrade risk banding (high/medium/low/unknown).
  • Expanded maintenance signals with a new slowing state based on repo push timing.
  • Added supply-chain combo reporting, including optional enforcement via --fail-on supply-chain-combo.
• Documentation
  • Updated README for maintenance signals, replacements, upgrade risk, and --fail-on (including supply-chain-combo).
• Changes
  • Report schema bumped to 1.7 and added the modernization finding category.
• Tests
  • Updated/added coverage for schema, replacements, upgrade risk, maintenance “slowing,” and supply-chain combo detection.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds dual-surface maintenance statuses, offline replacement suggestions, upgrade-risk bands, supply-chain combination findings and policy rules, schema 1.7 updates, and report UI support for displaying and filtering the new dependency data.

Changes

Report enrichment and risk signals

Layer / File(s)	Summary
Maintenance contracts and dual-surface status src/types.ts, src/runners/maintenanceSignals.ts, src/maintenanceCache.ts, src/schema.ts	Maintenance records include repository push timing and the slowing status, with updated cache persistence and schema metadata.
Replacement catalogue and upgrade risk scripts/build-replacements.ts, src/aggregator.ts, src/upgradeRisk.ts, src/findings.ts, src/explain.ts	Pinned manifests generate an offline catalogue; aggregation attaches replacements and computes upgrade-risk bands, findings, and explain output.
Supply-chain combinations and policy evaluation src/supplyChainCombos.ts, src/findings.ts, src/failOn.ts, src/reportDetailRules.ts, src/cli.ts	Install hooks are matched with source signals to produce findings, risk/key-point output, and the supply-chain-combo policy rule.
Report rendering and replacement filtering report-ui/*, src/report.ts, src/report-assets.ts, report-ui/sample-data.json, README.md	Reports display replacement suggestions, upgrade risk, repository push timing, slowing maintenance, and replacement filters and statistics.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant Aggregator
  participant Findings
  participant ReportUI
  CLI->>Aggregator: Aggregate dependencies and enrich records
  Aggregator->>Findings: Build findings from enriched records and signals
  Findings-->>CLI: Return findings and policy inputs
  CLI->>ReportUI: Render schema 1.7 report data
  ReportUI-->>CLI: Display replacement, maintenance, risk, and supply-chain details

Loading

Possibly related PRs

• JosephMaynard/dependency-radar#27: Extends the supply-chain signaling pipeline used by these findings and policy changes.
• JosephMaynard/dependency-radar#32: Overlaps with the src/failOn.ts supply-chain failure handling.
• JosephMaynard/dependency-radar#51: Shares the report-detail risk and key-point plumbing extended here.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main additions: e18e replacement suggestions, supply-chain combo flags, and new maintenance drift tiers.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/port-saas-analysis

---

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

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@report-ui/index.html`:
- Around line 239-247: Update the report stat-chip grid styling used by the
stat-replacements chip so all six desktop chips fit on one row, either by
changing the fixed layout to six columns or by using an adaptive grid. Preserve
the existing responsive behavior for narrower viewports.

In `@report-ui/types.ts`:
- Line 103: Update the schemaVersion type in report-ui/types.ts to include '1.7'
alongside the existing supported versions, keeping the report UI contract
aligned with CLI-generated payloads.

In `@src/cli.ts`:
- Around line 2335-2336: Update the aggregation flow around
applyUpgradeRisk(aggregated) so upgrade-risk derivation always runs immediately
after aggregation, regardless of enrichmentTouchedData. Keep only any
enrichment-dependent findings recomputation conditional, and add a CLI
regression test covering scans without registry or maintenance enrichment that
still produce dep.upgrade.risk from local outdated or blocker data.

In `@src/report-assets.ts`:
- Line 16: Update the source-signal indexing logic in function s so packageId is
used as the primary key, preserving its version-qualified identity when deriving
install-script combinations; fall back to packageName only when packageId is
absent. Ensure combination lookup in function i uses the same packageId-first
keying, then regenerate the JS_CONTENT bundle asset.

In `@src/supplyChainCombos.ts`:
- Around line 67-80: The supply-chain signal index currently collapses different
package instances by name, causing false combinations. In
src/supplyChainCombos.ts:67-80, key the map by packageId or the canonical
packageName@packageVersion identity; in src/failOn.ts:543-548, query it using
the matching dependency instance key such as dep.package.id. Add coverage
proving a source signal on one version and an install hook on another does not
trigger supply-chain-combo.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c357148c-f42d-4d65-b82a-f81c4032aa10

📥 Commits

Reviewing files that changed from the base of the PR and between 76774dd and c42ffc6.

⛔ Files ignored due to path filters (20)

• dist/aggregator.js is excluded by !**/dist/**
• dist/cli.js is excluded by !**/dist/**
• dist/explain.js is excluded by !**/dist/**
• dist/failOn.js is excluded by !**/dist/**
• dist/findings.js is excluded by !**/dist/**
• dist/generated/replacements.js is excluded by !**/dist/**, !**/generated/**
• dist/license.js is excluded by !**/dist/**
• dist/maintenanceCache.js is excluded by !**/dist/**
• dist/outputFormats.js is excluded by !**/dist/**
• dist/report-assets.js is excluded by !**/dist/**
• dist/report.js is excluded by !**/dist/**
• dist/reportDetailRules.js is excluded by !**/dist/**
• dist/runners/maintenanceSignals.js is excluded by !**/dist/**
• dist/runners/npmAudit.js is excluded by !**/dist/**
• dist/schema.js is excluded by !**/dist/**
• dist/supplyChainCombos.js is excluded by !**/dist/**
• dist/upgradeRisk.js is excluded by !**/dist/**
• report-ui/dist/report.css is excluded by !**/dist/**
• report-ui/dist/report.iife.js is excluded by !**/dist/**
• src/generated/replacements.ts is excluded by !**/generated/**

📒 Files selected for processing (27)

• README.md
• package.json
• report-ui/index.html
• report-ui/main.ts
• report-ui/sample-data.json
• report-ui/types.ts
• scripts/build-replacements.ts
• src/aggregator.ts
• src/cli.test.ts
• src/cli.ts
• src/explain.ts
• src/failOn.test.ts
• src/failOn.ts
• src/findings.test.ts
• src/findings.ts
• src/maintenanceCache.ts
• src/report-assets.ts
• src/report.ts
• src/reportDetailRules.ts
• src/runners/maintenanceSignals.test.ts
• src/runners/maintenanceSignals.ts
• src/schema.ts
• src/supplyChainCombos.test.ts
• src/supplyChainCombos.ts
• src/types.ts
• src/upgradeRisk.test.ts
• src/upgradeRisk.ts

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Prevent the replacement stat from wrapping into its own desktop row.

This adds a sixth chip, but the shipped report CSS uses grid-template-columns: repeat(5, 1fr). Reports with replacements will show a lone second-row stat. Use six columns or an adaptive grid.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@report-ui/index.html` around lines 239 - 247, Update the report stat-chip
grid styling used by the stat-replacements chip so all six desktop chips fit on
one row, either by changing the fixed layout to six columns or by using an
adaptive grid. Preserve the existing responsive behavior for narrower viewports.

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Apply upgrade-risk derivation even when no enrichment ran.

applyUpgradeRisk() is gated by enrichmentTouchedData, which remains false for scans without registry/maintenance enrichment (including offline-oriented runs). Those reports omit the new dep.upgrade.risk field despite having local outdated/blocker data. Invoke it immediately after aggregation; keep only findings recomputation conditional if needed. Add a no-enrichment CLI regression test.

Proposed fix

-    if (enrichmentTouchedData) {
-      applyUpgradeRisk(aggregated);
+    applyUpgradeRisk(aggregated);
+    if (enrichmentTouchedData) {
       const findings = buildDependencyFindings(aggregated, { targetNodeMajor: opts.targetNodeMajor });

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if (enrichmentTouchedData) {
	applyUpgradeRisk(aggregated);
	applyUpgradeRisk(aggregated);
	if (enrichmentTouchedData) {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli.ts` around lines 2335 - 2336, Update the aggregation flow around
applyUpgradeRisk(aggregated) so upgrade-risk derivation always runs immediately
after aggregation, regardless of enrichmentTouchedData. Keep only any
enrichment-dependent findings recomputation conditional, and add a CLI
regression test covering scans without registry or maintenance enrichment that
still produce dep.upgrade.risk from local outdated or blocker data.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Keep supply-chain combinations version-qualified.

The bundle indexes source signals by package name, discarding packageId versions before deriving combinations. If foo@1 is git-sourced and foo@2 is registry-sourced, both can receive the same install-script combination finding. Index by packageId first and only fall back to name when the source signal is genuinely unversioned; then regenerate this asset.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/report-assets.ts` at line 16, Update the source-signal indexing logic in
function s so packageId is used as the primary key, preserving its
version-qualified identity when deriving install-script combinations; fall back
to packageName only when packageId is absent. Ensure combination lookup in
function i uses the same packageId-first keying, then regenerate the JS_CONTENT
bundle asset.