@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/config/previous.js

@@ -0,0 +1,404 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The previous format of `fireforge.json`, and its conversion to the current
+ * one. This file is the only place that knows the previous keys.
+ *
+ * {@link upgradeConfig} is a pure function of the document. Every key it
+ * rewrites or drops is reported with its path and the reason, and whatever
+ * it cannot convert without a decision is a blocker: the caller then writes
+ * nothing. A document already in the current format converts to itself with
+ * nothing reported.
+ */
+import { isRecord, omitKeys } from '../kernel/json.js';
+import { CHECK_STEPS } from './schema/check.js';
+import { ARTIFACTS_PLACEHOLDER } from './schema/gate.js';
+import { configSchema } from './schema/index.js';
+/** The license a project without a `license` key had. */
+const PREVIOUS_DEFAULT_LICENSE = 'MPL-2.0';
+class Conversion {
+    converted = [];
+    removed = [];
+    manual = [];
+    blockers = [];
+    convert(key, message) {
+        this.converted.push({ key, message });
+    }
+    remove(key, message) {
+        this.removed.push({ key, message });
+    }
+    review(key, message) {
+        this.manual.push({ key, message });
+    }
+    block(key, message) {
+        this.blockers.push({ key, message });
+    }
+    /** Drops the listed keys of an object that are present, each with its reason. */
+    drop(object, at, reasons) {
+        const kept = {};
+        for (const [key, value] of Object.entries(object)) {
+            const reason = reasons[key];
+            if (reason === undefined || value === undefined)
+                kept[key] = value;
+            else
+                this.remove(`${at}.${key}`, reason);
+        }
+        return kept;
+    }
+}
+function objects(value) {
+    const isObject = (entry) => isRecord(entry);
+    return Array.isArray(value) && value.every(isObject) ? value : undefined;
+}
+function strings(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+        ? value
+        : undefined;
+}
+/** `sources` becomes `mode` and `source`. */
+function upgradeSources(document, conversion) {
+    const { sources, ...rest } = document;
+    if (sources === undefined)
+        return document;
+    if (!isRecord(sources) || sources['schemaVersion'] !== 1 || sources['mode'] !== 'authored') {
+        conversion.block('sources', 'is not a source-mode declaration this version can read (schemaVersion 1, mode "authored")');
+        return document;
+    }
+    conversion.convert('sources', 'is now "mode": "source" and the "source" block');
+    return {
+        ...rest,
+        mode: 'source',
+        source: {
+            root: sources['root'],
+            metadataRoot: sources['metadataRoot'],
+            pristineCommit: sources['pristineCommit'],
+        },
+    };
+}
+const LANE_REMOVED = {
+    owns: 'every lane runs in every gate; no lane is selected by the paths a change touches',
+    quiet: 'a gate runs its entries one after another in one workspace',
+    args: 'a lane takes no further test options; dispatch, headed, env, uploadDir and machArgs remain',
+    keepAwake: 'the gate does not manage the host’s sleep',
+    holdFront: 'a headed lane holds the display lock for its whole run',
+    throttle: 'lanes are not throttled',
+};
+function upgradeValidator(value, at, conversion) {
+    return isRecord(value)
+        ? conversion.drop(value, at, { footprint: 'validators are not scheduled by footprint' })
+        : value;
+}
+function upgradeLane(lane, at, conversion) {
+    const kept = conversion.drop(lane, at, {
+        ...LANE_REMOVED,
+        context: 'a stress run takes no context lanes',
+    });
+    if (kept['validate'] === undefined)
+        return kept;
+    const validate = upgradeValidator(kept['validate'], `${at}.validate`, conversion);
+    const command = isRecord(validate) ? strings(validate['command']) : undefined;
+    if (kept['uploadDir'] === true && command?.some((word) => word.includes(ARTIFACTS_PLACEHOLDER))) {
+        conversion.review(`${at}.validate.command`, `the harness uploads into ${ARTIFACTS_PLACEHOLDER}/upload, not ${ARTIFACTS_PLACEHOLDER}: an argument naming an uploaded file needs that directory`);
+    }
+    return { ...kept, validate };
+}
+/**
+ * A smoke start's argument vector as structured keys: the `fireforge run`
+ * options it used, then the browser's own arguments after `--`.
+ */
+function upgradeRun(run, at, conversion) {
+    const kept = conversion.drop(run, at, {
+        quiet: 'a gate runs its entries one after another in one workspace',
+        env: 'a smoke start takes no environment',
+        uploadDir: 'a smoke start writes into its output directory, which {artifacts} names',
+        keepAwake: 'the gate does not manage the host’s sleep',
+    });
+    const args = strings(kept['args']);
+    if (args === undefined)
+        return kept;
+    const next = omitKeys(kept, 'args');
+    let index = 0;
+    for (; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        const value = args[index + 1];
+        if (arg === '--') {
+            index += 1;
+            break;
+        }
+        if (arg === '--headless') {
+            next['headless'] = true;
+        }
+        else if (arg === '--smoke-exit' && /^[1-9]\d*$/.test(value ?? '')) {
+            next['smokeExit'] = Number(value);
+            index += 1;
+        }
+        else if (arg === '--console-allow-file' && value !== undefined) {
+            next['consoleAllowFile'] = value;
+            index += 1;
+        }
+        else if (arg === '--capture-console' && value === `${ARTIFACTS_PLACEHOLDER}/console.txt`) {
+            // Where a smoke start always writes its console.
+            index += 1;
+        }
+        else {
+            conversion.block(`${at}.args[${index}]`, `"${arg}" has no structured equivalent; a run takes smokeExit, headless, consoleAllowFile and args (the browser's arguments)`);
+            return kept;
+        }
+    }
+    const browserArgs = args.slice(index);
+    if (browserArgs.length > 0)
+        next['args'] = browserArgs;
+    if (next['smokeExit'] === undefined) {
+        conversion.block(`${at}.args`, 'names no --smoke-exit <seconds>, which a run needs as smokeExit');
+        return kept;
+    }
+    conversion.convert(`${at}.args`, 'is now smokeExit, headless, consoleAllowFile and args');
+    if (kept['validate'] !== undefined) {
+        next['validate'] = upgradeValidator(kept['validate'], `${at}.validate`, conversion);
+    }
+    return next;
+}
+function upgradeEntries(gate, list, upgrade) {
+    const entries = objects(gate[list]);
+    if (entries === undefined)
+        return gate;
+    return {
+        ...gate,
+        [list]: entries.map((entry, index) => upgrade(entry, `proof.gate.${list}[${index}]`)),
+    };
+}
+/** `proof` becomes `gate`. */
+function upgradeProof(document, conversion) {
+    const { proof, ...rest } = document;
+    if (proof === undefined)
+        return document;
+    if (!isRecord(proof)) {
+        conversion.block('proof', 'is not an object');
+        return document;
+    }
+    if (rest['gate'] !== undefined) {
+        conversion.block('proof', 'stands beside a "gate" section; keep one of them');
+        return document;
+    }
+    conversion.convert('proof', 'is now "gate"');
+    const { gate: declared, noneRoutes, ...other } = conversion.drop(proof, 'proof', {
+        mainBranch: 'the gate judges the checked-out commit, whatever its branch',
+        consumerLimit: 'there is no proof ledger to bound',
+    });
+    for (const key of Object.keys(other))
+        conversion.block(`proof.${key}`, 'is not a known key');
+    let gate = {};
+    if (isRecord(declared)) {
+        gate = conversion.drop(declared, 'proof.gate', {
+            mode: 'the gate builds the development configuration',
+            check: 'the gate always runs check first',
+        });
+        const lane = (entry, at) => upgradeLane(entry, at, conversion);
+        gate = upgradeEntries(gate, 'lanes', lane);
+        gate = upgradeEntries(gate, 'stress', lane);
+        gate = upgradeEntries(gate, 'controls', (entry, at) => conversion.drop(entry, at, {
+            compiled: 'a control builds what its mutation needs',
+            always: 'every control runs in every gate',
+        }));
+        gate = upgradeEntries(gate, 'runs', (entry, at) => upgradeRun(entry, at, conversion));
+        gate = upgradeEntries(gate, 'acceptance', (entry, at) => conversion.drop(entry, at, {
+            owns: 'an acceptance is owed by every gate that is not documents-only',
+        }));
+    }
+    else if (declared !== undefined) {
+        conversion.block('proof.gate', 'is not an object');
+    }
+    if (noneRoutes !== undefined) {
+        conversion.convert('proof.noneRoutes', 'is now gate.documents: a commit touching only these paths still runs check');
+        gate = { ...gate, documents: noneRoutes };
+    }
+    return Object.keys(gate).length === 0 ? rest : { ...rest, gate };
+}
+const SHELL_SYNTAX = /[|&;<>()$`\\"'*?[\]{}~#!\n]/;
+/** A shell line as an argument vector: split on blanks when it is plain words, else run by `sh -c`. */
+function commandVector(line) {
+    return SHELL_SYNTAX.test(line) ? ['sh', '-c', line] : line.trim().split(/\s+/);
+}
+function upgradeExtraStep(step, at, conversion) {
+    const name = typeof step['name'] === 'string' ? step['name'] : '';
+    const command = step['command'];
+    if (typeof command !== 'string')
+        return step;
+    const vector = commandVector(command);
+    if (CHECK_STEPS.some((builtin) => builtin === name)) {
+        const builtinCommand = name.split('-');
+        const runsBuiltin = /(^|\/)fireforge$/.test(vector[0] ?? '') &&
+            vector.slice(1).join(' ') === builtinCommand.join(' ');
+        if (runsBuiltin) {
+            conversion.remove(at, `"${name}" is a built-in step of check`);
+            return undefined;
+        }
+        conversion.block(`${at}.name`, `"${name}" is the name of a built-in step; rename this step`);
+        return step;
+    }
+    if (step['cwd'] !== undefined && step['cwd'] !== '.') {
+        conversion.block(`${at}.cwd`, 'extra steps run from the project root; move the directory change into the command');
+        return step;
+    }
+    conversion.convert(`${at}.command`, vector[0] === 'sh' && vector[1] === '-c'
+        ? 'is now an argument vector; it uses shell syntax, so it runs through sh -c'
+        : 'is now an argument vector');
+    const kept = conversion.drop(step, at, {
+        cwd: 'extra steps run from the project root',
+        footprint: 'steps are not scheduled by footprint; set "engine": true on a step that reads engine files',
+    });
+    return { ...kept, command: vector };
+}
+function upgradeCheck(document, conversion) {
+    const check = document['check'];
+    if (!isRecord(check))
+        return document;
+    let next = conversion.drop(check, 'check', {
+        timeout: 'built-in steps have no timeout; an extra step has its own, 600 seconds by default',
+        timeouts: 'built-in steps have no timeout',
+    });
+    if (isRecord(next['status'])) {
+        next = {
+            ...next,
+            status: conversion.drop(next['status'], 'check.status', {
+                failOnUnknown: 'an unknown status code is refused by the schema',
+            }),
+        };
+    }
+    const steps = objects(next['extraSteps']);
+    if (steps !== undefined) {
+        const upgraded = steps.flatMap((step, index) => {
+            const result = upgradeExtraStep(step, `check.extraSteps[${index}]`, conversion);
+            return result === undefined ? [] : [result];
+        });
+        next = upgraded.length === 0 ? omitKeys(next, 'extraSteps') : { ...next, extraSteps: upgraded };
+        if (upgraded.some((step) => Array.isArray(step['command']) && step['engine'] === undefined)) {
+            conversion.review('check.extraSteps', 'a step that reads engine files needs "engine": true: it then runs holding a workspace, with FIREFORGE_ENGINE naming the engine');
+        }
+    }
+    return { ...document, check: next };
+}
+const LINT_SWITCHES = {
+    jsdocClassMethods: 'jsdoc-class-method',
+    chromeScriptJsDoc: 'chrome-script-jsdoc',
+    testAssertionFloor: 'test-needs-assertion',
+};
+function upgradeLint(document, conversion) {
+    const lint = document['patchLint'];
+    if (!isRecord(lint))
+        return document;
+    const declared = isRecord(lint['rules']) ? lint['rules'] : {};
+    const rules = { ...declared };
+    const kept = {};
+    for (const [key, value] of Object.entries(lint)) {
+        const rule = LINT_SWITCHES[key];
+        if (rule === undefined) {
+            kept[key] = value;
+        }
+        else if (rules[rule] !== undefined && rules[rule] !== value) {
+            conversion.block(`patchLint.${key}`, `disagrees with patchLint.rules["${rule}"]; keep one`);
+            kept[key] = value;
+        }
+        else {
+            rules[rule] = value;
+            conversion.convert(`patchLint.${key}`, `is now patchLint.rules["${rule}"]`);
+        }
+    }
+    const next = conversion.drop(kept, 'patchLint', {
+        forwardRegistration: 'forward-registration always judges a patch queue; set its severity in patchLint.rules',
+        prettier: 'formatting is not a lint rule; run Prettier as a check.extraSteps entry',
+    });
+    return {
+        ...document,
+        patchLint: Object.keys(rules).length === 0 ? next : { ...next, rules },
+    };
+}
+function upgradePolicy(document, conversion) {
+    const policy = document['patchPolicy'];
+    if (!isRecord(policy))
+        return document;
+    let next = policy;
+    if (policy['mutationMode'] === 'force') {
+        conversion.convert('patchPolicy.mutationMode', '"force" is now "error": queue operations refuse a policy problem they would add');
+        next = { ...next, mutationMode: 'error' };
+    }
+    const rules = objects(policy['scopeRules']);
+    if (rules !== undefined) {
+        const scopeRules = rules.map((rule, index) => {
+            const at = `patchPolicy.scopeRules[${index}]`;
+            const { category, filenamePattern, ...rest } = rule;
+            if (category === undefined && filenamePattern === undefined)
+                return rule;
+            if (category !== undefined && filenamePattern !== undefined) {
+                conversion.block(at, 'selects by category and filenamePattern; write one "group" expression');
+                return rule;
+            }
+            if (typeof category === 'string') {
+                conversion.convert(`${at}.category`, 'is now "group", an expression over group IDs');
+                return { group: `^\\d+-${category}-`, ...rest };
+            }
+            conversion.convert(`${at}.filenamePattern`, 'is now "group", an expression over group IDs');
+            return { group: filenamePattern, ...rest };
+        });
+        next = { ...next, scopeRules };
+    }
+    return next === policy ? document : { ...document, patchPolicy: next };
+}
+function upgradeRest(document, conversion) {
+    let next = conversion.drop(document, '', {
+        slots: 'workspaces replace slots; nothing is cloned into a workspace besides the engine',
+        history: 'queue operations keep no history log',
+    });
+    if (isRecord(next['test'])) {
+        const removed = 'tests run in the foreground in one workspace, which reaps its own leftovers';
+        const test = conversion.drop(next['test'], 'test', {
+            canaryPath: 'no canary runs before a test',
+            canaryTimeoutSeconds: 'no canary runs before a test',
+            reapOrphans: removed,
+            lockMode: removed,
+            furnaceApply: 'components are always deployed before a test',
+        });
+        next = Object.keys(test).length === 0 ? omitKeys(next, 'test') : { ...next, test };
+    }
+    if (next['license'] === undefined) {
+        conversion.convert('license', `was unset, which meant "${PREVIOUS_DEFAULT_LICENSE}"; it is now written out`);
+        next = { ...next, license: PREVIOUS_DEFAULT_LICENSE };
+    }
+    return next;
+}
+/** `drop` reports top-level keys as `.key`; a note names them without the dot. */
+function tidy(notes) {
+    return notes.map((note) => ({ ...note, key: note.key.replace(/^\./, '') }));
+}
+/**
+ * Converts a `fireforge.json` document of the previous format.
+ *
+ * @param document - The document as parsed, in either format
+ * @returns The current-format document and what was done; a document
+ *   already current is returned with nothing reported
+ */
+export function upgradeConfig(document) {
+    const conversion = new Conversion();
+    if (configSchema.validate(document).ok) {
+        return { document, converted: [], removed: [], manual: [], blockers: [] };
+    }
+    let next = upgradeSources(document, conversion);
+    next = upgradeProof(next, conversion);
+    next = upgradeCheck(next, conversion);
+    next = upgradeLint(next, conversion);
+    next = upgradePolicy(next, conversion);
+    next = upgradeRest(next, conversion);
+    if (conversion.blockers.length === 0) {
+        const result = configSchema.validate(next);
+        if (!result.ok) {
+            for (const issue of result.issues)
+                conversion.block(issue.path, issue.message);
+        }
+    }
+    return {
+        document: next,
+        converted: tidy(conversion.converted),
+        removed: tidy(conversion.removed),
+        manual: tidy(conversion.manual),
+        blockers: tidy(conversion.blockers),
+    };
+}

package/dist/src/config/schema/build.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** `build` and `buildAudit`: how the browser is built and packaged, and the packaging audit. */
+import { posix } from 'node:path';
+import { s } from '../../kernel/schema.js';
+import { enginePath, isContainedRelative, positive, projectPath, text, uniqueBy, } from './common.js';
+/** One spelling per path: relative, normalized, forward slashes, no trailing slash. */
+function isCanonical(path) {
+    return (isContainedRelative(path) &&
+        path !== '.' &&
+        !path.includes('\\') &&
+        !path.endsWith('/') &&
+        posix.normalize(path) === path);
+}
+const releaseOutput = s
+    .string({ pattern: /\S/, format: 'a path in the release object directory' })
+    .refine((path) => isCanonical(path) && !posix.dirname(path).includes('*')
+    ? undefined
+    : 'must be a canonical path in the object directory, with * only in the last segment');
+const release = s
+    .object({
+    overlay: projectPath.describe('Captured mozconfig fragment appended last for a release build'),
+    secrets: s
+        .object({
+        variable: s
+            .string({ pattern: /^[A-Z][A-Z0-9_]{0,63}$/, format: 'an environment variable name' })
+            .describe('Environment variable naming the directory the overlay reads secrets from'),
+        files: s
+            .array(s.string({ pattern: /^[\w.-]+$/, format: 'a file name' }))
+            .describe('Files that must be in that directory; a release missing one refuses'),
+    })
+        .describe('Secret files the overlay reads, which are never committed')
+        .optional(),
+    outputs: s
+        .array(releaseOutput, { min: 1 })
+        .describe('Paths in the release object directory to collect, such as dist/*.dmg')
+        .optional(),
+})
+    .describe('How a release build differs from a development build');
+/** The `build` section. */
+export const buildSection = s
+    .object({
+    jobs: positive.describe('Parallel jobs for mach build').optional(),
+    release: release.optional(),
+})
+    .describe('Build settings');
+const unpackaged = s.object({
+    path: enginePath
+        .refine((path) => path.includes('**')
+        ? 'must not use "**": a carve-out may glob within one path segment only'
+        : undefined)
+        .describe('Engine-relative path, exact or with * inside one segment'),
+    reason: text.describe('Why the file is never packaged'),
+});
+/** The `buildAudit` section. */
+export const buildAuditSection = s
+    .object({
+    unpackaged: s
+        .array(unpackaged)
+        .refine(uniqueBy((entry) => entry.path, 'path'))
+        .describe('Sources the post-build audit treats as intentionally unpackaged')
+        .optional(),
+})
+    .describe('Post-build packaging audit');

package/dist/src/config/schema/check.js

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** `check`: the policy and project steps of the composed static check. */
+import { s } from '../../kernel/schema.js';
+import { positive, projectPath, text, uniqueBy } from './common.js';
+/** The built-in steps of `fireforge check`, in table order. */
+export const CHECK_STEPS = [
+    'status',
+    'verify',
+    'lint',
+    'typecheck',
+    'furnace-validate',
+    'token-coverage',
+    'token-lint',
+];
+const isBuiltin = (name) => CHECK_STEPS.some((step) => step === name);
+const extraStep = s.object({
+    name: s
+        .string({
+        pattern: /^[a-z0-9][a-z0-9-]*$/,
+        format: 'lowercase letters, digits and dashes, such as "policy-audit"',
+    })
+        .refine((name) => (isBuiltin(name) ? `must not reuse the built-in step "${name}"` : undefined))
+        .describe('Step name shown in the report'),
+    command: s
+        .array(text, { min: 1 })
+        .describe('Argument vector run from the project root; the step passes on exit 0'),
+    timeout: positive.describe('Seconds before the step is killed and fails').default(600),
+    engine: s
+        .boolean()
+        .describe('The step reads the engine: it runs holding the workspace, with FIREFORGE_ENGINE set')
+        .default(false),
+    after: s.array(text).describe('Steps that must finish first, whatever their outcome').optional(),
+});
+/** Every `after` names a known step, and the ordering has no cycle (whose steps would wait forever). */
+function orderingProblem(steps) {
+    const extras = new Map(steps.map((step) => [step.name, step]));
+    for (const step of steps) {
+        for (const dependency of step.after ?? []) {
+            if (dependency === step.name)
+                return `orders step "${step.name}" after itself`;
+            if (!isBuiltin(dependency) && !extras.has(dependency)) {
+                return `orders step "${step.name}" after unknown step "${dependency}"`;
+            }
+        }
+    }
+    const state = new Map();
+    const cycle = (name, path) => {
+        if (state.get(name) === 'done')
+            return undefined;
+        if (state.get(name) === 'visiting')
+            return [...path, name].join(' -> ');
+        state.set(name, 'visiting');
+        for (const dependency of extras.get(name)?.after ?? []) {
+            const found = extras.has(dependency) ? cycle(dependency, [...path, name]) : undefined;
+            if (found !== undefined)
+                return found;
+        }
+        state.set(name, 'done');
+        return undefined;
+    };
+    for (const step of steps) {
+        const found = cycle(step.name, []);
+        if (found !== undefined)
+            return `orders its steps in a cycle: ${found}`;
+    }
+    return undefined;
+}
+const unique = uniqueBy((step) => step.name, 'step name');
+/** The `check` section. Every key is optional. */
+export const checkSection = s
+    .object({
+    skip: s
+        .array(s.enum(CHECK_STEPS))
+        .describe('Built-in steps this project never runs')
+        .optional(),
+    status: s
+        .object({
+        failOn: s
+            .array(text)
+            .describe('Status codes that fail the status step; every code when unset')
+            .optional(),
+        allow: s.array(text).describe('Status codes the status step accepts').optional(),
+    })
+        .describe("The status step's policy")
+        .optional(),
+    maxWarnings: s
+        .object({
+        lint: s.int({ min: 0 }).describe('Warnings the lint step tolerates').optional(),
+        furnace: s
+            .int({ min: 0 })
+            .describe('Warnings the furnace-validate step tolerates')
+            .optional(),
+    })
+        .describe('Warning ceilings of the lint and furnace-validate steps')
+        .optional(),
+    extraSteps: s
+        .array(extraStep)
+        .refine((steps) => unique(steps) ?? orderingProblem(steps))
+        .describe('Project commands run as further steps')
+        .optional(),
+    minTokenCoverage: s
+        .int({ min: 0, max: 100 })
+        .describe('Percentage below which the token-coverage step fails')
+        .optional(),
+    failOnSkipped: s
+        .boolean()
+        .describe('Fail when a built-in step is skipped for having nothing to run')
+        .default(false),
+    lintReport: projectPath
+        .describe('Project-relative path the lint step writes its JSON report to')
+        .optional(),
+})
+    .describe('The composed static check');

package/dist/src/config/schema/common.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Field schemas several sections of `fireforge.json` share. Schemas are
+ * immutable values: `describe`, `optional` and `default` return new ones.
+ */
+import { isAbsolute } from 'node:path';
+import { toError } from '../../kernel/errors.js';
+import { isInside } from '../../kernel/fs.js';
+import { s } from '../../kernel/schema.js';
+const WINDOWS_ABSOLUTE = /^[a-zA-Z]:[\\/]/;
+/**
+ * Whether a path is relative and stays inside whatever directory it is
+ * resolved against: not absolute on any platform, no `..` that climbs out,
+ * no NUL.
+ *
+ * @param path - The path as written in the configuration
+ */
+export function isContainedRelative(path) {
+    return (path.trim() !== '' &&
+        !isAbsolute(path) &&
+        !WINDOWS_ABSOLUTE.test(path) &&
+        isInside('/fireforge-root', path));
+}
+/** A string with at least one non-whitespace character. */
+export const text = s.string({ pattern: /\S/, format: 'a non-empty string' });
+function relative(root) {
+    const noun = `${root === 'engine' ? 'an' : 'a'} ${root}-relative path`;
+    return s
+        .string({ pattern: /\S/, format: noun })
+        .refine((path) => isContainedRelative(path) ? undefined : `must be ${noun} inside the ${root}`);
+}
+/** A path relative to the project root that stays inside it. */
+export const projectPath = relative('project');
+/** A path or glob relative to the engine root that stays inside it. */
+export const enginePath = relative('engine');
+/** How loudly an opt-in rule reports; `off` disables it. */
+export const severity = s.enum(['off', 'warning', 'error']);
+/** A whole number of at least one. */
+export const positive = s.int({ min: 1 });
+/**
+ * A `refine` test refusing a list in which two entries share a name.
+ *
+ * @param name - Picks the name of an entry
+ * @param noun - What the name is, for the message: "group name", "step name"
+ */
+export function uniqueBy(name, noun) {
+    return (entries) => {
+        const seen = new Set();
+        for (const entry of entries) {
+            const key = name(entry);
+            if (seen.has(key))
+                return `repeats the ${noun} "${key}"`;
+            seen.add(key);
+        }
+        return undefined;
+    };
+}
+/**
+ * A `refine` test refusing a string that is not a valid regular expression.
+ *
+ * @param pattern - The pattern source
+ */
+export function validRegExp(pattern) {
+    try {
+        new RegExp(pattern);
+        return undefined;
+    }
+    catch (error) {
+        return `must be a valid regular expression: ${toError(error).message}`;
+    }
+}

package/dist/src/config/schema/export-queue.js

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** `exportQueue`: how a source-mode export groups created files into patches. */
+import { s } from '../../kernel/schema.js';
+import { enginePath, positive, uniqueBy } from './common.js';
+const tier = s
+    .literal('branding')
+    .describe('Size tier the group is held to instead of the one its files imply');
+const group = s.object({
+    name: s
+        .string({
+        pattern: /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/,
+        format: 'lowercase words joined by hyphens, such as "ui-sidebar"',
+    })
+        .describe('Patch name; its first word is the category'),
+    paths: s
+        .array(enginePath, { min: 1 })
+        .describe('Engine-relative globs; a created file joins the first group it matches'),
+    tier: tier.optional(),
+});
+/** The `exportQueue` section. Every key is optional. */
+export const exportQueueSection = s
+    .object({
+    groups: s
+        .array(group)
+        .refine(uniqueBy((entry) => entry.name, 'group name'))
+        .describe('Named groups of created files, matched in order')
+        .optional(),
+    componentTiers: s
+        .record(tier)
+        .describe('Size tier per component of upstream changes')
+        .optional(),
+    maxGroupBytes: positive
+        .describe('Byte budget of a directory group for created files no group matches')
+        .default(1_048_576),
+})
+    .describe('How an exported patch queue groups created files');