release: v1.28.0

[sonukapoor]

Added

• Cooldown-aware fix resolver: warns when a recommended fix version is newer than the project's configured release cooldown (npm min-release-age, pnpm minimumReleaseAge, yarn npmMinimalAgeGate); advisory only (no flag, no exit-code change, on by default), renders in terminal, --verbose, JSON, and HTML report; npm/pnpm/yarn, Bun not yet covered
• --check-maintenance (DM001) maintenance risk detector: flags direct dependencies that block a transitive CVE fix via a major-version constraint drag, or that are deprecated on npm; renders in terminal, JSON, multi-folder, and HTML report, and counts toward --fail-on
• advisories init command to create an empty offline advisory database for air-gapped users to populate themselves
• Show skipped manifest dependencies in the HTML report and report.json

Fixed

• Verify parent-upgrade recommendations actually resolve the vulnerable package before recommending them: the resolver walks the dependency path and only recommends a parent upgrade when the terminal package resolves to a fixed version or is dropped from the path; it returns no recommendation when no version fixes it, and marks unverifiable suggestions, excluding them from the "should fix all findings" claim
• Expire OSV detail cache records via a TTL so refined advisories are refetched instead of served stale; a stale detail no longer forces an unnecessary major bump over an available within-range fix. Cache format bumped to v4 with transparent migration
• Preserve vulnerability evidence when advisory detail lookups fail: transient failures now retry instead of being cached as a confirmed miss; only real 404/410 responses are negatively cached
• Count multi-folder --check-overrides findings toward --fail-on; previously a multi-folder CI scan silently passed on high override findings
• GitHub Action: omit --no-cache when offline mode is active, so the Action no longer fails the CLI's flag validation on the first run
• Apply --ca-cert to the main scan path via a cert-aware fetch using node:https
• Remove a dead null guard and de-collide the skipped-deps icon in the HTML report

Changed

• Unify the Override Hygiene and Maintenance Risk HTML report tables with the main Findings table styling
• Extract the cache TTL magic number to a named CACHE_TTL_MS constant

Docs

• Add a Release Cooldown Awareness docs page, README section, and homepage pill and FeatureCard
• Add a maintenance-risk (DM001) documentation section
• Document the advisories init command in the CLI reference and offline advisory DB guide
• Add a Renovate comparison page

Validation

• npm test
• npm run build

Contributors

Thanks to the external contributors whose work is part of this release:

• @Ayush7614 - count multi-folder override findings toward --fail-on; omit --no-cache in the Action when offline
• @ELHart05 - advisories init command, skipped manifest dependencies in the HTML report, and the advisories init docs
• @luojiyin1987 - preserve vulnerability evidence when advisory detail lookups fail
• @mgalore - extract the cache TTL to a named constant
• @pandeysambhi - minimal pull request template