@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/furnace.js

@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { arg, defineCommand, lockOptions, lockWaitMs, opt } from '../cli/command.js';
+import { componentDiff, createComponent, deploymentStatus, loadFurnaceConfig, overrideComponent, removeComponent, renameComponent, TEST_STYLES, typingDrift, updateTypingFiles, validateComponents, validationPasses, } from '../furnace/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { deployComponents, trackedFiles, withWorkspace } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+import { workspaceOptions } from './workspace.js';
+async function target(ctx) {
+    const project = await loadProject(ctx.cwd, ctx.env);
+    return { project, tracked: await trackedFiles(project, { declare: true }) };
+}
+/** Runs `body` in the workspace whose engine the components deploy into. */
+function inWorkspace(project, command, opts, body) {
+    return withWorkspace(project, { command: `furnace ${command}`, workspace: opts.workspace, waitMs: lockWaitMs(opts.waitLock) }, body);
+}
+const dryRun = opt.flag('Show what would change without writing');
+function reportEdit(ctx, result, dry) {
+    for (const path of result.paths)
+        ctx.out.line(`${dry ? 'would change' : 'changed'} ${path}`);
+    for (const note of result.notes)
+        ctx.out.line(`note: ${note}`);
+    ctx.out.json({ dryRun: dry, paths: result.paths, notes: result.notes });
+}
+function reportDeployment(ctx, result, dry) {
+    const touched = result.components.filter((component) => component.status !== 'current');
+    for (const component of touched) {
+        const verb = component.status === 'removed' ? 'undeploy' : 'deploy';
+        ctx.out.line(`${dry ? `would ${verb}` : `${verb}ed`} ${component.name}: ${component.reasons.join('; ')}`);
+    }
+    if (!result.changed)
+        ctx.out.line('Components are current.');
+    ctx.out.json({ ...result, dryRun: dry });
+}
+const create = defineCommand({
+    name: 'create',
+    summary: 'Create a custom component',
+    args: { name: arg.string('Tag of the new element, such as moz-my-widget') },
+    options: {
+        description: opt.string('What the component is', { short: 'd', valueName: 'text' }),
+        localized: opt.flag('Give it its own Fluent file'),
+        sharedFtl: opt.string('Share this existing feature Fluent file instead (implies --localized)', {
+            valueName: 'path',
+        }),
+        register: opt.flag('List the element in customElements.js', { negatable: true, default: true }),
+        compose: opt.list('A component it renders inside its template', { valueName: 'tag' }),
+        tests: opt.enum(TEST_STYLES, 'Scaffold a test in this harness'),
+        dryRun,
+        ...lockOptions,
+    },
+    json: true,
+    run: async (ctx, { name }, opts) => {
+        const { project, tracked } = await target(ctx);
+        const result = await createComponent(project, tracked, name, {
+            ...(opts.description === undefined ? {} : { description: opts.description }),
+            localized: opts.localized,
+            ...(opts.sharedFtl === undefined ? {} : { sharedFtl: opts.sharedFtl }),
+            register: opts.register,
+            composes: opts.compose,
+            ...(opts.tests === undefined ? {} : { tests: opts.tests }),
+            dryRun: opts.dryRun,
+            waitMs: lockWaitMs(opts.waitLock),
+        });
+        reportEdit(ctx, result, opts.dryRun);
+    },
+});
+const apply = defineCommand({
+    name: 'apply',
+    summary: 'Deploy the components into the engine',
+    description: 'Writes every component file whose engine copy differs, removes what components no longer have, ' +
+        'and brings jar.mn and customElements.js in line, in one transaction. Unchanged components cost nothing.',
+    options: { dryRun, ...workspaceOptions },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        const { project } = await target(ctx);
+        const result = await inWorkspace(project, 'apply', opts, (workspace) => deployComponents(workspace, { dryRun: opts.dryRun, waitMs: lockWaitMs(opts.waitLock) }));
+        reportDeployment(ctx, result, opts.dryRun);
+    },
+});
+const status = defineCommand({
+    name: 'status',
+    summary: 'List the components and whether the engine holds them as the project has them',
+    options: { ...workspaceOptions },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        const { project } = await target(ctx);
+        const result = await inWorkspace(project, 'status', opts, (workspace) => deploymentStatus(project, workspace));
+        for (const component of result.components) {
+            const why = component.reasons.length === 0 ? '' : `: ${component.reasons.join('; ')}`;
+            ctx.out.line(`${component.name} (${component.kind}) ${component.status}${why}`);
+        }
+        if (result.components.length === 0)
+            ctx.out.line('furnace.json lists no components.');
+        ctx.out.json(result);
+    },
+});
+const validate = defineCommand({
+    name: 'validate',
+    summary: 'Check the components against the accessibility, compatibility and token rules',
+    args: { name: arg.string('Judge only this component', { optional: true }) },
+    options: {
+        maxWarnings: opt.integer('Also fail when more warnings than this remain', { min: 0 }),
+        ...workspaceOptions,
+    },
+    json: true,
+    verdict: true,
+    run: async (ctx, { name }, opts) => {
+        const { project, tracked } = await target(ctx);
+        const report = await inWorkspace(project, 'validate', opts, (workspace) => validateComponents(project, tracked, {
+            workspace,
+            ...(name === undefined ? {} : { component: name }),
+        }));
+        for (const finding of report.findings) {
+            ctx.out.line(`${finding.severity} ${finding.component} [${finding.check}] ${finding.message}`);
+        }
+        for (const finding of report.excepted) {
+            ctx.out.line(`excepted ${finding.component} [${finding.check}] ${finding.reason}`);
+        }
+        const pass = validationPasses(report, opts.maxWarnings);
+        ctx.out.line(`${report.judged} component(s): ${report.errors} error(s), ${report.warnings} warning(s)`);
+        ctx.out.json({ pass, ...report });
+        ctx.out.verdict(pass, { errors: report.errors, warnings: report.warnings });
+        if (!pass) {
+            throw new FireForgeError('furnace-validation-failed', 'Component validation failed.', {
+                exitCode: ExitCode.FURNACE_ERROR,
+                hint: 'Fix the findings above. A warning that is reviewed and accepted goes in ' +
+                    'validationExceptions of furnace.json; an error cannot be excepted.',
+            });
+        }
+    },
+});
+const types = defineCommand({
+    name: 'types',
+    summary: 'Write the jsconfig paths and the tag map generated from the components',
+    options: {
+        check: opt.flag('Write nothing; fail while a generated file is out of date'),
+        ...lockOptions,
+    },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        const { project, tracked } = await target(ctx);
+        if (opts.check) {
+            const drift = await typingDrift(project, await loadFurnaceConfig(project), tracked);
+            for (const file of drift)
+                ctx.out.line(`${file.file}: ${file.detail}`);
+            ctx.out.json({ current: drift.length === 0, drift });
+            if (drift.length > 0) {
+                throw new FireForgeError('furnace-typing-drift', 'Generated typing files are out of date.', {
+                    exitCode: ExitCode.FURNACE_ERROR,
+                    hint: 'Run "fireforge furnace types".',
+                });
+            }
+            return;
+        }
+        reportEdit(ctx, await updateTypingFiles(project, tracked, { waitMs: lockWaitMs(opts.waitLock) }), false);
+    },
+});
+const diff = defineCommand({
+    name: 'diff',
+    summary: 'Show how components differ from their deployed copy (custom) or the stock files (override)',
+    args: { name: arg.string('Only this component', { optional: true }) },
+    options: { ...workspaceOptions },
+    run: async (ctx, { name }, opts) => {
+        const { project } = await target(ctx);
+        ctx.out.write(await inWorkspace(project, 'diff', opts, (workspace) => componentDiff(project, workspace, name)));
+    },
+});
+const rename = defineCommand({
+    name: 'rename',
+    summary: 'Rename a component, its files, its tests and every reference to it',
+    args: { from: arg.string('Current name'), to: arg.string('New name') },
+    options: { dryRun, ...lockOptions },
+    json: true,
+    run: async (ctx, { from, to }, opts) => {
+        const { project, tracked } = await target(ctx);
+        const options = { dryRun: opts.dryRun, waitMs: lockWaitMs(opts.waitLock) };
+        reportEdit(ctx, await renameComponent(project, tracked, from, to, options), opts.dryRun);
+    },
+});
+const remove = defineCommand({
+    name: 'remove',
+    summary: 'Remove a component, its tests and its furnace.json entry',
+    args: { name: arg.string('The component') },
+    options: { dryRun, ...lockOptions },
+    json: true,
+    run: async (ctx, { name }, opts) => {
+        const { project, tracked } = await target(ctx);
+        const options = { dryRun: opts.dryRun, waitMs: lockWaitMs(opts.waitLock) };
+        reportEdit(ctx, await removeComponent(project, tracked, name, options), opts.dryRun);
+    },
+});
+const override = defineCommand({
+    name: 'override',
+    summary: 'Start overriding a stock component with a copy in components/overrides/',
+    args: { name: arg.string('The stock component, such as moz-button') },
+    options: {
+        description: opt.string('Why it is overridden', { short: 'd', valueName: 'text' }),
+        cssOnly: opt.flag('Copy and deploy only its stylesheets'),
+        from: opt.string('Engine directory of the stock component (default toolkit/content/widgets/<name>)', { valueName: 'dir' }),
+        dryRun,
+        ...workspaceOptions,
+    },
+    json: true,
+    run: async (ctx, { name }, opts) => {
+        const { project, tracked } = await target(ctx);
+        const result = await inWorkspace(project, 'override', opts, (workspace) => overrideComponent(project, tracked, workspace, name, {
+            ...(opts.description === undefined ? {} : { description: opts.description }),
+            cssOnly: opts.cssOnly,
+            ...(opts.from === undefined ? {} : { from: opts.from }),
+            dryRun: opts.dryRun,
+            waitMs: lockWaitMs(opts.waitLock),
+        }));
+        reportEdit(ctx, result, opts.dryRun);
+    },
+});
+export const furnace = defineCommand({
+    name: 'furnace',
+    summary: 'Create, deploy and validate UI components',
+    group: 'Components',
+    subcommands: [create, apply, status, validate, types, diff, rename, remove, override],
+});

