@hominis/fireforge 0.18.9 → 0.18.10

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

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+import type { PatchLintIssue } from '../types/commands/index.js';
 /** Options controlling how the lint command filters and tags its output. */
 export interface LintCommandOptions {
     /**
@@ -46,6 +47,41 @@ export interface LintCommandOptions {
      */
     perPatch?: boolean;
 }
+/**
+ * Result of {@link applyAggregateLintIgnoreSuppression}.
+ */
+export interface AggregateLintIgnoreResult {
+    /** Issues remaining after suppression. */
+    issues: PatchLintIssue[];
+    /** Number of issues dropped because an owning patch listed the check in `lintIgnore`. */
+    dropped: number;
+}
+/**
+ * Filters aggregate-mode lint issues against per-patch `lintIgnore`
+ * lists drawn from the manifest. An issue is dropped when at least one
+ * patch whose `filesAffected` covers `issue.file` lists `issue.check`
+ * in its `lintIgnore`.
+ *
+ * Mirrors the per-patch contract: `--per-patch` mode threads each
+ * patch's `lintIgnore` directly into `lintExportedPatch`, so a check
+ * the operator explicitly waived in `patches.json` does not surface.
+ * Aggregate `--since` mode previously rediscovered the suppressed
+ * warning every CI run because the diff was treated as a single unit
+ * with no patch-level scope. Attributing each issue's file to its
+ * owning patch via `filesAffected` re-establishes the same suppression
+ * semantics. Cross-patch findings (forward-import, duplicate-creation)
+ * still attribute via `issue.file` because the `file` field is the
+ * offending site, which is owned by some patch.
+ *
+ * Multiple owners: an issue is dropped if **any** owning patch waived
+ * the rule. Conservative — never adds new findings, only drops
+ * already-explicitly-waived ones.
+ *
+ * @param issues - Issues collected from the aggregate lint run.
+ * @param ctx - Patch queue context used to attribute file → patch.
+ * @returns Filtered issue list and the count of dropped findings.
+ */
+export declare function applyAggregateLintIgnoreSuppression(issues: PatchLintIssue[], ctx: import('../core/patch-lint.js').PatchQueueContext): AggregateLintIgnoreResult;
 /**
  * Runs the lint command to check engine changes against patch quality rules.
  * @param projectRoot - Root directory of the project

package/dist/src/commands/lint.js

@@ -160,6 +160,53 @@ async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
     }
     return diff;
 }
+/**
+ * Filters aggregate-mode lint issues against per-patch `lintIgnore`
+ * lists drawn from the manifest. An issue is dropped when at least one
+ * patch whose `filesAffected` covers `issue.file` lists `issue.check`
+ * in its `lintIgnore`.
+ *
+ * Mirrors the per-patch contract: `--per-patch` mode threads each
+ * patch's `lintIgnore` directly into `lintExportedPatch`, so a check
+ * the operator explicitly waived in `patches.json` does not surface.
+ * Aggregate `--since` mode previously rediscovered the suppressed
+ * warning every CI run because the diff was treated as a single unit
+ * with no patch-level scope. Attributing each issue's file to its
+ * owning patch via `filesAffected` re-establishes the same suppression
+ * semantics. Cross-patch findings (forward-import, duplicate-creation)
+ * still attribute via `issue.file` because the `file` field is the
+ * offending site, which is owned by some patch.
+ *
+ * Multiple owners: an issue is dropped if **any** owning patch waived
+ * the rule. Conservative — never adds new findings, only drops
+ * already-explicitly-waived ones.
+ *
+ * @param issues - Issues collected from the aggregate lint run.
+ * @param ctx - Patch queue context used to attribute file → patch.
+ * @returns Filtered issue list and the count of dropped findings.
+ */
+export function applyAggregateLintIgnoreSuppression(issues, ctx) {
+    const suppressionsByFile = new Map();
+    for (const entry of ctx.entries) {
+        const ignoreList = entry.metadata?.lintIgnore;
+        if (!ignoreList || ignoreList.length === 0)
+            continue;
+        for (const f of entry.metadata?.filesAffected ?? []) {
+            let bucket = suppressionsByFile.get(f);
+            if (!bucket) {
+                bucket = new Set();
+                suppressionsByFile.set(f, bucket);
+            }
+            for (const id of ignoreList)
+                bucket.add(id);
+        }
+    }
+    if (suppressionsByFile.size === 0) {
+        return { issues, dropped: 0 };
+    }
+    const filtered = issues.filter((issue) => !suppressionsByFile.get(issue.file)?.has(issue.check));
+    return { issues: filtered, dropped: issues.length - filtered.length };
+}
 /**
  * Runs the lint command to check engine changes against patch quality rules.
  * @param projectRoot - Root directory of the project
@@ -217,7 +264,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
     if (await pathExists(paths.patches)) {
         ctx = await buildPatchQueueContext(paths.patches);
     }
-    const issues = [
+    let issues = [
         ...(await lintExportedPatch(paths.engine, filesAffected, diff, config, ctx)),
     ];
     // Cross-patch rules operate over the whole queue, so run them whenever a
@@ -226,6 +273,19 @@ export async function lintCommand(projectRoot, files, options = {}) {
     if (ctx) {
         issues.push(...lintPatchQueue(ctx));
     }
+    // Honor per-patch `lintIgnore` in aggregate mode by attributing each
+    // issue's file to its owning patches via the manifest's
+    // `filesAffected`. Per-patch mode threads `lintIgnore` directly into
+    // `lintExportedPatch`; aggregate mode previously had no patch-level
+    // scope to consult, so a check an operator had explicitly waived in
+    // `patches.json` re-surfaced on every `--since` run (CI default).
+    if (ctx) {
+        const result = applyAggregateLintIgnoreSuppression(issues, ctx);
+        issues = result.issues;
+        if (result.dropped > 0) {
+            info(`Suppressed ${result.dropped} issue(s) via per-patch lintIgnore (aggregate mode).`);
+        }
+    }
     // When a queue manifest exists AND files were NOT scoped explicitly, the
     // "diff" we just linted is every applied patch summed together. Patch-
     // size rules (`large-patch-lines`, `large-patch-files`) then fire against

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

@@ -1,14 +1,16 @@
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations (`compact`, `delete`, `lint-ignore`, `reorder`, `tier`) so
- * they do not clutter the top-level command list. Queue-level verbs
- * like `lint`, `export`, `verify`, and `status` stay flat.
+ * mutations (`compact`, `delete`, `lint-ignore`, `rename`, `reorder`,
+ * `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';
 export { patchCompactCommand } from './compact.js';
 export { patchDeleteCommand } from './delete.js';
 export { patchLintIgnoreCommand } from './lint-ignore.js';
+export { patchRenameCommand } from './rename.js';
 export { patchReorderCommand } from './reorder.js';
 export { patchTierCommand } from './tier.js';
 /**

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

@@ -1,18 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations (`compact`, `delete`, `lint-ignore`, `reorder`, `tier`) so
- * they do not clutter the top-level command list. Queue-level verbs
- * like `lint`, `export`, `verify`, and `status` stay flat.
+ * mutations (`compact`, `delete`, `lint-ignore`, `rename`, `reorder`,
+ * `tier`) so they do not clutter the top-level command list.
+ * Queue-level verbs like `lint`, `export`, `verify`, and `status` stay
+ * flat.
  */
 import { registerPatchCompact } from './compact.js';
 import { registerPatchDelete } from './delete.js';
 import { registerPatchLintIgnore } from './lint-ignore.js';
