docs: document direct and transitive dependency versions

[julianosouzanh]

Summary

Adds documentation for the remediation scenario where the same package appears as both a direct dependency and a transitive dependency at different installed versions.

Why this change

The existing How Remediation Works page explains cases where the same package is installed at different versions through different parent packages, but it does not cover the distinct case where one installed version is a declared direct dependency and another version of the same package is introduced transitively.

This documentation clarifies that each installed version should be classified independently. A package version should be treated as direct only when that specific installed version matches the project's declared direct dependency. Otherwise, another installed version with the same package name may still be transitive and should be remediated through the parent dependency path.

What changed

• Added a new section for direct and transitive versions of the same package
• Added a Mermaid diagram showing uuid@14.0.0 as a direct dependency and uuid@8.3.2 as a vulnerable transitive dependency
• Added generated fix command examples showing that remediation should target the parent package, not install another direct version of uuid

Validation

• Reviewed the updated MDX documentation locally
• Verified the new section follows the structure of the nearby remediation examples
• Confirmed this is a documentation-only change

User-facing impact

Does this change:

• affect scanning behavior
• affect output formatting
• affect JSON output
• affect docs only

Notes

Fixes #554

[sonukapoor]

Thanks Juliano - the explanation is accurate and the diagram follows the project's styling conventions well.

Two minor suggestions (not blockers):

1. uuid@14.0.1 is the current latest - you're using 14.0.0 which exists but is one patch behind. Up to you whether to update it.

2. The section mentions @compodoc/live-server, nyc, and codecov as parents, but the generated command targets only nyc. Worth adding a sentence like "CVE Lite CLI selects the most actionable upgrade path - in this case nyc - based on the dependency paths it resolves in your lockfile" before the command block. Readers will naturally ask why not the others.

Both are optional - happy to merge as-is if you'd prefer to keep the scope tight.

[julianosouzanh]

Thanks Juliano - the explanation is accurate and the diagram follows the project's styling conventions well.

Two minor suggestions (not blockers):

1. uuid@14.0.1 is the current latest - you're using 14.0.0 which exists but is one patch behind. Up to you whether to update it.
2. The section mentions @compodoc/live-server, nyc, and codecov as parents, but the generated command targets only nyc. Worth adding a sentence like "CVE Lite CLI selects the most actionable upgrade path - in this case nyc - based on the dependency paths it resolves in your lockfile" before the command block. Readers will naturally ask why not the others.

Both are optional - happy to merge as-is if you'd prefer to keep the scope tight.

Thanks for the review! I updated the example to use uuid@14.0.1 and added a sentence before the generated command block explaining why CVE Lite CLI selects nyc as the actionable parent upgrade path in this example.

[julianosouzanh]

@sonukapoor could you please review this PR when you have a chance?

[sonukapoor]

Good concept and correct placement - documenting the case where the same package is both direct and transitive is genuinely useful. The diagram is accurate, the Tabs usage is consistent with the rest of the file, and the classification logic is explained correctly. Three things to fix before this is merge-ready.

[julianosouzanh]

Good concept and correct placement - documenting the case where the same package is both direct and transitive is genuinely useful. The diagram is accurate, the Tabs usage is consistent with the rest of the file, and the classification logic is explained correctly. Three things to fix before this is merge-ready.

@sonukapoor Thanks for the review. I reworked the example to use a verified dependency path: nyc@15.1.0 -> istanbul-lib-processinfo@2.0.3 -> uuid@8.3.2, with nyc@18.0.0 as the generated parent upgrade command. This avoids implying that unrelated parent packages or unverified versions are valid remediation paths.

[sonukapoor]

The concept here is well explained and the example is technically sound - uuid@8.3.2 has a real OSV advisory, nyc@15.1.0 does pull it in via istanbul-lib-processinfo@2.x, and nyc@18.0.0 genuinely resolves the chain. Good work getting the dependency chain right.

One thing before approving: the example goes from nyc@15.1.0 to nyc@18.0.0, which is three major versions. The page already tells readers that CVE Lite CLI flags major version bumps as "Breaking?" in the output. A reader following this section won't see that warning - they'll just see npm install nyc@18.0.0 with no context. Could you add a short sentence acknowledging the jump? Something like: "This upgrade crosses major versions - review nyc's changelog before applying and rescan afterward to confirm the finding resolved."

Optional but worth considering: the generated fix command at the end follows the same pattern as Case 3. You could close with a cross-reference ("Because the vulnerable version is controlled by the parent, remediation follows the parent upgrade path - see Case 3 above") rather than restating the mechanics. Up to you on that one.

[sonukapoor]

The major version note and the Case 3 cross-reference are exactly what this needed. The section now gives readers the full picture - classification logic, why a direct install won't help, and where to go for the fix mechanics. Nice work on this one.

[julianosouzanh]

The major version note and the Case 3 cross-reference are exactly what this needed. The section now gives readers the full picture - classification logic, why a direct install won't help, and where to go for the fix mechanics. Nice work on this one.

Thanks for the review and guidance! Glad we got the example and remediation flow aligned.