cve-lite-cli 1.7.1 โ†’ 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,16 +1,22 @@
1
1
 
2
+ [![OWASP Incubator Project](https://img.shields.io/badge/OWASP-Incubator%20Project-48A646?logo=owasp)](https://owasp.org/cve-lite-cli)
2
3
  [![npm version](https://img.shields.io/npm/v/cve-lite-cli)](https://www.npmjs.com/package/cve-lite-cli)
3
4
  [![npm downloads](https://img.shields.io/npm/dm/cve-lite-cli)](https://www.npmjs.com/package/cve-lite-cli)
4
- [![CI](https://img.shields.io/github/actions/workflow/status/sonukapoor/cve-lite-cli/ci.yml?branch=main)](https://github.com/sonukapoor/cve-lite-cli/actions)
5
+ [![CI](https://img.shields.io/github/actions/workflow/status/OWASP/cve-lite-cli/ci.yml?branch=main)](https://github.com/OWASP/cve-lite-cli/actions)
5
6
  [![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-CVE%20Lite%20CLI-blue)](https://github.com/marketplace/actions/cve-lite-cli)
6
- [![License](https://img.shields.io/github/license/sonukapoor/cve-lite-cli)](https://github.com/sonukapoor/cve-lite-cli/blob/main/LICENSE)
7
- [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
7
+ [![License](https://img.shields.io/github/license/OWASP/cve-lite-cli)](https://github.com/OWASP/cve-lite-cli/blob/main/LICENSE)
8
+ [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/OWASP/cve-lite-cli)
8
9
 
9
10
  <div align="center">
10
- <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
11
+ <a href="https://owasp.org/cve-lite-cli">
12
+ <img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/logos-combined.svg" alt="CVE Lite CLI โ€” An OWASP Foundation Project" width="500"/>
13
+ </a>
11
14
 
12
15
  <h1>CVE Lite CLI</h1>
13
- <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.<br/>Practical fix guidance. Offline support. Clear direct vs transitive visibility.</p>
16
+
17
+ **๐Ÿ† Officially recognized as an [OWASP Incubator Project](https://owasp.org/cve-lite-cli)**
18
+
19
+ <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.<br/>Practical fix guidance. Offline support. Usage-aware reachability. Clear direct vs transitive visibility.</p>
14
20
 
15
21
  <strong>Scan. Understand. Fix.</strong>
16
22
 
@@ -30,9 +36,10 @@
30
36
  <a href="#quick-start">Quick Start</a> โ€ข
31
37
  <a href="#usage">Usage</a> โ€ข
32
38
  <a href="#what-it-looks-like">Screenshots</a> โ€ข
39
+ <a href="docs/html-report.md">HTML Report</a> โ€ข
33
40
  <a href="docs/comparison.md">Compare</a> โ€ข
34
41
  <a href="docs/roadmap.md">Roadmap</a> โ€ข
35
- <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a>
42
+ <a href="https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a>
36
43
  </p>
37
44
  </div>
38
45
 
@@ -60,6 +67,7 @@ It is built for the moment right before release: fast, local-first, and honest a
60
67
  **Key differentiators:**
61
68
 
62
69
  - **Copy-and-run fix commands** โ€” turns findings into package-manager-aware `npm install`, `pnpm add`, `yarn add`, or `bun add` commands you can run immediately
70
+ - **Usage-aware reachability scanning** โ€” uses static analysis to detect if vulnerable packages are actually imported in your code, cutting alert fatigue with `--usage` and `--only-used`
63
71
  - **Direct vs transitive visibility** โ€” shows whether the risk comes from something you installed directly or a nested dependency
64
72
  - **Offline advisory DB** โ€” sync advisory data ahead of time and scan with zero runtime API calls, useful for enterprise and restricted-network environments
65
73
  - **No account required** โ€” no sign-up, no cloud dashboard, no source code upload
@@ -72,7 +80,8 @@ It is built for the moment right before release: fast, local-first, and honest a
72
80
  | JS/TS lockfile scanning | โœ… | โœ… | โœ… | โœ… | โœ… |
73
81
  | npm + pnpm + Yarn + Bun support | โœ… | โŒ | โœ… | โœ… | โœ… |
74
82
  | No account required | โœ… | โœ… | โœ… | โŒ | โŒ |
75
- | **Free to use** | โœ… | โœ… | โœ… | โŒ | โŒ |
83
+ | Free to use | โœ… | โœ… | โœ… | โŒ | โŒ |
84
+ | Usage-aware reachability scanning | โœ… | โŒ | โŒ | โœ… | โš ๏ธ |
76
85
  | Direct vs transitive visibility | โœ… | โš ๏ธ | โœ… | โœ… | โœ… |
77
86
  | Copy-and-run fix commands | โœ… | โŒ | โŒ | โœ… | โš ๏ธ |
78
87
  | Suggested remediation plan | โœ… | โŒ | โš ๏ธ | โœ… | โš ๏ธ |
@@ -85,30 +94,48 @@ For detailed per-tool analysis, see [Comparison with other tools](docs/compariso
85
94
 
86
95
  ## What it looks like
87
96
 
88
- Default output on [OWASP Juice Shop](https://github.com/juice-shop/juice-shop):
89
-
90
- ```bash
91
- git clone https://github.com/juice-shop/juice-shop.git
92
- cd juice-shop
93
- cve-lite .
94
- ```
95
-
97
+ <table>
98
+ <tr>
99
+ <th align="center">Terminal output</th>
100
+ <th align="center">HTML dashboard (<code>--report</code>)</th>
101
+ </tr>
102
+ <tr>
103
+ <td align="center">
104
+ <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/default-output.png">
105
+ <img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/default-output.png" alt="CVE Lite CLI terminal output" width="440"/>
106
+ </a>
107
+ </td>
108
+ <td align="center">
109
+ <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/html-report-dashboard.png">
110
+ <img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/html-report-dashboard.png" alt="CVE Lite CLI HTML dashboard" width="440"/>
111
+ </a>
112
+ </td>
113
+ </tr>
114
+ <tr>
115
+ <td align="center"><sub>Default scan output ยท <a href="docs/how-to-read-verbose-output.md">verbose output guide</a></sub></td>
116
+ <td align="center"><sub>Generated with <code>--report</code> ยท <a href="docs/html-report.md">HTML report guide</a></sub></td>
117
+ </tr>
118
+ </table>
119
+
120
+ <details>
121
+ <summary>Verbose terminal output โ€” includes the full fix plan</summary>
96
122
  <p align="center">
97
- <a href="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/default-output.png">
98
- <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/default-output.png" alt="CVE Lite CLI default output" width="600"/>
99
- </a>
123
+ <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-1.png"><img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-1.png" alt="Verbose output part 1" width="280"/></a>
124
+ <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-2.png"><img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-2.png" alt="Verbose output part 2" width="280"/></a>
125
+ <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-3.png"><img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-3.png" alt="Verbose output part 3" width="280"/></a>
100
126
  </p>
127
+ </details>
101
128
 
102
- Verbose output โ€” includes the `Copy And Run These Fix Commands` section:
129
+ ## HTML vulnerability report (`--report`)
103
130
 
104
- <p align="center">
105
- <a href="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-1.png"><img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-1.png" alt="Verbose output part 1" width="280"/></a>
106
- <a href="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-2.png"><img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-2.png" alt="Verbose output part 2" width="280"/></a>
107
- <a href="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-3.png"><img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-3.png" alt="Verbose output part 3" width="280"/></a>
108
- </p>
109
- <p align="center"><sub>Click any screenshot to enlarge</sub></p>
131
+ Generate a self-contained HTML dashboard from any scan โ€” severity cards, an interactive findings table, and copy-ready fix commands, all written to a local directory and opened automatically in your browser.
110
132
 
111
- For a section-by-section walkthrough, see [How to read verbose output](docs/how-to-read-verbose-output.md).
133
+ ```bash
134
+ cve-lite /path/to/project --report
135
+ cve-lite /path/to/project --report ./my-report --no-open
136
+ ```
137
+
138
+ See the [HTML Report guide](docs/html-report.md) for the full option reference and output details.
112
139
 
113
140
  ## Usage
114
141
 
@@ -137,6 +164,16 @@ cve-lite /path/to/project --fail-on high
137
164
  # JSON output
138
165
  cve-lite /path/to/project --json
139
166
 
167
+ # Generate an HTML vulnerability dashboard (opens in browser automatically)
168
+ cve-lite /path/to/project --report
169
+ cve-lite /path/to/project --report ./my-report --no-open
170
+
171
+ # Scan project source files to check if vulnerable dependencies are actually imported
172
+ cve-lite /path/to/project --usage
173
+
174
+ # Filter out noise by only showing vulnerabilities in packages that are imported in your source code
175
+ cve-lite /path/to/project --usage --only-used
176
+
140
177
  # Sync the local advisory DB for offline scans
141
178
  cve-lite advisories sync
142
179
 
@@ -153,6 +190,10 @@ cve-lite /path/to/project --osv-url https://security.company.internal/osv
153
190
  cve-lite --version
154
191
  ```
155
192
 
193
+ ### Why is `--usage` an opt-in flag?
194
+
195
+ CVE Lite CLI is designed to be blazing fast. Scanning a lockfile is nearly instantaneous, whereas running static reachability analysis across thousands of source files takes significantly more time. Furthermore, static analysis can occasionally produce false negatives (e.g., if a package is used in a build script or dynamically imported at runtime). Making `--usage` opt-in ensures the default lockfile scan remains instant and strictly reflects your dependency graph, while giving you the option to aggressively filter out unreachable noise when triaging findings.
196
+
156
197
  ## Auto-fix mode (`--fix`)
157
198
 
158
199
  `--fix` applies validated direct dependency fixes using your project's package manager, then rescans automatically.
@@ -190,27 +231,37 @@ See the [Offline Advisory DB guide](docs/offline-advisory-db.md) for the full wo
190
231
  The project ships a first-party [GitHub Action on the Marketplace](https://github.com/marketplace/actions/cve-lite-cli):
191
232
 
192
233
  ```yaml
193
- - uses: sonukapoor/cve-lite-cli@v1
234
+ - uses: OWASP/cve-lite-cli@v1
194
235
  with:
195
236
  verbose: "true"
196
237
  fail-on: high
197
238
  ```
198
239
 
199
- CVE Lite CLI also uses itself in CI to scan its own dependencies. See [`self-scan.yml`](https://github.com/sonukapoor/cve-lite-cli/blob/main/.github/workflows/self-scan.yml).
240
+ CVE Lite CLI also uses itself in CI to scan its own dependencies. See [`self-scan.yml`](https://github.com/OWASP/cve-lite-cli/blob/main/.github/workflows/self-scan.yml).
200
241
 
201
242
  For full CI patterns including offline workflows, git hooks, and scripted automation, see the [CI and Workflow Integration guide](docs/ci-integration.md).
202
243
 
203
- ## Relationship to similar OWASP projects
244
+ ## Recognized by OWASP
245
+
246
+ CVE Lite CLI is an [OWASP Incubator Project](https://owasp.org/cve-lite-cli), peer-reviewed and maintained under the Open Web Application Security Project Foundation. Being part of OWASP means:
247
+
248
+ - **Peer-reviewed** by security professionals
249
+ - **Community-driven** development and governance
250
+ - **Vendor-neutral** with no commercial platform required
251
+ - **Open source** with transparent security practices and a minimal dependency footprint
204
252
 
205
- CVE Lite CLI is intentionally narrower than the broader OWASP security tooling ecosystem. Its role is workflow-focused: fast local checks and simple CI release gates for JavaScript and TypeScript dependency scanning.
253
+ **Where it fits in the OWASP ecosystem:**
206
254
 
207
- The closest OWASP comparisons are:
255
+ CVE Lite CLI fills a specific gap โ€” fast, local-first JS/TS dependency scanning close to release time โ€” that broader OWASP tools are not optimized for:
208
256
 
209
- - **OWASP Dependency-Check** โ€” broader ecosystem coverage, different operational model
210
- - **OWASP dep-scan** โ€” wider language and environment coverage
211
- - **OWASP Dependency-Track** โ€” SBOM- and platform-oriented, not a local developer CLI
257
+ | Tool | Focus |
258
+ |---|---|
259
+ | CVE Lite CLI | Lockfile-first, local developer CLI, remediation-focused, JS/TS |
260
+ | OWASP Dependency-Check | Multi-language, SAST-style, broader ecosystem |
261
+ | OWASP dep-scan | Multi-language and environment, SBOM and cloud-native |
262
+ | OWASP Dependency-Track | Platform and SBOM management, not a local CLI |
212
263
 
213
- CVE Lite CLI complements these tools by serving a practical developer workflow close to release time: lockfile-first, local-first, remediation-focused, and offline-capable. It is vendor-neutral and does not require any commercial platform.
264
+ CVE Lite CLI complements these tools. It is not a replacement for continuous monitoring or full SBOM management โ€” it is the fast local check you run before pushing.
214
265
 
215
266
  ## Real-world case studies
216
267
 
@@ -266,27 +317,27 @@ See [parser-coverage.md](docs/parser-coverage.md) for supported lockfile formats
266
317
 
267
318
  Feedback on output clarity, remediation guidance, ecosystem coverage, and CI usage is especially valuable.
268
319
 
269
- See [CONTRIBUTING.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md) to get started.
320
+ See [CONTRIBUTING.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md) to get started.
270
321
 
271
322
  ## Add a badge to your project
272
323
 
273
324
  If you use CVE Lite CLI in your project, add this badge to your README:
274
325
 
275
326
  ```markdown
276
- [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
327
+ [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/OWASP/cve-lite-cli)
277
328
  ```
278
329
 
279
- [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
330
+ [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/OWASP/cve-lite-cli)
280
331
 
281
332
  ## Community and support
282
333
 
283
- For bug reports and feature requests: [GitHub Issues](https://github.com/sonukapoor/cve-lite-cli/issues)
334
+ For bug reports and feature requests: [GitHub Issues](https://github.com/OWASP/cve-lite-cli/issues)
284
335
 
285
336
  Helpful feedback includes reproducible bug reports, real-world lockfile edge cases, ideas for clearer output and remediation guidance, and CI or JSON workflow examples.
286
337
 
287
- For security-related reporting: [SECURITY.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/SECURITY.md)
338
+ For security-related reporting: [SECURITY.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/SECURITY.md)
288
339
 
289
- If CVE Lite CLI helps your release workflow, a [GitHub star](https://github.com/sonukapoor/cve-lite-cli) helps more developers find it.
340
+ If CVE Lite CLI helps your release workflow, a [GitHub star](https://github.com/OWASP/cve-lite-cli) helps more developers find it.
290
341
 
291
342
  ## License
292
343
 
package/dist/cli/args.js CHANGED
@@ -129,6 +129,34 @@ export function parseArgs(argv) {
129
129
  options.minSeverity = arg.slice("--min-severity=".length);
130
130
  continue;
131
131
  }
132
+ if (arg === "--usage" || arg === "--usage-hints") {
133
+ options.usage = true;
134
+ continue;
135
+ }
136
+ if (arg === "--only-used") {
137
+ options.onlyUsed = true;
138
+ options.usage = true;
139
+ continue;
140
+ }
141
+ if (arg === "--report") {
142
+ const next = argv[i + 1];
143
+ if (next !== undefined && !next.startsWith("-")) {
144
+ options.report = next;
145
+ i++;
146
+ }
147
+ else {
148
+ options.report = true;
149
+ }
150
+ continue;
151
+ }
152
+ if (arg.startsWith("--report=")) {
153
+ options.report = arg.slice("--report=".length);
154
+ continue;
155
+ }
156
+ if (arg === "--no-open") {
157
+ options.noOpen = true;
158
+ continue;
159
+ }
132
160
  if (arg.startsWith("-"))
133
161
  throw new Error(`Unknown option: ${arg}`);
134
162
  if (!projectArg) {
package/dist/cli/help.js CHANGED
@@ -31,12 +31,16 @@ export function printHelp() {
31
31
  "",
32
32
  "Scan options:",
33
33
  " --json Print JSON output",
34
+ " --report [dir] Generate an HTML report in [dir] (default: ./cve-report)",
35
+ " --no-open Don't auto-open the report in the browser",
34
36
  " --fix Apply validated direct dependency fixes and rescan",
35
37
  " --osv-url <url> Use a custom OSV-compatible advisory endpoint",
36
38
  " --verbose Show detailed output with fix plan, paths, and full table",
37
39
  " --prod-only Exclude dev dependencies where available",
38
40
  " --fail-on <severity> Exit non-zero at or above severity (default: critical)",
39
41
  " --batch-size <number> OSV batch size (default: 100)",
42
+ " --usage Scan project source files to check if vulnerable dependencies are imported",
43
+ " --only-used Filter out findings for packages that are not imported in your source code",
40
44
  " --offline Scan using the local advisory database",
41
45
  " --offline-db <path> Use a specific local advisory database file",
42
46
  " --cache-dir <path> Override cache directory",
package/dist/index.js CHANGED
@@ -13,9 +13,11 @@ import { severityOrder } from "./constants.js";
13
13
  import { chalk } from "./utils/chalk.js";
14
14
  import { createSpinner } from "./output/spinner.js";
15
15
  import { buildSuggestedFixCommandPlan } from "./remediation/fix-commands.js";
16
+ import { scanProjectForPackageUsage } from "./usage/scanner.js";
16
17
  import { getCliVersion } from "./utils/version-info.js";
17
18
  import { isLikelyBlockedAdvisoryRequestError } from "./utils/network.js";
18
- import { logInfo, logWarn, printCacheSummary, serializeFinding } from "./output/formatters.js";
19
+ import { logInfo, logWarn, printCacheSummary, serializeFinding, sortFindingsForOutput } from "./output/formatters.js";
20
+ import { buildReportData, writeHtmlReport } from "./output/html-reporter.js";
19
21
  import { printSummary, printActionSummary, printPriorityFixes, printFixPlan, printSuggestedFixCommands, printSuggestedFixCommandSkips, printCoverage, printSkippedDependencies, printGroupSummary, printTable, printPathHints, printFinalStatus, printCompactOutput } from "./output/printers.js";
20
22
  let parsedArgs = null;
21
23
  try {
@@ -86,6 +88,9 @@ if (parsedArgs) {
86
88
  if (options.fix && options.json) {
87
89
  throw new Error("--fix cannot be used with --json");
88
90
  }
91
+ if (options.report && options.json) {
92
+ throw new Error("--report cannot be used with --json");
93
+ }
89
94
  let advisorySourceLine;
90
95
  let advisoryDbFreshnessLine = null;
91
96
  let advisoryDbWarning = null;
@@ -219,6 +224,26 @@ if (parsedArgs) {
219
224
  // Simplified output - cleaner, focused view
220
225
  printCompactOutput(scanState.sorted, scanInput);
221
226
  }
227
+ if (options.report) {
228
+ const outputDir = path.resolve(typeof options.report === "string" ? options.report : "./cve-report");
229
+ const reportData = buildReportData({
230
+ projectPath,
231
+ cliVersion,
232
+ packageManager: scanInput.source,
233
+ lockfileSource: scanInput.filePath ? path.basename(scanInput.filePath) : scanInput.source,
234
+ packageCount: packages.length,
235
+ findings: scanState.sorted,
236
+ suggestedFixCommands: scanState.suggestedFixCommands,
237
+ notes: [...scanInput.notes, ...scanState.coverage],
238
+ warnings: scanInput.warnings,
239
+ });
240
+ const { reportPath } = await writeHtmlReport({
241
+ outputDir,
242
+ data: reportData,
243
+ autoOpen: !options.noOpen,
244
+ });
245
+ console.log(`${chalk.gray("Report:")} ${chalk.cyan(reportPath)}`);
246
+ }
222
247
  const failLevel = normalizeSeverity(options.failOn);
223
248
  const shouldFail = scanState.sorted.some(f => severityOrder[f.severity] >= severityOrder[failLevel]);
224
249
  process.exit(shouldFail ? 1 : 0);
@@ -246,7 +271,25 @@ function formatAdvisorySourceLine(sourceLabel) {
246
271
  async function scanProject(params) {
247
272
  const directDependencyNames = readDirectDependencyNames(params.projectPath, !!params.options.prodOnly);
248
273
  const findings = await scanPackages(params.scanInput.packages, params.batchSize, params.options, { directDependencyNames });
249
- const sorted = findings.sort((a, b) => severityOrder[b.severity] - severityOrder[a.severity]);
274
+ if (params.options.usage) {
275
+ console.log(chalk.gray(`Scanning project source for usage hints...`));
276
+ const pkgNames = new Set(findings.map(f => f.pkg.name));
277
+ const usageData = scanProjectForPackageUsage(params.projectPath, pkgNames);
278
+ for (const finding of findings) {
279
+ const files = usageData[finding.pkg.name];
280
+ if (files) {
281
+ finding.usage = {
282
+ imported: files.length > 0,
283
+ files,
284
+ };
285
+ }
286
+ }
287
+ }
288
+ let finalFindings = findings;
289
+ if (params.options.onlyUsed) {
290
+ finalFindings = finalFindings.filter(f => f.usage?.imported);
291
+ }
292
+ const sorted = sortFindingsForOutput(finalFindings);
250
293
  const coverage = buildCoverageNotes(params.scanInput, !!params.options.offline || !!params.options.offlineDb);
251
294
  const minSeverity = normalizeSeverity(params.options.minSeverity || "medium");
252
295
  const tableFindings = params.options.all
@@ -17,9 +17,9 @@ export function formatSeverityLabel(severity) {
17
17
  return severity;
18
18
  }
19
19
  export function formatRelationshipLabel(value) {
20
- if (value === "direct")
20
+ if (value.startsWith("direct"))
21
21
  return chalk.green(value);
22
- if (value === "transitive")
22
+ if (value.startsWith("transitive"))
23
23
  return chalk.yellow(value);
24
24
  return chalk.gray(value);
25
25
  }
@@ -52,25 +52,37 @@ export function getRecommendedAction(finding) {
52
52
  return `Inspect the dependency path for ${finding.pkg.name} and choose the safest upgrade path.`;
53
53
  }
54
54
  export function summarizeRisk(finding) {
55
+ let risk = "";
55
56
  if (finding.severity === "critical" && finding.relationship === "direct") {
56
- return "Critical direct dependency. Prioritize this first because the project controls it directly.";
57
+ risk = "Critical direct dependency. Prioritize this first because the project controls it directly.";
57
58
  }
58
- if (finding.severity === "high" && finding.relationship === "direct") {
59
- return "High-severity direct dependency. A direct upgrade is likely the fastest path.";
59
+ else if (finding.severity === "high" && finding.relationship === "direct") {
60
+ risk = "High-severity direct dependency. A direct upgrade is likely the fastest path.";
60
61
  }
61
- if (finding.relationship === "transitive" && finding.recommendedParentUpgrade) {
62
- return `Transitive issue. A specific parent upgrade target was found for ${finding.recommendedParentUpgrade.package}.`;
62
+ else if (finding.relationship === "transitive" && finding.recommendedParentUpgrade) {
63
+ risk = `Transitive issue. A specific parent upgrade target was found for ${finding.recommendedParentUpgrade.package}.`;
63
64
  }
64
- if (finding.relationship === "transitive" && finding.firstFixedVersion) {
65
- return `Transitive issue. Look for a parent dependency upgrade that pulls in ${finding.firstFixedVersion}+`;
65
+ else if (finding.relationship === "transitive" && finding.firstFixedVersion) {
66
+ risk = `Transitive issue. Look for a parent dependency upgrade that pulls in ${finding.firstFixedVersion}+`;
66
67
  }
67
- if (finding.relationship === "transitive") {
68
- return "Transitive issue. Review the parent path and check whether an upstream package can be upgraded.";
68
+ else if (finding.relationship === "transitive") {
69
+ risk = "Transitive issue. Review the parent path and check whether an upstream package can be upgraded.";
69
70
  }
70
- if (finding.firstFixedVersion) {
71
- return `A fixed-version hint exists. Aim for at least ${finding.firstFixedVersion}.`;
71
+ else if (finding.firstFixedVersion) {
72
+ risk = `A fixed-version hint exists. Aim for at least ${finding.firstFixedVersion}.`;
73
+ }
74
+ else {
75
+ risk = "Review this finding and inspect the dependency path for the safest upgrade path.";
76
+ }
77
+ if (finding.usage && !finding.usage.imported) {
78
+ if (finding.relationship === "transitive") {
79
+ risk = risk.replace("Transitive issue.", "Transitive issue. No direct imports found in source code, so practical reachability may be low.");
80
+ }
81
+ else if (finding.relationship === "direct") {
82
+ risk = risk.replace("direct dependency.", "direct dependency. No direct imports found in source code, so practical reachability may be low.");
83
+ }
72
84
  }
73
- return "Review this finding and inspect the dependency path for the safest upgrade path.";
85
+ return risk;
74
86
  }
75
87
  export function summarizeNextAction(finding) {
76
88
  if (finding.relationship === "direct" && finding.firstFixedVersion) {
@@ -103,6 +115,7 @@ export function serializeFinding(finding) {
103
115
  recommendedParentUpgrade: finding.recommendedParentUpgrade,
104
116
  cves: finding.cveAliases,
105
117
  dependencyPaths: finding.dependencyPaths,
118
+ usage: finding.usage ?? null,
106
119
  vulnerabilities: finding.vulnerabilities.map(v => ({
107
120
  id: v.id,
108
121
  aliases: v.aliases ?? [],
@@ -141,6 +154,14 @@ export function sortFindingsForOutput(findings) {
141
154
  const sevDelta = severityOrder[b.severity] - severityOrder[a.severity];
142
155
  if (sevDelta !== 0)
143
156
  return sevDelta;
157
+ const usageScore = (f) => f.usage?.imported ? 1 : 0;
158
+ const usageDelta = usageScore(b) - usageScore(a);
159
+ if (usageDelta !== 0)
160
+ return usageDelta;
161
+ const relScore = (f) => f.relationship === "direct" ? 1 : 0;
162
+ const relDelta = relScore(b) - relScore(a);
163
+ if (relDelta !== 0)
164
+ return relDelta;
144
165
  return a.pkg.name.localeCompare(b.pkg.name);
145
166
  });
146
167
  }