@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/lint-per-patch.js

@@ -1,428 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { loadConfig } from '../core/config.js';
-import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
-import { withPrivateGitIndex } from '../core/git-readonly-index.js';
-import { buildPatchQueueContext, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, measurePatchSize, resolvePatchSizeTier, } from '../core/patch-lint.js';
-import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/patch-lint-cache.js';
-import { buildLintIgnoreChecks, evaluateLintIgnoreCeilings, formatLintIgnoreEntry, isLintIgnoreCeiling, lintIgnoreCacheTokens, removableCeilingIssues, } from '../core/patch-lint-ignore.js';
-import { loadPatchesManifest } from '../core/patch-manifest.js';
-import { evaluatePatchPolicy } from '../core/patch-policy.js';
-import { evaluatePatchPolicyContent } from '../core/patch-policy-content.js';
-import { selectPatchSubset } from '../core/patch-subset.js';
-import { GeneralError } from '../errors/base.js';
-import { mapWithConcurrency } from '../utils/concurrency.js';
-import { pathExists } from '../utils/fs.js';
-import { info, outro, success, warn } from '../utils/logger.js';
-import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
-import { writePerPatchLintReport } from './lint-report.js';
-function buildPerPatchMaxWarningsMessage(count, maxWarnings, linted) {
-    return (`Patch lint found ${count} warning(s) across ${linted} patch(es), exceeding --max-warnings ${maxWarnings}.` +
-        ' If this is a release gate, run with --per-patch to identify the owning patch. For intentional staged imports, use patch staged-dependency; for ownership repairs, preview patch move-files, patch reorder --dry-run, or re-export --files --dry-run; add scoped lintIgnore only after review.');
-}
-function emitTierNotice(filename, files, tier) {
-    const decision = resolvePatchSizeTier(files, tier);
-    if (decision.tier !== 'branding')
-        return;
-    info(decision.source === 'explicit'
-        ? `${filename}: branding threshold tier applied via patches.json \`tier: "branding"\` opt-in.`
-        : `${filename}: branding threshold tier applied (all files under browser/branding/ plus registration siblings).`);
-}
-/**
- * Lints one queued patch against its own isolated diff, reusing the cache entry
- * when the cache key matches. Returns the outcome and the patch's (unprefixed)
- * issues without touching shared state. The orchestrator applies the tier
- * notice, issue prefixing, and cache write in patch order after the pool
- * drains, so the bounded concurrency cannot reorder output. Returns `skipped`
- * (no files present / empty diff), `cached`, or `linted`.
- */
-async function lintQueuedPatch(patch, lintCtx) {
-    const { projectRoot, paths, config, ctx, cache, engineHeadSha } = lintCtx;
-    const present = await mapWithConcurrency(patch.filesAffected, 8, (f) => pathExists(join(paths.engine, f)));
-    const existing = patch.filesAffected.filter((_, index) => present[index] === true);
-    if (existing.length === 0) {
-        return {
-            status: 'skipped',
-            existingFiles: [],
-            rawIssues: [],
-            suppressedIssues: [],
-            lineCount: 0,
-            usedCheckJs: false,
-        };
-    }
-    const ignore = buildLintIgnoreChecks(patch.lintIgnore);
-    let cacheKey;
-    if (cache) {
-        cacheKey = await buildPerPatchLintCacheKey({
-            projectRoot,
-            engineDir: paths.engine,
-            patchesDir: paths.patches,
-            patch,
-            existingFiles: existing,
-            config,
-            queueContext: ctx,
-            ...(engineHeadSha === undefined ? {} : { engineHeadSha }),
-        });
-        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey, lintIgnoreCacheTokens(ignore));
-        if (cached) {
-            // Returning before the empty-diff probe below is safe: the cache key
-            // hashes every affected engine file's content plus engineHeadSha, so
-            // an engine-side revert that would empty the diff always changes the
-            // key and misses the cache (pinned by the "engine-side content
-            // revert invalidates the per-patch cache" test).
-            return {
-                status: 'cached',
-                existingFiles: existing,
-                rawIssues: cached.issues,
-                suppressedIssues: cached.suppressed,
-                lineCount: cached.lineCount,
-                usedCheckJs: false,
-            };
-        }
-    }
-    const diff = await getDiffForFilesAgainstHead(paths.engine, existing);
-    if (!diff.trim()) {
-        return {
-            status: 'skipped',
-            existingFiles: [],
-            rawIssues: [],
-            suppressedIssues: [],
-            lineCount: 0,
-            usedCheckJs: false,
-        };
-    }
-    // checkJs: instead of rebuilding the program per patch, slice this patch's
-    // findings out of the one queue-wide program (built lazily on first miss).
-    const suppressedIssues = [];
-    const lintOptions = {
-        onSuppressed: (suppressed) => suppressedIssues.push(...suppressed),
-    };
-    let usedCheckJs = false;
-    if (lintCtx.checkJs) {
-        const grouped = await lintCtx.checkJs.getGrouped();
-        usedCheckJs = true;
-        const owned = lintCtx.checkJs.ownedByPatch.get(patch.filename);
-        const precomputedCheckJs = [];
-        if (owned) {
-            for (const rel of owned)
-                precomputedCheckJs.push(...(grouped.byFile.get(rel) ?? []));
-        }
-        lintOptions.precomputedCheckJs = precomputedCheckJs;
-    }
-    // Measured from the working tree, like every other rule here: the files
-    // on disk are the would-be export, so a size tier fires mid-edit rather
-    // than first at the re-export.
-    const patchSize = await measurePatchSize(paths.engine, diff, existing, config);
-    const patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, {
-        ...lintOptions,
-        patchSizeMeasurement: patchSize,
-        patchQueueCtx: ctx,
-        ...(ignore ? { ignoreChecks: ignore } : {}),
-        ...(patch.tier ? { patchTier: patch.tier } : {}),
-    });
-    const result = {
-        status: 'linted',
-        existingFiles: existing,
-        rawIssues: patchIssues,
-        suppressedIssues,
-        lineCount: patchSize.lines,
-        usedCheckJs,
-    };
-    if (cache && cacheKey) {
-        result.cacheWrite = { key: cacheKey, lintIgnore: lintIgnoreCacheTokens(ignore) };
-    }
-    return result;
-}
-/** Size-rule check IDs whose waived measurement is still reported. */
-const SUPPRESSED_SIZE_CHECKS = new Set([
-    'large-patch-lines',
-    'large-patch-files',
-    'file-too-large',
-]);
-/**
- * Applies the per-patch results in patch order so the bounded concurrency
- * cannot reorder output: emits each tier notice, the once-only run-level
- * checkJs errors (before the first freshly linted patch's issues), the
- * filename-prefixed issue rows, and the cache writes, all in the same
- * sequence a serial run produced. Returns the run tallies.
- */
-async function applyPerPatchResults(subset, results, issues, checkJs, cache, heldNotices) {
-    const totals = {
-        linted: 0,
-        skipped: 0,
-        cacheDirty: false,
-        reusedCacheEntries: 0,
-        suppressed: 0,
-    };
-    let globalCheckJsEmitted = false;
-    for (let i = 0; i < subset.length; i++) {
-        const patch = subset[i];
-        const result = results[i];
-        if (!patch || !result)
-            continue;
-        if (result.status === 'skipped') {
-            totals.skipped++;
-            continue;
-        }
-        emitTierNotice(patch.filename, result.existingFiles, patch.tier);
-        // Run-level checkJs errors are emitted once, before the first
-        // non-skipped patch's own issues, matching the serial emit point.
-        // Not gated on `result.usedCheckJs`: global findings are
-        // run-level and never cached, so gating drops them entirely on an
-        // all-cache-hit run and lets a warm run report fewer errors than a cold
-        // one. PerRunCheckJs builds its program lazily, so the cost only
-        // materialises when checkJs is configured.
-        if (checkJs && !globalCheckJsEmitted) {
-            globalCheckJsEmitted = true;
-            issues.push(...(await checkJs.getGlobal()));
-        }
-        if (result.cacheWrite && cache) {
-            setCachedPerPatchLintIssues({
-                cache,
-                patchFilename: patch.filename,
-                key: result.cacheWrite.key,
-                issues: result.rawIssues,
-                suppressed: result.suppressedIssues,
-                lineCount: result.lineCount,
-                lintIgnore: result.cacheWrite.lintIgnore,
-            });
-            totals.cacheDirty = true;
-        }
-        for (const issue of result.rawIssues) {
-            issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
-        }
-        // A ceiling the patch no longer needs is reported as a notice naming
-        // the command that drops it.
-        issues.push(...removableCeilingIssues(patch.filename, evaluateLintIgnoreCeilings(patch.lintIgnore, [...result.rawIssues, ...result.suppressedIssues], { lines: result.lineCount, files: patch.filesAffected.length })));
-        // A waived size finding still reports its measurement: the finding stays
-        // suppressed (no exit-code / --max-warnings effect) but the current count
-        // is readable from the tool that enforces it, so a waiver's cited size
-        // can be calibrated without hand-measuring.
-        for (const suppressedIssue of result.suppressedIssues) {
-            if (!SUPPRESSED_SIZE_CHECKS.has(suppressedIssue.check))
-                continue;
-            if (heldNotices !== undefined) {
-                heldNotices.push({ check: suppressedIssue.check, patch: patch.filename, suppressed: true });
-                continue;
-            }
-            const ceilings = (patch.lintIgnore ?? []).filter((entry) => isLintIgnoreCeiling(entry) && entry.rule === suppressedIssue.check);
-            const ceiling = ceilings.find((entry) => isLintIgnoreCeiling(entry) && entry.share === suppressedIssue.share) ?? ceilings[0];
-            const waiver = ceiling === undefined ? 'lintIgnore' : `lintIgnore (${formatLintIgnoreEntry(ceiling)})`;
-            info(`NOTICE [${suppressedIssue.check}] ${patch.filename}: suppressed by ${waiver} — ${suppressedIssue.message}`);
-        }
-        totals.suppressed += result.suppressedIssues.length;
-        if (result.status === 'cached')
-            totals.reusedCacheEntries++;
-        totals.linted++;
-    }
-    return totals;
-}
-/**
- * Maximum patches linted concurrently. After the per-file→batched git change,
- * each patch is only a handful of git spawns, so a small pool overlaps their
- * I/O without oversubscribing git on the shared repository.
- */
-const PER_PATCH_LINT_CONCURRENCY = 8;
-/**
- * Lints every patch in `subset` with bounded concurrency, returning results in
- * patch order (each slot index matches `subset`). Mirrors the worker-pool idiom
- * used by the rollback restore path. Side effects are deferred to the caller so
- * issue ordering and cache writes stay deterministic.
- */
-async function lintSubsetConcurrently(subset, lintCtx) {
-    const results = new Array(subset.length);
-    let index = 0;
-    async function worker() {
-        while (index < subset.length) {
-            const current = index++;
-            const patch = subset[current];
-            if (!patch)
-                break;
-            results[current] = await lintQueuedPatch(patch, lintCtx);
-        }
-    }
-    const workers = Array.from({ length: Math.min(PER_PATCH_LINT_CONCURRENCY, subset.length) }, () => worker());
-    await Promise.all(workers);
-    return results;
-}
-/**
- * Reporting + exit phase of per-patch lint: renders every issue row,
- * prints the per-patch summary, and applies the failure criteria
- * (errors, `--max-warnings`) by throwing GeneralError.
- */
-function reportPerPatchOutcome(issues, linted, skipped, options, heldNotices) {
-    if (heldNotices !== undefined) {
-        reportNoticeSummary(heldNotices, issues);
-    }
-    if (issues.length === 0) {
-        if (linted === 0 && skipped > 0) {
-            info(`No patches in the queue have been applied to engine/. Run "fireforge import" first if you want lint findings against the staged hunks; otherwise this is expected.`);
-        }
-        const summary = skipped > 0
-            ? `No lint issues found across ${linted} patch(es) (${skipped} skipped — files not present in engine/).`
-            : `No lint issues found across ${linted} patch(es).`;
-        success(summary);
-        outro('Lint passed');
-        return;
-    }
-    const errors = issues.filter((i) => i.severity === 'error');
-    const warnings = issues.filter((i) => i.severity === 'warning');
-    const notices = issues.filter((i) => i.severity === 'notice');
-    if (heldNotices === undefined) {
-        for (const issue of notices)
-            info(`NOTICE ${formatPatchLintIssue(issue)}`);
-    }
-    for (const issue of warnings)
-        warn(formatPatchLintIssue(issue));
-    for (const issue of errors)
-        warn(`ERROR ${formatPatchLintIssue(issue)}`);
-    info(`\nLint (per-patch over ${linted} patch(es)): ${errors.length} error(s), ${warnings.length} warning(s)`);
-    if (errors.length > 0) {
-        outro('Lint failed');
-        throw new GeneralError(`Patch lint found ${errors.length} error(s) across ${linted} patch(es). Fix these before exporting.`);
-    }
-    if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
-        outro('Lint failed');
-        throw new GeneralError(buildPerPatchMaxWarningsMessage(warnings.length, options.maxWarnings, linted));
-    }
-    if (warnings.length > 0) {
-        outro('Lint passed with warnings');
-    }
-    else if (notices.length > 0) {
-        outro('Lint passed with notices');
-    }
-    else {
-        outro('Lint passed');
-    }
-}
-/**
- * `--notices summary`: one line per check instead of one per finding, for
- * a green queue whose hundreds of NOTICE lines are reviewed waivers and
- * under-threshold measurements. The full list stays in `--report`.
- * Errors and warnings are never summarised.
- */
-function reportNoticeSummary(heldNotices, issues) {
-    const byCheck = new Map();
-    const tally = (check, patch, suppressed) => {
-        const entry = byCheck.get(check) ?? { count: 0, suppressed: 0, patches: new Set() };
-        entry.count += 1;
-        if (suppressed)
-            entry.suppressed += 1;
-        entry.patches.add(patch);
-        byCheck.set(check, entry);
-    };
-    for (const held of heldNotices)
-        tally(held.check, held.patch, held.suppressed);
-    for (const issue of issues) {
-        if (issue.severity !== 'notice')
-            continue;
-        tally(issue.check, issue.patches?.[0] ?? issue.file.split(' :: ')[0] ?? issue.file, false);
-    }
-    for (const [check, entry] of [...byCheck].sort(([a], [b]) => a.localeCompare(b))) {
-        const suppressed = entry.suppressed > 0 ? `, ${entry.suppressed} of them suppressed by lintIgnore` : '';
-        info(`NOTICE [${check}]: ${entry.count} across ${entry.patches.size} patch(es)${suppressed} (see --report)`);
-    }
-}
-/** The refusal sentence `selectPatchSubset` adds for a `lint --per-patch` miss. */
-const PER_PATCH_SUBSET_HINT = 'In --per-patch mode, positional arguments and --patches select patches (filename, stem, ' +
-    'order number, manifest name, or slug) — not engine files; drop --per-patch to lint engine paths.';
-/**
- * Lints each patch in the queue as its own isolated diff, honouring
- * per-patch `lintIgnore` entries. Cross-patch rules still run once over
- * the whole queue so queue-level findings are not lost by the rescoping.
- * With `options.patches` set, only the named subset is linted (and the
- * queue-level findings are scoped to files those patches touch).
- */
-export async function lintPerPatch(projectRoot, paths, options = {}) {
-    // Read-only to the operator, but an index writer to git: the per-patch diffs
-    // run `git diff HEAD` (and, for untracked binaries, a real stage/unstage
-    // pair) against the primary checkout. A private index absorbs all of it
-    // so a concurrent `fireforge test` still gets an evidential verdict.
-    return withPrivateGitIndex(paths.engine, () => lintPerPatchInner(projectRoot, paths, options));
-}
-async function lintPerPatchInner(projectRoot, paths, options = {}) {
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest || manifest.patches.length === 0) {
-        info('No patches in manifest — nothing to lint per-patch.');
-        outro('Nothing to lint');
-        return;
-    }
-    const subset = options.patches && options.patches.length > 0
-        ? selectPatchSubset(manifest, options.patches, PER_PATCH_SUBSET_HINT)
-        : manifest.patches;
-    const subsetNames = new Set(subset.map((p) => p.filename));
-    const isSubset = subset.length !== manifest.patches.length;
-    const config = await loadConfig(projectRoot);
-    const ctx = await buildPatchQueueContext(paths.patches, config);
-    // Queue-level findings (policy, cross-patch) are scoped to the requested
-    // subset: a 5-patch slice should not fail on a policy or forward-import
-    // problem owned entirely by patches the operator did not target.
-    const subsetTouchedFiles = new Set();
-    if (isSubset) {
-        for (const entry of ctx.entries) {
-            if (!subsetNames.has(entry.filename))
-                continue;
-            for (const f of entry.newFiles.keys())
-                subsetTouchedFiles.add(f);
-            for (const f of entry.modifiedFileAdditions.keys())
-                subsetTouchedFiles.add(f);
-        }
-    }
-    const cache = options.noCache === true ? undefined : await loadPerPatchLintCache(projectRoot);
-    const engineHeadSha = cache ? await getPerPatchLintCacheHeadSha(paths.engine) : undefined;
-    const issues = [];
-    const policyIssues = [
-        ...evaluatePatchPolicy(config, manifest),
-        ...(await evaluatePatchPolicyContent(config, projectRoot, manifest, ctx.entries)),
-    ];
-    for (const issue of policyIssues) {
-        if (isSubset && !subsetNames.has(issue.filename))
-            continue;
-        issues.push({
-            file: issue.filename,
-            check: `patch-policy/${issue.code}`,
-            message: issue.message,
-            severity: issue.severity,
-        });
-    }
-    // With `--patches`, the checkJs program roots at only the subset's owned
-    // files. The full queue stays resolvable, so a cold subset run costs the
-    // subset's import closure instead of the whole queue.
-    const checkJs = buildPerRunCheckJs(projectRoot, paths, config, ctx, isSubset ? subsetNames : undefined);
-    // Lint patches concurrently, then apply every side effect in patch order so
-    // the issue rows, the run-level checkJs errors, and the saved cache are
-    // identical to a serial run.
-    const results = await lintSubsetConcurrently(subset, {
-        projectRoot,
-        paths,
-        config,
-        ctx,
-        cache,
-        engineHeadSha,
-        checkJs,
-    });
-    const heldNotices = options.notices === 'summary' ? [] : undefined;
-    const { linted, skipped, cacheDirty, reusedCacheEntries, suppressed } = await applyPerPatchResults(subset, results, issues, checkJs, cache, heldNotices);
-    const queueIssues = [];
-    for (const issue of lintPatchQueue(ctx)) {
-        // A finding that names a subset patch stays in scope even when its file
-        // is one the patch no longer touches (a stale staged declaration).
-        const namesSubset = issue.patches?.some((name) => subsetNames.has(name)) === true;
-        if (isSubset && !namesSubset && !subsetTouchedFiles.has(issue.file))
-            continue;
-        issues.push(issue);
-        queueIssues.push(issue);
-    }
-    if (cache && cacheDirty)
-        await savePerPatchLintCache(projectRoot, cache);
-    if (reusedCacheEntries > 0) {
-        info(`Reused lint cache for ${reusedCacheEntries} patch${reusedCacheEntries === 1 ? '' : 'es'}.`);
-    }
-    if (suppressed > 0) {
-        info(`Suppressed ${suppressed} issue(s) via per-patch lintIgnore.`);
-    }
-    if (options.report !== undefined) {
-        await writePerPatchLintReport(options.report, subset, results, config, queueIssues);
-    }
-    reportPerPatchOutcome(issues, linted, skipped, options, heldNotices);
-}

