@hominis/fireforge 0.50.0 → 0.51.0

package/dist/src/commands/park.d.ts

@@ -0,0 +1,22 @@
+import type { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+/** Options for `fireforge park`. */
+export interface ParkOptions {
+    label?: string;
+    hunks?: string;
+    restore?: string;
+    list?: boolean;
+    drop?: string;
+    dryRun?: boolean;
+    waitLock?: number | boolean;
+}
+/**
+ * Runs `fireforge park`.
+ *
+ * @param projectRoot - Project root
+ * @param identifier - The patch to park (omitted for --restore/--list/--drop)
+ * @param options - See {@link ParkOptions}
+ */
+export declare function parkCommand(projectRoot: string, identifier: string | undefined, options: ParkOptions): Promise<void>;
+/** Registers `fireforge park`. */
+export declare function registerPark(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/park.js

@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge park`: set one session's edits in a patch's files aside and
+ * put them back after the owner commits.
+ *
+ *   park <patch> [--label <l>] [--hunks <diff>]   park and restore baseline
+ *   park --restore <label>                         three-way merge them back
+ *   park --list | park --drop <label>
+ *
+ * Without `--hunks` every drifted file of the patch goes back to its
+ * queue-applied baseline. With `--hunks` only the named hunks are taken out
+ * of the working tree. Either way the park warns when a hunk it takes out
+ * removes a Fluent message id, or a whole file, that files outside the
+ * patch still reference: a parked string still used by markup another
+ * patch owns makes `document.l10n.ready` reject in every new window.
+ */
+import { basename, join } from 'node:path';
+import { getProjectPaths } from '../core/config.js';
+import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { appendHistoryBestEffort } from '../core/history-log.js';
+import { dropPark, fluentIds, listParks, planRestore, readEngineFile, readPark, removedLines, writeEngineFile, writePark, } from '../core/park-store.js';
+import { createPatchedContentContext } from '../core/patch-apply.js';
+import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../core/patch-manifest.js';
+import { parseDiffSections } from '../core/patch-parse.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { info, intro, outro, success, warn } from '../utils/logger.js';
+import { addWaitLockOption, resolveWaitLockSeconds } from '../utils/options.js';
+import { applyHunksByContext } from './re-export-hunks.js';
+import { normalizeEngineRelativeInput } from './re-export-scan.js';
+/** The patch-applied baseline of each of `patch`'s files (null = absent). */
+async function baselinesOf(paths, patch) {
+    const { computePatched } = await createPatchedContentContext(paths.patches, paths.engine);
+    const deleted = new Set(parseDiffSections(await readText(join(paths.patches, patch.filename)))
+        .filter((section) => section.isDeletedFile)
+        .map((section) => section.targetPath));
+    const baselines = new Map();
+    for (const file of patch.filesAffected) {
+        baselines.set(file, deleted.has(file) ? null : await computePatched(file));
+    }
+    return baselines;
+}
+/** The files a park would change, with both sides. */
+async function planPark(paths, patch, hunksPath) {
+    if (hunksPath === undefined) {
+        const baselines = await baselinesOf(paths, patch);
+        const files = [];
+        for (const [path, after] of baselines) {
+            const before = await readEngineFile(paths.engine, path);
+            if (before !== after)
+                files.push({ path, before, after });
+        }
+        return files;
+    }
+    if (!(await pathExists(hunksPath))) {
+        throw new InvalidArgumentError(`--hunks ${hunksPath} does not exist.`, '--hunks');
+    }
+    const owned = new Set(patch.filesAffected);
+    const files = [];
+    for (const section of parseDiffSections(await readText(hunksPath))) {
+        const path = normalizeEngineRelativeInput(section.targetPath, '--hunks');
+        if (!owned.has(path)) {
+            throw new InvalidArgumentError(`--hunks names ${path}, which ${patch.filename} does not own.`, '--hunks');
+        }
+        const before = await readEngineFile(paths.engine, path);
+        const after = applyHunksByContext(before ?? '', section.hunks, true, path);
+        if (before !== after)
+            files.push({ path, before, after });
+    }
+    return files;
+}
+/**
+ * Referrers outside the patch of what the park takes away: Fluent ids its
+ * removed lines declare, and files it removes outright.
+ */
+async function findOutsideReferrers(paths, manifest, patch, files) {
+    const needles = new Map();
+    for (const file of files) {
+        if (file.path.endsWith('.ftl')) {
+            for (const id of fluentIds(removedLines(file.before, file.after))) {
+                needles.set(id, `Fluent id "${id}" (${file.path})`);
+            }
+        }
+        if (file.before !== null && file.after === null) {
+            needles.set(basename(file.path), `file ${file.path}`);
+        }
+    }
+    if (needles.size === 0)
+        return [];
+    const own = new Set(patch.filesAffected);
+    const outside = [...new Set(manifest.patches.flatMap((entry) => entry.filesAffected))].filter((file) => !own.has(file));
+    const findings = [];
+    for (const file of outside) {
+        const content = await readEngineFile(paths.engine, file);
+        if (content === null)
+            continue;
+        for (const [needle, label] of needles) {
+            if (content.includes(needle))
+                findings.push(`${label} is still referenced by ${file}`);
+        }
+    }
+    return findings;
+}
+async function runPark(projectRoot, identifier, options) {
+    const paths = getProjectPaths(projectRoot);
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest)
+        throw new GeneralError('No patches/patches.json; nothing to park against.');
+    const patch = resolvePatchIdentifier(identifier, manifest.patches);
+    if (!patch) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), 'park');
+    }
+    const files = await planPark(paths, patch, options.hunks);
+    if (files.length === 0) {
+        info(`${patch.filename}: nothing to park; its files match ${options.hunks ?? 'the baseline'}.`);
+        return;
+    }
+    for (const finding of await findOutsideReferrers(paths, manifest, patch, files)) {
+        warn(`Parking removes what is still in use: ${finding}. Move it somewhere you own first.`);
+    }
+    const label = options.label ?? `${patch.filename.replace(/\.patch$/, '')}-${Date.now().toString(36)}`;
+    for (const file of files)
+        info(`  ${file.path}`);
+    if (options.dryRun === true) {
+        info(`[dry-run] would park ${files.length} file(s) of ${patch.filename} as "${label}".`);
+        return;
+    }
+    const dir = await writePark(projectRoot, {
+        label,
+        patch: patch.filename,
+        createdAt: new Date().toISOString(),
+        mode: options.hunks === undefined ? 'baseline' : 'hunks',
+        files,
+    });
+    for (const file of files)
+        await writeEngineFile(paths.engine, file.path, file.after);
+    await appendHistoryBestEffort(paths.patches, {
+        operation: 'park',
+        args: { label, patch: patch.filename, files: files.map((file) => file.path) },
+        result: 'ok',
+    }, `park ${label}`);
+    success(`Parked ${files.length} file(s) of ${patch.filename} as "${label}" (${dir}).`);
+    info(`Restore with: fireforge park --restore ${label}`);
+}
+async function runRestore(projectRoot, label, dryRun) {
+    const paths = getProjectPaths(projectRoot);
+    const park = await readPark(projectRoot, label);
+    const conflicts = [];
+    const plans = [];
+    for (const file of park.files) {
+        const now = await readEngineFile(paths.engine, file.path);
+        const plan = await planRestore(file, now);
+        plans.push({ file, ...plan });
+        if (plan.outcome === 'conflict')
+            conflicts.push(file.path);
+    }
+    for (const { file, outcome } of plans)
+        info(`  ${file.path}: ${outcome}`);
+    if (dryRun) {
+        info(`[dry-run] restoring "${label}" would leave ${conflicts.length} conflict(s).`);
+        return;
+    }
+    for (const { file, content, outcome } of plans) {
+        if (outcome !== 'unchanged')
+            await writeEngineFile(paths.engine, file.path, content);
+    }
+    await appendHistoryBestEffort(paths.patches, {
+        operation: 'park-restore',
+        args: { label, patch: park.patch, conflicts },
+        result: conflicts.length === 0 ? 'ok' : 'conflict',
+    }, `park --restore ${label}`);
+    if (conflicts.length > 0) {
+        throw new GeneralError(`Restoring "${label}" left conflict markers in ${conflicts.join(', ')}. Resolve them, ` +
+            `then drop the park with "fireforge park --drop ${label}".`);
+    }
+    await dropPark(projectRoot, label);
+    success(`Restored "${label}" into ${park.files.length} file(s) of ${park.patch}.`);
+}
+/**
+ * Runs `fireforge park`.
+ *
+ * @param projectRoot - Project root
+ * @param identifier - The patch to park (omitted for --restore/--list/--drop)
+ * @param options - See {@link ParkOptions}
+ */
+export async function parkCommand(projectRoot, identifier, options) {
+    intro('FireForge park');
+    const modes = [identifier !== undefined, options.restore, options.list, options.drop].filter((mode) => mode !== undefined && mode !== false);
+    if (modes.length !== 1) {
+        throw new InvalidArgumentError('Pass exactly one of: a patch to park, --restore <label>, --list or --drop <label>.', 'park');
+    }
+    if (options.list === true) {
+        const parks = await listParks(projectRoot);
+        if (parks.length === 0)
+            info('No parks.');
+        for (const park of parks) {
+            info(`${park.label}  ${park.patch}  ${park.files.length} file(s)  ${park.createdAt}`);
+        }
+    }
+    else if (options.drop !== undefined) {
+        await dropPark(projectRoot, options.drop);
+        success(`Dropped park "${options.drop}".`);
+    }
+    else if (options.restore !== undefined) {
+        await runRestore(projectRoot, options.restore, options.dryRun === true);
+    }
+    else if (identifier !== undefined) {
+        await runPark(projectRoot, identifier, options);
+    }
+    outro('Park complete');
+}
+/** Registers `fireforge park`. */
+export function registerPark(program, { getProjectRoot, withErrorHandling }) {
+    const command = program
+        .command('park [patch]')
+        .description("Set a session's edits in a patch's files aside (back to the queue-applied baseline, or minus the hunks a diff names) and three-way merge them back later")
+        .option('--label <label>', 'Name for the park (default: <patch>-<time>)')
+        .option('--hunks <diff>', 'Park only the hunks this diff names, not every drifted line')
+        .option('--restore <label>', 'Three-way merge a park back into the engine, then drop it')
+        .option('--list', 'List the parks')
+        .option('--drop <label>', 'Delete a park without restoring it')
+        .option('--dry-run', 'Show what would be parked or restored');
+    addWaitLockOption(command).action(withErrorHandling(async (patch, options) => {
+        const projectRoot = getProjectRoot();
+        if (options.list === true || options.drop !== undefined || options.dryRun === true) {
+            await parkCommand(projectRoot, patch, options);
+            return;
+        }
+        await withEngineSessionLock(projectRoot, 'park', () => parkCommand(projectRoot, patch, options), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+    }));
+}

package/dist/src/commands/patch/delete.js

@@ -20,6 +20,7 @@ import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../ut
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { describeProjectedGaps } from './delete-gap-notice.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
+import { deleteCreatedFiles, planClaimedFiles, withCreatedFileLock, } from './removal-created-files.js';
 import { collectRemovalDependents, queueSnapshot, removalConflict, warnDanglingStagedOwners, } from './removal-dependents.js';
 /**
  * Runs the `patch delete` command: removes a patch file and its manifest
@@ -55,14 +56,12 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
         warn(line);
     }
     const conflicts = removalConflict(dependents, target);
+    const claimed = await planClaimedFiles(baseCtx, target, paths.engine, options.deleteCreated === true);
     const summary = [
         `delete ${target.filename}  (category: ${target.category}, order: ${target.order})`,
         `description: ${target.description || '(none)'}`,
-        `files currently claimed by this patch (${target.filesAffected.length}):`,
+        ...claimed.summary,
     ];
-    for (const file of target.filesAffected) {
-        summary.push(`  ${file}  → will become unmanaged`);
-    }
     summary.push(...gapNotices);
     const decision = await confirmDestructive({
         operation: 'patch-delete',
@@ -83,7 +82,8 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     // mutation with no audit trail. A history append failure is warned but not
     // re-thrown: by that point the mutation has committed, and reporting
     // failure to the caller would mislead.
-    await withPatchDirectoryLock(paths.patches, async () => {
+    const waitLockSeconds = resolveWaitLockSeconds(options.waitLock);
+    await withCreatedFileLock(projectRoot, 'patch delete', claimed, waitLockSeconds, () => withPatchDirectoryLock(paths.patches, async () => {
         const current = await buildPatchQueueContext(paths.patches);
         // A changed body or manifest invalidates the dependency scan approved
         // before the prompt. Recheck all of its inputs while holding the lock.
@@ -91,18 +91,22 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
             throw new GeneralError('Patch queue changed while waiting for confirmation or the lock. Re-run patch delete to review the current dependencies.');
         }
         await removePatchFileAndManifest(paths.patches, target.filename);
+        await deleteCreatedFiles(paths.engine, claimed.deleteOnCommit);
         await appendHistoryBestEffort(paths.patches, {
             operation: 'patch-delete',
             args: {
                 filename: target.filename,
                 order: target.order,
                 filesAffected: target.filesAffected,
+                ...(claimed.deleteOnCommit.length > 0
+                    ? { deletedCreatedFiles: claimed.deleteOnCommit }
+                    : {}),
             },
             ...(options.yes === true ? { yes: true } : {}),
             ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
             result: 'ok',
         }, `patch delete committed (${target.filename})`);
-    }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'patch delete' });
+    }, { waitLockSeconds, command: 'patch delete' }));
     info(`Deleted ${target.filename}.`);
     outro('Delete complete');
 }
@@ -119,6 +123,7 @@ export function registerPatchDelete(parent, context) {
         .description('Delete a patch from the queue (destructive)')
         .option('--dry-run', 'Show what would happen without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .option('--delete-created', 'Also delete the engine files this patch creates that are still on disk, instead of leaving them unmanaged')
         .option('--force-unsafe', 'Bypass the refusal when a later patch depends on this patch (last resort)');
     addWaitLockOption(command).action(withErrorHandling(async (name, options) => {
         await patchDeleteCommand(getProjectRoot(), name, pickDefined(options));

package/dist/src/commands/patch/index.d.ts

@@ -1,9 +1,9 @@
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch mutations and
  * planners (`compact`, `delete`, `lint-ignore`, `move-files`, `rename`,
- * `reorder`, `retire`, `staged-dependency`, `tier`) so they do not clutter the
- * top-level command list. Queue-level verbs like `lint`, `export`, `verify`,
- * and `status` stay flat.
+ * `reorder`, `reserve`, `retire`, `split`, `stage`, `staged-dependency`,
+ * `tier`) so they do not clutter the top-level command list. Queue-level
+ * verbs like `lint`, `export`, `verify`, and `status` stay flat.
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';

package/dist/src/commands/patch/index.js

@@ -2,9 +2,9 @@
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch mutations and
  * planners (`compact`, `delete`, `lint-ignore`, `move-files`, `rename`,
- * `reorder`, `retire`, `staged-dependency`, `tier`) so they do not clutter the
- * top-level command list. Queue-level verbs like `lint`, `export`, `verify`,
- * and `status` stay flat.
+ * `reorder`, `reserve`, `retire`, `split`, `stage`, `staged-dependency`,
+ * `tier`) so they do not clutter the top-level command list. Queue-level
+ * verbs like `lint`, `export`, `verify`, and `status` stay flat.
  */
 import { Command } from 'commander';
 import { registerPatchCompact } from './compact.js';
@@ -13,8 +13,10 @@ import { registerPatchLintIgnore } from './lint-ignore.js';
 import { registerPatchMoveFiles } from './move-files.js';
 import { registerPatchRename } from './rename.js';
 import { registerPatchReorder } from './reorder.js';
+import { registerPatchReserve } from './reserve.js';
 import { registerPatchRetire } from './retire.js';
 import { registerPatchSplit } from './split.js';
+import { registerPatchStage } from './stage.js';
 import { registerPatchStagedDependency } from './staged-dependency.js';
 import { registerPatchTier } from './tier.js';
 /**
@@ -26,7 +28,7 @@ import { registerPatchTier } from './tier.js';
 export function registerPatch(program, context) {
     const patch = program
         .command('patch')
-        .description('Manage individual patches in the queue (compact, delete, lint-ignore, move-files, rename, reorder, retire, staged-dependency, tier)')
+        .description('Manage individual patches in the queue (compact, delete, lint-ignore, move-files, rename, reorder, reserve, retire, split, stage, staged-dependency, tier)')
         // Match `fireforge furnace`'s no-args contract: print the group's help
         // and exit 0. Without this default action, commander routes
         // `fireforge patch` (no subcommand) through its own help-then-exit-1
@@ -41,8 +43,10 @@ export function registerPatch(program, context) {
     registerPatchMoveFiles(patch, context);
     registerPatchRename(patch, context);
     registerPatchReorder(patch, context);
+    registerPatchReserve(patch, context);
     registerPatchRetire(patch, context);
     registerPatchSplit(patch, context);
+    registerPatchStage(patch, context);
     registerPatchStagedDependency(patch, context);
     registerPatchTier(patch, context);
 }

package/dist/src/commands/patch/lint-ignore-from.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Batch and per-entry input for `patch lint-ignore --add`. Split out of
+ * `lint-ignore.ts` for the per-file line budget.
+ *
+ * A rebaseline that sets a ceiling per rule used to take one call per rule,
+ * each taking the patch lock and rewriting `patches.json` (138 calls on one
+ * consumer's queue), because `--max` applied to every `--add` of a call.
+ * Two forms lift that:
+ *
+ * - `--add <rule>=<max>` gives each entry its own ceiling in one call.
+ * - `--from <json-file>` reads every entry from a file, under one lock hold
+ *   and one write. The file is a JSON array of entries (a check ID string,
+ *   or `{ rule, max, reason?, share?, meta?, patch? }`), or a
+ *   `lint --per-patch --report` document, whose `lintIgnoreCeilings` rows
+ *   for the target patch are rebaselined to their current measurement.
+ */
+import type { LintIgnoreEntry, PatchLintIgnoreOptions, PatchSizeShare } from '../../types/commands/index.js';
+/**
+ * Turns `--add` values into entries: `<rule>=<max>` is a ceiling at `max`,
+ * a bare ID is a ceiling at `--max` when that is given and a bare waiver
+ * otherwise. Every ceiling takes `--reason` (required) and `--share`.
+ *
+ * @param ids - The `--add` values
+ * @param options - Command options (`max`, `reason`, `share`)
+ * @returns The entries to upsert
+ */
+export declare function resolveAddEntries(ids: readonly string[], options: Pick<PatchLintIgnoreOptions, 'max' | 'reason' | 'share'>): LintIgnoreEntry[];
+/** Entries read from a `--from` file for one target patch. */
+export interface LintIgnoreBatch {
+    entries: LintIgnoreEntry[];
+    /** Entries naming a different patch, left out. */
+    skippedForOtherPatches: number;
+}
+/**
+ * Reads a `--from` file into entries for `targetFilename`.
+ *
+ * @param path - JSON file path
+ * @param targetFilename - The patch the command edits
+ * @param defaultReason - `--reason`, used for object entries without one
+ * @returns The validated entries and the count left out for other patches
+ */
+export declare function readLintIgnoreBatch(path: string, targetFilename: string, defaultReason: string | undefined): Promise<LintIgnoreBatch>;
+/** Parses `--share`. */
+export declare function parseShare(value: string): PatchSizeShare;

package/dist/src/commands/patch/lint-ignore-from.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Batch and per-entry input for `patch lint-ignore --add`. Split out of
+ * `lint-ignore.ts` for the per-file line budget.
+ *
+ * A rebaseline that sets a ceiling per rule used to take one call per rule,
+ * each taking the patch lock and rewriting `patches.json` (138 calls on one
+ * consumer's queue), because `--max` applied to every `--add` of a call.
+ * Two forms lift that:
+ *
+ * - `--add <rule>=<max>` gives each entry its own ceiling in one call.
+ * - `--from <json-file>` reads every entry from a file, under one lock hold
+ *   and one write. The file is a JSON array of entries (a check ID string,
+ *   or `{ rule, max, reason?, share?, meta?, patch? }`), or a
+ *   `lint --per-patch --report` document, whose `lintIgnoreCeilings` rows
+ *   for the target patch are rebaselined to their current measurement.
+ */
+import { LINT_IGNORE_CEILING_RULES, parseLintIgnoreEntries } from '../../core/patch-lint-ignore.js';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { readJson } from '../../utils/fs.js';
+import { isArray, isObject } from '../../utils/validation.js';
+const RULE_MAX_PATTERN = /^(?<rule>[^=\s]+)=(?<max>[1-9]\d*)$/;
+/**
+ * Turns `--add` values into entries: `<rule>=<max>` is a ceiling at `max`,
+ * a bare ID is a ceiling at `--max` when that is given and a bare waiver
+ * otherwise. Every ceiling takes `--reason` (required) and `--share`.
+ *
+ * @param ids - The `--add` values
+ * @param options - Command options (`max`, `reason`, `share`)
+ * @returns The entries to upsert
+ */
+export function resolveAddEntries(ids, options) {
+    const parsed = ids.map((id) => {
+        if (id.includes('=')) {
+            const match = RULE_MAX_PATTERN.exec(id);
+            if (match?.groups === undefined) {
+                throw new InvalidArgumentError(`--add ${id}: expected <rule>=<max> with a positive integer max.`, '--add');
+            }
+            return { rule: match.groups['rule'], max: Number(match.groups['max']) };
+        }
+        return { rule: id, max: options.max };
+    });
+    const ceilings = parsed.filter((entry) => entry.max !== undefined);
+    if (ceilings.length === 0) {
+        if (options.reason !== undefined || options.share !== undefined) {
+            throw new InvalidArgumentError('--reason and --share apply to ceilings: pass --max <n> or --add <rule>=<max>.', options.reason !== undefined ? '--reason' : '--share');
+        }
+        return parsed.map((entry) => entry.rule);
+    }
+    if (options.reason === undefined || options.reason.trim() === '') {
+        throw new InvalidArgumentError('A lintIgnore ceiling needs --reason <text> (with --max <n> or --add <rule>=<max>).', '--reason');
+    }
+    const unmeasured = ceilings.filter((entry) => !LINT_IGNORE_CEILING_RULES.includes(entry.rule));
+    if (unmeasured.length > 0) {
+        throw new InvalidArgumentError(`A ceiling only applies to the measured size rules (${LINT_IGNORE_CEILING_RULES.join(', ')}); ` +
+            `got ${unmeasured.map((entry) => entry.rule).join(', ')}.`, '--max');
+    }
+    const { reason, share } = options;
+    return validated(parsed.map((entry) => entry.max === undefined
+        ? entry.rule
+        : { rule: entry.rule, max: entry.max, reason, ...(share !== undefined ? { share } : {}) }), '--add');
+}
+/** Runs the manifest validator over CLI-built entries, as an argument error. */
+function validated(entries, flag) {
+    try {
+        return parseLintIgnoreEntries(entries, flag);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(toError(error).message, flag);
+    }
+}
+/** The target patch's ceiling rows of a lint report, rebaselined to their measurement. */
+function rebaselineFromReport(data, targetFilename) {
+    const patches = isArray(data['patches']) ? data['patches'] : [];
+    const row = patches.find((patch) => isObject(patch) && patch['filename'] === targetFilename);
+    const ceilings = isObject(row) && isArray(row['lintIgnoreCeilings']) ? row['lintIgnoreCeilings'] : [];
+    const raw = [];
+    for (const ceiling of ceilings) {
+        if (!isObject(ceiling) || typeof ceiling['measurement'] !== 'number')
+            continue;
+        if (ceiling['measurement'] <= 0)
+            continue;
+        const { measurement, rule, reason, share, meta } = ceiling;
+        raw.push({
+            rule,
+            max: measurement,
+            reason,
+            ...(share !== undefined ? { share } : {}),
+            ...(meta !== undefined ? { meta } : {}),
+        });
+    }
+    return { raw, skipped: patches.length - (row === undefined ? 0 : 1) };
+}
+/**
+ * Reads a `--from` file into entries for `targetFilename`.
+ *
+ * @param path - JSON file path
+ * @param targetFilename - The patch the command edits
+ * @param defaultReason - `--reason`, used for object entries without one
+ * @returns The validated entries and the count left out for other patches
+ */
+export async function readLintIgnoreBatch(path, targetFilename, defaultReason) {
+    let data;
+    try {
+        data = await readJson(path);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(`Cannot read --from ${path}: ${toError(error).message}`, '--from');
+    }
+    if (isObject(data)) {
+        const { raw, skipped } = rebaselineFromReport(data, targetFilename);
+        return { entries: validated(raw, '--from'), skippedForOtherPatches: skipped };
+    }
+    if (!isArray(data)) {
+        throw new InvalidArgumentError('--from must hold a JSON array of lintIgnore entries or a "lint --per-patch --report" document.', '--from');
+    }
+    const raw = [];
+    let skipped = 0;
+    for (const entry of data) {
+        if (!isObject(entry)) {
+            raw.push(entry);
+            continue;
+        }
+        const { patch, ...rest } = entry;
+        if (patch !== undefined && patch !== targetFilename) {
+            skipped++;
+            continue;
+        }
+        raw.push(rest['reason'] === undefined && defaultReason !== undefined
+            ? { ...rest, reason: defaultReason }
+            : rest);
+    }
+    return { entries: validated(raw, '--from'), skippedForOtherPatches: skipped };
+}
+/** Parses `--share`. */
+export function parseShare(value) {
+    if (value !== 'test' && value !== 'product') {
+        throw new InvalidArgumentError(`--share must be "test" or "product" (got "${value}").`, '--share');
+    }
+    return value;
+}