upgrade-interactive 1.0.0 → 1.1.0

package/src/components/App.js

@@ -2,40 +2,52 @@ import React, { useEffect, useRef, useState, useCallback } from 'react';
 import { Box, Text, useInput, useApp } from 'ink';
 import { Prompt } from './Prompt.js';
 import { Header } from './Header.js';
-import { Row, LoadingRow } from './Row.js';
+import { Row, VulnRow, OverrideRow, LoadingRow, SectionHeader } from './Row.js';
+import { OverridePicker } from './OverridePicker.js';
 import { fetchSuggestions } from '../semver-suggest.js';
 import { mapWithConcurrency } from '../registry.js';
+import { loadInstalledVersions } from '../lockfile.js';
+import { computeVulnerabilities } from '../vulnerabilities.js';
 
 const e = React.createElement;
 const CONCURRENCY = 8;
+// Stable reference so `overrides` defaulting doesn't allocate a fresh object
+// each render — otherwise the audit effect's deps change every commit and it
+// re-runs in an unbounded loop.
+const EMPTY_OVERRIDES = Object.freeze({});
 
 function clamp(n, min, max) {
   return Math.max(min, Math.min(max, n));
 }
 
-function findNavigable(entries, from, direction) {
-  let i = from;
-  for (let step = 0; step < entries.length; step++) {
-    i += direction;
-    if (i < 0 || i >= entries.length) return from;
-    if (entries[i] && typeof entries[i] === 'object') return i;
-  }
-  return from;
+function isNavigable(row) {
+  return row.kind === 'dep' || row.kind === 'vuln' || row.kind === 'override';
 }
 
-function firstNavigable(entries) {
-  for (let i = 0; i < entries.length; i++) {
-    if (entries[i] && typeof entries[i] === 'object') return i;
-  }
-  return -1;
+async function defaultRunAudit({ cwd, descriptors, overrides }) {
+  const installed = await loadInstalledVersions(cwd);
+  return computeVulnerabilities({ descriptors, installed, overrides });
 }
 
-export function App({ descriptors, onSubmit, onAbort }) {
+export function App({
+  descriptors,
+  onSubmit,
+  onAbort,
+  audit = false,
+  section = false,
+  cwd = process.cwd(),
+  overrides = EMPTY_OVERRIDES,
+  runAudit = defaultRunAudit,
+}) {
   const { exit } = useApp();
   const [entries, setEntries] = useState(() => descriptors.map(() => null));
   const [allLoaded, setAllLoaded] = useState(descriptors.length === 0);
-  const [focusedIndex, setFocusedIndex] = useState(-1);
+  const [focusedKey, setFocusedKey] = useState(null);
   const [selectedColumns, setSelectedColumns] = useState({});
+  const [stagedOverrides, setStagedOverrides] = useState({});
+  const [stagedRemovals, setStagedRemovals] = useState({}); // { name: true }
+  const [auditState, setAuditState] = useState(null); // { offline, vulns, removableOverrides } | null
+  const [override, setOverride] = useState(null); // { name, versions } | null
   const mountedRef = useRef(true);
 
   useEffect(() => {
@@ -44,6 +56,7 @@ export function App({ descriptors, onSubmit, onAbort }) {
     };
   }, []);
 
+  // Load upgrade suggestions for each descriptor.
   useEffect(() => {
     if (descriptors.length === 0) return;
     let cancelled = false;
@@ -73,29 +86,108 @@ export function App({ descriptors, onSubmit, onAbort }) {
     };
   }, [descriptors]);
 
-  // Keep focus pinned to a navigable (loaded, upgradeable) row as things load in.
+  // Check installed + range-resolved versions against npm's advisory database.
+  useEffect(() => {
+    if (!audit) return;
+    let cancelled = false;
+
+    Promise.resolve(runAudit({ cwd, descriptors, overrides }))
+      .then((res) => {
+        if (cancelled || !mountedRef.current) return;
+        setAuditState(res || { offline: false, vulns: new Map() });
+      })
+      .catch(() => {
+        if (cancelled || !mountedRef.current) return;
+        setAuditState({ offline: true, vulns: new Map() });
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [audit, cwd, descriptors, overrides, runAudit]);
+
+  // ---- Build the ordered display list (headers + rows) ----------------------
+  const vulns = auditState ? auditState.vulns : null;
+
+  const depItems = descriptors.map((descriptor, i) => ({ descriptor, entry: entries[i], i }));
+  const visibleDeps = allLoaded ? depItems.filter((x) => x.entry !== null) : depItems;
+
+  const depRow = (x) =>
+    x.entry === null
+      ? { kind: 'loading', key: `loading:${x.i}` }
+      : {
+          kind: 'dep',
+          key: `dep:${x.descriptor.name}`,
+          descriptor: x.descriptor,
+          entry: x.entry,
+          vuln: vulns ? vulns.get(x.descriptor.name) || null : null,
+        };
+
+  // A vuln shows inline on its dep row when that package has an upgrade row;
+  // everything else (transitive deps, or direct deps with no upgrade available)
+  // falls through to the Overrides section so it's never silently dropped.
+  const shownDepNames = new Set(visibleDeps.filter((x) => x.entry !== null).map((x) => x.descriptor.name));
+  const overrideVulns = vulns
+    ? [...vulns.entries()].filter(([name]) => !shownDepNames.has(name))
+    : [];
+  const removable = auditState && auditState.removableOverrides ? auditState.removableOverrides : null;
+  const removableList = removable ? [...removable.entries()] : [];
+
+  const rows = [];
+  const pushOverrides = () => {
+    if (overrideVulns.length === 0 && removableList.length === 0) return;
+    rows.push({ kind: 'header', key: 'h:overrides', title: 'Overrides' });
+    for (const [name, vuln] of overrideVulns) {
+      rows.push({ kind: 'vuln', key: `vuln:${name}`, name, vuln });
+    }
+    for (const [name, info] of removableList) {
+      rows.push({ kind: 'override', key: `ovr:${name}`, name, pin: info.pin, reason: info.reason });
+    }
+  };
+
+  if (section) {
+    const deps = visibleDeps.filter((x) => x.descriptor.field === 'dependencies');
+    const dev = visibleDeps.filter((x) => x.descriptor.field === 'devDependencies');
+    if (deps.length > 0) {
+      rows.push({ kind: 'header', key: 'h:deps', title: 'Dependencies' });
+      for (const x of deps) rows.push(depRow(x));
+    }
+    if (dev.length > 0) {
+      rows.push({ kind: 'header', key: 'h:dev', title: 'Dev dependencies' });
+      for (const x of dev) rows.push(depRow(x));
+    }
+    pushOverrides();
+  } else {
+    for (const x of visibleDeps) rows.push(depRow(x));
+    pushOverrides();
+  }
+
+  const navKeys = rows.filter(isNavigable).map((r) => r.key);
+  const navKeyStr = navKeys.join('|');
+  const focusedRow = rows.find((r) => r.key === focusedKey) || null;
+
+  // Keep focus on a navigable row as things load in / vulns arrive.
   useEffect(() => {
-    if (focusedIndex !== -1 && entries[focusedIndex] && typeof entries[focusedIndex] === 'object') return;
-    const next = firstNavigable(entries);
-    if (next !== focusedIndex) setFocusedIndex(next);
-  }, [entries, focusedIndex]);
+    if (focusedKey && navKeys.includes(focusedKey)) return;
+    setFocusedKey(navKeys[0] ?? null);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [navKeyStr, focusedKey]);
 
   const cycleColumn = useCallback(
     (direction) => {
-      if (focusedIndex === -1) return;
-      const entry = entries[focusedIndex];
-      if (!entry) return;
-      const name = entry.descriptor.name;
+      if (!focusedRow || focusedRow.kind !== 'dep') return;
+      const { suggestions } = focusedRow.entry;
+      const name = focusedRow.descriptor.name;
       const current = selectedColumns[name] ?? 0;
       let next = current;
-      for (let step = 0; step < entry.suggestions.length; step++) {
-        next = clamp(next + direction, 0, entry.suggestions.length - 1);
-        if (entry.suggestions[next].spans.length > 0 || next === 0) break;
+      for (let step = 0; step < suggestions.length; step++) {
+        next = clamp(next + direction, 0, suggestions.length - 1);
+        if (suggestions[next].spans.length > 0 || next === 0) break;
         if (next === current) break;
       }
       setSelectedColumns((prev) => ({ ...prev, [name]: next }));
     },
-    [focusedIndex, entries, selectedColumns]
+    [focusedRow, selectedColumns]
   );
 
   const bulkSelect = useCallback(
@@ -105,13 +197,9 @@ export function App({ descriptors, onSubmit, onAbort }) {
         for (const entry of entries) {
           if (!entry) continue;
           const { name } = entry.descriptor;
-          if (which === 'c') {
-            next[name] = 0;
-          } else if (which === 'r') {
-            next[name] = 1;
-          } else if (which === 'l') {
-            next[name] = entry.suggestions[2].value != null ? 2 : 1;
-          }
+          if (which === 'c') next[name] = 0;
+          else if (which === 'r') next[name] = 1;
+          else if (which === 'l') next[name] = entry.suggestions[2].value != null ? 2 : 1;
         }
         return next;
       });
@@ -119,55 +207,72 @@ export function App({ descriptors, onSubmit, onAbort }) {
     [entries]
   );
 
-  useInput((input, key) => {
-    if (key.ctrl && input === 'c') {
-      onAbort();
-      exit();
-      return;
-    }
-    if (key.escape) {
-      onAbort();
-      exit();
-      return;
-    }
-    if (key.upArrow) {
-      setFocusedIndex((idx) => findNavigable(entries, idx, -1));
-      return;
-    }
-    if (key.downArrow) {
-      setFocusedIndex((idx) => findNavigable(entries, idx, 1));
-      return;
-    }
-    if (key.leftArrow) {
-      cycleColumn(-1);
-      return;
-    }
-    if (key.rightArrow) {
-      cycleColumn(1);
-      return;
-    }
-    if (input === 'c' || input === 'r' || input === 'l') {
-      bulkSelect(input);
-      return;
-    }
-    if (key.return) {
-      const selections = new Map();
-      for (const entry of entries) {
-        if (!entry) continue;
-        const col = selectedColumns[entry.descriptor.name] ?? 0;
-        const value = entry.suggestions[col]?.value ?? null;
-        if (value) selections.set(entry.descriptor.name, value);
+  const openOverride = useCallback(() => {
+    if (!audit || !focusedRow) return;
+    if (focusedRow.kind !== 'dep' && focusedRow.kind !== 'vuln') return;
+    const vuln = focusedRow.vuln;
+    if (!vuln || !vuln.safeVersions || vuln.safeVersions.length === 0) return;
+    const name = focusedRow.kind === 'dep' ? focusedRow.descriptor.name : focusedRow.name;
+    setOverride({ name, versions: vuln.safeVersions });
+  }, [audit, focusedRow]);
+
+  const toggleRemoval = useCallback(() => {
+    if (!audit || !focusedRow || focusedRow.kind !== 'override') return;
+    const { name } = focusedRow;
+    setStagedRemovals((prev) => {
+      const next = { ...prev };
+      if (next[name]) delete next[name];
+      else next[name] = true;
+      return next;
+    });
+  }, [audit, focusedRow]);
+
+  const moveFocus = useCallback(
+    (direction) => {
+      setFocusedKey((cur) => {
+        const idx = navKeys.indexOf(cur);
+        if (idx === -1) return navKeys[0] ?? null;
+        const nextIdx = idx + direction;
+        if (nextIdx < 0 || nextIdx >= navKeys.length) return cur;
+        return navKeys[nextIdx];
+      });
+    },
+    [navKeyStr] // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  useInput(
+    (input, key) => {
+      if ((key.ctrl && input === 'c') || key.escape) {
+        onAbort();
+        exit();
+        return;
       }
-      onSubmit(selections);
-      exit();
-    }
-  });
+      if (key.upArrow) return moveFocus(-1);
+      if (key.downArrow) return moveFocus(1);
+      if (key.leftArrow) return cycleColumn(-1);
+      if (key.rightArrow) return cycleColumn(1);
+      if (input === 'o') return openOverride();
+      if (input === 'x') return toggleRemoval();
+      if (input === 'c' || input === 'r' || input === 'l') return bulkSelect(input);
+      if (key.return) {
+        const selections = new Map();
+        for (const entry of entries) {
+          if (!entry) continue;
+          const col = selectedColumns[entry.descriptor.name] ?? 0;
+          const value = entry.suggestions[col]?.value ?? null;
+          if (value) selections.set(entry.descriptor.name, value);
+        }
+        const removals = Object.keys(stagedRemovals).filter((name) => stagedRemovals[name]);
+        onSubmit(selections, { ...stagedOverrides }, removals);
+        exit();
+      }
+    },
+    { isActive: override == null }
+  );
 
-  const displayIndices = allLoaded
-    ? entries.map((_, i) => i).filter((i) => entries[i] !== null)
-    : entries.map((_, i) => i);
+  const auditDone = !audit || auditState !== null;
 
-  if (allLoaded && displayIndices.length === 0) {
+  if (allLoaded && auditDone && rows.length === 0) {
     return e(
       Box,
       { flexDirection: 'column' },
@@ -178,30 +283,65 @@ export function App({ descriptors, onSubmit, onAbort }) {
   }
 
   const termRows = (process.stdout && process.stdout.rows) || 24;
-  const maxRows = Math.max(5, termRows - 11);
-  const posInDisplay = Math.max(0, displayIndices.indexOf(focusedIndex));
-  let windowStart = clamp(posInDisplay - Math.floor(maxRows / 2), 0, Math.max(0, displayIndices.length - maxRows));
-  const windowEnd = Math.min(displayIndices.length, windowStart + maxRows);
-  const visible = displayIndices.slice(windowStart, windowEnd);
+  const maxRows = Math.max(5, termRows - 12);
+  const focusedIndex = Math.max(0, rows.findIndex((r) => r.key === focusedKey));
+  let windowStart = clamp(focusedIndex - Math.floor(maxRows / 2), 0, Math.max(0, rows.length - maxRows));
+  const windowEnd = Math.min(rows.length, windowStart + maxRows);
+  const visible = rows.slice(windowStart, windowEnd);
 
   return e(
     Box,
     { flexDirection: 'column' },
-    e(Prompt, null),
+    e(Prompt, { audit }),
     e(Header, null),
-    windowStart > 0 ? e(Text, { dimColor: true }, `  \u2191 ${windowStart} more above`) : null,
-    ...visible.map((i) => {
-      const entry = entries[i];
-      if (!entry) return e(LoadingRow, { key: i });
-      const col = selectedColumns[entry.descriptor.name] ?? 0;
+    audit && auditState && auditState.offline
+      ? e(Text, { color: 'yellow' }, "  ℹ no network — couldn't check for vulnerable packages")
+      : null,
+    windowStart > 0 ? e(Text, { dimColor: true }, `  ↑ ${windowStart} more above`) : null,
+    ...visible.map((row) => {
+      if (row.kind === 'header') return e(SectionHeader, { key: row.key, title: row.title });
+      if (row.kind === 'loading') return e(LoadingRow, { key: row.key });
+      if (row.kind === 'vuln') {
+        return e(VulnRow, {
+          key: row.key,
+          name: row.name,
+          active: row.key === focusedKey,
+          vuln: row.vuln,
+          override: stagedOverrides[row.name],
+        });
+      }
+      if (row.kind === 'override') {
+        return e(OverrideRow, {
+          key: row.key,
+          name: row.name,
+          active: row.key === focusedKey,
+          pin: row.pin,
+          reason: row.reason,
+          staged: !!stagedRemovals[row.name],
+        });
+      }
+      const col = selectedColumns[row.descriptor.name] ?? 0;
       return e(Row, {
-        key: i,
-        name: entry.descriptor.name,
-        active: i === focusedIndex,
-        suggestions: entry.suggestions,
+        key: row.key,
+        name: row.descriptor.name,
+        active: row.key === focusedKey,
+        suggestions: row.entry.suggestions,
         selectedColumn: col,
+        vuln: row.vuln,
+        override: stagedOverrides[row.descriptor.name],
       });
     }),
-    windowEnd < displayIndices.length ? e(Text, { dimColor: true }, `  \u2193 ${displayIndices.length - windowEnd} more below`) : null
+    windowEnd < rows.length ? e(Text, { dimColor: true }, `  ↓ ${rows.length - windowEnd} more below`) : null,
+    override
+      ? e(OverridePicker, {
+          name: override.name,
+          versions: override.versions,
+          onSelect: (version) => {
+            setStagedOverrides((prev) => ({ ...prev, [override.name]: version }));
+            setOverride(null);
+          },
+          onCancel: () => setOverride(null),
+        })
+      : null
   );
 }

package/src/components/OverridePicker.js

@@ -0,0 +1,44 @@
+import React, { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+
+const e = React.createElement;
+
+/**
+ * A small overlay for choosing which safe version to pin a vulnerable package
+ * to via npm `overrides`. ↑/↓ move, Enter selects, Esc cancels.
+ */
+export function OverridePicker({ name, versions, onSelect, onCancel }) {
+  const [index, setIndex] = useState(0);
+
+  useInput((input, key) => {
+    if (key.escape) {
+      onCancel();
+      return;
+    }
+    if (key.upArrow) {
+      setIndex((i) => Math.max(0, i - 1));
+      return;
+    }
+    if (key.downArrow) {
+      setIndex((i) => Math.min(versions.length - 1, i + 1));
+      return;
+    }
+    if (key.return) {
+      onSelect(versions[index]);
+    }
+  });
+
+  return e(
+    Box,
+    { flexDirection: 'column', marginTop: 1, borderStyle: 'round', paddingX: 1 },
+    e(Text, { bold: true }, 'Override ', e(Text, { color: 'cyanBright' }, name), ' to a safe version:'),
+    ...versions.map((v, i) =>
+      e(
+        Box,
+        { key: v },
+        e(Text, { color: i === index ? 'greenBright' : undefined }, i === index ? '❯ ' : '  ', v)
+      )
+    ),
+    e(Box, { marginTop: 1 }, e(Text, { dimColor: true }, '↑/↓ choose · <enter> apply · <esc> cancel'))
+  );
+}

package/src/components/Prompt.js

@@ -7,7 +7,7 @@ function Key({ children }) {
   return e(Text, { bold: true, color: 'cyanBright' }, children);
 }
 
-export function Prompt() {
+export function Prompt({ audit = false } = {}) {
   return e(
     Box,
     { flexDirection: 'row' },
@@ -50,7 +50,13 @@ export function Prompt() {
       Box,
       { flexDirection: 'column' },
       e(Box, { marginLeft: 1 }, e(Text, null, 'Press ', e(Key, null, '<enter>'), ' to install.')),
-      e(Box, { marginLeft: 1 }, e(Text, null, 'Press ', e(Key, null, '<ctrl+c>'), ' to abort.'))
+      e(Box, { marginLeft: 1 }, e(Text, null, 'Press ', e(Key, null, '<ctrl+c>'), ' to abort.')),
+      audit
+        ? e(Box, { marginLeft: 1 }, e(Text, null, 'Press ', e(Key, null, 'o'), ' to override a vulnerable package.'))
+        : null,
+      audit
+        ? e(Box, { marginLeft: 1 }, e(Text, null, 'Press ', e(Key, null, 'x'), ' to remove an unneeded override.'))
+        : null
     )
   );
 }

package/src/components/Row.js

@@ -1,5 +1,7 @@
 import React from 'react';
 import { Box, Text } from 'ink';
+import { hyperlink } from '../links.js';
+import { SEVERITY } from '../vulnerabilities.js';
 
 const e = React.createElement;
 
@@ -16,29 +18,96 @@ function Column({ suggestion, selected }) {
   const hasContent = suggestion && suggestion.spans.length > 0;
   return e(
     Box,
-    { width: 17 },
+    { width: 17, flexShrink: 0 },
     hasContent
-      ? e(Text, null, selected ? '\u25CF ' : '\u25CB ', e(Spans, { spans: suggestion.spans, inverse: selected }))
-      : e(Text, { dimColor: true }, selected ? '\u25CF' : '')
+      ? e(Text, null, selected ? '● ' : '○ ', e(Spans, { spans: suggestion.spans, inverse: selected }))
+      : e(Text, { dimColor: true }, selected ? '●' : '')
   );
 }
 
-export function Row({ name, active, suggestions, selectedColumn }) {
+// The ⚠ + severity + CVE link + affected/fixed-in summary shown on a flagged row.
+function VulnInfo({ vuln, override }) {
+  const sev = SEVERITY[vuln.severity] || SEVERITY.low;
+  let text = `⚠ ${sev.label} ${hyperlink(vuln.cve, vuln.url)} — affects ${vuln.affectedRange}`;
+  if (vuln.firstPatched) text += ` · fixed in ${vuln.firstPatched}`;
+  return e(
+    Box,
+    { marginLeft: 1 },
+    e(Text, { color: sev.color }, text),
+    override ? e(Text, { color: 'greenBright', bold: true }, `  → override ${override}`) : null
+  );
+}
+
+function NameCell({ name }) {
   const padLength = Math.max(1, 45 - name.length);
   return e(
+    Box,
+    { width: 45, flexShrink: 0 },
+    e(Text, { bold: true }, name),
+    e(Text, null, ' '.repeat(padLength))
+  );
+}
+
+export function SectionHeader({ title }) {
+  return e(Box, { marginTop: 1 }, e(Text, { bold: true, underline: true, color: 'gray' }, title));
+}
+
+export function Row({ name, active, suggestions, selectedColumn, vuln, override }) {
+  const main = e(
     Box,
     { flexDirection: 'row' },
-    e(Box, { width: 2 }, e(Text, { color: 'cyanBright', bold: true }, active ? '\u276F ' : '  ')),
-    e(
-      Box,
-      { width: 45 },
-      e(Text, { bold: true }, name),
-      e(Text, null, ' '.repeat(padLength))
-    ),
+    e(Box, { width: 2, flexShrink: 0 }, e(Text, { color: 'cyanBright', bold: true }, active ? '❯ ' : '  ')),
+    e(NameCell, { name }),
     e(Column, { suggestion: suggestions[0], selected: selectedColumn === 0 }),
     e(Column, { suggestion: suggestions[1], selected: selectedColumn === 1 }),
     e(Column, { suggestion: suggestions[2], selected: selectedColumn === 2 })
   );
+  if (!vuln) return main;
+  // Put the (potentially long) advisory detail on its own indented line so it
+  // stays readable instead of wrapping past the version columns.
+  return e(
+    Box,
+    { flexDirection: 'column' },
+    main,
+    e(Box, { marginLeft: 4 }, e(VulnInfo, { vuln, override }))
+  );
+}
+
+// A transitive (indirect) vulnerable package: no upgrade columns, just the
+// warning and an override affordance.
+export function VulnRow({ name, active, vuln, override }) {
+  return e(
+    Box,
+    { flexDirection: 'row' },
+    e(Box, { width: 2, flexShrink: 0 }, e(Text, { color: 'cyanBright', bold: true }, active ? '❯ ' : '  ')),
+    e(NameCell, { name }),
+    e(VulnInfo, { vuln, override }),
+    override ? null : e(Text, { dimColor: true }, '  press o to override')
+  );
+}
+
+// An existing `overrides` entry that no longer appears to be needed.
+export function OverrideRow({ name, active, pin, reason, staged }) {
+  const why =
+    reason === 'dead' ? 'nothing depends on it anymore' : 'no longer prevents a known vulnerability';
+  return e(
+    Box,
+    { flexDirection: 'row' },
+    e(Box, { width: 2, flexShrink: 0 }, e(Text, { color: 'cyanBright', bold: true }, active ? '❯ ' : '  ')),
+    e(NameCell, { name }),
+    e(
+      Box,
+      { marginLeft: 1 },
+      staged
+        ? e(Text, { color: 'greenBright', bold: true }, `✔ removing override ${pin}`)
+        : e(
+            Text,
+            { color: 'gray' },
+            `ⓘ override ${pin} not needed (${why}) `,
+            e(Text, { dimColor: true }, '— press x to remove')
+          )
+    )
+  );
 }
 
 export function LoadingRow() {

package/src/links.js

@@ -0,0 +1,17 @@
+// OSC 8 terminal hyperlinks, with a plain-text fallback.
+
+const OSC = ']8;;';
+const BEL = '';
+
+/**
+ * Render `text` as a clickable link to `url` using the OSC 8 escape sequence
+ * when writing to a TTY that can render it. When it can't (piped output, dumb
+ * terminal), fall back to `text (url)` so the URL stays visible and copyable.
+ */
+export function hyperlink(text, url) {
+  if (!url) return text;
+  if (process.stdout && process.stdout.isTTY) {
+    return `${OSC}${url}${BEL}${text}${OSC}${BEL}`;
+  }
+  return `${text} (${url})`;
+}

package/src/lockfile.js

@@ -0,0 +1,58 @@
+// Reads installed versions (direct + transitive) from package-lock.json.
+// Uses the npm v7+ "packages" map, which lists every installed path/version.
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/** Derive a package name from a lockfile path like "node_modules/@scope/name". */
+function nameFromPath(pkgPath) {
+  const marker = 'node_modules/';
+  const idx = pkgPath.lastIndexOf(marker);
+  if (idx === -1) return null;
+  const name = pkgPath.slice(idx + marker.length);
+  return name || null;
+}
+
+/**
+ * Return { versions: Map<name, Set<version>>, direct: Set<name>, packages }
+ * for the whole installed tree, or null if there's no usable lockfile (feature
+ * then degrades to range-resolved-only checks for direct deps). `packages` is
+ * the raw npm lockfile `packages` map, used to see which ranges dependents
+ * declare for a package (for spotting no-longer-needed overrides).
+ */
+export async function loadInstalledVersions(cwd) {
+  const filePath = path.join(cwd, 'package-lock.json');
+  let raw;
+  try {
+    raw = await readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  const packages = json.packages;
+  if (!packages || typeof packages !== 'object') return null;
+
+  const versions = new Map();
+  for (const [pkgPath, info] of Object.entries(packages)) {
+    if (!pkgPath || !info || !info.version) continue; // skip the "" root entry
+    const name = nameFromPath(pkgPath);
+    if (!name) continue;
+    if (!versions.has(name)) versions.set(name, new Set());
+    versions.get(name).add(info.version);
+  }
+
+  const root = packages[''] || {};
+  const direct = new Set([
+    ...Object.keys(root.dependencies || {}),
+    ...Object.keys(root.devDependencies || {}),
+  ]);
+
+  return { versions, direct, packages };
+}