@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/lint.js

@@ -1,547 +1,45 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { stat } from 'node:fs/promises';
-import { join } from 'node:path';
-import { Command } from 'commander';
-import { isBrandingManagedPath } from '../core/branding.js';
-import { getProjectPaths, loadConfig } from '../core/config.js';
-import { assertEngineGitReady } from '../core/engine-precondition.js';
-import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
-import { getStatusWithCodes, hasChanges } from '../core/git.js';
-import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
-import { expandUntrackedDirectoryEntries, getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, getWorkingTreeStatus, } from '../core/git-status.js';
-import { extractAffectedFiles } from '../core/patch-apply.js';
-import { buildPatchQueueContext, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, lintPatchSize, measurePatchSize, } from '../core/patch-lint.js';
-import { clearPerPatchLintCache } from '../core/patch-lint-cache.js';
-import { collectDiffFilePaths, tagLintIssues } from '../core/patch-lint-diff-tag.js';
-import { buildLintIgnoreChecks, filterLintIgnoredByOwners, partitionLintIgnoredIssues, } from '../core/patch-lint-ignore.js';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { pathExists } from '../utils/fs.js';
-import { info, intro, outro, success, warn } from '../utils/logger.js';
-import { addAcceptedWaitLockOption } from '../utils/options.js';
-import { stripEnginePrefix } from '../utils/paths.js';
-import { lintPerPatch } from './lint-per-patch.js';
-/**
- * Resolves the diff the lint command should run against. Returns `null` when
- * there is nothing to lint (no matching files, clean tree, or empty diff
- * content). Callers treat that as the early-exit signal and stop.
- *
- * Extracted from {@link lintCommand} so that function stays under the
- * per-function LOC budget. The two file-mode and aggregate-mode branches
- * share no state with the post-lint reporting pipeline.
- *
- * When `binaryName` is provided, the aggregate-mode branch (no explicit file
- * list) excludes paths under `browser/branding/<binaryName>/` from the diff.
- * `status` classifies those paths as `branding`, tool-managed material the
- * operator did not author directly, and without the exclusion
- * `fireforge lint` on a fresh project immediately fails `large-patch-lines`
- * / `large-patch-files` / `missing-license-header` on the generated branding
- * tree. File-list mode (explicit paths) is unaffected: passing a branding
- * file explicitly still lints it.
- */
-async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
-    if (files.length > 0) {
-        const collectedFiles = new Set();
-        let fileStatuses;
-        let untrackedFiles;
-        // Strip a leading `engine/` segment up-front so the rest of the lookup
-        // pipeline (directory stat, modified-files-in-dir, status probe) sees the
-        // engine-relative form. Without it, passing
-        // `engine/browser/base/content/foo.js` falls through to "No modified
-        // files found in the specified paths.", because git sees every path
-        // relative to engine/. The same normalization runs in `register`,
-        // `test`, and `export`.
-        const normalizedFiles = files.map((inputPath) => stripEnginePrefix(inputPath));
-        for (const inputPath of normalizedFiles) {
-            const fullInputPath = join(engineDir, inputPath);
-            let isDirectory = false;
-            try {
-                const fileStat = await stat(fullInputPath);
-                isDirectory = fileStat.isDirectory();
-            }
-            catch {
-                // Treat as file
-            }
-            if (isDirectory) {
-                const dirPath = inputPath.endsWith('/') ? inputPath.slice(0, -1) : inputPath;
-                const modifiedFiles = await getModifiedFilesInDir(engineDir, dirPath);
-                const dirUntrackedFiles = await getUntrackedFilesInDir(engineDir, dirPath);
-                for (const f of modifiedFiles)
-                    collectedFiles.add(f);
-                for (const f of dirUntrackedFiles)
-                    collectedFiles.add(f);
-            }
-            else {
-                if (!fileStatuses)
-                    fileStatuses = await getStatusWithCodes(engineDir);
-                if (!untrackedFiles)
-                    untrackedFiles = await getUntrackedFiles(engineDir);
-                const hasStatus = fileStatuses.some((s) => s.file === inputPath) || untrackedFiles.includes(inputPath);
-                if (hasStatus)
-                    collectedFiles.add(inputPath);
-            }
-        }
-        if (collectedFiles.size === 0) {
-            info('No modified files found in the specified paths.');
-            outro('Nothing to lint');
-            return null;
-        }
-        const diff = await getDiffForFilesAgainstHead(engineDir, [...collectedFiles].sort());
-        if (!diff.trim()) {
-            info('No diff content to lint.');
-            outro('Nothing to lint');
-            return null;
-        }
-        return diff;
-    }
-    if (!(await hasChanges(engineDir))) {
-        info('No changes to lint.');
-        outro('Nothing to lint');
-        return null;
-    }
-    // Aggregate-mode branding exclusion. A fresh-setup workspace carries a
-    // large tool-managed branding diff the operator did not author. Running
-    // the default lint against it fires size and license-header rules on
-    // content that was never intended to survive in the patch queue as-is. The
-    // exclusion mirrors the `branding` bucket in `fireforge status` so the two
-    // views stay consistent.
-    //
-    // `expandUntrackedDirectoryEntries` promotes collapsed `?? dir/` status
-    // rows to individual file entries before the diff pass. Without it, a
-    // patch that introduces a new directory shows up as
-    // `?? browser/modules/<fork>/` and `getDiffForFilesAgainstHead` crashes
-    // with EISDIR reading the directory as if it were a file.
-    if (binaryName) {
-        const rawStatus = await getWorkingTreeStatus(engineDir);
-        const expanded = await expandUntrackedDirectoryEntries(engineDir, rawStatus);
-        const allPaths = [...new Set(expanded.map((entry) => entry.file))];
-        const nonBrandingPaths = allPaths.filter((path) => !isBrandingManagedPath(path, binaryName));
-        const brandingExcluded = allPaths.length - nonBrandingPaths.length;
-        // Drop Furnace-managed paths the same way branding is dropped: their
-        // contents are tool output (overrides, custom widgets, preview-generated
-        // stories) that the operator did not author and never intended to land
-        // on the patch queue. Without the carve-out, a post-`furnace preview`
-        // aggregate `lint` fails with one `missing-license-header` error per
-        // generated story file. Each is header-less on purpose because it is
-        // re-generated from component metadata on every preview run.
-        const filteredPaths = furnacePrefixes
-            ? nonBrandingPaths.filter((path) => ![...furnacePrefixes].some((p) => path.startsWith(p)))
-            : nonBrandingPaths;
-        const furnaceExcluded = nonBrandingPaths.length - filteredPaths.length;
-        if (brandingExcluded > 0) {
-            info(`Excluded ${brandingExcluded} tool-managed branding file${brandingExcluded === 1 ? '' : 's'} from lint. Pass the path explicitly or use \`fireforge lint <path>\` to include them.`);
-        }
-        if (furnaceExcluded > 0) {
-            info(`Excluded ${furnaceExcluded} Furnace-managed file${furnaceExcluded === 1 ? '' : 's'} from lint (deployed components and preview-generated stories). Pass the path explicitly to include them.`);
-        }
-        if (filteredPaths.length === 0) {
-            info('No non-branding, non-Furnace changes to lint.');
-            outro('Nothing to lint');
-            return null;
-        }
-        const diff = await getDiffForFilesAgainstHead(engineDir, filteredPaths.sort());
-        if (!diff.trim()) {
-            info('No diff content to lint.');
-            outro('Nothing to lint');
-            return null;
-        }
-        return diff;
-    }
-    // Fallback path: no binaryName available (a caller without a loaded
-    // config). Lint the full diff so the lint surface stays at least as broad.
-    const diff = await getAllDiff(engineDir);
-    if (!diff.trim()) {
-        info('No diff content to lint.');
-        outro('Nothing to lint');
-        return null;
-    }
-    return diff;
-}
-function buildMaxWarningsMessage(count, maxWarnings, scope) {
-    const scoped = scope ? ` ${scope}` : '';
-    const base = `Patch lint found ${count} warning(s)${scoped}, exceeding --max-warnings ${maxWarnings}.`;
-    return (base +
-        ' 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.');
-}
-/**
- * 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 has no patch-level scope of its own and would otherwise rediscover
- * the suppressed warning every CI run. Attributing each issue's file to its
- * owning patch via `filesAffected` re-establishes the same suppression
- * semantics. Cross-patch findings (forward-import, duplicate-creation) also
- * attribute via `issue.file`, which is the offending site and is owned by
- * some patch.
- *
- * Multiple owners: an issue is dropped if any owning patch waived the
- * rule. This is conservative: it never adds new findings, only drops
- * already-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 filtered = filterLintIgnoredByOwners(issues, ctx.entries.map((entry) => entry.metadata));
-    return { issues: filtered, dropped: issues.length - filtered.length };
-}
-/**
- * Up-front flag validation for `lintCommand`: rejects `--only-introduced`
- * 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
- * and are validated downstream by `selectPatchSubset`.
- */
-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
-    // invocation fails loud instead of silently treating every error as
-    // cumulative and passing.
-    if (options.onlyIntroduced && !options.since) {
-        throw new GeneralError('--only-introduced requires --since <git-rev> so introduced-vs-cumulative can be distinguished.');
-    }
-    if (options.maxWarnings !== undefined &&
-        (!Number.isInteger(options.maxWarnings) || options.maxWarnings < 0)) {
-        throw new InvalidArgumentError('--max-warnings must be a non-negative integer.', '--max-warnings');
-    }
-    // `--patches` only means something in per-patch mode, where it filters
-    // the queue. In aggregate/file-list mode there is no patch loop to narrow.
-    if (options.patches !== undefined && !options.perPatch) {
-        throw new InvalidArgumentError('--patches requires --per-patch.', '--patches');
-    }
-    // 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 InvalidArgumentError('--report requires --per-patch.', '--report');
-    }
-    if (options.notices !== undefined && !options.perPatch) {
-        throw new InvalidArgumentError('--notices requires --per-patch.', '--notices');
-    }
-}
-/**
- * Aggregate-mode patch-size softening: when the linted diff is every
- * applied patch summed (no explicit file scope, multi-patch queue), the
- * `large-patch-lines` / `large-patch-files` counts are an artefact of
- * aggregation rather than a property of any one patch. Surface the
- * `--per-patch` hint and downgrade those two rules to warnings. Per-patch
- * mode keeps them as errors.
- */
-function downgradeAggregateSizeRules(issues, files, ctx) {
-    const aggregateHintApplicable = files.length === 0 && ctx !== undefined && ctx.entries.length > 1;
-    if (aggregateHintApplicable &&
-        issues.some((i) => i.check === 'large-patch-lines' || i.check === 'large-patch-files')) {
-        info('NOTE: aggregate diff across all applied patches. Use `fireforge lint --per-patch` to lint each patch individually; patch-size rules fire against the sum in aggregate mode and are reported as warnings rather than errors here.');
-        for (const issue of issues) {
-            if ((issue.check === 'large-patch-lines' || issue.check === 'large-patch-files') &&
-                issue.severity === 'error') {
-                issue.severity = 'warning';
-            }
-        }
-    }
-}
-/**
- * Evaluates the patch-size rules (`large-patch-files` / `large-patch-lines`)
- * for an ad-hoc explicit-file-list lint, scoped to each file's owning
- * patch rather than the combined file list.
- *
- * Feeding every passed file to `lintExportedPatch` as one synthetic patch
- * makes a cross-patch selection of eight files belonging to four patches
- * report `Patch affects 8 files` even though no single owning patch is
- * oversized. This helper groups the affected files by their owning patch
- * (via the manifest's `filesAffected`), then runs `lintPatchSize` against
- * each owner's real file count + diff, honouring that owner's `tier` and
- * `lintIgnore`, so `lint <files>`, `lint --per-patch`, and
- * `re-export --dry-run` agree on the same size findings for the same files.
- * Files no patch claims are evaluated together as one prospective new patch,
- * preserving the pre-export oversized-change warning.
- *
- * @param engineDir - Absolute engine directory
- * @param filesAffected - Engine-relative files touched by the ad-hoc diff
- * @param ctx - Patch queue context used to attribute file → owning patch
- * @returns Size issues, each attributed to its owning patch by message prefix
- */
-async function lintOwningPatchSizes(engineDir, filesAffected, ctx, config) {
-    const listed = new Set(filesAffected);
-    const owners = new Map();
-    const ownedListed = new Set();
-    for (const entry of ctx.entries) {
-        const md = entry.metadata;
-        if (!md)
-            continue;
-        let ownsAny = false;
-        for (const f of md.filesAffected) {
-            if (listed.has(f)) {
-                ownedListed.add(f);
-                ownsAny = true;
-            }
-        }
-        if (ownsAny)
-            owners.set(entry.filename, entry);
-    }
-    const issues = [];
-    const sizeForFiles = async (relPaths) => {
-        const existing = [];
-        for (const f of relPaths) {
-            if (await pathExists(join(engineDir, f)))
-                existing.push(f);
-        }
-        const diff = existing.length > 0 ? await getDiffForFilesAgainstHead(engineDir, existing) : '';
-        // The file count stays the owner's whole `filesAffected`, as before.
-        return measurePatchSize(engineDir, diff, relPaths, config);
-    };
-    for (const entry of owners.values()) {
-        const md = entry.metadata;
-        if (!md)
-            continue;
-        const size = await sizeForFiles(md.filesAffected);
-        const ignore = buildLintIgnoreChecks(md.lintIgnore);
-        const sized = lintPatchSize(md.filesAffected, size, md.tier, config);
-        for (const issue of partitionLintIgnoredIssues(sized, ignore).kept) {
-            issues.push({ ...issue, message: `${entry.filename}: ${issue.message}` });
-        }
-    }
-    // Files no patch claims are a prospective new patch: evaluate them as one
-    // unit so a genuinely oversized fresh change still surfaces.
-    const unowned = filesAffected.filter((f) => !ownedListed.has(f));
-    if (unowned.length > 0) {
-        const size = await sizeForFiles(unowned);
-        issues.push(...lintPatchSize(unowned, size, undefined, config));
-    }
-    return issues;
-}
-/**
- * Reporting + exit phase of `lintCommand`: tags issues against `--since`,
- * renders every notice/warning/error row, prints the summary, and applies
- * the failure criteria (`--only-introduced` scoping, `--max-warnings`)
- * by throwing GeneralError. Issues must be non-empty.
- */
-async function reportLintOutcome(engineDir, issues, options) {
-    // Diff-scoping: tag each issue as introduced-in-current-task vs
-    // cumulative-pre-existing-drift. Nothing is filtered (the full set still
-    // prints and exit code semantics are unchanged), but the per-line prefix
-    // and summary make triage easier on a large patch series.
-    const sinceActive = Boolean(options.since);
-    if (options.since) {
-        const diffFiles = await collectDiffFilePaths(engineDir, 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(`${tagPrefix(issue)}NOTICE ${formatPatchLintIssue(issue)}`);
-    }
-    for (const issue of warnings) {
-        warn(`${tagPrefix(issue)}${formatPatchLintIssue(issue)}`);
-    }
-    for (const issue of errors) {
-        warn(`${tagPrefix(issue)}ERROR ${formatPatchLintIssue(issue)}`);
-    }
-    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)`);
-    }
-    // Exit-code scope: `--only-introduced` narrows the failure criterion to
-    // issues tagged `introduced`. Cumulative errors still print so the
-    // operator sees the full queue state, but do not fail lint. The case
-    // this serves is a branch whose own diff is clean but whose repo
-    // already carries pre-existing queue errors from older patches.
-    const failingErrors = options.onlyIntroduced
-        ? errors.filter((i) => i.tag === 'introduced')
-        : errors;
-    if (failingErrors.length > 0) {
-        outro('Lint failed');
-        const cumulativeSuppressed = options.onlyIntroduced && errors.length > failingErrors.length
-            ? ` (${errors.length - failingErrors.length} cumulative error(s) suppressed by --only-introduced)`
-            : '';
-        throw new GeneralError(`Patch lint found ${failingErrors.length} ${options.onlyIntroduced ? 'introduced ' : ''}error(s). Fix these before exporting.${cumulativeSuppressed}`);
-    }
-    if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
-        outro('Lint failed');
-        throw new GeneralError(buildMaxWarningsMessage(warnings.length, options.maxWarnings));
-    }
-    // Notices are advisory and do not count as warnings: emitting "passed
-    // with warnings" when only notices fired contradicts the preceding
-    // `0 warning(s)` summary line and reads as a regression. Errors suppressed
-    // by --only-introduced still warrant the "with warnings" outro: they print
-    // as ERROR rows but do not fail the run, which is the same contract the
-    // operator gets from a real warning.
-    const suppressedErrors = options.onlyIntroduced && errors.length > 0;
-    if (warnings.length > 0 || suppressedErrors) {
-        outro('Lint passed with warnings');
-    }
-    else if (notices.length > 0) {
-        outro('Lint passed with notices');
-    }
-    else {
-        outro('Lint passed');
-    }
-}
-/**
- * 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, options = {}) {
-    intro('FireForge Lint');
-    validateLintFlags(options);
-    const paths = getProjectPaths(projectRoot);
-    await assertEngineGitReady(paths.engine);
-    if (options.perPatch) {
-        // Positional arguments in per-patch mode select patches through the
-        // same alias resolution as --patches. 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 `binaryName` can be passed
-    // into the aggregate-mode branding exclusion in `resolveLintDiff`.
-    const config = await loadConfig(projectRoot);
-    // Pull the Furnace-managed prefix set up-front so aggregate lint can
-    // mirror the branding exclusion for Furnace material. Without it,
-    // preview-generated stories under `browser/components/storybook/
-    // stories/furnace/` show up as license-header errors on every
-    // post-preview lint run.
-    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
-    const diff = await resolveLintDiff(paths.engine, files, config.binaryName, furnacePrefixes);
-    if (diff === null)
-        return;
-    const filesAffected = extractAffectedFiles(diff);
-    // Build patch queue context once so it can be shared between the
-    // per-patch ownership resolver and the cross-patch rules.
-    let ctx;
-    if (await pathExists(paths.patches)) {
-        ctx = await buildPatchQueueContext(paths.patches, config);
-    }
-    // Ad-hoc explicit-file-list mode evaluates the patch-size rules per
-    // owning patch (see `lintOwningPatchSizes`), so suppress the synthetic
-    // combined-list size check in the shared pass. Otherwise a cross-patch
-    // selection synthesises a phantom oversized patch from the file count.
-    const fileListMode = files.length > 0 && ctx !== undefined;
-    let issues = [
-        ...(await lintExportedPatch(paths.engine, filesAffected, diff, config, {
-            ...(ctx ? { patchQueueCtx: ctx } : {}),
-            ...(fileListMode ? { skipPatchSize: true } : {}),
-        })),
-    ];
-    if (files.length > 0 && ctx) {
-        issues.push(...(await lintOwningPatchSizes(paths.engine, filesAffected, ctx, config)));
-    }
-    // Cross-patch rules operate over the whole queue, so run them whenever a
-    // patches directory exists. They surface duplicate /dev/null creations
-    // and forward-import chains that the per-patch orchestrator cannot see.
-    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 has no patch-level scope to consult, so a check an
-    // operator explicitly waived in `patches.json` re-surfaces on every
-    // `--since` run (the 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).`);
-        }
-    }
-    downgradeAggregateSizeRules(issues, files, ctx);
-    if (issues.length === 0) {
-        success('No lint issues found.');
-        outro('Lint passed');
-        return;
-    }
-    await reportLintOutcome(paths.engine, issues, options);
-}
-/** Registers the lint command on the CLI program. */
-export function registerLint(program, { getProjectRoot, withErrorHandling }) {
-    const lint = program
-        .command('lint [paths...]')
-        .description('Lint engine changes against patch quality rules. Default: aggregate diff against HEAD ' +
-        '(every applied patch summed). Use --per-patch for per-patch scope, or pass explicit ' +
-        'file paths to narrow to those.')
-        .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 or whitespace lists, full filenames/stems, bare order numbers, 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>.')
-        .option('--notices <mode>', 'With --per-patch: "full" (default) prints every NOTICE line; "summary" prints one line per check with its count and patch count. The full list stays in --report. Errors and warnings always print in full.')
-        .action(withErrorHandling(async (paths, options) => {
-        const lintOptions = {};
-        if (options.since !== undefined) {
-            lintOptions.since = options.since;
-        }
-        if (options.onlyIntroduced !== undefined) {
-            lintOptions.onlyIntroduced = options.onlyIntroduced;
-        }
-        if (options.perPatch !== undefined) {
-            lintOptions.perPatch = options.perPatch;
-        }
-        if (options.patches !== undefined) {
-            lintOptions.patches = options.patches;
-        }
-        if (options.maxWarnings !== undefined) {
-            const maxWarnings = Number(options.maxWarnings);
-            if (!Number.isInteger(maxWarnings) || maxWarnings < 0) {
-                throw new InvalidArgumentError('--max-warnings must be a non-negative integer.', '--max-warnings');
-            }
-            lintOptions.maxWarnings = maxWarnings;
-        }
-        if (options.cache === false) {
-            lintOptions.noCache = true;
-        }
-        if (options.report !== undefined) {
-            lintOptions.report = options.report;
-        }
-        if (options.notices !== undefined) {
-            if (options.notices !== 'summary' && options.notices !== 'full') {
-                throw new InvalidArgumentError(`--notices must be "summary" or "full" (got "${options.notices}").`, '--notices');
-            }
-            lintOptions.notices = options.notices;
-        }
-        await lintCommand(getProjectRoot(), paths, lintOptions);
-    }));
-    // This action also has subcommands; all its wait flags are accept-only.
-    addAcceptedWaitLockOption(lint);
-    const lintCache = lint
-        .command('cache')
-        .description('Manage the per-patch lint result cache')
-        // Commander routes `fireforge lint cache` here even when the operator
-        // meant to lint an engine directory literally named `cache`. A bare
-        // `lint cache` (no subcommand) would otherwise silently do nothing, so
-        // make the ambiguity explicit instead of doing the wrong operation quietly.
-        .action(withErrorHandling(() => {
-        info('Nothing to do: "lint cache" manages the lint result cache (try "lint cache clear"). ' +
-            'To lint a directory named cache/, disambiguate with a trailing slash: "fireforge lint cache/".');
-        return Promise.resolve();
-    }));
-    addAcceptedWaitLockOption(lintCache);
-    lintCache
-        .command('clear')
-        .description('Clear cached per-patch lint results')
-        .action(withErrorHandling(async () => {
-        intro('FireForge Lint Cache');
-        await clearPerPatchLintCache(getProjectRoot());
-        success('Cleared per-patch lint cache.');
-        outro('Lint cache cleared');
-    }));
-}
+import { arg, defineCommand, lockOptions, lockWaitMs, opt } from '../cli/command.js';
+import { FireForgeError } from '../kernel/errors.js';
+import { isVerbose } from '../kernel/log.js';
+import { lintReportJson, lintVerdict, renderLintReport, runLint } from '../lint/index.js';
+import { lintSubject, typeCacheDir, withOwnedRead } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+export const lint = defineCommand({
+    name: 'lint',
+    summary: 'Check the owned changes against the quality rules',
+    description: 'Runs every rule over the owned changes (patchLint, patchPolicy, checkJs) and applies the ' +
+        "groups' waivers. Errors fail the run; warnings fail it past --max-warnings.",
+    group: 'Daily',
+    args: { paths: arg.list('Engine-relative files or directories to report on') },
+    options: {
+        maxWarnings: opt.integer('Fail when more warnings than this remain', { min: 0 }),
+        perPatch: opt.flag('Patch mode: judge the stored queue patch by patch instead of what the engine holds'),
+        ...lockOptions,
+    },
+    json: true,
+    run: async (ctx, { paths }, { maxWarnings, perPatch, waitLock }) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        await withOwnedRead(project, { command: 'lint', waitMs: lockWaitMs(waitLock) }, async () => {
+            const subject = await lintSubject(project, { scope: perPatch ? 'queue' : 'engine' });
+            const report = await runLint(subject.changes, subject.engine, project.config, {
+                projectRoot: project.root,
+                sequential: subject.sequential,
+                components: subject.components,
+                paths,
+                cacheDir: typeCacheDir(project),
+                ...(subject.tokens === undefined ? {} : { tokens: subject.tokens }),
+            });
+            const verdict = lintVerdict(report, maxWarnings);
+            for (const line of renderLintReport(report, verdict, isVerbose()))
+                ctx.out.line(line);
+            ctx.out.json(lintReportJson(report, verdict));
+            if (!verdict.pass) {
+                throw new FireForgeError('lint-failed', `Lint failed: ${verdict.reason ?? ''}.`, {
+                    hint: 'Fix the findings listed above, or, for a reviewed exception, add the rule to the ' +
+                        "group's lintIgnore.",
+                });
+            }
+        });
+    },
+});

