@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/json-preserving-edit.js

@@ -1,199 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Format-preserving rewrites of a JSON document.
- *
- * `fireforge source set`, `fireforge config` and `furnace init` change a
- * few keys of `fireforge.json`. Re-serializing the whole document with
- * `JSON.stringify` expands every compact object and array the project keeps
- * on one line, so a one-key change becomes a diff across unrelated policy
- * sections. This module diffs the document on disk against the wanted one
- * and edits only the values that differ, in place, keeping every other byte
- * (indentation, compact containers, key order, trailing newline).
- *
- * Inserted values follow the style of the container they land in: one line
- * inside a one-line container, the container's own indentation otherwise.
- */
-import { applyEdits, findNodeAtLocation, modify, parseTree } from 'jsonc-parser';
-import { isJsonObject } from '../utils/validation.js';
-/** The same reviver `readJson` uses, so both sides of the diff agree. */
-function parseJsonDocument(text) {
-    return JSON.parse(text, (key, value) => key === '__proto__' || key === 'constructor' || key === 'prototype' ? undefined : value);
-}
-function jsonEqual(a, b) {
-    if (a === b)
-        return true;
-    if (Array.isArray(a) || Array.isArray(b)) {
-        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
-            return false;
-        return a.every((value, index) => jsonEqual(value, b[index]));
-    }
-    if (!isJsonObject(a) || !isJsonObject(b))
-        return false;
-    const keysA = definedKeys(a);
-    const keysB = definedKeys(b);
-    return keysA.length === keysB.length && keysA.every((key) => jsonEqual(a[key], b[key]));
-}
-/** Keys whose value survives `JSON.stringify` (an `undefined` value is an absent key). */
-function definedKeys(object) {
-    return Object.keys(object).filter((key) => object[key] !== undefined);
-}
-function collectChanges(path, before, after, changes) {
-    if (jsonEqual(before, after))
-        return;
-    if (isJsonObject(before) && isJsonObject(after)) {
-        for (const key of definedKeys(before)) {
-            if (after[key] === undefined)
-                changes.push({ kind: 'remove', path: [...path, key] });
-        }
-        for (const key of definedKeys(after)) {
-            const next = after[key];
-            const previous = before[key];
-            if (previous === undefined) {
-                changes.push({ kind: 'set', path: [...path, key], value: next });
-            }
-            else {
-                collectChanges([...path, key], previous, next, changes);
-            }
-        }
-        return;
-    }
-    if (Array.isArray(before) && Array.isArray(after)) {
-        const isAppend = after.length > before.length &&
-            before.every((value, index) => jsonEqual(value, after[index]));
-        if (isAppend) {
-            for (const value of after.slice(before.length))
-                changes.push({ kind: 'append', path, value });
-            return;
-        }
-        if (after.length === before.length) {
-            before.forEach((value, index) => {
-                collectChanges([...path, index], value, after[index], changes);
-            });
-            return;
-        }
-    }
-    changes.push({ kind: 'set', path, value: after });
-}
-function detectStyle(text) {
-    const indent = /^([ \t]+)\S/m.exec(text)?.[1];
-    return {
-        eol: text.includes('\r\n') ? '\r\n' : '\n',
-        indentUnit: indent === undefined ? '  ' : indent.startsWith('\t') ? '\t' : indent,
-    };
-}
-function isMultiline(text, node) {
-    return node !== undefined && text.slice(node.offset, node.offset + node.length).includes('\n');
-}
-/** The object or array holding `node` (skipping the property node of an object member). */
-function containerOf(node) {
-    const parent = node.parent;
-    return parent?.type === 'property' ? parent.parent : parent;
-}
-/** Leading whitespace of the line `offset` sits on. */
-function lineIndent(text, offset) {
-    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
-    return /^[ \t]*/.exec(text.slice(lineStart))?.[0] ?? '';
-}
-function renderCompact(value) {
-    if (Array.isArray(value)) {
-        return `[${value.map(renderCompact).join(', ')}]`;
-    }
-    if (isJsonObject(value)) {
-        const entries = definedKeys(value).map((key) => `${JSON.stringify(key)}: ${renderCompact(value[key])}`);
-        return entries.length === 0 ? '{}' : `{ ${entries.join(', ')} }`;
-    }
-    return JSON.stringify(value);
-}
-function renderValue(value, multiline, indent, style) {
-    if (!multiline)
-        return renderCompact(value);
-    return JSON.stringify(value, null, style.indentUnit)
-        .split('\n')
-        .join(style.eol + indent);
-}
-function replaceRange(text, offset, length, content) {
-    return text.slice(0, offset) + content + text.slice(offset + length);
-}
-/** Replaces an existing value, keeping a container's one-line or multi-line shape. */
-function replaceNode(text, node, value, style) {
-    const isContainer = node.type === 'object' || node.type === 'array';
-    const multiline = isContainer ? isMultiline(text, node) : isMultiline(text, containerOf(node));
-    const rendered = renderValue(value, multiline, lineIndent(text, node.offset), style);
-    return replaceRange(text, node.offset, node.length, rendered);
-}
-/** Appends `entry` (a property or an array element) after the container's last child. */
-function appendEntry(text, container, renderEntry, style) {
-    const children = container.children ?? [];
-    const last = children[children.length - 1];
-    const containerIndent = lineIndent(text, container.offset);
-    if (last === undefined) {
-        // Empty container: open it up the way its parent is laid out.
-        const multiline = isMultiline(text, containerOf(container));
-        const [open, close] = container.type === 'array' ? ['[', ']'] : ['{', '}'];
-        const childIndent = containerIndent + style.indentUnit;
-        const body = multiline
-            ? `${open}${style.eol}${childIndent}${renderEntry(true, childIndent)}${style.eol}${containerIndent}${close}`
-            : container.type === 'array'
-                ? `${open}${renderEntry(false, childIndent)}${close}`
-                : `${open} ${renderEntry(false, childIndent)} ${close}`;
-        return replaceRange(text, container.offset, container.length, body);
-    }
-    const multiline = isMultiline(text, container);
-    const indent = multiline ? lineIndent(text, last.offset) : containerIndent;
-    const separator = multiline ? `,${style.eol}${indent}` : ', ';
-    return replaceRange(text, last.offset + last.length, 0, separator + renderEntry(multiline, indent));
-}
-function applyChange(text, change, style) {
-    const root = parseTree(text);
-    if (root === undefined) {
-        throw new Error('document is not valid JSON');
-    }
-    if (change.kind === 'remove') {
-        return applyEdits(text, modify(text, change.path, undefined, {}));
-    }
-    const target = findNodeAtLocation(root, change.path);
-    if (change.kind === 'append') {
-        if (target?.type !== 'array')
-            throw new Error('append target is not an array');
-        return appendEntry(text, target, (multiline, indent) => renderValue(change.value, multiline, indent, style), style);
-    }
-    if (target !== undefined) {
-        return replaceNode(text, target, change.value, style);
-    }
-    const parent = findNodeAtLocation(root, change.path.slice(0, -1));
-    const key = change.path[change.path.length - 1];
-    if (parent?.type !== 'object' || typeof key !== 'string') {
-        throw new Error('insertion parent is not an object');
-    }
-    return appendEntry(text, parent, (multiline, indent) => `${JSON.stringify(key)}: ${renderValue(change.value, multiline, indent, style)}`, style);
-}
-/**
- * Rewrites `text` so it parses to `next`, editing only the values that
- * differ. Returns `undefined` when `text` is not a JSON object or the edit
- * cannot be proven equivalent, so the caller can fall back to a full
- * re-serialization.
- */
-export function rewriteJsonPreservingFormat(text, next) {
-    let current;
-    try {
-        current = parseJsonDocument(text);
-    }
-    catch {
-        return undefined;
-    }
-    if (!isJsonObject(current))
-        return undefined;
-    const changes = [];
-    collectChanges([], current, next, changes);
-    const style = detectStyle(text);
-    try {
-        let edited = text;
-        for (const change of changes)
-            edited = applyChange(edited, change, style);
-        // The edits are structural; prove the result before trusting it.
-        return jsonEqual(parseJsonDocument(edited), next) ? edited : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}

package/dist/src/core/launchable-build.d.ts

@@ -1,39 +0,0 @@
-/**
- * Facts about the launchable build a test run will exercise: its build id
- * and when its compiled code was last linked.
- *
- * A green or red against a binary older than the C++ under test reads as a
- * verdict on that C++ unless the run says which binary it was. The
- * build id goes on the verdict line (`build-id=`), and the link time anchors
- * the stale-compiled preflight (`findCompiledSourcesNewerThanBinary` in
- * `test-stale-check.ts`).
- */
-/**
- * The `application.ini` beside a launchable binary: `Contents/Resources`
- * of the `.app` bundle on macOS, the binary's own directory (`dist/bin`)
- * elsewhere.
- *
- * @param binaryPath - Absolute launchable binary path
- */
-export declare function applicationIniPath(binaryPath: string): string;
-/**
- * Reads the `BuildID=` of the launchable build (the `moz:buildID` the
- * browser reports). Undefined when the file or the key is missing, so a
- * caller can simply leave the attribute off.
- *
- * @param engineDir - Absolute engine directory
- * @param launchablePath - Engine-relative launchable binary path
- */
-export declare function readBuildId(engineDir: string, launchablePath: string): Promise<string | undefined>;
-/**
- * When the launchable build's compiled code was last linked: the newest
- * mtime of the binary and the `libxul` beside it. Undefined when neither
- * can be read.
- *
- * @param engineDir - Absolute engine directory
- * @param launchablePath - Engine-relative launchable binary path
- */
-export declare function readLinkedAt(engineDir: string, launchablePath: string): Promise<{
-    mtimeMs: number;
-    path: string;
-} | undefined>;

package/dist/src/core/launchable-build.js

@@ -1,85 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Facts about the launchable build a test run will exercise: its build id
- * and when its compiled code was last linked.
- *
- * A green or red against a binary older than the C++ under test reads as a
- * verdict on that C++ unless the run says which binary it was. The
- * build id goes on the verdict line (`build-id=`), and the link time anchors
- * the stale-compiled preflight (`findCompiledSourcesNewerThanBinary` in
- * `test-stale-check.ts`).
- */
-import { stat } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
-import { getNodeErrorCode, toError } from '../utils/errors.js';
-import { readText } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-/**
- * The compiled libraries a build links next to the launchable binary.
- * `libxul` carries nearly all compiled engine code (C++, Rust, generated
- * bindings, prefs), so it, not the small launcher executable, is what a
- * compiled-source edit relinks.
- */
-const LINKED_LIBRARY_NAMES = ['XUL', 'libxul.so', 'xul.dll'];
-/**
- * The `application.ini` beside a launchable binary: `Contents/Resources`
- * of the `.app` bundle on macOS, the binary's own directory (`dist/bin`)
- * elsewhere.
- *
- * @param binaryPath - Absolute launchable binary path
- */
-export function applicationIniPath(binaryPath) {
-    const binaryDir = dirname(binaryPath);
-    if (basename(binaryDir) === 'MacOS' && basename(dirname(binaryDir)) === 'Contents') {
-        return join(dirname(binaryDir), 'Resources', 'application.ini');
-    }
-    return join(binaryDir, 'application.ini');
-}
-/**
- * Reads the `BuildID=` of the launchable build (the `moz:buildID` the
- * browser reports). Undefined when the file or the key is missing, so a
- * caller can simply leave the attribute off.
- *
- * @param engineDir - Absolute engine directory
- * @param launchablePath - Engine-relative launchable binary path
- */
-export async function readBuildId(engineDir, launchablePath) {
-    const iniPath = applicationIniPath(join(engineDir, launchablePath));
-    let content;
-    try {
-        content = await readText(iniPath);
-    }
-    catch (error) {
-        if (getNodeErrorCode(error) !== 'ENOENT') {
-            verbose(`Build id: could not read ${iniPath} — ${toError(error).message}`);
-        }
-        return undefined;
-    }
-    const match = /^BuildID=(\S+)\s*$/m.exec(content);
-    return match?.[1];
-}
-/**
- * When the launchable build's compiled code was last linked: the newest
- * mtime of the binary and the `libxul` beside it. Undefined when neither
- * can be read.
- *
- * @param engineDir - Absolute engine directory
- * @param launchablePath - Engine-relative launchable binary path
- */
-export async function readLinkedAt(engineDir, launchablePath) {
-    const binary = join(engineDir, launchablePath);
-    const candidates = [binary, ...LINKED_LIBRARY_NAMES.map((name) => join(dirname(binary), name))];
-    let newest;
-    for (const path of candidates) {
-        try {
-            // stat follows the dist/bin symlinks to the linked objdir file.
-            const { mtimeMs } = await stat(path);
-            if (newest === undefined || mtimeMs > newest.mtimeMs)
-                newest = { mtimeMs, path };
-        }
-        catch {
-            // A platform's other library names are simply absent.
-        }
-    }
-    return newest;
-}

package/dist/src/core/license-headers.d.ts

@@ -1,103 +0,0 @@
-import type { ProjectLicense } from '../types/config.js';
-/**
- * Comment style for license header formatting.
- * - `js`:   `// ...` line comments
- * - `css`:  block comments
- * - `hash`: `# ...` line comments (FTL, shell, etc.)
- */
-export type CommentStyle = 'js' | 'css' | 'hash';
-/** Default license when fireforge.json omits the license field. */
-export declare const DEFAULT_LICENSE: ProjectLicense;
-/**
- * Returns a formatted license header comment for the given license and
- * comment style.
- *
- * @param license - SPDX identifier of the project license
- * @param style   - Comment syntax to wrap the header in
- * @returns Multi-line string ready to be placed at the top of a source file
- */
-export declare function getLicenseHeader(license: ProjectLicense, style: CommentStyle): string;
-/**
- * Returns true if `content` starts with any known license header for the
- * given comment style.
- *
- * For `js` files, MPL-2.0 is also accepted in the upstream Mozilla block-
- * comment form (`/* ... *\/`) used by the Firefox source tree, not just the
- * `// ` line-comment form `getLicenseHeader` emits. Otherwise a new JS file
- * copied from upstream Firefox hits `missing-license-header` even with a
- * verbatim standard MPL header.
- *
- * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
- * leading the file are tolerated: Mozilla's canonical layout puts those on
- * lines 1 and 2 with the MPL header on lines 3+, which a raw `startsWith` check
- * would miss.
- *
- * The MPL-2.0 header is additionally matched on normalized whitespace (see
- * {@link normalizeCommentHead}) so upstream files using the older Mozilla
- * wrap (breaking after "file," instead of "with this") are accepted too.
- * Only the wrap position differs, never the wording.
- *
- * @param content - File content to check
- * @param style   - Comment syntax of the file
- */
-export declare function hasAnyLicenseHeader(content: string, style: CommentStyle): boolean;
-/**
- * Returns true if `content` starts with the verbatim upstream Mozilla
- * MPL-2.0 block header (`/* This Source Code Form … *\/`), optionally
- * preceded by editor-directive comments, the exact shape a JS file copied
- * from the Firefox source tree carries.
- *
- * Independent of the project license: a new JS file that
- * legitimately keeps its upstream MPL block header is valid in an
- * EUPL/GPL/0BSD project too.
- *
- * Matching is wrap-agnostic: after the exact `startsWith` fast path, the
- * leading block comment is compared on normalized whitespace (see
- * {@link normalizeCommentHead}) so the older upstream wrap (breaking after
- * "file," instead of "with this", as `ext-browser.js` ships) passes too.
- * Only the line-break position may differ. Altered wording still rejects.
- *
- * @param content - File content to check
- */
-export declare function hasUpstreamMplBlockHeader(content: string): boolean;
-/**
- * Returns true if `content` starts with any known license header in any
- * comment style (js, css, hash).
- *
- * @param content - File content to check
- */
-export declare function hasAnyLicenseHeaderAnyStyle(content: string): boolean;
-/**
- * Returns true if the first few lines of `content` contain a recognized
- * upstream license identifier string: Mozilla's MPL boilerplate, an SPDX
- * tag, the common permissive/copyleft license names, or the CC0
- * public-domain dedication upstream test files carry.
- *
- * @param content  - File content to check
- * @param maxLines - Number of leading lines to inspect (default 10)
- */
-export declare function containsUpstreamLicenseText(content: string, maxLines?: number): boolean;
-/**
- * Returns true when the head of `content` carries a recognized third-party
- * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0) or the
- * CC0 public-domain dedication, in any comment style. Used by `export` to
- * treat such files as vendored: offering to prepend the project's own
- * license header onto a byte-identity-pinned upstream bundle, or onto a
- * test file Mozilla dedicated to the public domain, would mislicense code
- * the project does not own.
- *
- * @param content  - File content to check
- * @param maxLines - Number of leading lines to inspect (default 30, because
- *   full MIT/BSD license texts run longer than the 10-line project-header
- *   scan)
- */
-export declare function hasThirdPartyPermissiveBanner(content: string, maxLines?: number): boolean;
-/**
- * Prepends the license header to a file on disk if it is not already present.
- *
- * @param filePath - Absolute path to the file
- * @param license  - SPDX identifier of the license to add
- * @param style    - Comment syntax matching the file type
- * @returns true if the header was added, false if already present
- */
-export declare function addLicenseHeaderToFile(filePath: string, license: ProjectLicense, style: CommentStyle): Promise<boolean>;