@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/re-export-lint.d.ts

@@ -1,137 +0,0 @@
-/**
- * Hoisted + cached lint context for `re-export`.
- *
- * Rebuilding the whole patch-queue context and a fresh queue-wide checkJs
- * TypeScript program for every patch costs tens of seconds of fixed setup
- * per patch, so an N-patch re-export pays it N times. This module:
- *
- * - Builds the queue context and the {@link PerRunCheckJs} program
- *   controller once per invocation (`buildReExportLintContext`) and slices
- *   per-patch findings out of it.
- * - Reuses the existing per-patch lint result cache
- *   (`.fireforge/lint-cache/per-patch-v1.json`) across invocations, since
- *   re-export lints the identical input `lint --per-patch` does (the fresh
- *   `git diff HEAD` of the owned files), and the key already hashes engine
- *   HEAD, per-file content, patch body, config, shims, and ownership, so a
- *   repeat single re-export is a warm hit. `--no-cache` opts out. Run-level
- *   checkJs globals are never cached and are emitted once per invocation.
- * - Keeps the in-memory queue context honest after each write
- *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
- *   against the just-refreshed body instead of the stale one.
- */
-import { type PatchQueueContext } from '../core/patch-lint.js';
-import { type PerPatchLintCacheFile } from '../core/patch-lint-cache.js';
-import { type LintIgnoreChecks } from '../core/patch-lint-ignore.js';
-import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
-import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
-import { type PerRunCheckJs } from './lint-per-run-checkjs.js';
-/** Per-invocation lint context, built once and threaded through the loop. */
-export interface ReExportLintContext {
-    projectRoot: string;
-    paths: ProjectPaths;
-    config: FireForgeConfig;
-    /** Whole-queue context, built with config so the forward-import hints
-     * match `lint --per-patch`. Undefined when no patches dir. */
-    patchQueueCtx: PatchQueueContext | undefined;
-    /** Queue-wide checkJs controller. Undefined when checkJs is off. */
-    checkJs: PerRunCheckJs | undefined;
-    /** Per-patch result cache. Undefined under `--no-cache`. */
-    cache: PerPatchLintCacheFile | undefined;
-    engineHeadSha: string | undefined;
-    cacheDirty: boolean;
-    reusedCacheEntries: number;
-    /** Run-level checkJs globals are emitted once per invocation. */
-    globalsEmitted: boolean;
-    /** The pre-existing-queue-errors note is printed once per invocation. */
-    queueBaselineWarned: boolean;
-}
-/**
- * Builds the once-per-invocation lint context.
- *
- * The checkJs program is rooted at the patches being re-exported, exactly as
- * `lint --per-patch --patches` roots it at its subset: the rest of the
- * queue stays resolvable, so cross-patch imports type-check identically,
- * but nothing else is parsed or checked. Unscoped, a one-patch re-export
- * that missed the lint cache type-checked the whole queue (76 s on a
- * 401-patch queue) to report on one patch.
- *
- * @param projectRoot - FireForge project root
- * @param paths - Resolved project paths
- * @param config - Loaded configuration
- * @param noCache - Skip the per-patch lint result cache (`--no-cache`)
- * @param scopePatches - Filenames of the patches this run re-exports
- */
-export declare function buildReExportLintContext(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig, noCache: boolean, scopePatches: ReadonlySet<string>): Promise<ReExportLintContext>;
-/** Fresh lint payload carried to the post-write cache store. */
-export interface ReExportLintResult {
-    issues: PatchLintIssue[];
-    suppressed: PatchLintIssue[];
-    lineCount: number;
-    /** Waiver ids in force for this lint run. */
-    lintIgnore: string[];
-}
-/**
- * Lints one re-exported patch body using the hoisted context. A cache hit
- * replays the stored issues through the shared reporter and returns `null`.
- * A miss lints with the queue-wide program's pre-attributed slices (or a
- * per-patch build when the fresh diff creates files the hoisted program
- * never saw, the `--scan` adoption case) and returns the payload for
- * {@link storeReExportLintResult}. Throws exactly like `runPatchLint` on
- * errors (unless `skipLint`).
- *
- * The cache key is built over the projected metadata (current
- * filesAffected, merged lintIgnore, effective tier) so `--tier` /
- * `--lint-ignore` flags change the key. The entry itself is stored after
- * the body write, because the key hashes the on-disk `.patch` file that
- * this very run is about to rewrite, so a pre-write store could never
- * match a later run.
- */
-export declare function lintReExportedPatch(args: {
-    lintCtx: ReExportLintContext;
-    patch: PatchMetadata;
-    projectedMetadata: PatchMetadata;
-    existingFiles: string[];
-    diffContent: string;
-    skipLint?: boolean;
-    ignoreChecks?: LintIgnoreChecks;
-    patchTier?: 'branding';
-}): Promise<ReExportLintResult | null>;
-/**
- * Stores a fresh lint result after the body write, keying against the
- * just-written `.patch` file and the refreshed queue context, which is the
- * state a later identical invocation will observe (call
- * {@link refreshQueueCtxEntry} first).
- */
-export declare function storeReExportLintResult(lintCtx: ReExportLintContext, patchFilename: string, projectedMetadata: PatchMetadata, existingFiles: string[], result: ReExportLintResult): Promise<void>;
-/**
- * Projects the rewritten body into the hoisted queue context and refuses
- * when the projection introduces error-severity cross-patch findings the
- * current queue does not have (a forward import an earlier owner gained,
- * say). Mirrors `re-export --files` (its projected-state conflict) and the
- * `--scan` adoption gate, which only covers files a scan adopted: without
- * this a plain re-export of an unchanged file set with new CONTENT would
- * pass, and the queue would carry the error until the next `export`
- * placement refused it.
- *
- * Runs in dry-run. `--force-unsafe` downgrades the refusal to warnings;
- * `--skip-lint` does not bypass it, same as `--files`. The baseline is the
- * hoisted context, which {@link refreshQueueCtxEntry} keeps equal to the
- * on-disk queue across an `--all` loop, so patch N+1 is projected against
- * the queue as it will exist.
- */
-export declare function assertRefreshedBodyHasNoNewQueueErrors(args: {
-    lintCtx: ReExportLintContext;
-    patchFilename: string;
-    diffContent: string;
-    forceUnsafe: boolean;
-}): void;
-/**
- * Refreshes the in-memory queue entry for a just-rewritten patch so later
- * iterations (and later cache keys) lint against the new body instead of
- * the stale one. The on-disk write is the authority. This mirrors it, via
- * the same projection `buildPatchQueueContext` derives an entry from, so
- * `createdFiles` and `modifiedFileAdditions` stay in step with a rebuild.
- */
-export declare function refreshQueueCtxEntry(lintCtx: ReExportLintContext, patchFilename: string, diffContent: string): void;
-/** Persists cache writes and reports reuse, once after the loop. */
-export declare function finishReExportLint(lintCtx: ReExportLintContext): Promise<void>;

