feat(diff): detect version downgrades instead of mislabeling them as upgrades

[dmchaledev]

Summary

diff() lumps every version change into the upgraded array, so a dependency that moves backwards (e.g. 1.3.0 → 1.1.0) is reported as a non-major "upgrade." For a tool keyworded supply-chain-security / vulnerability-management, a rollback is itself a high-signal event:

• a return to a yanked or CVE-affected release,
• a version-pinning regression that quietly undoes a security bump,
• a dependency-confusion / substitution that swaps in a lower version.

Today every one of those renders identically to a routine patch bump. This PR makes downgrades a distinct, visible signal.

Evidence (current behavior)

• src/diff.ts pushes any aComp.version !== bComp.version change into upgraded; direction is never considered.
• isMajorVersionBump() returns false for 2.0.0 → 1.0.0 (since toMajor > fromMajor is false), so a rollback across a major boundary shows up as a plain "upgrade" with no flag at all.

What changed

• types (src/types.ts) — additive, backward compatible:
  • VersionChange.isDowngrade: boolean
  • summary.totalDowngraded: number
• diff (src/diff.ts) — direction is computed with a small dependency-free segment comparator (compareVersions). A downgrade is never also reported as a major bump.
• reporter (src/reporter.ts) — text and Markdown gain a dedicated "Downgraded Components" section; the summary splits upgrades vs. downgrades so the counts are honest.
• tests — rollback detection, forward-upgrade non-regression, the major-version-rollback edge case, and both report renderers (5 new tests; suite goes 29 → 34, all green).

Example

Summary:
  Upgraded:    1
  Downgraded:  1
...
↑ Upgraded Components:
  ~ lodash: 4.17.20 → 4.17.21

↓ Downgraded Components:
  ~ left-pad: 1.3.0 → 1.1.0 [DOWNGRADE]

Why this is a clean addition

• Novel — no open issue or PR addresses version direction. It's orthogonal to the in-flight diff work: the purl-keying PRs (fix: correct upgrade detection and CLI default format #8/fix: detect version upgrades by purl and repair default CLI invocation #10/fix(diff): detect upgrades for version-qualified purls #20) change which components match, not how a matched version change is classified; Detect license changes in diff (parsed Component.license is currently extracted but never compared) #9 (license) and Detect component hash/integrity changes in diff (Component.hashes is declared but never parsed or compared) #22 (hashes) add new arrays rather than touching VersionChange.
• Additive & backward compatible — only adds fields to VersionChange / summary; no existing field or default CLI behavior changes.
• Composable with the proposed CI gate (feat(cli): add --fail-on CI/CD gate, --help/--version, robust arg parsing #5) — once isDowngrade / totalDowngraded exist, --fail-on downgrade becomes a trivial, high-signal gate condition.

Verification

npm run lint, npm run typecheck, npm test (34 passing), and npm run build all pass locally, plus an end-to-end CLI run against CycloneDX fixtures in both text and Markdown.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KPWdF3VnuxevNSR6iUwbQF

---

Generated by Claude Code