@hominis/fireforge 0.15.2 → 0.15.4

package/dist/src/commands/furnace/create-mochikit.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MochiKit (chrome://mochikit) test-harness scaffolder for
+ * `fireforge furnace create --test-style=mochikit`.
+ *
+ * Motivation: browser-chrome mochitests require a `tabbrowser` to exist in
+ * the top-level chrome document. Forks with a bespoke chrome document
+ * (e.g. `mybrowser.xhtml`) that deliberately omits tabbrowser cannot run
+ * browser-chrome tests today. MochiKit tests load the component module
+ * directly via `chrome://global/` and assert against `customElements`, so
+ * they work against any fork that registers the upstream toolkit test
+ * manifest tree — including those without a tabbrowser.
+ */
+import { type RollbackJournal } from '../../core/furnace-rollback.js';
+import type { ProjectLicense } from '../../types/config.js';
+/**
+ * Scaffolds a MochiKit test for a newly created custom component under
+ * `engine/toolkit/content/tests/widgets/`. Mirrors the layout stock
+ * Firefox widgets (moz-button, moz-toggle, etc.) use, so an operator who
+ * already added the `widgets/` tree to their test-manifest registration
+ * picks the new test up automatically.
+ *
+ * Appends a per-test entry to the existing `chrome.toml` when present,
+ * writes a fresh `[DEFAULT]`-headed one otherwise. The caller is still
+ * responsible for ensuring the `toolkit/content/tests/widgets/chrome.toml`
+ * path is registered somewhere in the moz.build tree; most forks inherit
+ * this from upstream via `TEST_HARNESS_FILES += [...]`.
+ */
+export declare function scaffoldMochikitTestFiles(componentName: string, license: ProjectLicense, paths: {
+    engine: string;
+}, journal?: RollbackJournal): Promise<string[]>;

package/dist/src/commands/furnace/create-mochikit.js

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * MochiKit (chrome://mochikit) test-harness scaffolder for
+ * `fireforge furnace create --test-style=mochikit`.
+ *
+ * Motivation: browser-chrome mochitests require a `tabbrowser` to exist in
+ * the top-level chrome document. Forks with a bespoke chrome document
+ * (e.g. `mybrowser.xhtml`) that deliberately omits tabbrowser cannot run
+ * browser-chrome tests today. MochiKit tests load the component module
+ * directly via `chrome://global/` and assert against `customElements`, so
+ * they work against any fork that registers the upstream toolkit test
+ * manifest tree — including those without a tabbrowser.
+ */
+import { join } from 'node:path';
+import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
+import { getLicenseHeader } from '../../core/license-headers.js';
+import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
+import { warn } from '../../utils/logger.js';
+import { generateMochikitChromeTomlEntry, generateMochikitChromeTomlSkeleton, generateMochikitTestContent, mochikitTestFileName, } from './create-templates.js';
+/**
+ * Scaffolds a MochiKit test for a newly created custom component under
+ * `engine/toolkit/content/tests/widgets/`. Mirrors the layout stock
+ * Firefox widgets (moz-button, moz-toggle, etc.) use, so an operator who
+ * already added the `widgets/` tree to their test-manifest registration
+ * picks the new test up automatically.
+ *
+ * Appends a per-test entry to the existing `chrome.toml` when present,
+ * writes a fresh `[DEFAULT]`-headed one otherwise. The caller is still
+ * responsible for ensuring the `toolkit/content/tests/widgets/chrome.toml`
+ * path is registered somewhere in the moz.build tree; most forks inherit
+ * this from upstream via `TEST_HARNESS_FILES += [...]`.
+ */
+export async function scaffoldMochikitTestFiles(componentName, license, paths, journal) {
+    const testDir = join(paths.engine, 'toolkit/content/tests/widgets');
+    if (journal && !(await pathExists(testDir))) {
+        recordCreatedDir(journal, testDir);
+    }
+    await ensureDir(testDir);
+    const hashHeader = getLicenseHeader(license, 'hash');
+    const writtenFiles = [];
+    const testFileName = mochikitTestFileName(componentName);
+    const testFilePath = join(testDir, testFileName);
+    if (journal)
+        await snapshotFile(journal, testFilePath);
+    await writeText(testFilePath, generateMochikitTestContent(componentName));
+    writtenFiles.push(testFileName);
+    // chrome.toml — append entry if the file already exists, otherwise write
+    // a fresh skeleton + entry. Idempotency: if the entry is already present
+    // the manifest is left untouched so re-runs don't double-register.
+    const manifestPath = join(testDir, 'chrome.toml');
+    const entry = generateMochikitChromeTomlEntry(componentName);
+    if (await pathExists(manifestPath)) {
+        const existing = await readText(manifestPath);
+        if (!existing.includes(`["${testFileName}"]`)) {
+            if (journal)
+                await snapshotFile(journal, manifestPath);
+            await writeText(manifestPath, existing.trimEnd() + '\n\n' + entry);
+        }
+    }
+    else {
+        if (journal)
+            await snapshotFile(journal, manifestPath);
+        await writeText(manifestPath, generateMochikitChromeTomlSkeleton(hashHeader) + entry);
+        writtenFiles.push('chrome.toml');
+    }
+    warn(`MochiKit scaffold written under toolkit/content/tests/widgets/. ` +
+        'Ensure `toolkit/content/tests/widgets/chrome.toml` is reachable from an existing test-harness registration (upstream TEST_HARNESS_FILES entries handle this by default).');
+    return writtenFiles;
+}
+//# sourceMappingURL=create-mochikit.js.map

package/dist/src/commands/furnace/create-templates.d.ts

@@ -45,3 +45,35 @@ export declare function generateXpcshellTestContent(name: string, header: string
  * component actually touches (Services.storage, observer topics, etc.).
  */
 export declare function generateXpcshellManifestContent(name: string, header: string): string;
+/** Returns the canonical mochikit test file basename for a component. */
+export declare function mochikitTestFileName(name: string): string;
+/**
+ * Generates a MochiKit (chrome://mochikit) test for a custom component.
+ *
+ * MochiKit tests load the component module directly via the global chrome
+ * URI and assert that `customElements.get(<tag>)` returns a constructor.
+ * They run on forks whose top-level chrome document lacks a `tabbrowser`
+ * (the class of bug that forces `--xpcshell` for storage code) because
+ * they do not traverse `URILoadingHelper.openLinkIn`.
+ *
+ * The scaffold here is a smoke test — the component is defined and the
+ * constructor is a function. Real UI assertions (render output, l10n
+ * wiring, keyboard interactions) are intentionally left out because they
+ * depend on the component's shape; operators can extend the test using
+ * the same SimpleTest APIs upstream toolkit widgets (moz-button, etc.)
+ * rely on.
+ */
+export declare function generateMochikitTestContent(name: string): string;
+/**
+ * Generates the `chrome.toml` entry block to append for a newly scaffolded
+ * mochikit test. When the manifest already exists the caller appends this
+ * snippet; when absent, the caller writes a file that starts with a
+ * `[DEFAULT]` stanza followed by this block.
+ */
+export declare function generateMochikitChromeTomlEntry(name: string): string;
+/**
+ * Generates the minimal `chrome.toml` used when the file does not yet
+ * exist in the tree. Keeps the `[DEFAULT]` stanza empty so each scaffold
+ * adds its own per-test entry, matching the stock Firefox convention.
+ */
+export declare function generateMochikitChromeTomlSkeleton(header: string): string;

package/dist/src/commands/furnace/create-templates.js

@@ -130,6 +130,75 @@ export function generateXpcshellManifestContent(name, header) {
 head = ""
 
 ["${xpcshellTestFileName(name)}"]
+`;
+}
+/** Returns the canonical mochikit test file basename for a component. */
+export function mochikitTestFileName(name) {
+    return `test_${name}.html`;
+}
+/**
+ * Generates a MochiKit (chrome://mochikit) test for a custom component.
+ *
+ * MochiKit tests load the component module directly via the global chrome
+ * URI and assert that `customElements.get(<tag>)` returns a constructor.
+ * They run on forks whose top-level chrome document lacks a `tabbrowser`
+ * (the class of bug that forces `--xpcshell` for storage code) because
+ * they do not traverse `URILoadingHelper.openLinkIn`.
+ *
+ * The scaffold here is a smoke test — the component is defined and the
+ * constructor is a function. Real UI assertions (render output, l10n
+ * wiring, keyboard interactions) are intentionally left out because they
+ * depend on the component's shape; operators can extend the test using
+ * the same SimpleTest APIs upstream toolkit widgets (moz-button, etc.)
+ * rely on.
+ */
+export function generateMochikitTestContent(name) {
+    return `<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Test the ${name} custom element</title>
+    <script src="chrome://mochikit/content/tests/SimpleTest/SimpleTest.js"></script>
+    <link rel="stylesheet" href="chrome://mochikit/content/tests/SimpleTest/test.css" />
+  </head>
+  <body>
+    <p id="display"></p>
+    <div id="content" style="display: none"></div>
+    <pre id="test"></pre>
+    <script type="module">
+      import "chrome://global/content/elements/${name}.mjs";
+
+      SimpleTest.waitForExplicitFinish();
+
+      add_task(async function test_${name.replace(/-/g, '_')}_defined() {
+        const ctor = await customElements.whenDefined("${name}");
+        ok(ctor, "${name} custom element should be defined");
+        is(typeof ctor, "function", "Constructor should be a function");
+      });
+    </script>
+  </body>
+</html>
+`;
+}
+/**
+ * Generates the `chrome.toml` entry block to append for a newly scaffolded
+ * mochikit test. When the manifest already exists the caller appends this
+ * snippet; when absent, the caller writes a file that starts with a
+ * `[DEFAULT]` stanza followed by this block.
+ */
+export function generateMochikitChromeTomlEntry(name) {
+    return `["${mochikitTestFileName(name)}"]\n`;
+}
+/**
+ * Generates the minimal `chrome.toml` used when the file does not yet
+ * exist in the tree. Keeps the `[DEFAULT]` stanza empty so each scaffold
+ * adds its own per-test entry, matching the stock Firefox convention.
+ */
+export function generateMochikitChromeTomlSkeleton(header) {
+    return `${header}
+
+[DEFAULT]
+
 `;
 }
 //# sourceMappingURL=create-templates.js.map

package/dist/src/commands/furnace/create.d.ts

@@ -1,4 +1,21 @@
 import type { FurnaceCreateOptions } from '../../types/commands/index.js';
+/** Resolved test-harness selection for a `furnace create` run. */
+export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'none';
+/**
+ * Collapses `--with-tests`, `--xpcshell`, and `--test-style` into the single
+ * scaffold dispatch used inside the mutation phase.
+ *
+ * Backwards-compat invariants:
+ * - `--xpcshell` alone is equivalent to `--test-style=xpcshell`.
+ * - `--with-tests` alone (no `--test-style`) now defaults to `mochikit`
+ *   (previously it defaulted to browser-chrome; the dogfooding pass
+ *   flagged browser-chrome as unrunnable against non-tabbrowser chrome).
+ *   Operators who need the old behavior can pass
+ *   `--with-tests --test-style=browser-chrome`.
+ * - `--xpcshell --with-tests` is rejected as ambiguous.
+ * @throws InvalidArgumentError when flags conflict.
+ */
+export declare function resolveTestStyle(options: FurnaceCreateOptions): ResolvedTestStyle;
 /**
  * Runs the furnace create command to scaffold a new custom component.
  * @param projectRoot - Root directory of the project

package/dist/src/commands/furnace/create.js

@@ -15,6 +15,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
 import { cancel, intro, isCancel, note, outro, success, warn } from '../../utils/logger.js';
+import { scaffoldMochikitTestFiles } from './create-mochikit.js';
 import { generateCssContent, generateFtlContent, generateMjsContent } from './create-templates.js';
 import { scaffoldXpcshellTestFiles } from './create-xpcshell.js';
 async function loadAuthoringFurnaceConfig(projectRoot) {
@@ -224,6 +225,35 @@ async function writeComponentFiles(componentDir, componentName, className, descr
     }
     return files;
 }
+/**
+ * Collapses `--with-tests`, `--xpcshell`, and `--test-style` into the single
+ * scaffold dispatch used inside the mutation phase.
+ *
+ * Backwards-compat invariants:
+ * - `--xpcshell` alone is equivalent to `--test-style=xpcshell`.
+ * - `--with-tests` alone (no `--test-style`) now defaults to `mochikit`
+ *   (previously it defaulted to browser-chrome; the dogfooding pass
+ *   flagged browser-chrome as unrunnable against non-tabbrowser chrome).
+ *   Operators who need the old behavior can pass
+ *   `--with-tests --test-style=browser-chrome`.
+ * - `--xpcshell --with-tests` is rejected as ambiguous.
+ * @throws InvalidArgumentError when flags conflict.
+ */
+export function resolveTestStyle(options) {
+    const xpcshellFlag = options.xpcshell ?? false;
+    const withTests = options.withTests ?? false;
+    const explicit = options.testStyle;
+    if (xpcshellFlag && explicit && explicit !== 'xpcshell') {
+        throw new InvalidArgumentError(`--xpcshell cannot be combined with --test-style=${explicit}; choose one.`, 'testStyle');
+    }
+    if (explicit)
+        return explicit;
+    if (xpcshellFlag)
+        return 'xpcshell';
+    if (withTests)
+        return 'mochikit';
+    return 'none';
+}
 /**
  * Performs the transactional mutation phase of furnace create. All file
  * writes and the config update are recorded in a rollback journal so a
@@ -259,14 +289,18 @@ async function performCreateMutations(args) {
         args.config.custom[args.componentName] = customEntry;
         await snapshotFile(journal, args.furnacePaths.furnaceConfig);
         await writeFurnaceConfig(args.projectRoot, args.config);
-        if (args.withTests) {
+        if (args.testStyle === 'browser-chrome') {
             const scafFiles = await scaffoldTestFiles(args.componentName, args.license, args.forgeConfig, args.paths, journal);
             testFiles.push(...scafFiles);
         }
-        if (args.xpcshellTests) {
+        else if (args.testStyle === 'xpcshell') {
             const xpcshellFiles = await scaffoldXpcshellTestFiles(args.componentName, args.license, args.forgeConfig, args.paths, journal);
             testFiles.push(...xpcshellFiles);
         }
+        else if (args.testStyle === 'mochikit') {
+            const mochikitFiles = await scaffoldMochikitTestFiles(args.componentName, args.license, args.paths, journal);
+            testFiles.push(...mochikitFiles);
+        }
     }
     catch (error) {
         try {
@@ -400,15 +434,13 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         return;
     }
     const { localized, register } = featureSelection;
-    // --with-tests writes files under engine/browser/base/content/test/ and
-    // registers them in moz.build. --xpcshell is the equivalent for forks
-    // without a tabbrowser (storage-layer code). Guard against a missing
-    // engine now rather than letting the scaffolders fabricate a partial
-    // engine tree with ensureDir.
-    const withTests = options.withTests ?? false;
-    const xpcshellTests = options.xpcshell ?? false;
-    if ((withTests || xpcshellTests) && !(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to use --with-tests or --xpcshell.', componentName);
+    // Collapse --with-tests / --xpcshell / --test-style into the single
+    // scaffold selection used by the mutation phase. The resolver validates
+    // incompatible combinations up-front so a bad flag set never strands a
+    // partial mutation behind.
+    const testStyle = resolveTestStyle(options);
+    if (testStyle !== 'none' && !(await pathExists(paths.engine))) {
+        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to use --with-tests, --xpcshell, or --test-style.', componentName);
     }
     // --- Generate component files ---
     const className = tagNameToClassName(componentName);
@@ -444,8 +476,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         forgeConfig,
         paths,
         license,
-        withTests,
-        xpcshellTests,
+        testStyle,
         ftlChromeSubPath,
         operationContext: ctx,
     }));
@@ -453,9 +484,16 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     let noteParts = `Files created in components/custom/${componentName}/:\n` +
         files.map((f) => `  ${f}`).join('\n');
     if (testFiles.length > 0) {
-        const testRoot = xpcshellTests
-            ? `engine/browser/base/content/test/${forgeConfig.binaryName}-xpcshell/${componentName}/`
-            : `engine/browser/base/content/test/${forgeConfig.binaryName}/`;
+        let testRoot;
+        if (testStyle === 'xpcshell') {
+            testRoot = `engine/browser/base/content/test/${forgeConfig.binaryName}-xpcshell/${componentName}/`;
+        }
+        else if (testStyle === 'mochikit') {
+            testRoot = 'engine/toolkit/content/tests/widgets/';
+        }
+        else {
+            testRoot = `engine/browser/base/content/test/${forgeConfig.binaryName}/`;
+        }
         noteParts += `\n\nTest files in ${testRoot}:\n` + testFiles.map((f) => `  ${f}`).join('\n');
     }
     noteParts +=

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

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
 import { furnaceApplyCommand } from './apply.js';
+import { furnaceChromeDocCreateCommand } from './chrome-doc.js';
 import { furnaceCreateCommand } from './create.js';
 import { furnaceDeployCommand } from './deploy.js';
 import { furnaceDiffCommand } from './diff.js';
@@ -15,6 +16,6 @@ import { furnaceScanCommand } from './scan.js';
 import { furnaceStatusCommand } from './status.js';
 import { furnaceSyncCommand } from './sync.js';
 import { furnaceValidateCommand } from './validate.js';
-export { furnaceApplyCommand, furnaceBatchOverrideCommand, furnaceCreateCommand, furnaceDeployCommand, furnaceDiffCommand, furnaceInitCommand, furnaceListCommand, furnaceOverrideCommand, furnacePreviewCommand, furnaceRefreshCommand, furnaceRemoveCommand, furnaceRenameCommand, furnaceScanCommand, furnaceStatusCommand, furnaceSyncCommand, furnaceValidateCommand, };
+export { furnaceApplyCommand, furnaceBatchOverrideCommand, furnaceChromeDocCreateCommand, furnaceCreateCommand, furnaceDeployCommand, furnaceDiffCommand, furnaceInitCommand, furnaceListCommand, furnaceOverrideCommand, furnacePreviewCommand, furnaceRefreshCommand, furnaceRemoveCommand, furnaceRenameCommand, furnaceScanCommand, furnaceStatusCommand, furnaceSyncCommand, furnaceValidateCommand, };
 /** Registers the furnace command on the CLI program. */
 export declare function registerFurnace(program: Command, context: CommandContext): void;

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

@@ -2,6 +2,7 @@
 import { Option } from 'commander';
 import { pickDefined } from '../../utils/options.js';
 import { furnaceApplyCommand } from './apply.js';
+import { furnaceChromeDocCreateCommand } from './chrome-doc.js';
 import { furnaceCreateCommand } from './create.js';
 import { furnaceDeployCommand } from './deploy.js';
 import { furnaceDiffCommand } from './diff.js';
@@ -16,7 +17,7 @@ import { furnaceScanCommand } from './scan.js';
 import { furnaceStatusCommand } from './status.js';
 import { furnaceSyncCommand } from './sync.js';
 import { furnaceValidateCommand } from './validate.js';
-export { furnaceApplyCommand, furnaceBatchOverrideCommand, furnaceCreateCommand, furnaceDeployCommand, furnaceDiffCommand, furnaceInitCommand, furnaceListCommand, furnaceOverrideCommand, furnacePreviewCommand, furnaceRefreshCommand, furnaceRemoveCommand, furnaceRenameCommand, furnaceScanCommand, furnaceStatusCommand, furnaceSyncCommand, furnaceValidateCommand, };
+export { furnaceApplyCommand, furnaceBatchOverrideCommand, furnaceChromeDocCreateCommand, furnaceCreateCommand, furnaceDeployCommand, furnaceDiffCommand, furnaceInitCommand, furnaceListCommand, furnaceOverrideCommand, furnacePreviewCommand, furnaceRefreshCommand, furnaceRemoveCommand, furnaceRenameCommand, furnaceScanCommand, furnaceStatusCommand, furnaceSyncCommand, furnaceValidateCommand, };
 /**
  * Registers Furnace commands for querying component state: status, scan,
  * and action commands like apply, deploy, and create.
@@ -71,12 +72,28 @@ function registerFurnaceInfoCommands(furnace, context) {
         .option('-d, --description <desc>', 'Component description')
         .option('--localized', 'Include Fluent l10n support')
         .option('--no-register', 'Skip customElements.js registration')
-        .option('--with-tests', 'Scaffold Mochitest directory and register in moz.build')
-        .option('--xpcshell', 'Scaffold an xpcshell test harness (for storage-layer code on forks without tabbrowser)')
+        .option('--with-tests', 'Scaffold a test harness (defaults to MochiKit; see --test-style)')
+        .option('--xpcshell', 'Scaffold an xpcshell test harness (for storage-layer code on forks without tabbrowser); equivalent to --test-style=xpcshell')
+        .option('--test-style <style>', "Override the harness written by --with-tests: mochikit (default, runs against non-tabbrowser chrome), browser-chrome (today's scaffold, needs tabbrowser), or xpcshell (headless)", (value) => {
+        if (value !== 'mochikit' && value !== 'browser-chrome' && value !== 'xpcshell') {
+            throw new Error(`--test-style must be one of: mochikit, browser-chrome, xpcshell. Got: "${value}".`);
+        }
+        return value;
+    })
         .option('--compose <tags>', 'Record stock tags composed internally (metadata only, comma-separated)', (val) => val.split(',').map((s) => s.trim()))
         .action(withErrorHandling(async (name, options) => {
         await furnaceCreateCommand(getProjectRoot(), name, options);
     }));
+    const chromeDoc = furnace
+        .command('chrome-doc')
+        .description('Scaffold top-level chrome documents (xhtml + js + css + ftl + jar.mn)');
+    chromeDoc
+        .command('create <name>')
+        .description('Scaffold a new top-level chrome document')
+        .option('--no-titlebar', 'Frameless overlay-style document (omits titlebar-buttonbox)')
+        .action(withErrorHandling(async (name, options) => {
+        await furnaceChromeDocCreateCommand(getProjectRoot(), name, pickDefined(options));
+    }));
 }
 /**
  * Registers Furnace commands for authoring, inspection, and maintenance:

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

@@ -1,10 +1,22 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+/** Options controlling how the lint command filters and tags its output. */
+export interface LintCommandOptions {
+    /**
+     * When set, tag each issue as `introduced` or `cumulative` based on
+     * whether its file changed since this git revision (e.g. `HEAD`, a
+     * branch name, or a SHA). Issues are not filtered — the full set still
+     * prints and the exit code is unchanged — but a diff-scoped summary
+     * makes it trivial to see which errors the current task introduced.
+     */
+    since?: string;
+}
 /**
  * Runs the lint command to check engine changes against patch quality rules.
  * @param projectRoot - Root directory of the project
  * @param files - Optional file/directory paths to lint (relative to engine/)
+ * @param options - Additional lint options such as `--since` diff-scoping
  */
-export declare function lintCommand(projectRoot: string, files: string[]): Promise<void>;
+export declare function lintCommand(projectRoot: string, files: string[], options?: LintCommandOptions): Promise<void>;
 /** Registers the lint command on the CLI program. */
 export declare function registerLint(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/lint.js

@@ -7,6 +7,7 @@ import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { buildPatchQueueContext, lintExportedPatch, lintPatchQueue } from '../core/patch-lint.js';
+import { collectDiffFilePaths, tagLintIssues } from '../core/patch-lint-diff-tag.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
@@ -14,8 +15,9 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
  * Runs the lint command to check engine changes against patch quality rules.
  * @param projectRoot - Root directory of the project
  * @param files - Optional file/directory paths to lint (relative to engine/)
+ * @param options - Additional lint options such as `--since` diff-scoping
  */
-export async function lintCommand(projectRoot, files) {
+export async function lintCommand(projectRoot, files, options = {}) {
     intro('FireForge Lint');
     const paths = getProjectPaths(projectRoot);
     if (!(await pathExists(paths.engine))) {
@@ -105,19 +107,38 @@ export async function lintCommand(projectRoot, files) {
         outro('Lint passed');
         return;
     }
+    // Diff-scoping: tag each issue as introduced-in-current-task vs
+    // cumulative-pre-existing-drift. Never filters — full set still prints
+    // and exit code semantics are unchanged — but the per-line prefix and
+    // summary make triage trivial on a large patch series.
+    const sinceActive = Boolean(options.since);
+    if (options.since) {
+        const diffFiles = await collectDiffFilePaths(paths.engine, options.since);
+        tagLintIssues(issues, diffFiles);
+    }
     const errors = issues.filter((i) => i.severity === 'error');
     const warnings = issues.filter((i) => i.severity === 'warning');
     const notices = issues.filter((i) => i.severity === 'notice');
+    const tagPrefix = (issue) => sinceActive && issue.tag ? `[${issue.tag}] ` : '';
     for (const issue of notices) {
-        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+        info(`${tagPrefix(issue)}NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
     }
     for (const issue of warnings) {
-        warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
+        warn(`${tagPrefix(issue)}[${issue.check}] ${issue.file}: ${issue.message}`);
     }
     for (const issue of errors) {
-        warn(`ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+        warn(`${tagPrefix(issue)}ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+    }
+    if (sinceActive) {
+        const introducedErrors = errors.filter((i) => i.tag === 'introduced').length;
+        const introducedWarnings = warnings.filter((i) => i.tag === 'introduced').length;
+        const cumulativeErrors = errors.length - introducedErrors;
+        const cumulativeWarnings = warnings.length - introducedWarnings;
+        info(`\nLint: ${introducedErrors} introduced error(s), ${introducedWarnings} introduced warning(s); ${cumulativeErrors} cumulative error(s), ${cumulativeWarnings} cumulative warning(s)`);
+    }
+    else {
+        info(`\nLint: ${errors.length} error(s), ${warnings.length} warning(s)`);
     }
-    info(`\nLint: ${errors.length} error(s), ${warnings.length} warning(s)`);
     if (errors.length > 0) {
         outro('Lint failed');
         throw new GeneralError(`Patch lint found ${errors.length} error(s). Fix these before exporting.`);
@@ -129,8 +150,13 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('lint [paths...]')
         .description('Lint engine changes against patch quality rules')
-        .action(withErrorHandling(async (paths) => {
-        await lintCommand(getProjectRoot(), paths);
+        .option('--since <git-rev>', 'Tag issues as [introduced] or [cumulative] based on whether the file changed since <git-rev> (e.g. HEAD, a branch, a SHA)')
+        .action(withErrorHandling(async (paths, options) => {
+        const lintOptions = {};
+        if (options.since !== undefined) {
+            lintOptions.since = options.since;
+        }
+        await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
 }
 //# sourceMappingURL=lint.js.map