package/dist/src/commands/re-export-lint.js

@@ -1,303 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Hoisted + cached lint context for `re-export`.
- *
- * Rebuilding the whole patch-queue context and a fresh queue-wide checkJs
- * TypeScript program for every patch costs tens of seconds of fixed setup
- * per patch, so an N-patch re-export pays it N times. This module:
- *
- * - Builds the queue context and the {@link PerRunCheckJs} program
- *   controller once per invocation (`buildReExportLintContext`) and slices
- *   per-patch findings out of it.
- * - Reuses the existing per-patch lint result cache
- *   (`.fireforge/lint-cache/per-patch-v1.json`) across invocations, since
- *   re-export lints the identical input `lint --per-patch` does (the fresh
- *   `git diff HEAD` of the owned files), and the key already hashes engine
- *   HEAD, per-file content, patch body, config, shims, and ownership, so a
- *   repeat single re-export is a warm hit. `--no-cache` opts out. Run-level
- *   checkJs globals are never cached and are emitted once per invocation.
- * - Keeps the in-memory queue context honest after each write
- *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
- *   against the just-refreshed body instead of the stale one.
- */
-import { buildPatchQueueContext, detectNewFilesInDiff, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, measurePatchSize, resolvePatchSizeTier, } from '../core/patch-lint.js';
-import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/patch-lint-cache.js';
-import { invalidateNewFileCreatorsCache } from '../core/patch-lint-cross.js';
-import { lintIgnoreCacheTokens } from '../core/patch-lint-ignore.js';
-import { resolvePatchOwnedSysMjs } from '../core/patch-lint-ownership.js';
-import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
-import { GeneralError } from '../errors/base.js';
-import { pathExists } from '../utils/fs.js';
-import { info, warn } from '../utils/logger.js';
-import { reportPatchLintOutcome } from './export-shared.js';
-import { formatForwardImportRemedy } from './forward-import-remedy.js';
-import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
-import { projectEntryBody } from './patch/entry-projection.js';
-import { categoryOf, manifestFromQueue } from './re-export-scan.js';
-/**
- * Builds the once-per-invocation lint context.
- *
- * The checkJs program is rooted at the patches being re-exported, exactly as
- * `lint --per-patch --patches` roots it at its subset: the rest of the
- * queue stays resolvable, so cross-patch imports type-check identically,
- * but nothing else is parsed or checked. Unscoped, a one-patch re-export
- * that missed the lint cache type-checked the whole queue (76 s on a
- * 401-patch queue) to report on one patch.
- *
- * @param projectRoot - FireForge project root
- * @param paths - Resolved project paths
- * @param config - Loaded configuration
- * @param noCache - Skip the per-patch lint result cache (`--no-cache`)
- * @param scopePatches - Filenames of the patches this run re-exports
- */
-export async function buildReExportLintContext(projectRoot, paths, config, noCache, scopePatches) {
-    const patchQueueCtx = (await pathExists(paths.patches))
-        ? await buildPatchQueueContext(paths.patches, config)
-        : undefined;
-    const checkJs = patchQueueCtx
-        ? buildPerRunCheckJs(projectRoot, paths, config, patchQueueCtx, scopePatches)
-        : undefined;
-    const cache = noCache ? undefined : await loadPerPatchLintCache(projectRoot);
-    if (patchQueueCtx) {
-        // The queue rules and the projection below read every patch, so the
-        // wait is named rather than left behind one spinner line.
-        info(`Lint scope: queue rules over all ${patchQueueCtx.entries.length} patch(es); ` +
-            `checkJs rooted at the ${scopePatches.size} re-exported patch(es); ` +
-            (cache === undefined
-                ? 'lint cache off (--no-cache).'
-                : `lint cache ${Object.keys(cache.entries).length === 0 ? 'empty' : 'loaded'}.`));
-    }
-    const engineHeadSha = cache ? await getPerPatchLintCacheHeadSha(paths.engine) : undefined;
-    return {
-        projectRoot,
-        paths,
-        config,
-        patchQueueCtx,
-        checkJs,
-        cache,
-        engineHeadSha,
-        cacheDirty: false,
-        reusedCacheEntries: 0,
-        globalsEmitted: false,
-        queueBaselineWarned: false,
-    };
-}
-/** The checkJs-relevant files this fresh diff creates. */
-function checkJsFilesInDiff(diffContent, checkJs) {
-    const files = new Set();
-    for (const f of detectNewFilesInDiff(diffContent)) {
-        if (checkJs.isRelevant(f))
-            files.add(f);
-    }
-    return files;
-}
-/**
- * Lints one re-exported patch body using the hoisted context. A cache hit
- * replays the stored issues through the shared reporter and returns `null`.
- * A miss lints with the queue-wide program's pre-attributed slices (or a
- * per-patch build when the fresh diff creates files the hoisted program
- * never saw, the `--scan` adoption case) and returns the payload for
- * {@link storeReExportLintResult}. Throws exactly like `runPatchLint` on
- * errors (unless `skipLint`).
- *
- * The cache key is built over the projected metadata (current
- * filesAffected, merged lintIgnore, effective tier) so `--tier` /
- * `--lint-ignore` flags change the key. The entry itself is stored after
- * the body write, because the key hashes the on-disk `.patch` file that
- * this very run is about to rewrite, so a pre-write store could never
- * match a later run.
- */
-export async function lintReExportedPatch(args) {
-    const { lintCtx, patch, projectedMetadata, existingFiles, diffContent } = args;
-    const { paths, config, patchQueueCtx, checkJs, cache } = lintCtx;
-    // Tier notice, identical to runPatchLint's head. It is surfaced on both
-    // the cached and fresh paths so the governing tier is never silent.
-    const tierDecision = resolvePatchSizeTier(existingFiles, args.patchTier);
-    if (tierDecision.tier === 'branding') {
-        info(tierDecision.source === 'explicit'
-            ? 'Lint: branding threshold tier applied via patches.json `tier: "branding"` opt-in.'
-            : 'Lint: branding threshold tier applied (patch is all under browser/branding/ plus registration siblings).');
-    }
-    // Run-level checkJs globals surface exactly once per invocation, never
-    // from the cache. On an all-warm run this is a cheap probe,
-    // not a program build.
-    let globalIssues = [];
-    if (checkJs && !lintCtx.globalsEmitted) {
-        lintCtx.globalsEmitted = true;
-        globalIssues = await checkJs.getGlobal();
-    }
-    if (cache && patchQueueCtx) {
-        const cacheKey = await buildPerPatchLintCacheKey({
-            projectRoot: lintCtx.projectRoot,
-            engineDir: paths.engine,
-            patchesDir: paths.patches,
-            patch: projectedMetadata,
-            existingFiles,
-            config,
-            queueContext: patchQueueCtx,
-            ...(lintCtx.engineHeadSha === undefined ? {} : { engineHeadSha: lintCtx.engineHeadSha }),
-        });
-        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey, lintIgnoreCacheTokens(args.ignoreChecks));
-        if (cached) {
-            lintCtx.reusedCacheEntries++;
-            reportPatchLintOutcome([...globalIssues, ...cached.issues], args.skipLint);
-            return null;
-        }
-    }
-    const lintOptions = {};
-    const suppressedIssues = [];
-    lintOptions.onSuppressed = (suppressed) => suppressedIssues.push(...suppressed);
-    if (checkJs) {
-        const created = checkJsFilesInDiff(diffContent, checkJs);
-        if (created.size > 0) {
-            info(`checkJs: type-checking ${created.size} file(s) of ${patch.filename} (lint cache ${cache ? 'miss' : 'off'}).`);
-        }
-        // A file the scoped program does not root at would be resolvable but
-        // never checked, so it takes the per-patch build too.
-        const allKnown = [...created].every((f) => checkJs.resolutionSet.has(f) && (checkJs.rootScope?.has(f) ?? true));
-        if (allKnown) {
-            // Slice this patch's findings out of the one queue-wide program.
-            lintOptions.precomputedCheckJs = await checkJs.sliceFor(created);
-        }
-        else {
-            // Fresh `--scan` adoption created checkJs-relevant files the hoisted
-            // program has never seen, so fall back to a per-patch build with the
-            // usual report scope and nothing is silently unchecked.
-            lintOptions.checkJsReportScope = resolvePatchOwnedSysMjs(detectNewFilesInDiff(diffContent));
-        }
-    }
-    else if (patchQueueCtx) {
-        lintOptions.checkJsReportScope = resolvePatchOwnedSysMjs(detectNewFilesInDiff(diffContent));
-    }
-    const patchSize = await measurePatchSize(paths.engine, diffContent, existingFiles, config);
-    const issues = await lintExportedPatch(paths.engine, existingFiles, diffContent, config, {
-        ...lintOptions,
-        patchSizeMeasurement: patchSize,
-        ...(patchQueueCtx ? { patchQueueCtx } : {}),
-        ...(args.ignoreChecks ? { ignoreChecks: args.ignoreChecks } : {}),
-        ...(args.patchTier ? { patchTier: args.patchTier } : {}),
-    });
-    reportPatchLintOutcome([...globalIssues, ...issues], args.skipLint);
-    return {
-        issues,
-        suppressed: suppressedIssues,
-        lineCount: patchSize.lines,
-        lintIgnore: lintIgnoreCacheTokens(args.ignoreChecks),
-    };
-}
-/**
- * Stores a fresh lint result after the body write, keying against the
- * just-written `.patch` file and the refreshed queue context, which is the
- * state a later identical invocation will observe (call
- * {@link refreshQueueCtxEntry} first).
- */
-export async function storeReExportLintResult(lintCtx, patchFilename, projectedMetadata, existingFiles, result) {
-    const { cache, patchQueueCtx, paths, config } = lintCtx;
-    if (!cache || !patchQueueCtx)
-        return;
-    const cacheKey = await buildPerPatchLintCacheKey({
-        projectRoot: lintCtx.projectRoot,
-        engineDir: paths.engine,
-        patchesDir: paths.patches,
-        patch: projectedMetadata,
-        existingFiles,
-        config,
-        queueContext: patchQueueCtx,
-        ...(lintCtx.engineHeadSha === undefined ? {} : { engineHeadSha: lintCtx.engineHeadSha }),
-    });
-    setCachedPerPatchLintIssues({
-        cache,
-        patchFilename,
-        key: cacheKey,
-        issues: result.issues,
-        suppressed: result.suppressed,
-        lineCount: result.lineCount,
-        lintIgnore: result.lintIgnore,
-    });
-    lintCtx.cacheDirty = true;
-}
-/**
- * Projects the rewritten body into the hoisted queue context and refuses
- * when the projection introduces error-severity cross-patch findings the
- * current queue does not have (a forward import an earlier owner gained,
- * say). Mirrors `re-export --files` (its projected-state conflict) and the
- * `--scan` adoption gate, which only covers files a scan adopted: without
- * this a plain re-export of an unchanged file set with new CONTENT would
- * pass, and the queue would carry the error until the next `export`
- * placement refused it.
- *
- * Runs in dry-run. `--force-unsafe` downgrades the refusal to warnings;
- * `--skip-lint` does not bypass it, same as `--files`. The baseline is the
- * hoisted context, which {@link refreshQueueCtxEntry} keeps equal to the
- * on-disk queue across an `--all` loop, so patch N+1 is projected against
- * the queue as it will exist.
- */
-export function assertRefreshedBodyHasNoNewQueueErrors(args) {
-    const { lintCtx, patchFilename, diffContent, forceUnsafe } = args;
-    const ctx = lintCtx.patchQueueCtx;
-    if (!ctx)
-        return;
-    const projection = projectEntryBody(diffContent);
-    const projectedEntries = ctx.entries.map((entry) => entry.filename === patchFilename ? { ...entry, ...projection } : entry);
-    const isError = (issue) => issue.severity === 'error';
-    const baseline = lintPatchQueue(ctx).filter(isError);
-    // The whole context carries over (patchPolicy and the
-    // `patchLint.forwardRegistration` scope): dropping the scope here let a
-    // forward jar.mn registration pass this gate and surface only in the
-    // later queue audit, separately from the forward import it packages.
-    const projected = lintPatchQueue({ ...ctx, entries: projectedEntries }).filter(isError);
-    const regressions = computeProjectedLintRegressions(baseline, projected);
-    if (regressions.length === 0) {
-        if (baseline.length > 0 && !lintCtx.queueBaselineWarned) {
-            lintCtx.queueBaselineWarned = true;
-            warn(`Note: projected queue still has ${baseline.length} pre-existing ` +
-                'cross-patch error(s) unrelated to this re-export. Run "fireforge verify" to list them.');
-        }
-        return;
-    }
-    const details = regressions.map((issue) => `  ${formatPatchLintIssue(issue)}`).join('\n');
-    const hasForwardImport = regressions.some((issue) => issue.check === 'forward-import');
-    const message = `Refusing to re-export ${patchFilename} because the refreshed body introduces ` +
-        `${regressions.length} new cross-patch lint error${regressions.length === 1 ? '' : 's'}:\n${details}` +
-        (hasForwardImport
-            ? `\n${formatForwardImportRemedy({
-                reRunHint: 're-running the re-export',
-                issues: regressions,
-                manifest: manifestFromQueue(ctx),
-                config: lintCtx.config,
-                ...categoryOf(ctx, patchFilename),
-            })}`
-            : '');
-    if (forceUnsafe) {
-        warn(message);
-        warn('Proceeding because --force-unsafe was provided.');
-        return;
-    }
-    throw new GeneralError(message);
-}
-/**
- * Refreshes the in-memory queue entry for a just-rewritten patch so later
- * iterations (and later cache keys) lint against the new body instead of
- * the stale one. The on-disk write is the authority. This mirrors it, via
- * the same projection `buildPatchQueueContext` derives an entry from, so
- * `createdFiles` and `modifiedFileAdditions` stay in step with a rebuild.
- */
-export function refreshQueueCtxEntry(lintCtx, patchFilename, diffContent) {
-    const ctx = lintCtx.patchQueueCtx;
-    if (!ctx)
-        return;
-    const entry = ctx.entries.find((e) => e.filename === patchFilename);
-    if (!entry)
-        return;
-    Object.assign(entry, projectEntryBody(diffContent));
-    invalidateNewFileCreatorsCache(ctx);
-}
-/** Persists cache writes and reports reuse, once after the loop. */
-export async function finishReExportLint(lintCtx) {
-    if (lintCtx.cache && lintCtx.cacheDirty) {
-        await savePerPatchLintCache(lintCtx.projectRoot, lintCtx.cache);
-    }
-    if (lintCtx.reusedCacheEntries > 0) {
-        info(`Reused lint cache for ${lintCtx.reusedCacheEntries} patch${lintCtx.reusedCacheEntries === 1 ? '' : 'es'}.`);
-    }
-}

