feat: honor --usage and --only-used in multi-folder scans

[Ayush7614]

Summary

• Multi-folder scans now run the same per-folder source usage annotation as single-folder scanProject when --usage / --only-used are set.
• --only-used filters each subfolder’s findings to packages actually imported in that folder’s source.
• Previously these flags were accepted (and exposed in the GitHub Action) but silently ignored in multi-folder mode.
• Includes a two-subfolder isolation regression test.

Why

Package-based monorepos (no root lockfile, ≥2 nested lockfiles) route through handleMultiFolderScan, which never called scanProjectForPackageUsage. Teams enabling usage via CLI or Action inputs got unannotated / unfiltered results with no warning.

Test plan

• npm test -- tests/multi-folder-scan.test.ts (usage annotate, only-used filter, per-folder isolation, no-op without flag)
• npm run build
• Rebased onto latest main (merged with multi-folder ratchet baseline path)

Closes #919

[sonukapoor]

Nice fix @Ayush7614, thanks for tracking this down. I traced the loop and the per-folder scoping is right: subfolderAbs is already computed per iteration for readDirectDependencyNames, and you reuse it for scanProjectForPackageUsage, so there is no risk of one folder's findings getting filtered against another folder's imports.

One thing before merging: none of the three new tests exercise more than one subfolder, so nothing proves the per-folder isolation this PR is about. The --check-overrides tests just above yours already do this (two subfolders, a and b, asserting the mock is called twice with the right args). Could you add a similar one, ideally with a package imported in one folder and not the other, so we get a regression test for the actual bug rather than just the annotate/filter mechanics?

Two small things while you are in there: the if (!params.options.json) guard around the logInfo call is redundant, since logInfo already no-ops when options.json is set (which is why the single-folder call site does not wrap it). And longer-term (not blocking) it would be worth pulling the annotate-then-filter block into a shared helper used by both index.ts and multi-folder-scan.ts. This repo keeps hitting the "single-folder has X, multi-folder quietly does not" pattern (#866, #878, #879), and this logic living in two files is exactly how that happens again.

Also worth linking an issue in the PR body if one exists. Happy to open one on our side if you did not file it.

[Ayush7614]

Addressed review feedback:

1. Added a two-subfolder isolation test: same package in packages/a and packages/b, imported only in a — with --only-used, a keeps the finding and b is empty. Also asserts scanProjectForPackageUsage is called once per folder with the correct absolute paths.
2. Removed the redundant if (!params.options.json) guard around logInfo (matches single-folder).

No issue was filed for this gap when the PR was opened — happy for you to open one on your side if you want it linked; otherwise this can land as a direct parity fix.

[Ayush7614]

@sonukapoor thanks for the review — addressed:

1. Added a two-subfolder isolation test: same package in packages/a and packages/b, imported only in a — with --only-used, a keeps the finding and b is empty. Also asserts scanProjectForPackageUsage is called once per folder with the correct absolute paths.
2. Removed the redundant if (!params.options.json) guard around logInfo (matches single-folder).

No issue was filed for this gap when the PR was opened — happy for you to open one on your side if you want it linked.

Also rebased this branch onto latest main.

[sonukapoor]

Thanks @Ayush7614 - the multi-subfolder isolation test is a genuinely good regression test. This now conflicts with main since it moved, so a rebase on the latest main would get it ready. I will sort out a tracking issue to link it on our side. Merge once it is rebased.

[Ayush7614]

@sonukapoor rebased onto latest main and resolved conflicts with the multi-folder ratchet/baseline path (usage annotate/filter runs before per-folder baseline filtering). Also linked Closes #919 in the PR body. Should be clean to merge now.

[sonukapoor]

Hey @Ayush7614, this one has drifted into a conflict with main - could you rebase it on the latest main and resolve the conflicts? Once it is mergeable again I will give it another review. Thanks for your patience on it.

[Ayush7614]

@sonukapoor rebased onto latest main, resolved conflicts with ratchet/completeness/audit-log changes, and squashed to a single commit under my author only (no agent/cursor co-authors). Linked Closes #919. Ready for merge.

[sonukapoor]

Heads up @Ayush7614 - this has a conflict with main now (we just merged a large feature branch). Mind rebasing when you get a chance? Nothing wrong with the PR itself, the isolation test looks good.

[Ayush7614]

@sonukapoor rebased onto latest main and resolved the conflict with the telemetry imports in multi-folder-scan.ts (kept both telemetry + usage wiring). Should be mergeable now.

[sonukapoor]

Confirmed - the per-folder isolation test survived the rebase intact, CI is green. Thanks for tracking this down and adding the regression coverage.

[sonukapoor]

Merged - thank you @Ayush7614!