Problem
The CLI now has more nuanced remediation behavior for both direct and transitive findings, especially for npm projects.
It can:
- distinguish direct vs transitive findings
- recommend direct package upgrades when a safe target is known
- recommend a specific parent upgrade when a transitive fix requires changing the parent version
- recommend
npm update <parent> when a safe transitive resolution already fits within the current parent range
That behavior is useful, but it is not documented clearly enough for users or contributors to understand how the CLI decides which package to update and why a recommendation looks the way it does.
Why this matters
CVE Lite CLI is positioned around actionable remediation. If the command selection logic is not documented, users can misinterpret the output, especially in cases like:
- why a transitive issue recommends upgrading a parent instead of the vulnerable package itself
- why some findings produce
npm update <parent> while others produce npm install <parent>@<version>
- why some findings still report that no confident automatic path was found
- how workspace and hoisted npm dependency paths affect remediation reasoning
Clear documentation also helps contributors avoid breaking the intended remediation model when they work on parser or output logic.
Proposed documentation
Add a focused docs page under docs/ that explains:
- How the CLI identifies vulnerable packages from supported lockfiles
- How it classifies direct vs transitive dependencies
- How direct upgrade targets are chosen
- How transitive parent upgrade recommendations are chosen
- When npm-specific
update-parent-within-range recommendations are used
- Why the CLI should not recommend installing a vulnerable transitive package directly
- What
no confident automatic path means
- Known limitations and package-manager-specific nuances
Scope
This should be a user-facing behavior document, not just internal developer notes.
It should explain the CLI's current behavior plainly, with small examples where helpful, and it should stay aligned with the actual implementation rather than describing aspirational logic.
Impact
This would make remediation output easier to trust, easier to explain publicly, and easier for contributors to maintain correctly over time.
Problem
The CLI now has more nuanced remediation behavior for both direct and transitive findings, especially for npm projects.
It can:
npm update <parent>when a safe transitive resolution already fits within the current parent rangeThat behavior is useful, but it is not documented clearly enough for users or contributors to understand how the CLI decides which package to update and why a recommendation looks the way it does.
Why this matters
CVE Lite CLI is positioned around actionable remediation. If the command selection logic is not documented, users can misinterpret the output, especially in cases like:
npm update <parent>while others producenpm install <parent>@<version>Clear documentation also helps contributors avoid breaking the intended remediation model when they work on parser or output logic.
Proposed documentation
Add a focused docs page under
docs/that explains:update-parent-within-rangerecommendations are usedno confident automatic pathmeansScope
This should be a user-facing behavior document, not just internal developer notes.
It should explain the CLI's current behavior plainly, with small examples where helpful, and it should stay aligned with the actual implementation rather than describing aspirational logic.
Impact
This would make remediation output easier to trust, easier to explain publicly, and easier for contributors to maintain correctly over time.