package/dist/src/commands/re-export-options.d.ts

@@ -1,29 +0,0 @@
-import type { ReExportOptions } from '../types/commands/index.js';
-/** Result of {@link normalizeReExportFilesPositionals}. */
-export interface NormalizedReExportArguments {
-    patches: string[];
-    options: ReExportOptions;
-    /** Extra positionals that were folded into the `--files` list. */
-    foldedPaths: string[];
-}
-/**
- * Accepts the `export`-style space-separated path shape for
- * `re-export <patch> --files`. Commander's `--files <paths>` consumes one
- * comma-separated value, so `re-export 006-x --files a/b.js c/d.js` parks
- * `c/d.js` in the positional patches and fails with "--files operates on
- * exactly one target patch", pointing at the wrong argument. When every
- * positional beyond the first looks like a file path, fold them into the
- * file list.
- */
-export declare function normalizeReExportFilesPositionals(patches: readonly string[], options: ReExportOptions): NormalizedReExportArguments;
-/**
- * Folding wrapper used by the command layer: applies
- * {@link normalizeReExportFilesPositionals} and logs the folded paths so
- * the operator sees exactly which positionals became file-list entries.
- */
-export declare function applyReExportFilesPositionalFolding(patches: string[], options: ReExportOptions): {
-    patches: string[];
-    options: ReExportOptions;
-};
-/** Validates mutually exclusive `re-export` targeting and metadata options. */
-export declare function validateReExportOptionCombinations(patches: readonly string[], options: ReExportOptions): void;