package/dist/src/commands/merge-driver.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { dirname, resolve } from 'node:path';
+import { arg, defineCommand } from '../cli/command.js';
+import { FireForgeError } from '../kernel/errors.js';
+import { warn } from '../kernel/log.js';
+import { pinnedPristine } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+import { installMergeDriver, requireSourceMode, runMergeDriver } from '../source/index.js';
+const run = defineCommand({
+    name: 'run',
+    summary: 'Merge one owned file (git runs this)',
+    hidden: true,
+    args: {
+        base: arg.path('%O: the ancestor version'),
+        ours: arg.path('%A: our version, which receives the result'),
+        theirs: arg.path('%B: their version'),
+        path: arg.string('%P: the path being merged'),
+        label: arg.string('%S: the ancestor label', { optional: true }),
+    },
+    run: async (ctx, args) => {
+        const project = requireSourceMode(await loadProject(dirname(resolve(ctx.cwd, args.path)), ctx.env));
+        const clean = await runMergeDriver(project, () => pinnedPristine(project), {
+            base: args.base,
+            ours: args.ours,
+            theirs: args.theirs,
+            path: args.path,
+            ...(args.label === undefined ? {} : { label: args.label }),
+        });
+        if (!clean) {
+            throw new FireForgeError('merge-conflict', `Conflicts left in ${args.path}.`, {
+                hint: 'Resolve the conflict markers in the file, then "git add" it.',
+            });
+        }
+    },
+});
+const install = defineCommand({
+    name: 'install',
+    summary: 'Configure the merge driver in this repository',
+    json: true,
+    run: async (ctx) => {
+        const project = requireSourceMode(await loadProject(ctx.cwd, ctx.env));
+        const installed = await installMergeDriver(project);
+        if (!installed.labelSupported) {
+            warn('This git does not pass the ancestor label to merge drivers (Git 2.44 or later does); ' +
+                'first touches of one upstream file will conflict as git reports them.');
+        }
+        ctx.out.line(`merge.fireforge.driver = ${installed.driver}`);
+        ctx.out.json({ ...installed });
+    },
+});
+export const mergeDriver = defineCommand({
+    name: 'merge-driver',
+    summary: 'Git merge driver that merges first touches of upstream files against pristine',
+    group: 'Source',
+    subcommands: [install, run],
+});