feat: show override hygiene hint when overrides detected but --check-overrides not passed

src/index.ts

@@ -44,21 +44,22 @@ import { buildReportData, writeHtmlReport } from "./output/html-reporter.js";
 import { writeOutputs } from "./output/write-outputs.js";
 import { selectFindingsForTable } from "./output/finding-display.js";
 import {
-  printSummary,
   printActionSummary,
-  printSuggestedFixCommands,
-  printSuggestedFixCommandSkips,
+  printCompactOutput,
   printCoverage,
+  printFinalStatus,
+  printOverrideHint,
   printSkippedDependencies,
+  printSuggestedFixCommands,
+  printSuggestedFixCommandSkips,
+  printSummary,
   printTable,
-  printFinalStatus,
-  printCompactOutput
 } from "./output/printers.js";
 import { renderOverrideFindings } from "./output/override-findings-terminal.js";
 import { installSkill } from "./skills/install.js";
 import { readConfig, validateCaCertFile } from "./cli/config.js";
 import { runConfigCommand } from "./cli/config-command.js";
-import { readDirectDependencyNames } from "./utils/package-json.js";
+import { readDirectDependencyNames, hasOverrideEntries } from "./utils/package-json.js";
 import {
   applyFixesIfRequested,
   FixExecutionResult,
@@ -616,6 +617,7 @@ if (parsedArgs) {
 
       if (!(options.json || options.sarif || options.cdx) || options.verbose) {
         const offline = !!options.offline || !!options.offlineDb;
+        const showOverrideHint = !options.checkOverrides && !options.ratchet && hasOverrideEntries(projectPath);
         if (options.verbose) {
           const overrideCount = options.checkOverrides ? overrideFindings.length : 0;
           printSummary(scanState.sorted, packages.length, scanInput);
@@ -643,6 +645,7 @@ if (parsedArgs) {
           }
           printCoverage([...scanInput.notes, ...scanState.coverage]);
           printFinalStatus(scanState.sorted, overrideCount);
+          if (showOverrideHint) printOverrideHint();
         } else {
           const compactPmLabel = scanState.suggestedFixCommands
             ? `${chalk.cyan(scanState.suggestedFixCommands.packageManager)} ${chalk.gray(`(${scanState.suggestedFixCommands.sourceLabel})`)}`
@@ -651,6 +654,7 @@ if (parsedArgs) {
           if (options.checkOverrides) {
             console.log(renderOverrideFindings(overrideFindings, { verbose: false }));
           }
+          if (showOverrideHint) printOverrideHint();
         }
       }
     }

src/output/printers.ts

@@ -348,6 +348,10 @@ export function printFinalStatus(findings: Finding[], overrideCount = 0) {
   );
 }
 
+export function printOverrideHint(): void {
+  console.log("💡 " + chalk.gray("Tip:") + " override entries detected - run with --check-overrides to audit them for stale or broken overrides.");
+}
+
 function renderRow(cells: string[], widths: number[]) {
   const formatted = cells.map((cell, i) => {
     const truncated = truncate(cell, widths[i]);

src/scan/multi-folder-scan.ts

@@ -9,9 +9,10 @@ import { sortFindingsForOutput } from "../output/formatters.js";
 import { normalizeSeverity } from "../osv/severity.js";
 import { selectFindingsForTable } from "../output/finding-display.js";
 import { buildSuggestedFixCommandPlan } from "../remediation/fix-commands.js";
-import { readDirectDependencyNames } from "../utils/package-json.js";
+import { readDirectDependencyNames, hasOverrideEntries } from "../utils/package-json.js";
 import { DEFAULT_BATCH_SIZE, DEFAULT_SEARCH_DEPTH, severityOrder } from "../constants.js";
 import { printMultiFolderResults } from "../output/multi-folder-printer.js";
+import { printOverrideHint } from "../output/printers.js";
 import { writeMultiFolderHtmlReport } from "../output/multi-folder-html-reporter.js";
 import { chalk } from "../utils/chalk.js";
 import { getCliVersion } from "../utils/version-info.js";
@@ -143,6 +144,15 @@ export async function handleMultiFolderScan(params: {
         console.log(renderOverrideFindings(r.overrideFindings, { verbose: !!params.options.verbose }));
       }
     }
+    if (!params.options.checkOverrides && !params.options.ratchet) {
+      for (const r of results) {
+        const subfolderPath = path.join(params.projectRoot, r.subfolder);
+        if (hasOverrideEntries(subfolderPath)) {
+          printOverrideHint();
+          break; // one hint is enough even if multiple subfolders have overrides
+        }
+      }
+    }
   }
 
   if (params.options.report) {

src/utils/package-json.ts

@@ -141,3 +141,19 @@ function expandWorkspacePattern(projectPath: string, segments: string[], current
 export function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
+
+export function hasOverrideEntries(dir: string): boolean {
+  const pkgPath = path.join(dir, "package.json");
+  if (!fs.existsSync(pkgPath)) return false;
+  try {
+    const raw = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as Record<string, unknown>;
+    if (!raw || typeof raw !== "object") return false;
+    if (isRecord(raw.overrides) && Object.keys(raw.overrides).length > 0) return true;
+    const pnpm = raw.pnpm;
+    if (isRecord(pnpm) && isRecord(pnpm.overrides) && Object.keys(pnpm.overrides).length > 0) return true;
+    if (isRecord(raw.resolutions) && Object.keys(raw.resolutions).length > 0) return true;
+    return false;
+  } catch {
+    return false;
+  }
+}

tests/cli-integration.test.ts

@@ -28,6 +28,7 @@ const printSkippedDependenciesMock = jest.fn<any>();
 const printTableMock = jest.fn<any>();
 const printFinalStatusMock = jest.fn<any>();
 const printCompactOutputMock = jest.fn<any>();
+const printOverrideHintMock = jest.fn<any>();
 const buildSuggestedFixCommandPlanMock = jest.fn<any>();
 const spawnMock = jest.fn<any>();
 const buildReportDataMock = jest.fn<any>();
@@ -101,6 +102,7 @@ jest.unstable_mockModule("../src/output/printers.js", () => ({
   printTable: printTableMock,
   printFinalStatus: printFinalStatusMock,
   printCompactOutput: printCompactOutputMock,
+  printOverrideHint: printOverrideHintMock,
 }));
 
 jest.unstable_mockModule("../src/remediation/fix-commands.js", () => ({

tests/multi-folder-printer.test.ts

@@ -9,6 +9,7 @@ const printSkippedDependenciesMock = jest.fn<any>();
 const printTableMock = jest.fn<any>();
 const printFinalStatusMock = jest.fn<any>();
 const printCompactOutputMock = jest.fn<any>();
+const printOverrideHintMock = jest.fn<any>();
 const logInfoMock = jest.fn<any>();
 const logWarnMock = jest.fn<any>();
 
@@ -22,6 +23,7 @@ jest.unstable_mockModule("../src/output/printers.js", () => ({
   printTable: printTableMock,
   printFinalStatus: printFinalStatusMock,
   printCompactOutput: printCompactOutputMock,
+  printOverrideHint: printOverrideHintMock,
 }));
 
 jest.unstable_mockModule("../src/output/formatters.js", () => ({

tests/multi-folder-scan.test.ts

@@ -42,8 +42,11 @@ jest.unstable_mockModule("../src/remediation/fix-commands.js", () => ({
   findSuggestedCommandForFinding: jest.fn(() => null),
 }));
 
+const hasOverrideEntriesMock = jest.fn<any>(() => false);
+
 jest.unstable_mockModule("../src/utils/package-json.js", () => ({
   readDirectDependencyNames: readDirectDependencyNamesMock,
+  hasOverrideEntries: hasOverrideEntriesMock,
 }));
 
 jest.unstable_mockModule("../src/overrides/index.js", () => ({
@@ -60,6 +63,10 @@ jest.unstable_mockModule("../src/output/multi-folder-printer.js", () => ({
   printMultiFolderResults: jest.fn(),
 }));
 
+jest.unstable_mockModule("../src/output/printers.js", () => ({
+  printOverrideHint: jest.fn(),
+}));
+
 jest.unstable_mockModule("../src/output/multi-folder-html-reporter.js", () => ({
   writeMultiFolderHtmlReport: jest.fn(() => Promise.resolve({ reportPath: "/tmp/report/index.html" })),
 }));

tests/output.test.ts

@@ -22,6 +22,7 @@ import {
   printActionSummary,
   printCompactOutput,
   printFinalStatus,
+  printOverrideHint,
   printSuggestedFixCommands,
   printSuggestedFixCommandSkips,
   printSummary,
@@ -2423,3 +2424,14 @@ describe("printCompactOutput - packageManager option", () => {
     consoleSpy.mockRestore();
   });
 });
+
+describe("printOverrideHint", () => {
+  it("prints the hint line", () => {
+    const consoleSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    printOverrideHint();
+    const out = consoleSpy.mock.calls.map(c => stripAnsi(String(c[0]))).join("\n");
+    expect(out).toContain("--check-overrides");
+    expect(out).toContain("override entries detected");
+    consoleSpy.mockRestore();
+  });
+});

tests/utils/package-json.test.ts

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { hasOverrideEntries } from "../../src/utils/package-json.js";
+
+function makeTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "pkg-json-test-"));
+}
+
+function writePackageJson(dir: string, content: Record<string, unknown>): void {
+  fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify(content));
+}
+
+describe("hasOverrideEntries", () => {
+  it("returns false when package.json does not exist", () => {
+    const dir = makeTempDir();
+    expect(hasOverrideEntries(dir)).toBe(false);
+  });
+
+  it("returns false when package.json has no override fields", () => {
+    const dir = makeTempDir();
+    writePackageJson(dir, { name: "test", version: "1.0.0" });
+    expect(hasOverrideEntries(dir)).toBe(false);
+  });
+
+  it("returns false when overrides is an empty object", () => {
+    const dir = makeTempDir();
+    writePackageJson(dir, { overrides: {} });
+    expect(hasOverrideEntries(dir)).toBe(false);
+  });
+
+  it("returns false when pnpm.overrides is an empty object", () => {
+    const dir = makeTempDir();
+    writePackageJson(dir, { pnpm: { overrides: {} } });
+    expect(hasOverrideEntries(dir)).toBe(false);
+  });
+
+  it("returns false when resolutions is an empty object", () => {
+    const dir = makeTempDir();
+    writePackageJson(dir, { resolutions: {} });
+    expect(hasOverrideEntries(dir)).toBe(false);
+  });
+
+  it("returns true when overrides has entries (npm/Bun)", () => {
+    const dir = makeTempDir();
+    writePackageJson(dir, { overrides: { "lodash": "4.17.21" } });
+    expect(hasOverrideEntries(dir)).toBe(true);
+  });
+
+  it("returns true when pnpm.overrides has entries", () => {
+    const dir = makeTempDir();
+    writePackageJson(dir, { pnpm: { overrides: { "semver": "7.6.0" } } });
+    expect(hasOverrideEntries(dir)).toBe(true);
+  });
+
+  it("returns true when resolutions has entries (Yarn)", () => {
+    const dir = makeTempDir();
+    writePackageJson(dir, { resolutions: { "minimatch": "3.1.2" } });
+    expect(hasOverrideEntries(dir)).toBe(true);
+  });
+
+  it("returns false when package.json is malformed JSON", () => {
+    const dir = makeTempDir();
+    fs.writeFileSync(path.join(dir, "package.json"), "not json {");
+    expect(hasOverrideEntries(dir)).toBe(false);
+  });
+});