pr-checkmate 3.0.4 → 3.1.0

package/dist/esm/core/run-checks.js

@@ -0,0 +1,293 @@
+import { isCiEnvironment, logger } from '../utils/index.js';
+import { packageVersion } from '../utils/package-version.js';
+import { Semaphore, resolveConcurrency, runPool, withTimeout } from '../utils/pool.js';
+import { clearToolPaths } from '../utils/resolve-bin.js';
+import { ResultCollector } from '../utils/result-collector.js';
+import { buildContext } from './context.js';
+import { prepareTooling, noTooling } from './install/prepare.js';
+import { REGISTRY } from './registry.js';
+import { report } from './reporters.js';
+import { PHASES, } from './types.js';
+/**
+ * Resolve which checks to run: the built-in registry, custom `opts.checks`, or a mix.
+ * - no custom checks → the built-in registry
+ * - `extendRegistry !== false` → registry + custom (a custom check overrides a
+ *   built-in one sharing its name)
+ * - `extendRegistry === false` → only the provided custom checks
+ */
+function resolveChecks(opts) {
+    const custom = opts.checks ?? [];
+    if (opts.extendRegistry === false)
+        return custom;
+    if (custom.length === 0)
+        return REGISTRY;
+    const byName = new Map();
+    for (const c of REGISTRY)
+        byName.set(c.name, c);
+    for (const c of custom)
+        byName.set(c.name, c); // custom wins on name clash
+    return [...byName.values()];
+}
+/**
+ * Emit the report via a preset channel or a custom reporter function.
+ *
+ * Returns whether delivery succeeded so the caller can honour
+ * `reporter.onPostFailure`. A custom function owns its own error handling, so it
+ * is always treated as delivered.
+ */
+async function emitReport(reporter, result, cfg) {
+    if (typeof reporter === 'function') {
+        await reporter(result);
+        return { attempted: false, ok: true };
+    }
+    return report(reporter ?? 'stdout', result, cfg);
+}
+/** Apply only/skip filters to the resolved check set. */
+function selectChecks(checks, opts) {
+    const only = opts.only && opts.only.length > 0 ? new Set(opts.only) : null;
+    const skip = new Set(opts.skip ?? []);
+    return checks.filter(c => {
+        if (skip.has(c.name))
+            return false;
+        if (only && !only.has(c.name))
+            return false;
+        return true;
+    });
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message.split('\n')[0].slice(0, 160) : String(err);
+}
+/**
+ * Apply the universal `config.severity` override for a check. Only remaps
+ * between warn↔fail (pass/skip are never changed); `off` is handled earlier by
+ * excluding the check from the run entirely. This is what lets a repo turn any
+ * advisory check into a gate, or downgrade a blocking one, by name.
+ */
+export function applySeverity(name, status, ctx) {
+    const sev = ctx.config.severity?.[name];
+    if (sev === 'error' && status === 'warn')
+        return 'fail';
+    if (sev === 'warn' && status === 'fail')
+        return 'warn';
+    return status;
+}
+/**
+ * Whether a diff-only check's skip is worth a row in the report.
+ *
+ * The two cases look identical from inside the check and are opposites to the
+ * person reading the result:
+ *
+ * - The range is missing because the run FELL BACK to a full scan — a shallow
+ *   clone, an unreachable PR base. Coverage was lost without anyone choosing
+ *   that, and saying nothing is how it stays lost (ticket 057).
+ * - The full scan was ASKED FOR. `--full` means "look at everything now", so
+ *   three rows explaining that three checks review a diff repeat what the reader
+ *   just said and push the real findings further down.
+ *
+ * `always` and `never` remain absolute; only `auto` distinguishes them.
+ */
+export function shouldReportDiffSkip(scope, reportSkipped = 'auto') {
+    if (reportSkipped === 'never')
+        return false;
+    if (reportSkipped === 'always')
+        return true;
+    const askedForFullScan = scope?.kind === 'full' && !scope.degraded;
+    return !askedForFullScan;
+}
+/**
+ * Why a `requiresDiff` check could not run, phrased for the person reading the
+ * report. A full scan the client asked for is expected; one we fell back to is
+ * a configuration problem, and the message says which.
+ */
+function noDiffReason(ctx) {
+    const scope = ctx.scope;
+    if (scope?.degraded)
+        return `no diff range (${scope.reason}) — set fetch-depth: 0`;
+    return 'full scan — this check reviews a diff';
+}
+/**
+ * Whether a skip came from the missing diff range, as opposed to any other reason
+ * a check can decline to run.
+ *
+ * `reportDegradedScope` counts these to say how much coverage a fallback to a full
+ * scan cost. It used to count every skip in the report, which already included
+ * unrelated ones ("mypy not installed"), and tooling skips would have added more —
+ * turning a number that means "checks you lost to a shallow clone" into "skips,
+ * roughly". Matched on the phrasing {@link noDiffReason} produces, which is the
+ * only thing that distinguishes them once a skip is just a status and a string.
+ */
+function isDiffSkip(details) {
+    return Boolean(details && /^no diff range|^full scan — this check reviews a diff/.test(details));
+}
+/**
+ * Run one check: gate on `applies`, execute, translate throws into `fail`.
+ *
+ * `heavy` admits only a couple of expensive checks at a time, and the per-check
+ * timeout means one that never returns costs a warning rather than the run.
+ */
+async function runOne(check, ctx, collector, heavy, tooling) {
+    try {
+        // A diff-only check without a range is usually a hole in coverage rather
+        // than an irrelevance, so it is reported as a skip and the gap stays visible
+        // (ticket 057).
+        //
+        // Except when the whole-repository scan was ASKED FOR. `--full` means "look
+        // at everything now", and answering with three rows explaining that three
+        // checks review a diff tells the reader something they just said themselves.
+        // A degraded scope still reports: there the missing range is a symptom —
+        // a shallow clone, an unreachable base — and staying quiet about it is how
+        // coverage disappears unnoticed.
+        if (check.requiresDiff && !ctx.baseSha) {
+            if (shouldReportDiffSkip(ctx.scope, ctx.config.run?.reportSkipped) &&
+                (await check.applies(ctx))) {
+                collector.register(check.name, 'skip', noDiffReason(ctx));
+            }
+            return;
+        }
+        if (!(await check.applies(ctx))) {
+            // A check that doesn't apply is irrelevant to this project/run — e.g. a
+            // language-specific check (SwiftLint, ktlint, Ruff, C++) in a repo of a
+            // different language, or a check disabled in config. Omit it from the report
+            // entirely rather than listing it as "not applicable": in a single-language
+            // repo those rows are pure noise and inflate the skipped count. Runtime skips
+            // from run() (e.g. "no relevant files changed") are still reported.
+            return;
+        }
+        // Tooling is checked AFTER `applies`, so the row only appears for a check
+        // that would otherwise have run. A Ruff row in a TypeScript repository would
+        // be noise; a Ruff row in a Python repository whose toolchain never arrived
+        // is the whole point — ticket 057, applied to tooling instead of diffs.
+        const missing = tooling.unavailable.get(check.name);
+        if (missing) {
+            // Severity still has the last word, as it does for every other outcome: a
+            // client who made this check advisory does not get a hard failure out of
+            // `onMissingTool: "error"`, and one who promoted it does.
+            const status = applySeverity(check.name, tooling.fatal ? 'fail' : 'skip', ctx);
+            logger.warn(`[runChecks]: ${status === 'fail' ? '❌' : '⏭️'} ${check.name}: ${missing}`);
+            collector.register(check.name, status, `tooling unavailable — ${missing}`);
+            return;
+        }
+        const started = Date.now();
+        const timeoutMs = ctx.config.run?.checkTimeoutMs ?? 300000;
+        const execute = () => withTimeout(check.run(ctx), timeoutMs, () => {
+            logger.warn(`[runChecks]: ⏱️ ${check.name} exceeded ${timeoutMs}ms`);
+            return { status: 'warn', details: `timed out after ${timeoutMs}ms` };
+        });
+        const outcome = check.weight === 'heavy' ? await heavy.run(execute) : await execute();
+        if (ctx.config.run?.timings) {
+            logger.info(`[runChecks]: ${check.name} took ${Date.now() - started}ms`);
+        }
+        collector.register(check.name, applySeverity(check.name, outcome.status, ctx), outcome.details);
+    }
+    catch (err) {
+        // An unexpected throw in a blocking check fails the run; in informational/format
+        // phases it only warns — those phases never block, matching the legacy pipeline.
+        const base = check.phase === 'blocking' ? 'fail' : 'warn';
+        const status = applySeverity(check.name, base, ctx);
+        logger.error(`[runChecks]: ${status === 'fail' ? '❌' : '⚠️'} ${check.name} threw: ${err}`);
+        collector.register(check.name, status, errMessage(err));
+    }
+}
+/**
+ * Run all applicable checks and return a structured report.
+ *
+ * Never throws for check violations and never calls `process.exit` — callers
+ * (CLI, PRValidator) decide what a failure means. Phases run in order; checks
+ * within a phase run in parallel.
+ */
+export async function runChecks(opts = {}) {
+    const ctx = await buildContext(opts);
+    // `severity: { "<name>": "off" }` disables any check by name, universally —
+    // a superset of the per-check `enabled: false` flags.
+    const off = ctx.config.severity ?? {};
+    const selected = selectChecks(resolveChecks(opts), opts).filter(c => off[c.name] !== 'off');
+    const collector = new ResultCollector();
+    // Config Validation verifies that `severity` keys name real checks. It reads
+    // the list from here rather than importing the registry, which would make
+    // registry → check → registry a cycle.
+    ctx.checkNames = resolveChecks(opts).map(c => c.name);
+    // Before any check starts: make sure the tools they need are reachable, and
+    // learn which ones are not. Doing this per-check would fetch the same profile
+    // from several checks at once and leave each of them guessing on failure.
+    const tooling = await prepareToolingFor(ctx, selected);
+    const limit = resolveConcurrency(ctx.config.run?.concurrency);
+    const heavyLimit = Math.max(1, ctx.config.run?.heavyConcurrency ?? 1);
+    const heavy = new Semaphore(heavyLimit);
+    for (const phase of PHASES) {
+        const inPhase = selected.filter(c => c.phase === phase);
+        await runPool(inPhase.map(c => () => runOne(c, ctx, collector, heavy, tooling)), limit);
+    }
+    reportDegradedScope(ctx, collector);
+    const build = () => {
+        const summary = collector.getSummary();
+        return { results: collector.getResults(), summary, ok: summary.failed === 0 };
+    };
+    const result = build();
+    const posted = await emitReport(opts.reporter, result, ctx.config.reporter ?? {});
+    // A summary that never reached the PR can matter as much as a finding. The row
+    // is added after the report was rendered — the printed table is what the run
+    // actually found — and the returned report carries it so the exit code can.
+    const onFailure = ctx.config.reporter?.onPostFailure ?? 'warn';
+    if (posted.attempted && !posted.ok && onFailure !== 'off') {
+        collector.register('Reporting', onFailure === 'error' ? 'fail' : 'warn', posted.error);
+        return build();
+    }
+    return result;
+}
+/**
+ * Prepare the tooling the selected checks need, or explain what is missing.
+ *
+ * Separate from `prepareTooling` itself so the failure of the *preparation* is
+ * never the failure of the *run*: fetching tooling is best-effort by nature —
+ * offline runners, read-only caches, a registry having a bad day — and a throw
+ * here would take down a run that could still have done most of its job. The
+ * checks that needed the tooling report it themselves, one row each.
+ *
+ * `install.strategy: "manual"` and a caller that supplied its own checks both
+ * arrive here; neither is special-cased, because a profile whose packages ship
+ * with us needs no preparation either way and the loop exits having done nothing.
+ */
+async function prepareToolingFor(ctx, selected) {
+    try {
+        return await prepareTooling({
+            cwd: ctx.cwd,
+            config: ctx.config,
+            // A hand-built context (the SDK, a test) carries no counts. Treating its
+            // languages as real rather than marker-only is the honest reading: a caller
+            // that names a language is asserting it, not guessing.
+            usage: ctx.usage ?? ctx.languages.map(lang => ({ lang, files: 1, marker: true })),
+            selected: selected.map(c => c.name),
+            version: packageVersion(),
+        });
+    }
+    catch (err) {
+        logger.warn(`[install]: ⚠️ could not prepare tooling: ${errMessage(err)}`);
+        // Preparation may have registered roots before it threw. Leaving them behind
+        // would point resolution at a half-installed directory for the whole run.
+        clearToolPaths();
+        return noTooling();
+    }
+}
+/**
+ * Surface a scope that silently narrowed the run.
+ *
+ * Falling back to a full scan keeps the file-based checks working, but it drops
+ * every diff-only check — most of the security surface — and the report gives no
+ * sign of it. Outside CI a full scan is simply the default, so this stays quiet
+ * there; inside CI it means the range could not be built, which is a
+ * configuration problem the client should hear about.
+ *
+ * `run.onDegradedScope: "error"` turns it into a gate, for repos where losing
+ * the security checks silently is worse than a red build.
+ */
+function reportDegradedScope(ctx, collector) {
+    const mode = ctx.config.run?.onDegradedScope ?? 'warn';
+    if (mode === 'off' || !ctx.scope?.degraded || !isCiEnvironment())
+        return;
+    const dropped = collector
+        .getResults()
+        .filter(r => r.status === 'skip' && isDiffSkip(r.details)).length;
+    const detail = `${ctx.scope.reason}; ${dropped} diff-only check(s) did not run — set fetch-depth: 0`;
+    logger.error(`[runChecks]: ${mode === 'error' ? '❌' : '⚠️'} Degraded scope: ${detail}`);
+    collector.register('Scan Scope', mode === 'error' ? 'fail' : 'warn', detail);
+}

