@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `patchPolicy`: how the patch queue is ordered and named (read by the
+ * queue), and which upstream files owned changes may touch and how (read by
+ * lint over the owned changes). A `reservedRanges` exception names a group
+ * that may change the upstream files it lists outside `upstreamAllowlist`.
+ */
+import { s } from '../../kernel/schema.js';
+import { positive, projectPath, text, validRegExp } from './common.js';
+const category = s.string({
+    pattern: /^[a-z][a-z0-9-]*$/,
+    format: 'a lowercase category identifier (letters, digits, hyphens)',
+});
+const regExpSource = s.string().refine(validRegExp);
+function bounded(schema) {
+    return schema.refine(({ from, to }) => to < from ? `must have "to" (${to}) at or above "from" (${from})` : undefined);
+}
+function disjoint(ranges) {
+    const sorted = [...ranges].sort((a, b) => a.from - b.from || a.to - b.to);
+    for (const [index, current] of sorted.entries()) {
+        const previous = sorted[index - 1];
+        if (previous !== undefined && current.from <= previous.to) {
+            return `must not overlap (${previous.from}-${previous.to} overlaps ${current.from}-${current.to})`;
+        }
+    }
+    return undefined;
+}
+const range = bounded(s.object({
+    from: positive.describe('Inclusive lower bound'),
+    to: positive.describe('Inclusive upper bound'),
+    category: category.describe('Category that owns the range'),
+}));
+const reservedRange = bounded(s.object({
+    from: positive,
+    to: positive,
+    allowed: s
+        .array(s.object({
+        filename: text.describe('Exact patch filename allowed in the reserved range'),
+        files: s.array(s.string()).describe('Exact files the patch may affect').optional(),
+        adr: projectPath.describe('Decision record documenting the exception').optional(),
+        documentation: projectPath.describe('Documentation of the exception').optional(),
+    }))
+        .describe('The exceptions allowed in the range'),
+}));
+const upstreamEntry = s.object({
+    path: text.describe('Engine-relative glob'),
+    addOnly: s
+        .boolean()
+        .describe('Owned changes may only add lines carrying the marker to a matching file')
+        .optional(),
+    marker: text.describe('Marker an added line must carry; overrides addOnlyMarker').optional(),
+    retiredPaths: s
+        .array(text, { min: 1 })
+        .describe('With addOnly: paths whose registration lines may be removed')
+        .optional(),
+});
+const scopeRule = s.object({
+    group: regExpSource.describe('Regular expression over group IDs (patch filenames, component names) the rule scopes'),
+    files: s
+        .array(text, { min: 1 })
+        .describe('Engine-relative globs every file such a group touches must match'),
+});
+const patchPolicyObject = s.object({
+    filenamePattern: regExpSource
+        .describe('Regular expression with named captures order, category and slug')
+        .optional(),
+    requireDescription: s
+        .boolean()
+        .describe('An empty patch description is a violation')
+        .default(false),
+    allowGaps: s.boolean().describe('Allow numeric gaps within a category range').default(true),
+    mutationMode: s
+        .enum(['error', 'warn'])
+        .describe('Whether queue operations refuse a policy violation they would add or report it')
+        .default('error'),
+    ranges: s.array(range, { min: 1 }).refine(disjoint).describe('Order bands owned by categories'),
+    reservedRanges: s
+        .array(reservedRange)
+        .refine(disjoint)
+        .describe('Order bands for listed exceptional patches')
+        .optional(),
+    upstreamAllowlist: s
+        .array(s.union(text, upstreamEntry))
+        .describe('Globs (or entries) naming the upstream files owned changes may modify')
+        .optional(),
+    addOnlyMarker: text.describe('Marker for addOnly entries that set none').optional(),
+    scopeRules: s
+        .array(scopeRule)
+        .describe('File scopes per class of group, chosen by group ID')
+        .optional(),
+    verifyDocumentPaths: s
+        .boolean()
+        .describe('Require the adr and documentation paths of reserved exceptions to exist')
+        .default(false),
+});
+/** The `patchPolicy` section. */
+export const patchPolicySection = patchPolicyObject
+    .refine(({ upstreamAllowlist = [], addOnlyMarker }) => {
+    for (const [index, entry] of upstreamAllowlist.entries()) {
+        if (typeof entry === 'string')
+            continue;
+        if (entry.retiredPaths !== undefined && entry.addOnly !== true) {
+            return `sets retiredPaths on upstreamAllowlist[${index}], which applies only with addOnly: true`;
+        }
+        if (entry.addOnly === true && entry.marker === undefined && addOnlyMarker === undefined) {
+            return `sets addOnly on upstreamAllowlist[${index}] without a marker: set its marker or addOnlyMarker`;
+        }
+    }
+    return undefined;
+})
+    .describe('Patch queue ordering and upstream-touch policy');

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

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `mode` and `source`: where the project keeps its owned changes. Patch mode
+ * keeps them as a patch queue; source mode keeps them as tracked files under
+ * `source.root`, with the upstream identity of every touched upstream file
+ * recorded under `source.metadataRoot`.
+ */
+import { posix } from 'node:path';
+import { s } from '../../kernel/schema.js';
+/** The storage modes a project can be in. */
+export const PROJECT_MODES = ['patches', 'source'];
+/** Top-level directories the tool or the workspace own, which a source root may not claim. */
+const RESERVED_ROOTS = [
+    'engine',
+    '.git',
+    '.fireforge',
+    'node_modules',
+    'patches',
+    'secrets',
+    'components',
+    'configs',
+];
+/**
+ * Why a path cannot be a source directory, or undefined: it must be one
+ * canonical spelling of a relative directory (no `.`, `..`, backslash,
+ * control character, trailing slash or surrounding whitespace) outside the
+ * reserved top-level directories, compared case-insensitively as a
+ * case-insensitive file system would.
+ */
+function directoryProblem(path) {
+    const canonical = path !== '' &&
+        path.trim() === path &&
+        !posix.isAbsolute(path) &&
+        !/^[A-Za-z]:/.test(path) &&
+        !/[\\\p{Cc}]/u.test(path) &&
+        posix.normalize(path) === path &&
+        !path.endsWith('/') &&
+        !path.split('/').some((part) => part === '.' || part === '..' || foldCase(part) === '.git');
+    if (!canonical)
+        return 'must be a canonical relative directory inside the project';
+    const top = foldCase(path).split('/')[0] ?? '';
+    return RESERVED_ROOTS.includes(top)
+        ? `must not be inside the reserved "${top}" directory`
+        : undefined;
+}
+function foldCase(path) {
+    return path.normalize('NFC').toLocaleLowerCase('en-US');
+}
+const directory = s
+    .string({ pattern: /\S/, format: 'a relative directory' })
+    .refine(directoryProblem);
+/** The `source` section, present exactly when `mode` is `source`. */
+export const sourceSection = s
+    .object({
+    root: directory.describe('Directory whose files supply the engine files of the same path'),
+    metadataRoot: directory.describe('Directory holding the upstream identity of every overridden upstream file'),
+    pristineCommit: s
+        .string({
+        pattern: /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/,
+        format: 'a complete lowercase Git object ID',
+    })
+        .describe('Commit of the pristine repository the pin resolves to'),
+})
+    .refine(({ root, metadataRoot }) => {
+    const [a, b] = [foldCase(root), foldCase(metadataRoot)];
+    return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`)
+        ? 'must keep root and metadataRoot apart: neither may contain the other'
+        : undefined;
+})
+    .describe('Source mode: where the owned files and their upstream records live');
+/** The `mode` key. */
+export const modeKey = s
+    .enum(PROJECT_MODES)
+    .describe('Where owned changes live: a patch queue (patches) or tracked files (source)')
+    .default('patches');
+/**
+ * The root-level rule tying `mode` to `source`, for the root schema's
+ * `refine`: source mode needs the block, and patch mode refuses a stale one.
+ *
+ * @param config - The root document, already valid key by key
+ */
+export function modeProblem(config) {
+    if (config.mode === 'source' && config.source === undefined) {
+        return 'needs a "source" block when "mode" is "source"';
+    }
+    if (config.mode === 'patches' && config.source !== undefined) {
+        return 'has a "source" block, which applies only when "mode" is "source"';
+    }
+    return undefined;
+}

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

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** `test`: how `fireforge test` treats the host and reads harness output. */
+import { s } from '../../kernel/schema.js';
+import { validRegExp } from './common.js';
+/** The `test` section. Every key is optional. */
+export const testSection = s
+    .object({
+    mochitestPorts: s
+        .enum(['fixed', 'auto'])
+        .describe('auto lets a run proceed while another workspace holds the Marionette port or, where the harness can move, a mochitest server port')
+        .default('fixed'),
+    harnessFailurePatterns: s
+        .array(s.string({ min: 1 }).refine(validRegExp), { min: 1 })
+        .describe('Regular expressions of output lines meaning the browser failed before any test ran; such a run reads crash, not no-tests')
+        .optional(),
+})
+    .describe('Test command settings');

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

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** `externalToolchains`: project-specific tools `fireforge doctor` probes for. */
+import { s } from '../../kernel/schema.js';
+import { text } from './common.js';
+const tool = s.object({
+    name: text.describe('Tool name, and the PATH or xcrun lookup key when no path is set'),
+    path: text.describe('Absolute or project-relative executable path').optional(),
+    xcrun: s.boolean().describe('Resolve with xcrun -find instead of PATH').optional(),
+    required: s.boolean().describe('A missing tool is an error rather than a warning').default(true),
+});
+/** The `externalToolchains` section. */
+export const toolchainsSection = s
+    .array(s.object({
+    name: text.describe('Toolchain name, such as "seasonal-branding"'),
+    tools: s.array(tool, { min: 1 }).describe('The tools it needs'),
+}))
+    .describe('Named groups of external tools the project needs');

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

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** `typecheck`: the whole-project type check of `fireforge typecheck`. */
+import { s } from '../../kernel/schema.js';
+import { projectPath, severity } from './common.js';
+const typecheckObject = s.object({
+    projects: s
+        .array(projectPath, { min: 1 })
+        .describe('Project-relative jsconfig or tsconfig files checked as whole projects'),
+    extraShim: projectPath
+        .describe('Project-relative .d.ts added to the Firefox globals shim of every project')
+        .optional(),
+    projectOverrides: s
+        .record(s.union(s.literal(null), projectPath))
+        .describe('Per project (keyed as in projects): another .d.ts instead of extraShim, or null for none')
+        .optional(),
+    undefinedIdentifiers: severity
+        .describe('How undefined identifiers are reported')
+        .default('warning'),
+    litTypes: s.boolean().describe('Type Lit in the shim with closed member lists').default(false),
+});
+/** The `typecheck` section. */
+export const typecheckSection = typecheckObject
+    .refine(({ projects, projectOverrides }) => {
+    const stray = Object.keys(projectOverrides ?? {}).find((key) => !projects.includes(key));
+    return stray === undefined
+        ? undefined
+        : `overrides "${stray}", which is not one of its projects`;
+})
+    .describe('Whole-project type checking');

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

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** `wire`: where `fireforge wire` puts chrome subscripts and DOM fragments. */
+import { s } from '../../kernel/schema.js';
+import { enginePath } from './common.js';
+/** The `wire` section. */
+export const wireSection = s
+    .object({
+    subscriptDir: enginePath
+        .describe('Engine-relative directory of wired chrome subscripts')
+        .default('browser/base/content'),
+    domTarget: enginePath
+        .describe('Engine-relative top-level chrome document that wired DOM fragments are included into')
+        .default('browser/base/content/browser.xhtml'),
+})
+    .describe('Chrome subscript wiring');

package/dist/src/diff/apply.js

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The one in-memory patch applier: a file section's hunks applied to a
+ * file's bytes, without git or the filesystem.
+ *
+ * Content is handled as a byte string (Latin-1, one character per byte) and
+ * each hunk line is converted to the same form, so the result is exact
+ * whatever the file's encoding and whatever the patch's.
+ */
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { hunkSides } from './query.js';
+function conflict(file, message) {
+    return new FireForgeError('diff-apply-conflict', `${file.path}: ${message}`, {
+        exitCode: ExitCode.PATCH_ERROR,
+        hint: 'The file is not in the state the patch was taken from. Regenerate the patch or resolve by hand.',
+    });
+}
+function toByteString(file, line) {
+    // An ASCII line is the same in both encodings.
+    return file.encoding === 'latin1' || Buffer.byteLength(line, 'utf8') === line.length
+        ? line
+        : Buffer.from(line, 'utf8').toString('latin1');
+}
+function blockOf(file, hunk, reverse) {
+    const sides = hunkSides(hunk);
+    if (sides.old.length !== hunk.oldCount || sides.new.length !== hunk.newCount) {
+        throw new FireForgeError('diff-corrupt', `${file.path}: hunk "${hunk.header}" declares ${hunk.oldCount}/${hunk.newCount} lines but holds ${sides.old.length}/${sides.new.length}.`, { exitCode: ExitCode.PATCH_ERROR, hint: 'The patch was edited by hand; regenerate it.' });
+    }
+    const old = sides.old.map((line) => toByteString(file, line));
+    const next = sides.new.map((line) => toByteString(file, line));
+    // A side of zero lines names the line before the change (`@@ -4,0 +5,2 @@`).
+    const start = reverse
+        ? hunk.newStart - (hunk.newCount === 0 ? 0 : 1)
+        : hunk.oldStart - (hunk.oldCount === 0 ? 0 : 1);
+    const [from, to] = reverse ? [next, old] : [old, next];
+    const [fromNoNewline, toNoNewline] = reverse
+        ? [sides.newNoNewline, sides.oldNoNewline]
+        : [sides.oldNoNewline, sides.newNoNewline];
+    return { hunk, from, to, fromNoNewline, toNoNewline, start };
+}
+function matchesAt(lines, block, at) {
+    if (at < 0 || at + block.length > lines.length)
+        return false;
+    return block.every((line, index) => lines[at + index] === line);
+}
+/** Where `block` matches: at `expected` if it does there, else the nearest match at or after `floor`. */
+function locate(lines, block, expected, floor) {
+    for (let distance = 0; distance <= lines.length; distance++) {
+        for (const at of distance === 0 ? [expected] : [expected - distance, expected + distance]) {
+            if (at >= floor && matchesAt(lines, block, at))
+                return at;
+        }
+    }
+    return undefined;
+}
+function applyBlock(file, content, block, place) {
+    const { lines } = content;
+    const expected = Math.min(lines.length, Math.max(place.floor, block.start + place.offset));
+    const at = block.from.length === 0 ? expected : locate(lines, block.from, expected, place.floor);
+    if (at === undefined) {
+        throw conflict(file, `hunk "${block.hunk.header}" does not apply: its lines were not found.`);
+    }
+    const reachesEnd = at + block.from.length === lines.length;
+    const newlineMismatch = block.from.length > 0
+        ? (block.fromNoNewline && !reachesEnd) ||
+            (reachesEnd && content.finalNewline === block.fromNoNewline)
+        : reachesEnd && lines.length > 0 && !content.finalNewline;
+    if (newlineMismatch) {
+        throw conflict(file, `hunk "${block.hunk.header}" disagrees about the newline at the end of the file.`);
+    }
+    lines.splice(at, block.from.length, ...block.to);
+    if (reachesEnd)
+        content.finalNewline = !block.toNoNewline;
+    place.offset += at - expected + block.to.length - block.from.length;
+    place.floor = at + block.to.length;
+}
+function readContent(bytes) {
+    const text = Buffer.from(bytes).toString('latin1');
+    if (text === '')
+        return { lines: [], finalNewline: true };
+    const lines = text.split('\n');
+    const finalNewline = lines.at(-1) === '';
+    if (finalNewline)
+        lines.pop();
+    return { lines, finalNewline };
+}
+/**
+ * Applies a file section to a file's content. Each hunk is tried at the
+ * line its header names, shifted by what earlier hunks moved; where its
+ * lines are not there, at the nearest place they are. Hunk line counts and
+ * end-of-file newlines are verified, and a hunk that cannot be placed fails
+ * the whole section.
+ *
+ * For a new-file section, `applyFileDiff(file, undefined)` is the content the
+ * section creates.
+ *
+ * @param file - The section
+ * @param content - The file's bytes, or undefined when it does not exist
+ * @param options - See {@link ApplyFileOptions}
+ * @returns The new bytes, or undefined when the section deletes the file
+ * @throws FireForgeError `diff-apply-conflict` when the content does not fit,
+ *   `diff-corrupt` for a hunk whose counts disagree with its body, `diff-binary`
+ *   for a binary section
+ */
+export function applyFileDiff(file, content, options = {}) {
+    const reverse = options.reverse === true;
+    if (file.binary !== undefined) {
+        throw new FireForgeError('diff-binary', `${file.path}: a binary section cannot be applied in memory.`, {
+            exitCode: ExitCode.PATCH_ERROR,
+        });
+    }
+    const creates = file.status === (reverse ? 'deleted' : 'added');
+    const removes = file.status === (reverse ? 'added' : 'deleted');
+    if (content === undefined && !creates)
+        throw conflict(file, 'the file does not exist.');
+    if (content !== undefined && creates)
+        throw conflict(file, 'the file already exists.');
+    const state = content === undefined ? { lines: [], finalNewline: true } : readContent(content);
+    const place = { offset: 0, floor: 0 };
+    for (const hunk of file.hunks)
+        applyBlock(file, state, blockOf(file, hunk, reverse), place);
+    if (removes) {
+        if (state.lines.length > 0)
+            throw conflict(file, 'the file holds more than the patch removes.');
+        return undefined;
+    }
+    const text = state.lines.length === 0 ? '' : state.lines.join('\n') + (state.finalNewline ? '\n' : '');
+    return Buffer.from(text, 'latin1');
+}

package/dist/src/diff/index.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The unified diff model: parse a patch into per-file sections, write it back
+ * byte for byte, ask it questions, and apply a section to content in memory.
+ * Pure: no git, no filesystem. Producing a patch from a tree is `git/`'s job.
+ *
+ * Encoding: a patch is decoded once, as UTF-8 when valid and as Latin-1
+ * otherwise, and written back the same way (see `model.ts`), so
+ * `formatPatch(parsePatch(bytes))` equals `bytes` for any input.
+ *
+ * Slicing: a patch of some of a patch's sections is
+ * `formatPatch({ ...patch, preamble: [], files })`.
+ */
+export { applyFileDiff } from './apply.js';
+export { formatPatch, parsePatch } from './model.js';
+export { addedLines, affectedPaths, hunkSides } from './query.js';