@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/config/edit.js

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Reading and editing single keys of `fireforge.json` through the schema: a
+ * key exists when the schema declares it, a value is typed by the key's
+ * schema, and the whole document is validated before anything is written.
+ * An edit rewrites only the changed value, so the file keeps its layout.
+ * `mode` is the one key an edit cannot change: it moves together with the
+ * `source` section and the project's files, which a single-key edit cannot do.
+ *
+ * A key is written the way validation reports paths: dotted names, array
+ * indices as `[2]` or `.2`, and a dictionary key that is not a plain word in
+ * brackets, as in `typecheck.projectOverrides["browser/jsconfig.json"]`.
+ */
+import { join } from 'node:path';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { writeFile } from '../kernel/fs.js';
+import { isRecord, parseJson, stringifyJson, } from '../kernel/json.js';
+import { editJsonText } from '../kernel/json-edit.js';
+import { withLock } from '../kernel/lock.js';
+import { describeKeys } from '../kernel/schema.js';
+import { nearest } from '../kernel/text.js';
+import { CONFIG_FILE, readConfigDocument } from './load.js';
+import { configSchema } from './schema/index.js';
+import { modeKey } from './schema/source.js';
+const RESERVED_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+function unknownKey(key, why) {
+    const suggestion = nearest(key, describeKeys(configSchema).map((info) => info.path));
+    return new FireForgeError('config-unknown-key', `"${key}" ${why}`, {
+        exitCode: ExitCode.INVALID_ARGUMENT,
+        hint: suggestion === undefined
+            ? 'docs/configuration.md lists the keys of fireforge.json.'
+            : `Did you mean "${suggestion}"?`,
+    });
+}
+/** The text of a bracketed, JSON-quoted key segment. */
+function quoted(key, body) {
+    let value;
+    try {
+        value = parseJson(`"${body}"`);
+    }
+    catch {
+        value = undefined;
+    }
+    if (typeof value !== 'string')
+        throw unknownKey(key, 'has a malformed quoted segment');
+    return value;
+}
+/** Splits a key into its segments, refusing a malformed or prototype-reaching one. */
+function segmentsOf(key) {
+    const segments = [];
+    let rest = key;
+    while (rest !== '') {
+        const match = /^\["((?:[^"\\]|\\.)*)"\]/.exec(rest) ??
+            /^\[(\d+)\]/.exec(rest) ??
+            (segments.length === 0 ? /^([^.[\]]+)/ : /^\.([^.[\]]+)/).exec(rest);
+        const segment = match?.[1];
+        if (match === null || segment === undefined)
+            throw unknownKey(key, 'is not a valid key path');
+        const name = match[0].startsWith('["') ? quoted(key, segment) : segment;
+        if (RESERVED_SEGMENTS.has(name))
+            throw unknownKey(key, `cannot name "${name}"`);
+        segments.push(name);
+        rest = rest.slice(match[0].length);
+    }
+    if (segments.length === 0)
+        throw unknownKey(key, 'is empty');
+    return segments;
+}
+/** The schema of the value a key path names, following object keys, dictionary keys and indices. */
+function schemaOf(key, segments) {
+    let current = configSchema;
+    for (const segment of segments) {
+        const structure = current.structure;
+        const { shape, element } = structure;
+        current =
+            shape === undefined ? element : Object.hasOwn(shape, segment) ? shape[segment] : undefined;
+        if (current === undefined)
+            throw unknownKey(key, 'is not a key of fireforge.json');
+    }
+    return current;
+}
+function describeKey(path, schema) {
+    return {
+        path,
+        type: schema.type,
+        doc: schema.doc,
+        required: !schema.isOptional && schema.fallback === undefined,
+        container: schema.structure.shape !== undefined,
+        defaultValue: schema.fallback?.value,
+    };
+}
+/** Every key `fireforge.json` declares, depth first, containers included. */
+export function configKeys() {
+    return describeKeys(configSchema).map((info) => describeKey(info.path, info.schema));
+}
+function valueAt(document, segments) {
+    let current = document;
+    for (const segment of segments) {
+        if (Array.isArray(current))
+            current = /^\d+$/.test(segment) ? current[Number(segment)] : undefined;
+        else if (isRecord(current) && Object.hasOwn(current, segment))
+            current = current[segment];
+        else
+            return undefined;
+    }
+    return current;
+}
+/**
+ * Reads one key from `fireforge.json` as written, beside its type,
+ * documentation and default.
+ *
+ * @param projectRoot - The project directory
+ * @param key - A key path such as `firefox.version`
+ * @throws `config-unknown-key` (exit code 8) for a key the schema does not declare
+ */
+export async function getConfigValue(projectRoot, key) {
+    const segments = segmentsOf(key);
+    const schema = schemaOf(key, segments);
+    const { document } = await readConfigDocument(projectRoot);
+    return { ...describeKey(key, schema), value: valueAt(document, segments) };
+}
+function issueLines(prefix, issues) {
+    return issues
+        .map((issue) => {
+        const path = issue.path === ''
+            ? prefix
+            : issue.path.startsWith('[') || prefix === ''
+                ? `${prefix}${issue.path}`
+                : `${prefix}.${issue.path}`;
+        return `"${path}" ${issue.message}`;
+    })
+        .join('\n  ');
+}
+function invalidValue(key, issues) {
+    return new FireForgeError('config-invalid-value', issueLines(key, issues), {
+        exitCode: ExitCode.INVALID_ARGUMENT,
+    });
+}
+/**
+ * Turns command-line text into the value a key takes. JSON is read as JSON
+ * when the key accepts the result (`4`, `true`, `null`, `["a"]`), and the text
+ * stays a string otherwise, so a string key never turns `128` into a number.
+ *
+ * @param key - A key path
+ * @param text - The value as typed
+ * @throws `config-invalid-value` (exit code 8) when the key accepts neither reading
+ */
+export function coerceConfigValue(key, text) {
+    const schema = schemaOf(key, segmentsOf(key));
+    let parsed;
+    try {
+        parsed = parseJson(text);
+    }
+    catch {
+        parsed = undefined;
+    }
+    const asJson = parsed === undefined ? undefined : schema.validate(parsed);
+    if (asJson?.ok === true && parsed !== undefined)
+        return parsed;
+    const asText = schema.validate(text);
+    if (asText.ok)
+        return text;
+    const issues = asJson !== undefined && !asJson.ok && typeof parsed !== 'string'
+        ? asJson.issues
+        : asText.issues;
+    throw invalidValue(key, issues);
+}
+/** A copy of `document` with `value` at the key path, creating missing objects on the way. */
+function withValue(document, key, segments, value) {
+    const next = structuredClone(document);
+    let parent = next;
+    for (const [index, segment] of segments.entries()) {
+        const last = index === segments.length - 1;
+        if (Array.isArray(parent)) {
+            const position = /^\d+$/.test(segment) ? Number(segment) : Number.NaN;
+            if (!(position <= parent.length)) {
+                throw unknownKey(key, `names index ${segment} of a list of ${parent.length}`);
+            }
+            if (last)
+                parent[position] = value;
+            else
+                parent = parent[position] ??= {};
+        }
+        else if (isRecord(parent)) {
+            const object = parent;
+            if (last)
+                object[segment] = value;
+            else
+                parent = object[segment] ??= {};
+        }
+        else {
+            throw unknownKey(key, 'reaches inside a value that is not an object or a list');
+        }
+    }
+    return next;
+}
+/** The refusal to move a project to another mode by editing its `mode` key. */
+function modeSwitch(target) {
+    return new FireForgeError('config-mode-switch', `"mode" cannot be set to ${JSON.stringify(target)} with "config set": the mode changes together with the "source" section and the files that hold the owned changes`, {
+        exitCode: ExitCode.INVALID_ARGUMENT,
+        hint: target === 'source'
+            ? 'Run "fireforge migrate --to-source" to convert a patch-mode project to source mode.'
+            : 'Run "fireforge export" to write the patch queue, then edit fireforge.json by hand: set "mode" to "patches" and remove "source" (docs/source-workflow.md, "Coming from patch mode, going back").',
+    });
+}
+/**
+ * Sets one key of `fireforge.json` from command-line text. The value is typed
+ * by the key's schema ({@link coerceConfigValue}), the whole resulting document
+ * must validate, and only the changed value is rewritten. Concurrent edits are
+ * serialised, so none is lost.
+ *
+ * @param projectRoot - The project directory
+ * @param key - A key path such as `build.jobs`
+ * @param text - The value as typed
+ * @throws `config-unknown-key`, `config-invalid-value`, or `config-mode-switch` for a
+ *   change of `mode` (exit code 8)
+ */
+export async function setConfigValue(projectRoot, key, text) {
+    const segments = segmentsOf(key);
+    const value = coerceConfigValue(key, text);
+    const lock = join(projectRoot, '.fireforge', 'config.lock');
+    return withLock(lock, { label: CONFIG_FILE, info: { command: 'config set' } }, async () => {
+        const current = await readConfigDocument(projectRoot);
+        if (key === 'mode' && value !== (current.document['mode'] ?? modeKey.fallback?.value)) {
+            throw modeSwitch(value);
+        }
+        const next = withValue(current.document, key, segments, value);
+        const result = configSchema.validate(next);
+        if (!result.ok)
+            throw invalidValue('', result.issues);
+        const edited = editJsonText(current.text, next) ?? stringifyJson(next);
+        const changed = edited !== current.text;
+        if (changed)
+            await writeFile(join(projectRoot, CONFIG_FILE), edited);
+        return { path: key, value, changed };
+    });
+}

