--only-used does not scope override-hygiene / maintenance findings in the --fail-on gate

Note: in-house item already being handled by the maintainer - not open for contribution. Filed for tracking only.

Summary

--only-used filters vulnerability findings down to reachable (imported) ones before --fail-on evaluates, so a team can scope the CI gate to vulnerabilities their code actually imports. But override-hygiene and maintenance-risk findings, which also trip --fail-on, are not scoped by --only-used. A build run with --only-used --fail-on high can still fail on an override or maintenance finding even though the user scoped the gate to reachable findings, which reads as "the flag is broken."

Where

• src/index.ts:794-797 - the gate ORs three sources together:

  const shouldFail =
    reachesFailOn(scanState.sorted, options.failOn) ||       // vulnerability findings (scoped by --only-used)
    reachesFailOn(overrideFindings, options.failOn) ||        // NOT scoped
    reachesFailOn(maintenanceFindings, options.failOn);       // NOT scoped
  

• src/index.ts:884-886 - --only-used filters only the vulnerability findings (finalFindings.filter(f => f.usage?.imported)), which become scanState.sorted.

Options

1. Document it (likely correct). Override-hygiene and maintenance-risk are not import-reachability concepts - they are about override config and package maintenance, not whether your code imports a vulnerable package - so it is defensible that --usage/--only-used does not apply to them. If so, the CLI reference and the --only-used/--fail-on docs should state explicitly that --only-used scopes vulnerability findings only, and override/maintenance findings still gate independently. One sentence prevents the surprise.
2. Change behavior. If we decide reachability should scope the whole gate, also filter override/maintenance findings under --only-used. Semantically questionable; probably not desired.

Optionally, the scan summary could note which finding classes the --fail-on gate is currently considering.

Recommendation

Lean toward option 1 (docs), with an explicit note. Needs a maintainer decision on approach before implementing.

Context

Surfaced by an external reviewer evaluating the tool for a neutral SCA comparison - flagged as a footgun that "one sentence prevents."

Start by reviewing the gate logic in src/index.ts:794-797 and the --only-used filtering at src/index.ts:884-886. A maintainer must first decide whether documentation or behavior should change; if documentation is chosen, update the CLI reference and --only-used/--fail-on guidance. Done means the chosen semantics are agreed and clearly represented.