package/dist/esm/core/targets.d.ts

@@ -0,0 +1,140 @@
+import { type CheckContext, type CheckOutcome } from './types.js';
+/**
+ * Drop files that live under any excluded directory (client `ignoreDirs` or the
+ * curated default), matched on any path segment so nesting depth doesn't matter.
+ * Applied to every check's file list so build/tooling/report dirs are never
+ * scanned, even when committed.
+ *
+ * `keepDirs` un-ignores specific segments for a single check — e.g. YAML lint
+ * keeps the CI dirs (`.github`, `.gitlab`, `.circleci`), which are ignored
+ * globally but hold the workflow files a YAML linter most needs to see.
+ */
+/**
+ * Drop files the client excluded by path.
+ *
+ * Separate from `ignoreDirs`, which matches a directory *name* on any segment:
+ * that cannot express "this one file" and cannot express "this one path" —
+ * `ignoreDirs: ["generated"]` silences every `generated/` in the repository, not
+ * the one that is actually generated. Globs answer both, and because this sits
+ * in the one function every file-scanning check calls, a client writes the rule
+ * once instead of hunting for the right key on each check.
+ *
+ * Exported because three checks build their file list themselves and cannot go
+ * through the resolvers above — and `excludePaths` is documented as "the only
+ * exclusion that reaches every check", which was not true of them (ticket 080).
+ * Each has a real reason to skip `sourcePath` and `ignoreDirs`; none has one to
+ * ignore a client saying "do not look here".
+ */
+export declare function excludeClientPaths(files: string[], cwd: string): string[];
+/**
+ * Lists the files a language check should operate on, matched by pathspec `globs`
+ * (e.g. `['*.py']`). Uses the PR diff range when available (delta mode), else
+ * scans all tracked files. Returns an empty array when nothing matches, and
+ * `null` when git itself is unusable (caller should `skip`).
+ *
+ * Only ACMR files are returned (Added/Copied/Modified/Renamed) — deletions are
+ * excluded. Results are additionally filtered to paths that still exist on disk,
+ * so a rename/move within the diff range (where the old path shows up but no
+ * longer exists) can never hand a missing path to a downstream tool like ESLint
+ * or Prettier, which crash hard on a non-existent pattern.
+ */
+export declare function resolveTargetFiles(ctx: CheckContext, globs: string[], opts?: {
+    keepDirs?: string[];
+}): Promise<string[] | null>;
+/**
+ * Like {@link resolveTargetFiles} but restricts results to the configured
+ * `sourcePath`(s). Preserves the semantics of the old `sourcePath` full-scan
+ * fallback while gaining delta support on every platform via `ctx.baseSha`.
+ */
+export declare function resolveScopedTargetFiles(ctx: CheckContext, globs: string[], sourcePaths: string[]): Promise<string[] | null>;
+/**
+ * The files to work on, or the outcome to return instead of working.
+ *
+ * One value rather than two, because the two-value shape is what kept going
+ * wrong. Every file-scanning check ends up writing the same triple —
+ *
+ * ```typescript
+ * const targets = await resolveTargetFiles(ctx, globs);
+ * if (targets === null) return skip('git unavailable');
+ * if (targets.length === 0) return pass('no Kotlin files changed');
+ * ```
+ *
+ * — and it was written out seventeen times, with nineteen exact copies of the
+ * middle line and seven copies of the comment explaining why the two cases are
+ * not the same (ticket 079). The point of collapsing it is not the four lines. It
+ * is that `null` means "git could not tell us" and `[]` means "git did and there
+ * is nothing", they are opposite answers, and a check that conflates them reports
+ * a clean pass over a tree it never opened — which is ticket 072, and before that
+ * ticket 067, and both were found in security checks, where it cost the most.
+ *
+ * Written this way round — an array or an outcome, not a nullable array — so the
+ * caller's one line is `if (!Array.isArray(targets)) return targets;` and there
+ * is no second case left to forget.
+ *
+ * Not exported: it is the return type of {@link resolveTargets} and every caller
+ * gets it by inference, so exporting it would only widen the public surface and
+ * show up as an unused export in our own Dead Code check.
+ */
+type TargetsOrOutcome = string[] | CheckOutcome;
+/** How a check wants an empty file list phrased, and at which status. */
+type EmptyResult = {
+    pass: string;
+} | {
+    skip: string;
+};
+/** Options for {@link resolveTargets} beyond the globs themselves. */
+interface ResolveOptions {
+    /**
+     * What no matching files means to this check, and in what words.
+     *
+     * Not defaulted, and that is deliberate: the two halves of the corpus disagree.
+     * A language check has genuinely nothing to do when its language is not in the
+     * diff, so `{ pass: 'no Kotlin files changed' }`. A whole-tree check that finds
+     * no files at all has not reviewed the repository, so `{ skip: 'no tracked
+     * files' }`. Picking one for the caller would make half of them wrong.
+     */
+    onEmpty: EmptyResult;
+    /** Walk every tracked file instead of the PR diff range. */
+    wholeTree?: boolean;
+    /** Restrict the result to the configured `sourcePath`(s). */
+    scoped?: boolean;
+    /** Un-ignore specific directory segments, as in {@link resolveTargetFiles}. */
+    keepDirs?: string[];
+}
+/**
+ * Resolve a check's file list, or the outcome it should report instead.
+ *
+ * The one entry point for checks that operate on whole files. It wraps
+ * {@link resolveTargetFiles} and {@link listTrackedFiles} rather than replacing
+ * them — a check that needs the raw list (because it distinguishes the two cases
+ * itself, or scans in several passes) still calls those directly.
+ */
+export declare function resolveTargets(ctx: CheckContext, globs: string[], opts: ResolveOptions): Promise<TargetsOrOutcome>;
+/**
+ * List ALL tracked files matching `globs` (never delta), scoped to
+ * `sourcePath`(s).
+ *
+ * For whole-repo analyses like circular-dependency detection that need the full
+ * graph, not just the PR diff. Using `git ls-files` means untracked
+ * `node_modules` is excluded by construction.
+ *
+ * `keepDirs` un-ignores segments for one caller, exactly as in
+ * {@link resolveTargetFiles}. It was missing here, and that made Workflow
+ * Security blind on the whole-tree path: `.github` is in the default ignore list,
+ * so `git ls-files .github/workflows/*.yml` returned the workflow and this
+ * function then dropped it. A blocking security check reported a clean pass over
+ * files it had never been handed — the surviving half of ticket 067, found by
+ * level 1 of the release regression plan.
+ *
+ * `null` when git could not answer, `[]` when it answered "nothing". The two are
+ * opposites to a caller and used to be the same value: `reject: false` keeps a
+ * failed git out of the catch below, so a directory git cannot read returned an
+ * empty list, and every caller read that as "nothing to review" and passed. On a
+ * directory holding real code that produced three green rows — Diff Security,
+ * Workflow Security, Diff Smells — over files none of them had opened
+ * (ticket 072).
+ */
+export declare function listTrackedFiles(ctx: CheckContext, globs: string[], sourcePaths: string[], opts?: {
+    keepDirs?: string[];
+}): Promise<string[] | null>;
+export {};