package/dist/src/commands/lint-per-run-checkjs.d.ts

@@ -1,66 +0,0 @@
-/**
- * Per-run checkJs program controller, shared by `lint --per-patch` and
- * `re-export`.
- *
- * The dominant fixed cost of patch lint is one `ts.createProgram` over the
- * queue's patch-owned `.sys.mjs` files, tens of seconds on a large queue.
- * This controller builds that program at most once per command invocation
- * (lazily, promise-memoised) and lets callers slice per-patch findings out of
- * the grouped result. Three levers keep the cost paid only when it buys
- * something:
- *
- * - Lazy build: nothing is built until the first cache miss asks.
- * - Root scoping (`rootScopePatches`): with `--patches <subset>` the
- *   program's roots are only the subset's owned files. The full queue stays
- *   resolvable, so cross-patch imports type-check identically while
- *   unrelated files are never parsed.
- * - Warm-run probe: run-level ("global") checkJs findings come only from a
- *   missing `typescript` package or an unreadable shim, never from the built
- *   program, so an all-cache-hit run satisfies "warm never reports less than
- *   cold" via `probeCheckJsGlobalIssues` instead of building anything.
- */
-import { type GroupedCheckJsResult } from '../core/patch-lint-checkjs.js';
-import type { PatchQueueContext } from '../core/patch-lint-cross.js';
-import type { PatchLintIssue } from '../types/commands/index.js';
-import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
-/**
- * Queue-wide checkJs program built once per run and sliced per patch, so a
- * single type regression surfaces once against its owning patch instead of
- * being duplicated for every patch in the queue.
- */
-export interface PerRunCheckJs {
-    /** Patch filename → the checkJs-relevant files that patch creates. */
-    ownedByPatch: Map<string, Set<string>>;
-    /** Every checkJs-relevant file in the queue (sys + test scripts), the
-     *  resolution universe the program can see. Callers use it to detect
-     *  files the hoisted program has never heard of (fresh `--scan`
-     *  adoptions) and fall back to a per-patch build. */
-    resolutionSet: ReadonlySet<string>;
-    /** Builds (once, lazily on first cache miss) and returns the grouped run.
-     *  Promise-memoised so the bounded per-patch pool builds the program exactly
-     *  once even when several patches reach it concurrently. */
-    getGrouped: () => Promise<GroupedCheckJsResult>;
-    /** Run-level checkJs errors (e.g. TypeScript missing). When the program
-     *  was never built (all-warm run) this probes the two global failure
-     *  sources directly instead of building it, which is safe because the
-     *  built program never contributes globals of its own. */
-    getGlobal: () => Promise<PatchLintIssue[]>;
-    /** The byFile slices for `files` (globals are excluded because they
-     *  are run-level, never cached, and emitted once per invocation via
-     *  `getGlobal`). Feed to `LintExportedPatchOptions.precomputedCheckJs`. */
-    sliceFor: (files: ReadonlySet<string>) => Promise<PatchLintIssue[]>;
-    /** True when this file kind participates in the run's checkJs surface
-     *  (`.sys.mjs`, plus test scripts when `checkJsTestFiles` is on). */
-    isRelevant: (file: string) => boolean;
-    /** The program's roots under `rootScopePatches`, or undefined for the
-     *  whole queue. A file outside it is resolvable but never checked. */
-    rootScope: ReadonlySet<string> | undefined;
-}
-/**
- * Builds the per-run checkJs program controller when `patchLint.checkJs` is
- * enabled, or returns undefined. With `rootScopePatches` set (the
- * `--patches` subset, by patch filename), the program roots at only the
- * subset's owned files and the test-file pass runs only the subset's own
- * scripts (head.js discovery still spans the queue).
- */
-export declare function buildPerRunCheckJs(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig, ctx: PatchQueueContext, rootScopePatches?: ReadonlySet<string>): PerRunCheckJs | undefined;