+import { registerPatchRename } from './rename.js';
 import { registerPatchReorder } from './reorder.js';
 import { registerPatchTier } from './tier.js';
 export { patchCompactCommand } from './compact.js';
 export { patchDeleteCommand } from './delete.js';
 export { patchLintIgnoreCommand } from './lint-ignore.js';
+export { patchRenameCommand } from './rename.js';
 export { patchReorderCommand } from './reorder.js';
 export { patchTierCommand } from './tier.js';
 /**
@@ -24,7 +27,7 @@ export { patchTierCommand } from './tier.js';
 export function registerPatch(program, context) {
     const patch = program
         .command('patch')
-        .description('Manage individual patches in the queue (compact, delete, lint-ignore, reorder, tier)')
+        .description('Manage individual patches in the queue (compact, delete, lint-ignore, rename, reorder, 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 path, so scripts that
@@ -37,6 +40,7 @@ export function registerPatch(program, context) {
     registerPatchCompact(patch, context);
     registerPatchDelete(patch, context);
     registerPatchLintIgnore(patch, context);
+    registerPatchRename(patch, context);
     registerPatchReorder(patch, context);
     registerPatchTier(patch, context);
 }

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

@@ -21,6 +21,13 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
 import type { PatchLintIgnoreOptions } from '../../types/commands/index.js';
+type LintIgnoreMode = 'add' | 'remove' | 'clear';
+/**
+ * Renders a one-line summary of the planned change for use in
+ * `info()` / dry-run / history args. Exported for unit-testing the
+ * message format directly without mocking the logger transport.
+ */
+export declare function describeChange(before: ReadonlyArray<string>, after: ReadonlyArray<string>, mode: LintIgnoreMode, values: ReadonlyArray<string>): string;
 /**
  * Runs the `patch lint-ignore` command: reads the patch's existing
  * `lintIgnore`, applies the requested mode, and writes the manifest.
@@ -37,3 +44,4 @@ export declare function patchLintIgnoreCommand(projectRoot: string, identifier:
  * @param context - Shared CLI registration context
  */
 export declare function registerPatchLintIgnore(parent: Command, context: CommandContext): void;
