feat: consolidate print-graph flags [CSENG-190]

[neema-beglou-snyk]

Pull Request Submission Checklist

• Follows CONTRIBUTING guidelines
• Commit messages
  are release-note ready, emphasizing
  what was changed, not how.
• Includes detailed description of changes
• Contains risk assessment (Low | Medium | High)
• Highlights breaking API changes (if applicable)
• Links to automated tests covering new functionality
• Includes manual testing instructions (if necessary)
• Updates relevant GitBook documentation (PR link: ___)
• Includes product update to be announced in the next stable release notes

What does this PR do?

Replaces four overlapping --print-graph family flags with a composable two-flag model:

New flags	Behavior
--print-graph --prune	Pruned/deduplicated dep graphs, JSONL output
--print-graph --jsonl	Complete (unpruned) dep graphs, JSONL output
--print-graph (bare)	Plaintext output (unchanged, Phase 2: becomes JSONL)

The old flags (--print-effective-graph, --print-effective-graph-with-errors, --print-output-jsonl-with-errors) are accepted as deprecated aliases. When used, they emit a deprecation warning to stderr and are tracked via analytics.add('deprecatedLegacyDepGraphFlag', flag) for Phase 2 removal.

Internally, flag interpretation is separated into three distinct concerns:

• shouldPrintGraph(opts) — whether to print
• isJsonl(opts) — output format (JSONL vs plaintext)
• shouldEmbedErrors(opts) — whether to embed scan errors inline or throw

Additional fixes included:

• --prune plumbed into pruneIsRequired() for monitor and test paths
• DeriveExitCode now handles snyk_errors.Error (e.g. SNYK-CLI-0008 "no supported files found" maps to exit code 3 instead of generic 2), using the existing mapping from behavior/maperrortoexitcode.go
• Relative file path bug fixed in printDepGraphError() — targetFile is now resolved before calling path.relative()

Where should the reviewer start?

src/lib/snyk-test/common.ts — the mapLegacyGraphFlags() function and the three concern helpers (shouldPrintGraph, isJsonl, shouldEmbedErrors). This is the core of the change.

Then src/lib/snyk-test/run-test.ts for how the new flags are consumed in the test path.

How should this be manually tested?

# New flags
snyk test --print-graph --prune <target>       # pruned JSONL
snyk test --print-graph --jsonl <target>       # complete JSONL
snyk test --print-graph <target>               # plaintext (unchanged)

# Legacy flags should still work with deprecation warning on stderr
snyk test --print-effective-graph <target>
snyk test --print-effective-graph-with-errors <target>
snyk test --print-output-jsonl-with-errors <target>

# Verify --prune triggers pruning in monitor path
snyk monitor --print-graph --prune <target>

# Verify exit code 3 for unsupported projects
snyk test --print-graph --prune <dir-with-no-supported-files>
echo $?  # should be 3

What's the product update that needs to be communicated to CLI users?

CLI users should not be aware of the changes, this layer of interfacing with the CLI is for extensions/plugins. Ideally we move all consumers to interface with extension-dep-graph instead of directly with the legacyCLI.

Risk assessment (Low | Medium | High)?

Medium

• Legacy flags are preserved as aliases, so no existing integrations break.
• The flag resolution logic is covered by 9 new unit tests in print-graph-flag-resolution.spec.ts.
• Main risk is downstream consumers that parse CLI stdout — the output format itself is unchanged for each mode, only the flags to request it changed.

Any background context you want to provide?

This is the CLI (producer) side of a cross-repo initiative (CSENG-190). Companion PRs in the dep-graph router (CSENG-191), SBOM extension (CSENG-192), snyk-delta (CSENG-193), and container-cli (CSENG-198) update consumers to use the new flags. The CLI ships first; consumers can migrate independently because legacy flags remain functional.
The migration for consumers is 2 fold, always parse JSONL and if we don't want partial results then parse the embedded error and throw.

Phase 2 (pending analytics confirming zero legacy flag usage): remove legacy flag mappings, remove --jsonl (bare --print-graph becomes JSONL), delete plaintext output path.

What are the relevant tickets?

• CSENG-190 (this PR)
• CSENG-191 (dep-graph router)
• CSENG-192 (SBOM extension)
• CSENG-193 (snyk-delta)
• CSENG-198 (container-cli)

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[snyk-pr-review-bot]

PR Reviewer Guide 🔍

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Logic Regression 🟡 [minor] In executeTest, the condition for verboseEnabled was changed to (!!options['print-graph'] && !options['prune']). Previously, it was !!options['print-graph'] || !!options['print-output-jsonl-with-errors']. The new condition is more restrictive: it will now return false if --prune is used, even if --print-graph is present. This may prevent Maven exhaustive dependency collection for users using the new --print-graph --prune combination. (!!options['print-graph'] && !options['prune']); Incomplete Flag Mapping 🟡 [minor] The mapLegacyGraphFlags function returns immediately after matching one legacy flag in the legacyMappings loop. If a user specifies multiple legacy flags (e.g. --print-effective-graph --print-output-jsonl-with-errors), only the first one encountered in the array will be mapped. While these flags are deprecated, the previous architecture (implicit in the deleted shouldPrint... helpers) would have evaluated all of them. return;

📚 Repository Context Analyzed This review considered 28 relevant code sections from 12 files (average relevance: 0.95) src/lib/types.ts (lines 1-300) help/cli-commands/test.md (lines 34-195) help/cli-commands/monitor.md (lines 43-206) packages/snyk-fix/src/types.ts (lines 1-251) package.json (lines 1-224) cliv2/cmd/cliv2/behavior/legacy/validation.go (lines 1-99) src/cli/commands/monitor/index.ts (lines 472-634) ... and 5 more file(s)