package/dist/src/commands/lint-per-run-checkjs.js

@@ -1,102 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Per-run checkJs program controller, shared by `lint --per-patch` and
- * `re-export`.
- *
- * The dominant fixed cost of patch lint is one `ts.createProgram` over the
- * queue's patch-owned `.sys.mjs` files, tens of seconds on a large queue.
- * This controller builds that program at most once per command invocation
- * (lazily, promise-memoised) and lets callers slice per-patch findings out of
- * the grouped result. Three levers keep the cost paid only when it buys
- * something:
- *
- * - Lazy build: nothing is built until the first cache miss asks.
- * - Root scoping (`rootScopePatches`): with `--patches <subset>` the
- *   program's roots are only the subset's owned files. The full queue stays
- *   resolvable, so cross-patch imports type-check identically while
- *   unrelated files are never parsed.
- * - Warm-run probe: run-level ("global") checkJs findings come only from a
- *   missing `typescript` package or an unreadable shim, never from the built
- *   program, so an all-cache-hit run satisfies "warm never reports less than
- *   cold" via `probeCheckJsGlobalIssues` instead of building anything.
- */
-import { invokePatchLintCheckJsGrouped, probeCheckJsGlobalIssues, runCheckJsTestFilesGrouped, } from '../core/patch-lint-checkjs.js';
-import { isTestScriptFile, resolvableModulesForTests, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from '../core/patch-lint-ownership.js';
-/**
- * Builds the per-run checkJs program controller when `patchLint.checkJs` is
- * enabled, or returns undefined. With `rootScopePatches` set (the
- * `--patches` subset, by patch filename), the program roots at only the
- * subset's owned files and the test-file pass runs only the subset's own
- * scripts (head.js discovery still spans the queue).
- */
-export function buildPerRunCheckJs(projectRoot, paths, config, ctx, rootScopePatches) {
-    const patchLint = config.patchLint;
-    if (!patchLint?.checkJs)
-        return undefined;
-    const testFilesEnabled = patchLint.checkJsTestFiles === true;
-    const ownedByPatch = new Map();
-    for (const entry of ctx.entries) {
-        const owned = new Set();
-        for (const f of entry.newFiles.keys()) {
-            if (f.endsWith('.sys.mjs'))
-                owned.add(f);
-            else if (testFilesEnabled && isTestScriptFile(f))
-                owned.add(f);
-        }
-        if (owned.size > 0)
-            ownedByPatch.set(entry.filename, owned);
-    }
-    const resolutionSet = new Set();
-    for (const files of ownedByPatch.values()) {
-        for (const f of files)
-            resolutionSet.add(f);
-    }
-    // The subset's owned files, split by program kind. Undefined = full queue.
-    let scopedRoots;
-    if (rootScopePatches !== undefined) {
-        scopedRoots = new Set();
-        for (const [patchFilename, files] of ownedByPatch) {
-            if (!rootScopePatches.has(patchFilename))
-                continue;
-            for (const f of files)
-                scopedRoots.add(f);
-        }
-    }
-    // One build for the whole run: the queue-wide `.sys.mjs` program, plus
-    // (when `patchLint.checkJsTestFiles` is on) one small script-scope
-    // program per patch-owned test file, merged by file.
-    const buildAll = async () => {
-        const sys = await invokePatchLintCheckJsGrouped(paths.engine, resolvePatchOwnedSysMjs(new Set(), ctx), patchLint, projectRoot, scopedRoots);
-        if (!testFilesEnabled)
-            return sys;
-        const tests = await runCheckJsTestFilesGrouped(paths.engine, resolvePatchOwnedTestScripts(new Set(), ctx), patchLint, projectRoot, scopedRoots, resolvableModulesForTests(ctx));
-        const byFile = new Map(sys.byFile);
-        for (const [rel, list] of tests.byFile) {
-            byFile.set(rel, [...(byFile.get(rel) ?? []), ...list]);
-        }
-        return { byFile, global: [...sys.global, ...tests.global] };
-    };
-    // Memoise the promise rather than the resolved value: under the bounded pool
-    // several patches can reach `getGrouped` before the first build resolves, and
-    // `??=` on the promise (a synchronous expression) guarantees a single build.
-    let groupedPromise;
-    const getGrouped = () => (groupedPromise ??= buildAll());
-    return {
-        ownedByPatch,
-        resolutionSet,
-        getGrouped,
-        getGlobal: async () => groupedPromise !== undefined
-            ? (await groupedPromise).global
-            : probeCheckJsGlobalIssues(patchLint, projectRoot),
-        sliceFor: async (files) => {
-            const grouped = await getGrouped();
-            const issues = [];
-            for (const rel of files) {
-                issues.push(...(grouped.byFile.get(rel) ?? []));
-            }
-            return issues;
-        },
-        isRelevant: (file) => file.endsWith('.sys.mjs') || (testFilesEnabled && isTestScriptFile(file)),
-        rootScope: scopedRoots,
-    };
-}

package/dist/src/commands/lint-report.d.ts

@@ -1,25 +0,0 @@
-import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.js';
-/**
- * Structural view of one per-patch lint outcome. Mirrors the relevant
- * fields of lint-per-patch's QueuedPatchResult without importing it:
- * that module imports this one, and a type back-edge would trip the
- * dpdm cycle gate.
- */
-export interface PerPatchReportResult {
-    status: 'skipped' | 'cached' | 'linted';
-    existingFiles: string[];
-    rawIssues: PatchLintIssue[];
-    suppressedIssues: PatchLintIssue[];
-    lineCount: number;
-}
-/**
- * Writes the per-patch lint report JSON. Called after the per-patch
- * results are assembled in patch order. Policy findings are
- * patch-attributed by their `filename` field upstream and are not
- * duplicated here. Cross-patch findings (`forward-import`,
- * `forward-registration`, …) go in `queueIssues`, with the
- * `stagedDeclarations` that discharge them, so the report can be handed to
- * `patch staged-dependency --from` as is.
- */
-export declare function writePerPatchLintReport(reportPath: string, subset: readonly PatchMetadata[], results: readonly PerPatchReportResult[], config: Pick<FireForgeConfig, 'patchLint'>, queueIssues?: readonly PatchLintIssue[]): Promise<void>;