package/dist/src/commands/re-export-options.js

@@ -1,191 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { InvalidArgumentError } from '../errors/base.js';
-import { info } from '../utils/logger.js';
-import { validateScanFileOwners } from './re-export-scan-owner.js';
-/**
- * Heuristic for `--files` positional folding: an extra positional that
- * contains a path separator and is not a `.patch` filename is an engine
- * file path, not a patch identifier.
- */
-function looksLikeFilePath(value) {
-    return value.includes('/') && !value.endsWith('.patch');
-}
-/**
- * Accepts the `export`-style space-separated path shape for
- * `re-export <patch> --files`. Commander's `--files <paths>` consumes one
- * comma-separated value, so `re-export 006-x --files a/b.js c/d.js` parks
- * `c/d.js` in the positional patches and fails with "--files operates on
- * exactly one target patch", pointing at the wrong argument. When every
- * positional beyond the first looks like a file path, fold them into the
- * file list.
- */
-export function normalizeReExportFilesPositionals(patches, options) {
-    if (options.files === undefined || patches.length <= 1) {
-        return { patches: [...patches], options, foldedPaths: [] };
-    }
-    const [first, ...rest] = patches;
-    if (first !== undefined && rest.every(looksLikeFilePath)) {
-        return {
-            patches: [first],
-            options: { ...options, files: [...options.files, ...rest] },
-            foldedPaths: rest,
-        };
-    }
-    return { patches: [...patches], options, foldedPaths: [] };
-}
-/**
- * Folding wrapper used by the command layer: applies
- * {@link normalizeReExportFilesPositionals} and logs the folded paths so
- * the operator sees exactly which positionals became file-list entries.
- */
-export function applyReExportFilesPositionalFolding(patches, options) {
-    const normalized = normalizeReExportFilesPositionals(patches, options);
-    if (normalized.foldedPaths.length > 0) {
-        info(`--files: treating ${normalized.foldedPaths.length} extra positional path(s) as part ` +
-            `of the file list: ${normalized.foldedPaths.join(', ')}`);
-    }
-    return { patches: normalized.patches, options: normalized.options };
-}
-/**
- * Each carve-out flag is inert without the refusal it modifies, and a
- * silently-inert whitelist is the worst shape: the operator believes an
- * exception is in force while the refusal it was meant to relax was never
- * armed. Refuse the combination instead of ignoring it.
- */
-function validateWhitelistFlagDependencies(options) {
-    if (options.expect !== undefined &&
-        options.expect.length > 0 &&
-        options.refuseForeignDrift !== true) {
-        throw new InvalidArgumentError('--expect names files whose drift is expected under --refuse-foreign-drift and has no effect without it. Pass --refuse-foreign-drift, or drop --expect.', '--expect');
-    }
-    if (options.expectUnmanaged !== undefined &&
-        options.expectUnmanaged.length > 0 &&
-        options.refuseAdjacentUnmanaged !== true) {
-        throw new InvalidArgumentError('--expect-unmanaged names approved exceptions to --refuse-adjacent-unmanaged and has no effect without it. Pass --refuse-adjacent-unmanaged, or drop --expect-unmanaged.', '--expect-unmanaged');
-    }
-    for (const [flag, values] of [
-        ['--expect-new', options.expectNew],
-        ['--adjacent-ignore', options.adjacentIgnore],
-    ]) {
-        if (values !== undefined && values.length > 0 && options.refuseAdjacentUnmanaged !== true) {
-            throw new InvalidArgumentError(`${flag} relaxes --refuse-adjacent-unmanaged and has no effect without it. Pass --refuse-adjacent-unmanaged, or drop ${flag}.`, flag);
-        }
-    }
-    if (options.adjacentIgnore?.some((entry) => entry.includes('**'))) {
-        throw new InvalidArgumentError('--adjacent-ignore takes a path or a glob whose * stays within one path segment; ** is refused, because a subtree carve-out is how a reviewed exception becomes a blanket one.', '--adjacent-ignore');
-    }
-}
-/**
- * Refuses a path-valued flag whose value starts with `-`. Commander hands a
- * required option value whatever follows it, so a list that ended early
- * (`--expect-unmanaged --dry-run`) silently turned the next flag into a path
- * and the dry run into a write. No engine path starts with a dash.
- */
-function validatePathFlagValues(options) {
-    for (const [flag, values] of [
-        ['--expect', options.expect],
-        ['--expect-unmanaged', options.expectUnmanaged],
-        ['--expect-new', options.expectNew],
-        ['--expect-removed', options.expectRemoved],
-        ['--adjacent-ignore', options.adjacentIgnore],
-        ['--scan-file', options.scanFiles],
-    ]) {
-        const swallowed = (values ?? []).filter((value) => value.trim().startsWith('-'));
-        if (swallowed.length > 0) {
-            throw new InvalidArgumentError(`${flag} was given ${swallowed.map((value) => `"${value}"`).join(', ')}, which is a flag, not an engine path: ` +
-                `the ${flag} before it had no value, so it took the next argument. Give every ${flag} a path.`, flag);
-        }
-    }
-}
-/**
- * A retirement names its owner among explicitly selected patches. It
- * combines with `--scan`: the retired path leaves the scan's base first,
- * and the scan cannot adopt it back, since a retired created file is absent
- * and a retired upstream file is clean at HEAD.
- */
-function validateExpectedRemovalUsage(patches, options) {
-    if (options.expectRemoved?.length &&
-        (options.all || options.files !== undefined || patches.length === 0)) {
-        throw new InvalidArgumentError('--expect-removed requires explicit selected patches and cannot combine with --files or --all.', '--expect-removed');
-    }
-}
-/**
- * `--hunks-from` and `--exclude-hunks` rebuild one patch's files from named
- * hunks, so they take exactly one explicit patch and no flag that sets the
- * file list another way.
- */
-function validateHunkSelectionUsage(patches, options) {
-    if (options.hunksFrom !== undefined && options.excludeHunks !== undefined) {
-        throw new InvalidArgumentError('--hunks-from and --exclude-hunks are alternatives; pass one.', '--hunks-from');
-    }
-    const flag = options.hunksFrom !== undefined
-        ? '--hunks-from'
-        : options.excludeHunks !== undefined
-            ? '--exclude-hunks'
-            : undefined;
-    if (flag === undefined)
-        return;
-    if (patches.length !== 1 ||
-        options.all ||
-        options.scan ||
-        options.files !== undefined ||
-        options.scanFilesManifest !== undefined) {
-        throw new InvalidArgumentError(`${flag} rebuilds one patch's files from named hunks: pass exactly one patch, without --scan, --files or --all.`, flag);
-    }
-}
-/** Validates mutually exclusive `re-export` targeting and metadata options. */
-export function validateReExportOptionCombinations(patches, options) {
-    // First: a swallowed flag would otherwise surface as whichever
-    // combination error it happens to trip, naming the wrong problem.
-    validatePathFlagValues(options);
-    validateExpectedRemovalUsage(patches, options);
-    validateHunkSelectionUsage(patches, options);
-    if (options.files !== undefined) {
-        if (options.all || options.scan) {
-            throw new InvalidArgumentError('--files cannot be combined with --scan or --all.', '--files');
-        }
-        if (options.scanFilesManifest !== undefined) {
-            throw new InvalidArgumentError('--files cannot be combined with --scan-files.', '--files');
-        }
-        if (patches.length !== 1) {
-            throw new InvalidArgumentError('--files operates on exactly one target patch. Pass a single patch identifier. ' +
-                'File paths can be passed space-separated after --files (path-shaped extras are folded ' +
-                'into the file list automatically) or as one comma-separated --files value.', '--files');
-        }
-    }
-    if (options.scanFiles !== undefined) {
-        if (!options.scan)
-            throw new InvalidArgumentError('--scan-file requires --scan.', '--scan-file');
-        if (options.scanFilesManifest !== undefined) {
-            throw new InvalidArgumentError('--scan-file cannot be combined with --scan-files.', '--scan-file');
-        }
-        if (options.all) {
-            throw new InvalidArgumentError('--scan-file cannot be combined with --all. Pass the target patch identifiers.', '--scan-file');
-        }
-        validateScanFileOwners(patches, options.scanFiles);
-    }
-    if (options.scanFilesManifest !== undefined) {
-        if (!options.scan)
-            throw new InvalidArgumentError('--scan-files requires --scan.', '--scan-files');
-        if (options.all || patches.length > 0) {
-            throw new InvalidArgumentError('--scan-files selects patches from its manifest and cannot be combined with positional patches or --all.', '--scan-files');
-        }
-    }
-    // Beside --scan the belt judges the neighbours the scan did not adopt;
-    // --files replaces the file list outright, so there is nothing to judge.
-    if (options.refuseAdjacentUnmanaged === true && options.files !== undefined) {
-        throw new InvalidArgumentError('--refuse-adjacent-unmanaged cannot be combined with --files (it sets filesAffected explicitly).', '--refuse-adjacent-unmanaged');
-    }
-    // Beside --scan the belt covers the files each patch already owns; the
-    // files a scan adopts are the run's stated intent. --files replaces the
-    // file list outright, so there is no owned set left to guard.
-    if (options.refuseForeignDrift === true && options.files !== undefined) {
-        throw new InvalidArgumentError('--refuse-foreign-drift cannot be combined with --files (it sets filesAffected explicitly and captures the current engine state).', '--refuse-foreign-drift');
-    }
-    validateWhitelistFlagDependencies(options);
-    const usingTierFlag = options.tier !== undefined;
-    const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
-    if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {
-        throw new InvalidArgumentError('--tier and --lint-ignore require explicit patch identifiers and cannot be combined with --all (different patches typically need different metadata).', '--all');
-    }
-}