@hominis/fireforge 0.39.0 → 0.41.0

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

@@ -3,14 +3,15 @@ import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/lint-cache.js';
-import { buildPatchQueueContext, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
-import { invokePatchLintCheckJsGrouped, } from '../core/patch-lint-checkjs.js';
-import { resolvePatchOwnedSysMjs } from '../core/patch-lint-ownership.js';
+import { buildPatchQueueContext, countNonBinaryDiffLines, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { evaluatePatchPolicy } from '../core/patch-policy.js';
 import { GeneralError } from '../errors/base.js';
+import { mapWithConcurrency } from '../utils/concurrency.js';
 import { pathExists } from '../utils/fs.js';
 import { info, outro, success, warn } from '../utils/logger.js';
+import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
+import { writePerPatchLintReport } from './lint-report.js';
 function buildPerPatchMaxWarningsMessage(count, maxWarnings, linted) {
     return (`Patch lint found ${count} warning(s) across ${linted} patch(es), exceeding --max-warnings ${maxWarnings}.` +
         ' If this is a release gate, run with --per-patch to identify the owning patch. For intentional staged imports, use patch staged-dependency; for ownership repairs, preview patch move-files, patch reorder --dry-run, or re-export --files --dry-run; add scoped lintIgnore only after review.');
@@ -33,13 +34,17 @@ function emitTierNotice(filename, files, tier) {
  */
 async function lintQueuedPatch(patch, lintCtx) {
     const { projectRoot, paths, config, ctx, cache, engineHeadSha } = lintCtx;
-    const existing = [];
-    for (const f of patch.filesAffected) {
-        if (await pathExists(join(paths.engine, f)))
-            existing.push(f);
-    }
+    const present = await mapWithConcurrency(patch.filesAffected, 8, (f) => pathExists(join(paths.engine, f)));
+    const existing = patch.filesAffected.filter((_, index) => present[index] === true);
     if (existing.length === 0) {
-        return { status: 'skipped', existingFiles: [], rawIssues: [], usedCheckJs: false };
+        return {
+            status: 'skipped',
+            existingFiles: [],
+            rawIssues: [],
+            suppressedIssues: [],
+            lineCount: 0,
+            usedCheckJs: false,
+        };
     }
     const ignore = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
     let cacheKey;
@@ -61,16 +66,33 @@ async function lintQueuedPatch(patch, lintCtx) {
             // an engine-side revert that would empty the diff always changes the
             // key and misses the cache (pinned by the "engine-side content
             // revert invalidates the per-patch cache" test — FORGE F5).
-            return { status: 'cached', existingFiles: existing, rawIssues: cached, usedCheckJs: false };
+            return {
+                status: 'cached',
+                existingFiles: existing,
+                rawIssues: cached.issues,
+                suppressedIssues: cached.suppressed,
+                lineCount: cached.lineCount,
+                usedCheckJs: false,
+            };
         }
     }
     const diff = await getDiffForFilesAgainstHead(paths.engine, existing);
     if (!diff.trim()) {
-        return { status: 'skipped', existingFiles: [], rawIssues: [], usedCheckJs: false };
+        return {
+            status: 'skipped',
+            existingFiles: [],
+            rawIssues: [],
+            suppressedIssues: [],
+            lineCount: 0,
+            usedCheckJs: false,
+        };
     }
     // checkJs: instead of rebuilding the program per patch, slice this patch's
     // findings out of the one queue-wide program (built lazily on first miss).
-    let lintOptions;
+    const suppressedIssues = [];
+    const lintOptions = {
+        onSuppressed: (suppressed) => suppressedIssues.push(...suppressed),
+    };
     let usedCheckJs = false;
     if (lintCtx.checkJs) {
         const grouped = await lintCtx.checkJs.getGrouped();
@@ -81,20 +103,28 @@ async function lintQueuedPatch(patch, lintCtx) {
             for (const rel of owned)
                 precomputedCheckJs.push(...(grouped.byFile.get(rel) ?? []));
         }
-        lintOptions = { precomputedCheckJs };
+        lintOptions.precomputedCheckJs = precomputedCheckJs;
     }
     const patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, ctx, ignore, patch.tier, lintOptions);
     const result = {
         status: 'linted',
         existingFiles: existing,
         rawIssues: patchIssues,
+        suppressedIssues,
+        lineCount: countNonBinaryDiffLines(diff).textLines,
         usedCheckJs,
     };
     if (cache && cacheKey) {
-        result.cacheWrite = { key: cacheKey, issues: patchIssues };
+        result.cacheWrite = { key: cacheKey };
     }
     return result;
 }
+/** Size-rule check IDs whose waived measurement is still reported (FORGE G10). */
+const SUPPRESSED_SIZE_CHECKS = new Set([
+    'large-patch-lines',
+    'large-patch-files',
+    'file-too-large',
+]);
 /**
  * Applies the per-patch results in patch order so the bounded concurrency
  * cannot reorder output: emits each tier notice, the once-only run-level
@@ -108,6 +138,7 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
         skipped: 0,
         cacheDirty: false,
         reusedCacheEntries: 0,
+        suppressed: 0,
     };
     let globalCheckJsEmitted = false;
     for (let i = 0; i < subset.length; i++) {
@@ -132,12 +163,22 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
             issues.push(...(await checkJs.getGlobal()));
         }
         if (result.cacheWrite && cache) {
-            setCachedPerPatchLintIssues(cache, patch.filename, result.cacheWrite.key, result.cacheWrite.issues);
+            setCachedPerPatchLintIssues(cache, patch.filename, result.cacheWrite.key, result.rawIssues, result.suppressedIssues, result.lineCount);
             totals.cacheDirty = true;
         }
         for (const issue of result.rawIssues) {
             issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
         }
+        // A waived size finding still reports its MEASUREMENT (FORGE G10):
+        // the finding stays suppressed (no exit-code / --max-warnings effect)
+        // but the current count is readable from the tool that enforces it,
+        // so a waiver's cited size can be calibrated without hand-measuring.
+        for (const suppressedIssue of result.suppressedIssues) {
+            if (!SUPPRESSED_SIZE_CHECKS.has(suppressedIssue.check))
+                continue;
+            info(`NOTICE [${suppressedIssue.check}] ${patch.filename}: suppressed by lintIgnore — ${suppressedIssue.message}`);
+        }
+        totals.suppressed += result.suppressedIssues.length;
         if (result.status === 'cached')
             totals.reusedCacheEntries++;
         totals.linted++;
@@ -193,11 +234,11 @@ function reportPerPatchOutcome(issues, linted, skipped, options) {
     const warnings = issues.filter((i) => i.severity === 'warning');
     const notices = issues.filter((i) => i.severity === 'notice');
     for (const issue of notices)
-        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+        info(`NOTICE ${formatPatchLintIssue(issue)}`);
     for (const issue of warnings)
-        warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
+        warn(formatPatchLintIssue(issue));
     for (const issue of errors)
-        warn(`ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+        warn(`ERROR ${formatPatchLintIssue(issue)}`);
     info(`\nLint (per-patch over ${linted} patch(es)): ${errors.length} error(s), ${warnings.length} warning(s)`);
     if (errors.length > 0) {
         outro('Lint failed');
@@ -248,7 +289,9 @@ function selectPatchSubset(manifest, requested) {
         const found = manifest.patches.filter((p) => matches(p, name));
         if (found.length === 0) {
             const available = manifest.patches.map((p) => p.filename).join(', ');
-            throw new GeneralError(`--patches: no patch in the queue matches "${name}". Available patches: ${available}`);
+            throw new GeneralError(`No patch in the queue matches "${name}". In --per-patch mode, positional arguments ` +
+                `and --patches select patches (filename, stem, manifest name, or slug) — not engine ` +
+                `files; drop --per-patch to lint engine paths. Available patches: ${available}`);
         }
         for (const p of found) {
             if (!seen.has(p.filename)) {
@@ -259,36 +302,6 @@ function selectPatchSubset(manifest, requested) {
     }
     return selected;
 }
-/**
- * Builds the per-run checkJs program controller when `patchLint.checkJs` is
- * enabled, or returns undefined. The program is built lazily on the first
- * cache miss (so an all-warm run never pays for it) and reused for every
- * subsequent patch in the run.
- */
-function buildPerRunCheckJs(projectRoot, paths, config, ctx) {
-    const patchLint = config.patchLint;
-    if (!patchLint?.checkJs)
-        return undefined;
-    const ownedByPatch = new Map();
-    for (const entry of ctx.entries) {
-        const owned = new Set();
-        for (const f of entry.newFiles.keys()) {
-            if (f.endsWith('.sys.mjs'))
-                owned.add(f);
-        }
-        if (owned.size > 0)
-            ownedByPatch.set(entry.filename, owned);
-    }
-    // Memoise the *promise*, not the resolved value: under the bounded pool
-    // several patches can reach `getGrouped` before the first build resolves, and
-    // `??=` on the promise (a synchronous expression) guarantees a single build.
-    let groupedPromise;
-    return {
-        ownedByPatch,
-        getGrouped: () => (groupedPromise ??= invokePatchLintCheckJsGrouped(paths.engine, resolvePatchOwnedSysMjs(new Set(), ctx), patchLint, projectRoot)),
-        getGlobal: async () => (await (groupedPromise ??= invokePatchLintCheckJsGrouped(paths.engine, resolvePatchOwnedSysMjs(new Set(), ctx), patchLint, projectRoot))).global,
-    };
-}
 /**
  * Lints each patch in the queue as its own isolated diff, honouring
  * per-patch `lintIgnore` entries. Cross-patch rules still run once over
@@ -337,7 +350,10 @@ export async function lintPerPatch(projectRoot, paths, options = {}) {
             severity: issue.severity,
         });
     }
-    const checkJs = buildPerRunCheckJs(projectRoot, paths, config, ctx);
+    // With `--patches`, the checkJs program roots at only the subset's owned
+    // files — the full queue stays resolvable, so a cold subset run costs the
+    // subset's import closure instead of the whole queue (FORGE J1c).
+    const checkJs = buildPerRunCheckJs(projectRoot, paths, config, ctx, isSubset ? subsetNames : undefined);
     // Lint patches concurrently, then apply every side effect in patch order so
     // the issue rows, the run-level checkJs errors, and the saved cache are
     // identical to a serial run.
@@ -350,7 +366,7 @@ export async function lintPerPatch(projectRoot, paths, options = {}) {
         engineHeadSha,
         checkJs,
     });
-    const { linted, skipped, cacheDirty, reusedCacheEntries } = await applyPerPatchResults(subset, results, issues, checkJs, cache);
+    const { linted, skipped, cacheDirty, reusedCacheEntries, suppressed } = await applyPerPatchResults(subset, results, issues, checkJs, cache);
     for (const issue of lintPatchQueue(ctx)) {
         if (isSubset && !subsetTouchedFiles.has(issue.file))
             continue;
@@ -361,5 +377,11 @@ export async function lintPerPatch(projectRoot, paths, options = {}) {
     if (reusedCacheEntries > 0) {
         info(`Reused lint cache for ${reusedCacheEntries} patch${reusedCacheEntries === 1 ? '' : 'es'}.`);
     }
+    if (suppressed > 0) {
+        info(`Suppressed ${suppressed} issue(s) via per-patch lintIgnore.`);
+    }
+    if (options.report !== undefined) {
+        await writePerPatchLintReport(options.report, subset, results);
+    }
     reportPerPatchOutcome(issues, linted, skipped, options);
 }

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

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

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

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

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

@@ -0,0 +1,21 @@
+import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
+/**
+ * Structural view of one per-patch lint outcome. Mirrors the relevant
+ * fields of lint-per-patch's QueuedPatchResult without importing it —
+ * that module imports this one, and a type back-edge would trip the
+ * dpdm cycle gate.
+ */
+export interface PerPatchReportResult {
+    status: 'skipped' | 'cached' | 'linted';
+    existingFiles: string[];
+    rawIssues: PatchLintIssue[];
+    suppressedIssues: PatchLintIssue[];
+    lineCount: number;
+}
+/**
+ * Writes the per-patch lint report JSON. Called after the per-patch
+ * results are assembled in patch order; queue-level and policy findings
+ * are patch-attributed by their `file`/`filename` fields upstream and
+ * are NOT duplicated here — the report is the per-patch view.
+ */
+export declare function writePerPatchLintReport(reportPath: string, subset: readonly PatchMetadata[], results: readonly PerPatchReportResult[]): Promise<void>;

package/dist/src/commands/lint-report.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Machine-readable per-patch lint report (`lint --per-patch --report
+ * <path>`, FORGE G9 + G10). One mechanism serves both observability
+ * gaps: consumers get each patch's size metrics against the SAME
+ * thresholds the size rules fire on (no more mirroring
+ * `countNonBinaryDiffLines`), and lintIgnore-suppressed issues stay
+ * visible with their measurements instead of vanishing.
+ *
+ * Helper module consumed by lint-per-patch.ts; no registrar is exported
+ * and none is wanted.
+ */
+import { getPatchSizeThresholds, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { writeJson } from '../utils/fs.js';
+import { info } from '../utils/logger.js';
+const LINT_REPORT_SCHEMA_VERSION = 1;
+/**
+ * Writes the per-patch lint report JSON. Called after the per-patch
+ * results are assembled in patch order; queue-level and policy findings
+ * are patch-attributed by their `file`/`filename` fields upstream and
+ * are NOT duplicated here — the report is the per-patch view.
+ */
+export async function writePerPatchLintReport(reportPath, subset, results) {
+    const patches = [];
+    let errors = 0;
+    let warnings = 0;
+    let suppressed = 0;
+    let linted = 0;
+    let skipped = 0;
+    for (let i = 0; i < subset.length; i++) {
+        const patch = subset[i];
+        const result = results[i];
+        if (!patch || !result)
+            continue;
+        const tier = resolvePatchSizeTier(result.existingFiles, patch.tier);
+        patches.push({
+            filename: patch.filename,
+            name: patch.name,
+            status: result.status,
+            lineCount: result.lineCount,
+            filesAffected: patch.filesAffected.length,
+            tier,
+            thresholds: getPatchSizeThresholds(tier.tier),
+            issues: result.rawIssues,
+            suppressedIssues: result.suppressedIssues,
+        });
+        if (result.status === 'skipped')
+            skipped++;
+        else
+            linted++;
+        errors += result.rawIssues.filter((issue) => issue.severity === 'error').length;
+        warnings += result.rawIssues.filter((issue) => issue.severity === 'warning').length;
+        suppressed += result.suppressedIssues.length;
+    }
+    await writeJson(reportPath, {
+        schemaVersion: LINT_REPORT_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        patches,
+        totals: { linted, skipped, errors, warnings, suppressed },
+    });
+    info(`Per-patch lint report written to ${reportPath}.`);
+}

package/dist/src/commands/lint.js

@@ -10,7 +10,7 @@ import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { expandUntrackedDirectoryEntries, getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, getWorkingTreeStatus, } from '../core/git-status.js';
 import { clearPerPatchLintCache } from '../core/lint-cache.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
-import { buildPatchQueueContext, countNonBinaryDiffLines, lintExportedPatch, lintPatchQueue, lintPatchSize, } from '../core/patch-lint.js';
+import { buildPatchQueueContext, countNonBinaryDiffLines, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, lintPatchSize, } 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';
@@ -217,11 +217,12 @@ export function applyAggregateLintIgnoreSuppression(issues, ctx) {
 }
 /**
  * Up-front flag validation for `lintCommand`: rejects `--only-introduced`
- * without `--since`, non-integer `--max-warnings`, and `--per-patch`
- * combined with explicit file paths — each a misconfiguration that should
- * fail loud rather than silently narrow the result.
+ * without `--since` and non-integer `--max-warnings` — each a
+ * misconfiguration that should fail loud rather than silently narrow the
+ * result. Positional arguments in per-patch mode are patch selectors
+ * (FORGE G14) and are validated downstream by `selectPatchSubset`.
  */
-function validateLintFlags(options, files) {
+function validateLintFlags(options) {
     // `--only-introduced` scopes the exit code to `--since`-tagged issues, so
     // without a revision to anchor the diff there is no "introduced" subset
     // to scope to — reject the combination up-front so a misconfigured CI
@@ -234,22 +235,16 @@ function validateLintFlags(options, files) {
         (!Number.isInteger(options.maxWarnings) || options.maxWarnings < 0)) {
         throw new GeneralError('--max-warnings must be a non-negative integer.');
     }
-    // `--per-patch` rescopes the diff from "aggregate engine state" to "each
-    // patch's own filesAffected". Mixing in explicit engine file paths would
-    // produce an ambiguous set — is the file list an additional filter, or
-    // does it replace the per-patch scope? Reject up-front, but point at the
-    // first-class subset filter so an operator who wanted to target patches
-    // (not engine files) knows the supported syntax.
-    if (options.perPatch && files.length > 0) {
-        throw new GeneralError('--per-patch cannot be combined with explicit engine file paths. ' +
-            'To lint a subset of patches, use `--per-patch --patches <name…>`; ' +
-            'to lint specific engine files, drop --per-patch.');
-    }
     // `--patches` only means something in per-patch mode (it filters the
     // queue); in aggregate/file-list mode there is no patch loop to narrow.
     if (options.patches !== undefined && !options.perPatch) {
         throw new GeneralError('--patches requires --per-patch.');
     }
+    // The JSON report is a per-patch artifact (per-patch size metrics and
+    // suppressed issues); aggregate mode has no per-patch rows to report.
+    if (options.report !== undefined && !options.perPatch) {
+        throw new GeneralError('--report requires --per-patch.');
+    }
 }
 /**
  * Aggregate-mode patch-size softening: when the linted diff is every
@@ -366,13 +361,13 @@ async function reportLintOutcome(engineDir, issues, options) {
     const notices = issues.filter((i) => i.severity === 'notice');
     const tagPrefix = (issue) => sinceActive && issue.tag ? `[${issue.tag}] ` : '';
     for (const issue of notices) {
-        info(`${tagPrefix(issue)}NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+        info(`${tagPrefix(issue)}NOTICE ${formatPatchLintIssue(issue)}`);
     }
     for (const issue of warnings) {
-        warn(`${tagPrefix(issue)}[${issue.check}] ${issue.file}: ${issue.message}`);
+        warn(`${tagPrefix(issue)}${formatPatchLintIssue(issue)}`);
     }
     for (const issue of errors) {
-        warn(`${tagPrefix(issue)}ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+        warn(`${tagPrefix(issue)}ERROR ${formatPatchLintIssue(issue)}`);
     }
     if (sinceActive) {
         const introducedErrors = errors.filter((i) => i.tag === 'introduced').length;
@@ -429,7 +424,7 @@ async function reportLintOutcome(engineDir, issues, options) {
  */
 export async function lintCommand(projectRoot, files, options = {}) {
     intro('FireForge Lint');
-    validateLintFlags(options, files);
+    validateLintFlags(options);
     const paths = getProjectPaths(projectRoot);
     if (!(await pathExists(paths.engine))) {
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
@@ -438,7 +433,12 @@ export async function lintCommand(projectRoot, files, options = {}) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
     if (options.perPatch) {
-        await lintPerPatch(projectRoot, paths, options);
+        // Positional arguments in per-patch mode select PATCHES through the
+        // same alias resolution as --patches (FORGE G14) — a non-matching
+        // positional fails loud against the queue listing, so an engine path
+        // can never silently lint. Explicit --patches entries come first.
+        const perPatchOptions = files.length > 0 ? { ...options, patches: [...(options.patches ?? []), ...files] } : options;
+        await lintPerPatch(projectRoot, paths, perPatchOptions);
         return;
     }
     // Load the config before resolving the diff so we can pass
@@ -511,9 +511,10 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         .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)')
         .option('--only-introduced', 'Fail only on issues tagged [introduced] (requires --since). Cumulative errors still print but do not set a non-zero exit.')
         .option('--per-patch', "Lint each patch in the queue as its own isolated diff. Rescopes patch-size rules so they fire against individual patches rather than the aggregate. Honours each patch's `lintIgnore` entries.")
-        .option('--patches <names...>', 'With --per-patch, lint only the named patches. Accepts repeated flags, comma lists, full filenames/stems, manifest names, category-prefixed slugs, or bare slugs.')
+        .option('--patches <names...>', 'With --per-patch, lint only the named patches. Accepts repeated flags, comma lists, full filenames/stems, manifest names, category-prefixed slugs, or bare slugs. Positional arguments after --per-patch are treated the same way.')
         .option('--max-warnings <n>', 'Fail when lint reports more than <n> warning(s); use 0 for warning-clean release gates.')
         .option('--no-cache', 'Bypass per-patch lint result cache reads and writes.')
+        .option('--report <path>', 'With --per-patch, write a machine-readable JSON report (per-patch size metrics, tier, thresholds, issues, and lintIgnore-suppressed issues) to <path>.')
         .action(withErrorHandling(async (paths, options) => {
         const lintOptions = {};
         if (options.since !== undefined) {
@@ -538,6 +539,9 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         if (options.cache === false) {
             lintOptions.noCache = true;
         }
+        if (options.report !== undefined) {
+            lintOptions.report = options.report;
+        }
         await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
     const lintCache = lint

package/dist/src/commands/manifest.js

@@ -11,7 +11,7 @@ import { registerImport } from './import.js';
 import { registerLint } from './lint.js';
 import { registerPackage } from './package.js';
 import { registerPatch } from './patch/index.js';
-import { registerReExport } from './re-export.js';
+import { registerReExport } from './re-export-register.js';
 import { registerRebase } from './rebase.js';
 import { registerRegister } from './register.js';
 import { registerReset } from './reset.js';
@@ -22,6 +22,7 @@ import { registerSource } from './source.js';
 import { registerStatus } from './status.js';
 import { registerTest } from './test-register.js';
 import { registerToken } from './token.js';
+import { registerTree } from './tree.js';
 import { registerTypecheck } from './typecheck.js';
 import { registerVerify } from './verify.js';
 import { registerWatch } from './watch.js';
@@ -50,6 +51,7 @@ export const COMMAND_MANIFEST = [
     { name: 'package', group: 'workflow', register: registerPackage },
     { name: 'watch', group: 'workflow', register: registerWatch },
     { name: 'test', group: 'workflow', register: registerTest },
+    { name: 'tree', group: 'workflow', register: registerTree },
     { name: 'config', group: 'project', register: registerConfig },
     { name: 'doctor', group: 'diagnostics', register: registerDoctor },
     { name: 'register', group: 'workflow', register: registerRegister },