docs: add override hygiene auditing documentation

[sonukapoor]

Adds comprehensive documentation for the cve-lite overrides command, surfaces the feature across the website, and includes real-world example fixtures from four major JS projects.

What changed

• New website/docs/override-hygiene/ section with an index page and one page per rule (OA001-OA008), each with explanation, example, terminal output, fix command, and diagrams
• Sidebar updated with Override Hygiene category under Integrate
• Homepage stat pill and feature card added
• Comparison table row added (override hygiene auditing vs all peer tools)
• Docs index entry added
• Fix mode guide updated with --check-overrides combo and standalone audit command
• Workflow integration guide updated with CI patterns and GitHub Actions two-step example
• Footer Guides link added
• README comparison table updated
• Example fixtures added from cal.com, Next.js, NoCoDB, and Jest for reproducible override audit scanning and future test use

Closes #728

[sonukapoor]

@alamb-hex, can you take a look at this PR, please?

[Copilot]

Pull request overview

Adds a new “Override Hygiene Auditing” documentation section for the cve-lite overrides command (OA001–OA008), and surfaces it across the Docusaurus site and top-level docs/README so users can discover and integrate the feature. Also introduces several real-world package.json fixtures intended for reproducible override-audit scanning.

Changes:

• Adds a new /docs/override-hygiene guide index plus one page per rule (OA001–OA008), including examples, outputs, fix guidance, and diagrams.
• Integrates the new docs section into the website UI (homepage feature card, sidebar category, footer/nav link) and existing guides (workflow integration, fix mode, docs index, comparison tables).
• Adds example fixtures from cal.com, Next.js, NoCoDB, and Jest under examples/ for future scans/tests.

Reviewed changes

Copilot reviewed 21 out of 25 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
website/src/pages/index.tsx	Adds homepage messaging + a new feature card linking to override hygiene docs.
website/sidebars.ts	Adds an “Override Hygiene” sidebar category with OA001–OA008 entries.
website/docusaurus.config.ts	Adds a footer/nav link to the override hygiene docs.
website/docs/workflow-integration.md	Documents CI usage patterns for override hygiene audits.
website/docs/override-hygiene/index.md	New top-level guide page: how to run, rule summary, autofix table, CI guidance, comparisons.
website/docs/override-hygiene/oa001.md	New OA001 rule page.
website/docs/override-hygiene/oa002.md	New OA002 rule page.
website/docs/override-hygiene/oa003.md	New OA003 rule page.
website/docs/override-hygiene/oa004.md	New OA004 rule page.
website/docs/override-hygiene/oa005.md	New OA005 rule page.
website/docs/override-hygiene/oa006.md	New OA006 rule page.
website/docs/override-hygiene/oa007.md	New OA007 rule page.
website/docs/override-hygiene/oa008.md	New OA008 rule page.
website/docs/index.md	Adds an entry for the override hygiene docs in the main docs index.
website/docs/fix-mode.md	Documents using --check-overrides with --fix, plus the standalone audit flow.
website/docs/comparison.md	Adds “Override hygiene auditing” row to the docs comparison table.
README.md	Adds an “Override hygiene auditing” row to the README comparison table + link to the new guide.
examples/nocodb/package.json	Adds a real-world fixture package.json for override auditing scenarios.
examples/nextjs/package.json	Adds a real-world fixture package.json for override auditing scenarios.
examples/jest/package.json	Adds a real-world fixture package.json (Yarn resolutions) for override auditing scenarios.
examples/cal-com/package.json	Adds a real-world fixture package.json (Yarn resolutions) for override auditing scenarios.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[alamb-hex]

Took a pass focused on the OA rule docs for technical accuracy against the merged detectors. The structure is great - one page per rule with explanation, example, terminal output, fix command, and diagrams is exactly what this needed, and the per-rule fix descriptions are accurate for OA001-OA005, OA007, OA008. Two things to fix, both where the docs drifted from current behavior:

1. OA006 fix description is inaccurate (the important one)

oa006.md says "Auto-fix: yes", "--fix applies the structural rewrite automatically", and "adds a parent override at >=<parent-installed-version>". The merged detector does something deliberately different:

• The fix is tier: 'proposed' - surfaced as a recommendation, not applied by default. So it's not auto-fix.
• It writes a parent dependency floor, never a new override entry - that's the chokepoint-guard invariant (the fix hook can remove/repin/relocate existing overrides but never invents a new override key). If the parent already has an override it repins that to the floor; if not, it relocates (retire the binary override + add a /dependencies floor).

Suggested wording:

Auto-fix: proposed (suggested, not applied by default)

--fix surfaces a recommendation rather than applying it. If the parent already has an override, it repins that to a >=<parent-installed-version> floor; if not, it relocates - retires the binary override and adds a parent dependency floor (an upgrade), never a new override key. Because the floor is inferred, it is surfaced for review rather than auto-applied.

The "OA006 checks node_modules before firing / stays silent when already effective" part is accurate - keep that.

2. Terminal-output examples don't match shipped output

The ## Terminal output blocks in oa001-oa007 (7 files) show:

fix: applicable patch (1 op)

The renderer in src/output/override-findings-terminal.ts actually prints:

fix: autofix available (1 op)

(It was renamed from the original "applyable" to "autofix available" - the spelling fix to "applicable" landed in the docs but the code emits "autofix available".) Updating the seven examples to fix: autofix available (N op) keeps the captures matching real output. oa008 correctly has no fix line (auto-fix: no).

Nice-to-have, not blocking: the cal.com / Next.js / NoCoDB / Jest fixtures are a great real-world demo set. Worth noting they are complementary to - not a substitute for - small synthetic per-rule fixtures for deterministic e2e (the #44 / examples-library thread); these real lockfiles will drift with upstream, the synthetic ones won't. Happy to take that on separately.

Everything else verified accurate against the detectors. Great addition - this makes the feature real for users.

[sonukapoor]

@alamb-hex Both items are addressed:

• ebb250a updates the terminal output label from "applicable patch" to "autofix available" across oa001-oa005 and oa007.
• 83c7237 changes the OA006 auto-fix header to "proposed (suggested, not applied by default)", rewrites the --fix prose to reflect the tier: 'proposed' behavior, and updates both summary tables in index.md.

The note about complementing real-world fixtures with synthetic per-rule fixtures for deterministic e2e is a good idea - will open a separate issue for that.

[sonukapoor]

@alamb-hex Can you review this one more time?

[alamb-hex]

Both items from the last round are verified fixed:

• Terminal-output examples now read fix: autofix available (N op) across oa001-oa007 (oa008 correctly has no fix line) - matches the renderer.
• OA006 is now Auto-fix: proposed (suggested, not applied by default) and the prose reflects the real behavior - repin an existing override or relocate to a parent dependency floor, never a new override key. Accurate against the tier: 'proposed' detector.

Docs are technically accurate now. LGTM.

One heads-up before merge: the branch conflicts with main, and it's just the tool-comparison table in website/docs/comparison.md. Main has since grown that table to 8 tools (added DependencyCheck and dep-scan) and already includes the "Override hygiene auditing" row. So on rebase, just take main's version of that table - the override row is already there in the wider form, nothing from this branch's 6-tool copy is needed. That's the only conflict; the other 24 files are clean.