package/dist/src/commands/gate.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { acceptGate, checkJson, gateFailure, gateStatus, renderCheck, renderGate, runGate, VERIFIED_REF, } from '../check/index.js';
+import { arg, defineCommand, lockWaitMs, opt } from '../cli/command.js';
+import { loadProject } from '../project/index.js';
+import { workspaceOptions } from './workspace.js';
+const accept = defineCommand({
+    name: 'accept',
+    summary: "Record a person's decision for the checked-out commit",
+    description: 'Records who decided, when, and the note for a gate.acceptance entry, against the tree of ' +
+        'the checked-out commit. The lanes the entry names as evidence must have passed for this ' +
+        'commit in this checkout. The record is a git ref, shared by every worktree.',
+    args: { id: arg.string('The acceptance ID from gate.acceptance') },
+    options: {
+        note: opt.string('What was looked at and decided', { required: true, valueName: 'text' }),
+        by: opt.string("Who decides (default: the repository's user.name, else the login name)", {
+            valueName: 'name',
+        }),
+    },
+    json: true,
+    run: async (ctx, { id }, opts) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const result = await acceptGate(project, id, { note: opts.note, by: opts.by });
+        ctx.out.line(`Recorded "${id}" by ${result.acceptance.by} for commit ${result.commit.slice(0, 12)}.`);
+        ctx.out.line(result.pending.length === 0
+            ? 'Every acceptance is recorded; run "fireforge gate" to move the verified ref.'
+            : `Still outstanding: ${result.pending.join(', ')}.`);
+        ctx.out.json({ ...result });
+    },
+});
+const status = defineCommand({
+    name: 'status',
+    summary: 'Show where the verified ref is and what the gate recorded for HEAD',
+    json: true,
+    run: async (ctx) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const report = await gateStatus(project);
+        const short = (commit) => commit.slice(0, 12);
+        const where = {
+            verified: `${VERIFIED_REF} is at HEAD (${short(report.head)}).`,
+            ahead: `HEAD (${short(report.head)}) is ${report.ahead ?? 0} commit(s) ahead of ${VERIFIED_REF} (${short(report.verified ?? '')}).`,
+            diverged: `HEAD (${short(report.head)}) does not descend from ${VERIFIED_REF} (${short(report.verified ?? '')}).`,
+            unverified: `No commit is verified yet; HEAD is ${short(report.head)}.`,
+        };
+        ctx.out.line(where[report.relation]);
+        if (!report.clean)
+            ctx.out.line('The working tree has uncommitted changes.');
+        if (report.result === undefined) {
+            ctx.out.line('No gate result is recorded for HEAD in this checkout.');
+        }
+        else {
+            const red = report.result.entries.filter((entry) => entry.status !== 'pass');
+            ctx.out.line(`The gate ${report.result.pass ? 'passed' : 'failed'} on HEAD at ${report.result.finishedAt}` +
+                (red.length === 0
+                    ? '.'
+                    : `: ${red.map((entry) => `${entry.id} ${entry.status}`).join(', ')}.`));
+        }
+        for (const [id, acceptance] of Object.entries(report.accepted)) {
+            ctx.out.line(`accepted  ${id}  by ${acceptance.by} at ${acceptance.at}: ${acceptance.note}`);
+        }
+        for (const id of report.pending)
+            ctx.out.line(`pending   ${id}`);
+        ctx.out.json({
+            ...report,
+            verified: report.verified ?? null,
+            ahead: report.ahead ?? null,
+            result: report.result ?? null,
+        });
+    },
+});
+export const gate = defineCommand({
+    name: 'gate',
+    summary: 'Check, build and test the committed tree; on a pass, mark the commit verified',
+    description: 'On a clean committed tree, in one workspace: check, the build (gate.build), then every ' +
+        'declared lane, stress run, negative control and smoke start. One run reports every entry. ' +
+        `When all pass and every gate.acceptance is recorded, ${VERIFIED_REF} moves to the commit, ` +
+        'fast-forward only. Outstanding acceptances leave the result pending, and the next gate ' +
+        'reuses the recorded pass. A commit changing only gate.documents paths needs check alone. ' +
+        '--lane is feedback only: it runs the named entries plus the build on the working tree ' +
+        'as it is, committed or not, runs no check, records nothing and never moves ' +
+        `${VERIFIED_REF}.`,
+    group: 'Daily',
+    options: {
+        lane: opt.list('Feedback only: run this declared entry (an ID, or kind:id) and the build on the working ' +
+            'tree as it is, with no check, no record and no move of the verified ref; repeat for several', { valueName: 'id' }),
+        allowRewrite: opt.flag('Move the verified ref to a commit that does not descend from it'),
+        ...workspaceOptions,
+    },
+    constraints: { exclusive: [['lane', 'allowRewrite']] },
+    json: true,
+    verdict: true,
+    subcommands: [accept, status],
+    run: async (ctx, _args, opts) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const report = await runGate(project, {
+            only: opts.lane,
+            allowRewrite: opts.allowRewrite,
+            workspace: opts.workspace,
+            waitMs: lockWaitMs(opts.waitLock),
+        });
+        if (report.check !== undefined)
+            for (const line of renderCheck(report.check))
+                ctx.out.line(line);
+        for (const line of renderGate(report))
+            ctx.out.line(line);
+        ctx.out.json({
+            outcome: report.outcome,
+            basis: report.basis,
+            pass: report.pass,
+            commit: report.commit ?? null,
+            tree: report.tree ?? null,
+            entries: report.entries,
+            check: report.check === undefined ? null : checkJson(report.check),
+            pending: report.pending,
+            artifacts: report.artifacts ?? null,
+        });
+        const red = report.entries.filter((entry) => entry.status === 'fail').map((entry) => entry.id);
+        ctx.out.verdict(report.pass, {
+            result: report.outcome,
+            ...(report.pass ? {} : { reason: 'gate-failed', failed: red.join(',') }),
+            ...(report.commit === undefined ? {} : { commit: report.commit }),
+            ...(report.pending.length === 0 ? {} : { accept: report.pending.join(',') }),
+        });
+        const failure = gateFailure(report);
+        if (failure !== undefined)
+            throw failure;
+    },
+});