feat: add --exclude-paths flag for path-based file exclusion

[danielroymoore]

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)
• Links to automated tests covering new functionality
• Includes manual testing instructions (if necessary)

What does this PR do?

Adds a new --exclude-paths CLI flag that accepts comma-separated file or directory paths for excluding specific files and directories during --all-projects and --yarn-workspaces scans. This complements the existing --exclude flag, which only matches basenames.

The problem

The existing --exclude flag matches by basename only (e.g. --exclude=package.json excludes all package.json files). In workspace-style monorepos, this makes it impossible to exclude a specific package without excluding every package that shares the same manifest filename:

my-app/
  package.json         ← root
  packages/
    api/package.json   ← want to exclude this one
    web/package.json   ← but not this one

--exclude=package.json excludes all three. There was no way to target just packages/api/package.json.

What changed

New flag: --exclude-paths

• Accepts comma-separated paths (e.g. --exclude-paths=packages/api/package.json,packages/web/package.json)
• Accepts both relative and absolute paths
• Requires --all-projects or --yarn-workspaces (same constraint as --exclude)
• Whitespace around commas is trimmed

File discovery (find-files.ts)

• Added excludePaths to FindFilesConfig — an array of resolved absolute paths
• New isExcludedPath() helper performs exact path matching, with case-insensitive comparison on Windows
• Paths are resolved once and reused for both exclusion filtering and recursive traversal (avoids duplicate pathLib.resolve calls)

Plugin integration (get-deps-from-plugin.ts)

• Parses options.excludePaths into resolved absolute paths and passes them as excludePaths to find()
• After the workspace plugin returns scanned projects, filters out any that match excluded paths — this catches projects discovered by workspace parsers (e.g. pnpm) that bypass the filesystem walk
• Includes excludePaths in analytics data

Validation & errors

• ExcludePathsFlagInvalidInputError with clear messaging about allowed input format
• MissingOptionError when used without --all-projects or --yarn-workspaces
• args.ts registers 'exclude-paths' for camelCase transformation
• types.ts adds the option to Options and SupportedUserReachableFacingCliArgs

Help documentation

• help/cli-commands/test.md and help/cli-commands/monitor.md updated with --exclude-paths documentation

Tests

• Unit tests (test/tap/find-files.test.ts): Verifies excludePaths excludes specific files by absolute path, doesn't affect same-basename files at other paths, and can exclude entire directories
• Acceptance tests (test/jest/acceptance/cli-args.spec.ts): Validates error messages for missing --all-projects
• Acceptance tests (test/jest/acceptance/snyk-test/all-projects.spec.ts): End-to-end tests with pnpm workspace fixture confirming single path exclusion, multiple path exclusion, absolute path support, and that non-targeted package.json files are unaffected

Where should the reviewer start?

1. src/cli/main.ts — validation logic for the new flag
2. src/lib/find-files.ts — core exclusion in the file discovery engine
3. src/lib/plugins/get-deps-from-plugin.ts — integration with the plugin system and post-scan filtering

How should this be manually tested?

In a workspace monorepo with multiple package.json files:

# Without --exclude-paths (all packages scanned)
snyk test --all-projects

# Exclude a specific workspace package
snyk test --all-projects --exclude-paths=packages/api/package.json

# Exclude multiple paths
snyk test --all-projects --exclude-paths=packages/api/package.json,packages/web/package.json

# Verify --exclude still works as before (basename-only)
snyk test --all-projects --exclude=package.json

# Validation: should error
snyk test --exclude-paths=packages/api/package.json  # missing --all-projects

Risk assessment: Low

• Purely additive — no changes to existing --exclude behaviour or any other flags
• The new flag goes through the same validation and discovery pipeline as --exclude
• All changes are gated behind the presence of --exclude-paths; when absent, zero code paths are affected

Companion PR

This is consumed by snyk/cli-extension-dep-graph#152, which replaces the path.Split workaround in the orchestrator with --exclude-paths for forwarding processed file exclusions to the legacy CLI.

Trade-offs & callouts

1. --exclude is unchanged. Existing behaviour is fully preserved. Both flags can be used together — --exclude for basename patterns, --exclude-paths for specific paths.
2. Post-scan filtering in get-deps-from-plugin.ts. Workspace parsers (e.g. pnpm) discover projects by reading workspace config files rather than walking the filesystem, so they bypass the find() exclusion. An additional filter on inspectRes.scannedProjects catches these. This is intentional and mirrors how --exclude already needs special handling for workspace-discovered projects.
3. No glob support. The flag accepts literal paths only, not globs. This keeps the implementation simple and predictable. Glob support could be added later if needed.
4. Windows path handling. isExcludedPath() uses case-insensitive comparison on win32 to match Windows filesystem semantics. On Unix, comparison is exact.

[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.

[github-actions]

	Warnings
⚠️	Please make changes to snyk help text in Gitbook. Changes will be automatically synchronised to Snyk CLI as a scheduled PR. For more information, see: help/README.md.
⚠️	Since the CLI is unifying on a standard and improved tooling, we're starting to migrate old-style imports and exports to ES6 ones. A file you've modified is using either module.exports or require(). If you can, please update them to ES6 import syntax and export syntax. Files found: src/cli/args.ts src/cli/main.ts
⚠️	There are multiple commits on your branch, please squash them locally before merging!
⚠️	"refactor: rename --exclude-relative to --exclude-paths and accept absolute paths" is too long. Keep the first line of your commit message under 72 characters.

Generated by 🚫 dangerJS against 04be038

[snyk-pr-review-bot]

PR Reviewer Guide 🔍

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Potential Plugin Exclusion Bypass 🟡 [minor] In getDepsFromPlugin, the code filters inspectRes.scannedProjects using pathLib.resolve(root, targetFile). However, if a plugin returns a targetFile that is already an absolute path, pathLib.resolve(root, targetFile) will simply return the absolute path. If the user provided a relative path to --exclude-paths, it was resolved against the current working directory in getDepsFromPlugin. If root (the scan target) differs from the process CWD, the excludePaths array and the resolved project path will not match, causing the exclusion to fail silently. inspectRes.scannedProjects = inspectRes.scannedProjects.filter( (project) => { const targetFile = project.meta?.targetFile || project.targetFile; if (!targetFile) return true; const resolved = pathLib.resolve(root, targetFile); return !excludePaths.includes(resolved); },

📚 Repository Context Analyzed This review considered 19 relevant code sections from 9 files (average relevance: 0.78) help/cli-commands/monitor.md (2 segments, lines 43-202) help/cli-commands/test.md (4 segments, lines 433-580) help/cli-commands/code-test.md (lines 1-125) src/lib/types.ts (lines 1-295) help/cli-commands/ignore.md (lines 1-204) src/lib/find-files.ts (lines 1-271) src/cli/args.ts (2 segments, lines 74-293) ... and 2 more file(s)