package/dist/src/config/index.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge.json`: its schema (the single source of its types, validation,
+ * key paths and key documentation), loading, and editing one key at a time.
+ */
+export { coerceConfigValue, configKeys, getConfigValue, setConfigValue } from './edit.js';
+export { CONFIG_FILE, loadConfig, readConfigDocument } from './load.js';
+export { upgradeConfig } from './previous.js';
+export { CHECK_STEPS } from './schema/check.js';
+export { FIREFOX_PRODUCTS, inferFirefoxProduct, } from './schema/firefox.js';
+export { ARTIFACTS_PLACEHOLDER } from './schema/gate.js';
+export { DEFAULT_LICENSE, markerComment, PROJECT_LICENSES } from './schema/identity.js';
+export { configSchema } from './schema/index.js';
+export { fileSizeBands, LINT_RULE_IDS, matchesPropertyName, patchSizeBands, } from './schema/lint.js';
+export { PROJECT_MODES } from './schema/source.js';

package/dist/src/config/load.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** Reading `fireforge.json`: the raw document and the validated configuration. */
+import { join } from 'node:path';
+import { ExitCode, FireForgeError, toError } from '../kernel/errors.js';
+import { readTextIfExists } from '../kernel/fs.js';
+import { isRecord, parseJson } from '../kernel/json.js';
+import { configSchema } from './schema/index.js';
+/** The configuration file's name at the project root. */
+export const CONFIG_FILE = 'fireforge.json';
+/**
+ * Reads `fireforge.json` as a JSON object without validating it, for editing.
+ *
+ * @param projectRoot - The directory holding the file
+ * @returns The document and its text as on disk
+ * @throws `config-missing` or `config-invalid` (exit code 2)
+ */
+export async function readConfigDocument(projectRoot) {
+    const path = join(projectRoot, CONFIG_FILE);
+    const text = await readTextIfExists(path);
+    if (text === undefined) {
+        throw new FireForgeError('config-missing', `${path} does not exist`, {
+            exitCode: ExitCode.CONFIG_ERROR,
+            hint: 'Run "fireforge setup" to create a project.',
+        });
+    }
+    let document;
+    try {
+        document = parseJson(text, { source: path });
+    }
+    catch (error) {
+        throw new FireForgeError('config-invalid', toError(error).message, {
+            exitCode: ExitCode.CONFIG_ERROR,
+            cause: error,
+        });
+    }
+    if (!isRecord(document)) {
+        throw new FireForgeError('config-invalid', `${path} must hold a JSON object`, {
+            exitCode: ExitCode.CONFIG_ERROR,
+            hint: 'Restore fireforge.json from version control.',
+        });
+    }
+    return { document, text };
+}
+/**
+ * Loads and validates `fireforge.json`, with defaults applied. Every problem
+ * in the file is reported at once, each by its key path; an unknown key names
+ * the nearest known one.
+ *
+ * @param projectRoot - The directory holding the file
+ * @throws `config-missing` or `config-invalid` (exit code 2)
+ */
+export async function loadConfig(projectRoot) {
+    const { document } = await readConfigDocument(projectRoot);
+    return configSchema.parse(document, {
+        source: join(projectRoot, CONFIG_FILE),
+        code: 'config-invalid',
+        exitCode: ExitCode.CONFIG_ERROR,
+    });
+}