package/dist/esm/core/targets.js

@@ -0,0 +1,213 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getIgnoredDirs, getSourcePaths } from '../config/index.js';
+import { loadProjectConfig } from '../config/loader.js';
+import { execa } from '../utils/execa.js';
+import { isUnderIgnoredDir, logger, matchesAnyGlob } from '../utils/index.js';
+import { pass, skip } from './types.js';
+/**
+ * Drop files that live under any excluded directory (client `ignoreDirs` or the
+ * curated default), matched on any path segment so nesting depth doesn't matter.
+ * Applied to every check's file list so build/tooling/report dirs are never
+ * scanned, even when committed.
+ *
+ * `keepDirs` un-ignores specific segments for a single check — e.g. YAML lint
+ * keeps the CI dirs (`.github`, `.gitlab`, `.circleci`), which are ignored
+ * globally but hold the workflow files a YAML linter most needs to see.
+ */
+/**
+ * Drop files the client excluded by path.
+ *
+ * Separate from `ignoreDirs`, which matches a directory *name* on any segment:
+ * that cannot express "this one file" and cannot express "this one path" —
+ * `ignoreDirs: ["generated"]` silences every `generated/` in the repository, not
+ * the one that is actually generated. Globs answer both, and because this sits
+ * in the one function every file-scanning check calls, a client writes the rule
+ * once instead of hunting for the right key on each check.
+ *
+ * Exported because three checks build their file list themselves and cannot go
+ * through the resolvers above — and `excludePaths` is documented as "the only
+ * exclusion that reaches every check", which was not true of them (ticket 080).
+ * Each has a real reason to skip `sourcePath` and `ignoreDirs`; none has one to
+ * ignore a client saying "do not look here".
+ */
+export function excludeClientPaths(files, cwd) {
+    let patterns = [];
+    try {
+        patterns = loadProjectConfig(cwd).excludePaths ?? [];
+    }
+    catch {
+        // A config that cannot be read is the loader's problem to report, not a
+        // reason to scan nothing.
+    }
+    return patterns.length > 0 ? files.filter(f => !matchesAnyGlob(f, patterns)) : files;
+}
+function excludeIgnoredDirs(files, cwd, keepDirs = []) {
+    const ignored = new Set(getIgnoredDirs(cwd));
+    for (const dir of keepDirs)
+        ignored.delete(dir);
+    if (ignored.size === 0)
+        return files;
+    return files.filter(f => !isUnderIgnoredDir(f, ignored));
+}
+/**
+ * Lists the files a language check should operate on, matched by pathspec `globs`
+ * (e.g. `['*.py']`). Uses the PR diff range when available (delta mode), else
+ * scans all tracked files. Returns an empty array when nothing matches, and
+ * `null` when git itself is unusable (caller should `skip`).
+ *
+ * Only ACMR files are returned (Added/Copied/Modified/Renamed) — deletions are
+ * excluded. Results are additionally filtered to paths that still exist on disk,
+ * so a rename/move within the diff range (where the old path shows up but no
+ * longer exists) can never hand a missing path to a downstream tool like ESLint
+ * or Prettier, which crash hard on a non-existent pattern.
+ */
+export async function resolveTargetFiles(ctx, globs, opts = {}) {
+    try {
+        const args = ctx.baseSha
+            ? [
+                'diff',
+                '--name-only',
+                '--diff-filter=ACMR',
+                ctx.baseSha,
+                ctx.headSha ?? 'HEAD',
+                '--',
+                ...globs,
+            ]
+            : ['ls-files', ...globs];
+        const cacheKey = `t:${args.join('
')}`;
+        let stdout = ctx.cache?.get(cacheKey);
+        const fromCache = stdout !== undefined;
+        if (stdout === undefined) {
+            // `reject: false` keeps a failed git out of the catch below, so the exit
+            // code is the only thing separating "git could not answer" from "nothing
+            // matched". They are opposites to the caller: every caller turns `null`
+            // into a skip with a reason and `[]` into a clean pass. Without this
+            // branch a directory git cannot read produced the second — seven checks
+            // reporting ✅ over code none of them had looked at, while the docstring
+            // above had promised `null` all along. Found by ticket 062's corpus.
+            //
+            // A pathspec that matches nothing still exits 0, so the ordinary empty
+            // result cannot be swallowed here.
+            const result = await execa('git', args, { cwd: ctx.cwd, reject: false });
+            if (result.exitCode !== 0) {
+                logger.warn(`[targets]: ⚠️ git could not list files (exit ${result.exitCode})`);
+                return null;
+            }
+            stdout = result.stdout;
+            ctx.cache?.set(cacheKey, stdout);
+        }
+        const files = excludeClientPaths(excludeIgnoredDirs(stdout
+            .split('\n')
+            .map(f => f.trim())
+            .filter(Boolean), ctx.cwd, opts.keepDirs), ctx.cwd).filter(f => fs.existsSync(path.join(ctx.cwd, f)));
+        // One line per actual git call, not per consumer. Several checks ask for the
+        // same globs in a run and were each answered from the cache, but the line was
+        // printed after the cache branch — so four checks sharing one lookup printed
+        // four identical `Delta: 1 file(s) for *` lines and the log implied four walks
+        // of the tree.
+        //
+        // Demoted rather than dropped on a cache hit: the count is computed AFTER
+        // filtering, and two callers with the same globs but different `keepDirs` get
+        // different lists from the same cached output. Losing the second line would
+        // hide a real difference, so it moves to `debug` instead of disappearing.
+        const line = `[targets]: ${ctx.baseSha ? '📂 Delta' : 'Full scan'}: ${files.length} file(s) for ${globs.join(', ')}`;
+        if (fromCache)
+            logger.debug(`${line} (cached)`);
+        else
+            logger.info(line);
+        return files;
+    }
+    catch (err) {
+        logger.warn(`[targets]: ⚠️ Could not list files\n${err}`);
+        return null;
+    }
+}
+/**
+ * Restrict a list of repo-relative paths to the configured `sourcePath`(s).
+ * A source path of `.` (or one that normalizes to empty) imposes no
+ * restriction, so the whole repo is considered.
+ */
+function scopeToSourcePaths(files, sourcePaths) {
+    const scopes = sourcePaths.map(p => p.replace(/^\.\/?/, '').replace(/\/+$/, '')).filter(Boolean);
+    if (scopes.length === 0)
+        return files;
+    return files.filter(f => scopes.some(s => f === s || f.startsWith(`${s}/`)));
+}
+/**
+ * Like {@link resolveTargetFiles} but restricts results to the configured
+ * `sourcePath`(s). Preserves the semantics of the old `sourcePath` full-scan
+ * fallback while gaining delta support on every platform via `ctx.baseSha`.
+ */
+export async function resolveScopedTargetFiles(ctx, globs, sourcePaths) {
+    const files = await resolveTargetFiles(ctx, globs);
+    if (files === null)
+        return null;
+    return scopeToSourcePaths(files, sourcePaths);
+}
+/**
+ * Resolve a check's file list, or the outcome it should report instead.
+ *
+ * The one entry point for checks that operate on whole files. It wraps
+ * {@link resolveTargetFiles} and {@link listTrackedFiles} rather than replacing
+ * them — a check that needs the raw list (because it distinguishes the two cases
+ * itself, or scans in several passes) still calls those directly.
+ */
+export async function resolveTargets(ctx, globs, opts) {
+    const listOpts = opts.keepDirs ? { keepDirs: opts.keepDirs } : {};
+    // Read once, and only when something will use it. A whole-tree walk is always
+    // scoped — that is what `listTrackedFiles` promises its callers — while a delta
+    // walk is scoped only on request.
+    const sourcePaths = opts.wholeTree || opts.scoped ? getSourcePaths(ctx.cwd) : [];
+    const files = opts.wholeTree
+        ? await listTrackedFiles(ctx, globs, sourcePaths, listOpts)
+        : await resolveTargetFiles(ctx, globs, listOpts);
+    if (files === null)
+        return skip('git unavailable');
+    const scoped = opts.wholeTree ? files : scopeToSourcePaths(files, sourcePaths);
+    if (scoped.length > 0)
+        return scoped;
+    return 'pass' in opts.onEmpty ? pass(opts.onEmpty.pass) : skip(opts.onEmpty.skip);
+}
+/**
+ * List ALL tracked files matching `globs` (never delta), scoped to
+ * `sourcePath`(s).
+ *
+ * For whole-repo analyses like circular-dependency detection that need the full
+ * graph, not just the PR diff. Using `git ls-files` means untracked
+ * `node_modules` is excluded by construction.
+ *
+ * `keepDirs` un-ignores segments for one caller, exactly as in
+ * {@link resolveTargetFiles}. It was missing here, and that made Workflow
+ * Security blind on the whole-tree path: `.github` is in the default ignore list,
+ * so `git ls-files .github/workflows/*.yml` returned the workflow and this
+ * function then dropped it. A blocking security check reported a clean pass over
+ * files it had never been handed — the surviving half of ticket 067, found by
+ * level 1 of the release regression plan.
+ *
+ * `null` when git could not answer, `[]` when it answered "nothing". The two are
+ * opposites to a caller and used to be the same value: `reject: false` keeps a
+ * failed git out of the catch below, so a directory git cannot read returned an
+ * empty list, and every caller read that as "nothing to review" and passed. On a
+ * directory holding real code that produced three green rows — Diff Security,
+ * Workflow Security, Diff Smells — over files none of them had opened
+ * (ticket 072).
+ */
+export async function listTrackedFiles(ctx, globs, sourcePaths, opts = {}) {
+    try {
+        const result = await execa('git', ['ls-files', ...globs], { cwd: ctx.cwd, reject: false });
+        if (result.exitCode !== 0) {
+            logger.warn(`[targets]: ⚠️ git could not list tracked files (exit ${result.exitCode})`);
+            return null;
+        }
+        const files = excludeClientPaths(excludeIgnoredDirs(result.stdout
+            .split('\n')
+            .map(f => f.trim())
+            .filter(Boolean), ctx.cwd, opts.keepDirs), ctx.cwd);
+        return scopeToSourcePaths(files, sourcePaths);
+    }
+    catch (err) {
+        logger.warn(`[targets]: ⚠️ Could not list tracked files\n${err}`);
+        return null;
+    }
+}