+export {};

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

@@ -53,9 +53,10 @@ function applyMode(existing, mode, values) {
 }
 /**
  * Renders a one-line summary of the planned change for use in
- * `info()` / dry-run / history args.
+ * `info()` / dry-run / history args. Exported for unit-testing the
+ * message format directly without mocking the logger transport.
  */
-function describeChange(before, after, mode, values) {
+export function describeChange(before, after, mode, values) {
     const beforeSet = new Set(before);
     const afterSet = new Set(after);
     if (mode === 'clear') {
@@ -63,17 +64,20 @@ function describeChange(before, after, mode, values) {
             ? 'lintIgnore was already empty — no change'
             : `lintIgnore cleared (was ${before.join(', ')})`;
     }
+    const currentLabel = before.length > 0 ? `[${before.join(', ')}]` : '(empty)';
     if (mode === 'add') {
         const added = values.filter((v) => !beforeSet.has(v));
         if (added.length === 0) {
-            return 'lintIgnore unchanged (all requested IDs were already present)';
+            // Surface the existing list so a no-op `--add` does not require a
+            // follow-up `patches.json` read to confirm what was already present.
+            return `lintIgnore unchanged (current: ${currentLabel}; all requested IDs already present)`;
         }
         return `lintIgnore += ${added.join(', ')} → ${[...afterSet].join(', ') || '(empty)'}`;
     }
     // mode === 'remove'
     const removed = values.filter((v) => beforeSet.has(v));
     if (removed.length === 0) {
-        return 'lintIgnore unchanged (none of the requested IDs were present)';
+        return `lintIgnore unchanged (current: ${currentLabel}; none of the requested IDs were present)`;
     }
     return `lintIgnore −= ${removed.join(', ')} → ${[...afterSet].join(', ') || '(empty)'}`;
 }

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

@@ -0,0 +1,36 @@
+/**
+ * `fireforge patch rename <name>` — relabels a patch's filename, manifest
+ * `name`, and (optionally) `description` without rewriting the `.patch`
+ * file body.
+ *
+ * Companion to `re-export --files <subset>`. Re-export shrinks the body
+ * + `filesAffected`, but leaves the patch's identity describing the
+ * pre-shrink scope. Before this verb existed, the only workaround for
+ * that drift was `delete` + re-export, which briefly removed the patch
+ * from the queue (any forward-import dependent would refuse the
+ * re-export until the deleted patch's siblings were rewritten).
+ *
+ * The filename rename and the manifest mutation happen under the patch
+ * directory lock so concurrent exports cannot allocate the new
+ * filename, and a filesystem rename failure rolls back before the
+ * manifest is touched.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchRenameOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch rename` command: relabels filename + manifest entry
+ * for a single patch atomically.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options (`--to <new-name>` is required)
+ */
+export declare function patchRenameCommand(projectRoot: string, identifier: string, options?: PatchRenameOptions): Promise<void>;
+/**
+ * Registers the `patch rename` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchRename(parent: Command, context: CommandContext): void;

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

@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch rename <name>` — relabels a patch's filename, manifest
+ * `name`, and (optionally) `description` without rewriting the `.patch`
+ * file body.
+ *
+ * Companion to `re-export --files <subset>`. Re-export shrinks the body
+ * + `filesAffected`, but leaves the patch's identity describing the
+ * pre-shrink scope. Before this verb existed, the only workaround for
+ * that drift was `delete` + re-export, which briefly removed the patch
+ * from the queue (any forward-import dependent would refuse the
+ * re-export until the deleted patch's siblings were rewritten).
+ *
+ * The filename rename and the manifest mutation happen under the patch
+ * directory lock so concurrent exports cannot allocate the new
+ * filename, and a filesystem rename failure rolls back before the
+ * manifest is touched.
+ */
+import { rename as fsRename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getProjectPaths } from '../../core/config.js';
+import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { sanitizeName } from '../../core/patch-export.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifest, resolvePatchIdentifier, savePatchesManifest, } from '../../core/patch-manifest.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, outro, warn } from '../../utils/logger.js';
+import { pickDefined } from '../../utils/options.js';
+/**
+ * Pulls the ordinal-string + category prefix out of a patch filename so
+ * the rename keeps the existing ordinal padding verbatim. Returning the
+ * literal substring (rather than recomputing from the parsed integer)
+ * avoids any chance of the new filename's ordinal differing from the
+ * old by a leading-zero count.
+ */
+function splitPatchFilename(filename) {
+    const m = /^(\d+)-([a-z]+)-(.+)\.patch$/.exec(filename);
+    if (!m?.[1] || !m[2] || !m[3])
+        return null;
+    return { ordinalStr: m[1], category: m[2], slug: m[3] };
+}
+/**
+ * Performs the rename's transactional core under the patch directory
+ * lock: re-reads the manifest, re-checks for filename collisions,
+ * renames the `.patch` file on disk (when applicable), writes the
+ * updated manifest, and appends a history entry. Filesystem rename
+ * happens before the manifest save so an interrupted run never leaves
+ * the manifest pointing at a missing file; a manifest-save failure
+ * rolls the filesystem rename back.
+ */
+async function commitRenameUnderLock(input) {
+    const { patchesDir, target, newFilename, newName, newDescription, filenameChanging, nameChanging, descriptionChanging, } = input;
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const fresh = await loadPatchesManifest(patchesDir);
+        if (!fresh) {
+            throw new GeneralError('Manifest disappeared between resolution and rename.');
+        }
+        const idx = fresh.patches.findIndex((p) => p.filename === target.filename);
+        if (idx === -1) {
+            throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during rename. Re-run after investigating.`);
+        }
+        const before = fresh.patches[idx];
+        if (!before) {
+            throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during rename.`);
+        }
+        if (filenameChanging) {
+            const collisionInLock = fresh.patches.find((p) => p.filename === newFilename && p.filename !== target.filename);
+            if (collisionInLock) {
+                throw new InvalidArgumentError(`Cannot rename to "${newFilename}" — a different patch claimed that filename concurrently.`, 'patch rename');
+            }
+            const oldPath = join(patchesDir, target.filename);
+            const newPath = join(patchesDir, newFilename);
+            if (await pathExists(newPath)) {
+                throw new InvalidArgumentError(`Cannot rename: ${newFilename} already exists on disk. Resolve manually before retrying.`, 'patch rename');
+            }
+            await fsRename(oldPath, newPath);
+            fresh.patches[idx] = {
+                ...before,
+                filename: newFilename,
+                name: newName,
+                ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
+            };
+            try {
+                await savePatchesManifest(patchesDir, fresh);
+            }
+            catch (saveError) {
+                try {
+                    await fsRename(newPath, oldPath);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not restore ${target.filename} after manifest write failure: ${toError(rollbackError).message}`);
+                }
+                throw saveError;
+            }
+        }
+        else {
+            fresh.patches[idx] = {
+                ...before,
+                ...(nameChanging ? { name: newName } : {}),
+                ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
+            };
+            await savePatchesManifest(patchesDir, fresh);
+        }
+        try {
+            await appendHistory(patchesDir, {
+                operation: 'patch-rename',
+                args: {
+                    oldFilename: target.filename,
+                    newFilename,
+                    oldName: target.name,
+                    newName,
+                    ...(descriptionChanging ? { oldDescription: target.description, newDescription } : {}),
+                },
+                ...(input.yes === true ? { yes: true } : {}),
+                result: 'ok',
+            });
+        }
+        catch (historyError) {
+            warn(`History log append failed after patch rename committed (${newFilename}): ${toError(historyError).message}`);
+        }
+    });
+}
+/**
+ * Runs the `patch rename` command: relabels filename + manifest entry
+ * for a single patch atomically.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options (`--to <new-name>` is required)
+ */
+export async function patchRenameCommand(projectRoot, identifier, options = {}) {
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge patch rename (dry run)' : 'FireForge patch rename');
+    if (options.to === undefined || options.to.trim() === '') {
+        throw new InvalidArgumentError('Specify --to <new-name>. The new name is sanitised into the filename slug the same way `export --name` is.', 'patch rename');
+    }
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        throw new GeneralError('Patches directory not found.');
+    }
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const target = resolvePatchIdentifier(identifier, manifest.patches);
+    if (!target) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
+    }
+    const split = splitPatchFilename(target.filename);
+    if (!split) {
+        throw new GeneralError(`Cannot rename ${target.filename}: filename does not match the expected {ordinal}-{category}-{slug}.patch convention. Re-export the patch instead.`);
+    }
+    const newSlug = sanitizeName(options.to);
+    if (newSlug === '') {
+        throw new InvalidArgumentError('--to must contain at least one alphanumeric character after sanitisation.', 'patch rename');
+    }
+    const newFilename = `${split.ordinalStr}-${split.category}-${newSlug}.patch`;
+    const filenameChanging = newFilename !== target.filename;
+    const nameChanging = options.to !== target.name;
+    const descriptionChanging = options.description !== undefined && options.description !== target.description;
+    if (!filenameChanging && !nameChanging && !descriptionChanging) {
+        info(`${target.filename}: name and description already match — nothing to change.`);
+        outro(isDryRun ? 'Dry run complete — no changes made' : 'Patch rename (no-op)');
+        return;
+    }
+    // Pre-flight collision check against the manifest snapshot we already
+    // loaded. The authoritative check happens again inside the lock to
+    // close the TOCTOU window — surface a helpful error here when the
+    // collision is obvious so the operator does not get surprised by a
+    // late refusal after a confirmation prompt.
+    if (filenameChanging) {
+        const collision = manifest.patches.find((p) => p.filename === newFilename && p.filename !== target.filename);
+        if (collision) {
+            throw new InvalidArgumentError(`Cannot rename to "${newFilename}" — a different patch already uses that filename.`, 'patch rename');
+        }
+    }
+    const summary = [];
+    if (filenameChanging) {
+        summary.push(`rename ${target.filename} → ${newFilename}`);
+    }
+    if (nameChanging) {
+        summary.push(`name: "${target.name}" → "${options.to}"`);
+    }
+    if (descriptionChanging) {
+        summary.push(`description: "${target.description || '(none)'}" → "${options.description ?? '(none)'}"`);
+    }
+    const decision = await confirmDestructive({
+        operation: 'patch-rename',
+        title: `Rename ${target.filename}`,
+        summary,
+        yes: options.yes === true,
+        dryRun: isDryRun,
+        conflicts: null,
+    });
+    if (decision === 'dry-run') {
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    if (decision === 'cancelled') {
+        outro('Rename cancelled');
+        return;
+    }
+    await commitRenameUnderLock({
+        patchesDir: paths.patches,
+        target,
+        newFilename,
+        newName: options.to,
+        ...(options.description !== undefined ? { newDescription: options.description } : {}),
+        filenameChanging,
+        nameChanging,
+        descriptionChanging,
+        ...(options.yes === true ? { yes: true } : {}),
+    });
+    if (filenameChanging) {
+        info(`${target.filename} → ${newFilename}`);
+    }
+    else {
+        info(`${target.filename}: metadata updated.`);
+    }
+    outro('Patch rename complete');
+}
+/**
+ * Registers the `patch rename` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchRename(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('rename <name>')
+        .description('Rename a patch: filename + manifest name (and optional description) update without rewriting the .patch body.')
+        .requiredOption('--to <new-name>', 'New human-readable name (sanitised into the filename slug)')
+        .option('--description <text>', 'Replacement description (omit to leave description unchanged)')
+        .option('--dry-run', 'Show what would change without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .action(withErrorHandling(async (name, options) => {
+        await patchRenameCommand(getProjectRoot(), name, pickDefined(options));
+    }));
+}
+//# sourceMappingURL=rename.js.map

package/dist/src/core/license-headers.d.ts

@@ -29,6 +29,11 @@ export declare function getLicenseHeader(license: ProjectLicense, style: Comment
  * standard MPL header — operators were forced to `--skip-lint` over a real
  * false positive.
  *
+ * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
+ * leading the file are tolerated — Mozilla's canonical layout puts those
+ * on lines 1–2 with the MPL header on lines 3+, which the raw
+ * `startsWith` check would otherwise miss.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */

package/dist/src/core/license-headers.js

@@ -53,6 +53,39 @@ export function getLicenseHeader(license, style) {
             return lines.map((l) => `# ${l}`).join('\n');
     }
 }
+/**
+ * Single-line `/* ... *\/` block comments containing either an Emacs
+ * file-mode marker (`-*-`) or a vim modeline (`vim:`) — Mozilla's
+ * canonical first-line editor directives that legitimately precede the
+ * license header in many Firefox source files.
+ *
+ * Restricted to single-line blocks so a multi-line license header never
+ * gets accidentally consumed.
+ */
+const EDITOR_DIRECTIVE_BLOCK_COMMENT = /^[ \t]*\/\*[^\r\n]*?(?:-\*-|\bvim:)[^\r\n]*?\*\/[ \t]*\r?\n?/;
+/**
+ * Strips any leading run of editor-directive block comments and blank
+ * lines, returning the remaining content.
+ *
+ * Mozilla's coding convention places editor directives like
+ * `/* -*- Mode: javascript; ... -*- *\/` and `/* vim: set ... *\/` on
+ * lines 1–2, with the canonical license header following on lines 3+.
+ * The raw `content.startsWith(...)` check used by {@link hasAnyLicenseHeader}
+ * never matches in that shape; this helper lets the caller test the
+ * post-directive prefix as a fallback.
+ *
+ * @param content - File content to strip
+ */
+function stripLeadingEditorDirectives(content) {
+    let result = content;
+    let prev;
+    do {
+        prev = result;
+        result = result.replace(/^[ \t]*\r?\n/, '');
+        result = result.replace(EDITOR_DIRECTIVE_BLOCK_COMMENT, '');
+    } while (result !== prev);
+    return result;
+}
 /**
  * Returns true if `content` starts with any known license header for the
  * given comment style.
@@ -65,16 +98,24 @@ export function getLicenseHeader(license, style) {
  * standard MPL header — operators were forced to `--skip-lint` over a real
  * false positive.
  *
+ * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
+ * leading the file are tolerated — Mozilla's canonical layout puts those
+ * on lines 1–2 with the MPL header on lines 3+, which the raw
+ * `startsWith` check would otherwise miss.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */
 export function hasAnyLicenseHeader(content, style) {
+    const candidates = [content, stripLeadingEditorDirectives(content)];
     const licenses = Object.keys(HEADER_LINES);
-    if (licenses.some((license) => content.startsWith(getLicenseHeader(license, style)))) {
-        return true;
-    }
-    if (style === 'js' && content.startsWith(getLicenseHeader('MPL-2.0', 'css'))) {
-        return true;
+    for (const candidate of candidates) {
+        if (licenses.some((license) => candidate.startsWith(getLicenseHeader(license, style)))) {
+            return true;
+        }
+        if (style === 'js' && candidate.startsWith(getLicenseHeader('MPL-2.0', 'css'))) {
+            return true;
+        }
     }
     return false;
 }

package/dist/src/core/patch-export.d.ts

@@ -5,6 +5,16 @@ import type { PatchCategory, PatchesManifest, PatchInfo, PatchMetadata } from '.
  * @returns Next patch number (e.g., "005" for 4 existing patches)
  */
 export declare function getNextPatchNumber(patchesDir: string): Promise<string>;
+/**
+ * Sanitizes a human-readable name into a filename slug.
+ *
+ * Exported so `patch rename` can produce a filename slug from its
+ * `--to <new-name>` argument using the exact same convention `export`
+ * uses, without duplicating the lowercase + non-alnum collapse + length
+ * cap rules. Drift between the two would let an operator rename a patch
+ * to a slug `export` could never reach.
+ */
+export declare function sanitizeName(name: string): string;
 /**
  * Generates the next patch filename with category.
  * @param patchesDir - Path to the patches directory

package/dist/src/core/patch-export.js

@@ -25,9 +25,15 @@ export async function getNextPatchNumber(patchesDir) {
     return String(nextNumber).padStart(Math.max(3, String(nextNumber).length), '0');
 }
 /**
- * Sanitizes a string for use in a filename.
+ * Sanitizes a human-readable name into a filename slug.
+ *
+ * Exported so `patch rename` can produce a filename slug from its
+ * `--to <new-name>` argument using the exact same convention `export`
+ * uses, without duplicating the lowercase + non-alnum collapse + length
+ * cap rules. Drift between the two would let an operator rename a patch
+ * to a slug `export` could never reach.
  */
-function sanitizeName(name) {
+export function sanitizeName(name) {
     return name
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')

package/dist/src/core/patch-lint-cross.js

@@ -396,6 +396,10 @@ export function lintPatchQueueForwardImports(ctx) {
                 .map((o) => `${o.filename}:${o.fullPath}`)
                 .sort((a, b) => a.localeCompare(b))
                 .join(',');
+            // Lowest ordinal that lands AFTER every later-ordered creator —
+            // turns the operator's "guess and re-run" loop into a single shot
+            // when the only fix is reordering.
+            const suggestedOrder = Math.max(...laterOwners.map((o) => o.order)) + 1;
             issues.push({
                 file: sitePath,
                 check: 'forward-import',
@@ -404,7 +408,8 @@ export function lintPatchQueueForwardImports(ctx) {
                     `but the matching new file is created by a later patch: ${ownersSummary}. ` +
                     'Reorder the patches so the dependency is created first, move the import ' +
                     'into the later patch, or mark the import with ' +
-                    `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive.`,
+                    `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive. ` +
+                    `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`,
                 severity: 'error',
             });
         }

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

@@ -1,6 +1,6 @@
 /**
  * Re-exports all command-related types from focused sub-modules.
  */
-export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchReorderOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
+export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchRenameOptions, PatchReorderOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
 export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, } from './patches.js';
 export type { DoctorCheck, ProjectStatus, TokenCoverageFileEntry, TokenCoverageReport, } from './project.js';

package/dist/src/types/commands/options.d.ts

@@ -501,6 +501,34 @@ export interface PatchDeleteOptions {
     /** Bypass the hard refusal when later patches depend on the target. */
     forceUnsafe?: boolean;
 }
+/**
+ * Options for the `fireforge patch rename` subcommand. Updates the
+ * patch's filename, manifest `name`, and (optionally) `description`
+ * atomically without rewriting the `.patch` file body. Companion to
+ * `re-export --files` for the case where the body is already correct
+ * but the patch's identity (filename + description) describes a
+ * pre-shrink scope; before this verb existed the only workaround was
+ * `delete` + re-export, which briefly dropped the patch from the queue.
+ */
+export interface PatchRenameOptions {
+    /**
+     * New human-readable name. Sanitised the same way `export --name`
+     * sanitises into the filename slug (lowercase, non-alphanumerics
+     * collapsed to `-`, length-capped). The patch's `name` field stores
+     * the raw value; the filename uses the sanitised slug.
+     */
+    to?: string;
+    /**
+     * Replacement description. Omit to leave the description unchanged
+     * (intentional — operators frequently want to relabel the slug
+     * without touching the description).
+     */
+    description?: string;
+    /** Print the planned change without writing. */
+    dryRun?: boolean;
+    /** Skip the confirmation prompt (required for non-TTY). */
+    yes?: boolean;
+}
 /**
  * Options for the patch reorder command.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.18.9",
+  "version": "0.18.10",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",