@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/diff/model.js

@@ -0,0 +1,267 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The unified diff as git writes it (`git diff --binary`, `git diff-tree -p`):
+ * a {@link Patch} of per-file {@link FileDiff} sections, parsed from bytes and
+ * written back to the same bytes.
+ *
+ * Bytes and strings: a patch is bytes. {@link parsePatch} decodes it once, as
+ * UTF-8 when the whole input is valid UTF-8 and as Latin-1 (one character per
+ * byte) otherwise, and records the choice in `encoding`. {@link formatPatch}
+ * encodes every string back the same way, so parse then format is the
+ * identity on any input. Patches FireForge generates are always valid UTF-8,
+ * because the generator turns a file that is not into a binary section; the
+ * Latin-1 reading exists for patches written elsewhere, and for those it
+ * reads a Latin-1 file's lines as the right characters.
+ *
+ * Every line is kept verbatim (headers, hunk headers, `\ No newline` markers,
+ * binary payloads, lines that belong to nothing), so a section of real git
+ * output never loses a byte. The parsed fields are a reading of those lines.
+ */
+import { unquoteC } from '../kernel/text.js';
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+const UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+function decode(input) {
+    try {
+        return { text: UTF8.decode(input), encoding: 'utf8' };
+    }
+    catch {
+        return { text: Buffer.from(input).toString('latin1'), encoding: 'latin1' };
+    }
+}
+/** A path as git wrote it (quoted or bare), decoded from its bytes as UTF-8. */
+function headerPath(raw, quoted, encoding) {
+    return (quoted ? unquoteC(raw, encoding) : Buffer.from(raw, encoding)).toString('utf8');
+}
+const QUOTED_HEADER = /^(?:"[ab]\/((?:[^"\\]|\\.)*)"|[ab]\/(\S+)) (?:"[ab]\/((?:[^"\\]|\\.)*)"|[ab]\/(.+))$/;
+/**
+ * Reads the two paths of a `diff --git` line. The quoted form is unquoted;
+ * the bare form is split symmetrically first (`a/<p> b/<p>`), which is exact
+ * even when `<p>` holds ` b/`, and at the first ` b/` otherwise.
+ *
+ * @param line - The line
+ * @param encoding - How the line's characters map to bytes
+ * @returns The paths, or undefined when the line is not a `diff --git` header
+ */
+export function parseGitHeader(line, encoding = 'utf8') {
+    if (!line.startsWith('diff --git '))
+        return undefined;
+    const body = line.slice('diff --git '.length);
+    const quoted = QUOTED_HEADER.exec(body);
+    if (quoted && (quoted[1] !== undefined || quoted[3] !== undefined)) {
+        return {
+            oldPath: headerPath(quoted[1] ?? quoted[2] ?? '', quoted[1] !== undefined, encoding),
+            newPath: headerPath(quoted[3] ?? quoted[4] ?? '', quoted[3] !== undefined, encoding),
+        };
+    }
+    if (!body.startsWith('a/') || /[\n\r\u2028\u2029]/.test(body))
+        return undefined;
+    const rest = body.slice(2);
+    if ((rest.length - 3) % 2 === 0) {
+        const candidate = rest.slice(0, (rest.length - 3) / 2);
+        if (rest === `${candidate} b/${candidate}`) {
+            const path = headerPath(candidate, false, encoding);
+            return { oldPath: path, newPath: path };
+        }
+    }
+    const split = rest.indexOf(' b/', 1);
+    if (split === -1 || split + 3 >= rest.length)
+        return undefined;
+    return {
+        oldPath: headerPath(rest.slice(0, split), false, encoding),
+        newPath: headerPath(rest.slice(split + 3), false, encoding),
+    };
+}
+/** Reads one extended header line into `fields`. Unknown lines are ignored. */
+function readHeaderLine(line, fields, encoding) {
+    const match = /^(new file mode|deleted file mode|old mode|new mode|rename from|rename to|copy from|copy to) (.+)$/.exec(line);
+    const [, key, value = ''] = match ?? [];
+    if (key === 'new file mode') {
+        fields.status = 'added';
+        fields.newMode = value;
+    }
+    else if (key === 'deleted file mode') {
+        fields.status = 'deleted';
+        fields.oldMode = value;
+    }
+    else if (key === 'old mode')
+        fields.oldMode = value;
+    else if (key === 'new mode')
+        fields.newMode = value;
+    else if (key !== undefined) {
+        fields.status = key.startsWith('rename') ? 'renamed' : 'copied';
+        const path = headerPath(value, value.startsWith('"'), encoding);
+        if (key.endsWith('from'))
+            fields.oldPath = path;
+        else
+            fields.newPath = path;
+    }
+    else if (/^Binary files .* differ$/.test(line))
+        fields.binary = 'stub';
+    else {
+        const index = /^index ([0-9a-f]+)\.\.([0-9a-f]+)(?: (\d+))?$/.exec(line);
+        if (index?.[1] !== undefined && index[2] !== undefined) {
+            fields.oldHash = index[1];
+            fields.newHash = index[2];
+            if (index[3] !== undefined) {
+                fields.oldMode ??= index[3];
+                fields.newMode ??= index[3];
+            }
+        }
+    }
+}
+/** A parsed hunk header, or undefined. */
+function hunkCounts(line) {
+    const match = HUNK_HEADER.exec(line);
+    if (!match)
+        return undefined;
+    return {
+        oldStart: Number(match[1]),
+        oldCount: match[2] === undefined ? 1 : Number(match[2]),
+        newStart: Number(match[3]),
+        newCount: match[4] === undefined ? 1 : Number(match[4]),
+    };
+}
+class Walker {
+    lines;
+    encoding;
+    index = 0;
+    constructor(lines, encoding) {
+        this.lines = lines;
+        this.encoding = encoding;
+    }
+    get line() {
+        return this.lines[this.index];
+    }
+    atSection() {
+        const line = this.line;
+        return line !== undefined && parseGitHeader(line, this.encoding) !== undefined;
+    }
+    atHunk() {
+        const line = this.line;
+        return line !== undefined && HUNK_HEADER.test(line);
+    }
+    /** Takes lines while `keep` holds, up to the next section. */
+    takeWhile(keep) {
+        const taken = [];
+        while (this.line !== undefined && !this.atSection() && keep(this.line)) {
+            taken.push(this.line);
+            this.index++;
+        }
+        return taken;
+    }
+}
+/**
+ * Reads a hunk body by its header counts, as `git apply` does: a line that
+ * does not fit (or the end of the counts) ends it. An empty line inside the
+ * counts is an empty context line.
+ */
+function readHunk(walker) {
+    const header = walker.line ?? '';
+    const counts = hunkCounts(header) ?? { oldStart: 0, oldCount: 0, newStart: 0, newCount: 0 };
+    walker.index++;
+    const lines = [];
+    let oldLeft = counts.oldCount;
+    let newLeft = counts.newCount;
+    for (let line = walker.line; line !== undefined; line = walker.line) {
+        const marker = line.charAt(0);
+        if (marker === '\\') {
+            if (lines.length === 0)
+                break;
+        }
+        else if (oldLeft <= 0 && newLeft <= 0)
+            break;
+        else if (marker === ' ' || line === '') {
+            oldLeft--;
+            newLeft--;
+        }
+        else if (marker === '-')
+            oldLeft--;
+        else if (marker === '+')
+            newLeft--;
+        else
+            break;
+        lines.push(line);
+        walker.index++;
+    }
+    const trailing = walker.takeWhile(() => !walker.atHunk());
+    return { ...counts, header, lines, trailing };
+}
+function readSection(walker) {
+    const encoding = walker.encoding;
+    const first = walker.line ?? '';
+    const paths = parseGitHeader(first, encoding) ?? { oldPath: '', newPath: '' };
+    const fields = { ...paths, status: 'modified' };
+    walker.index++;
+    const header = [
+        first,
+        ...walker.takeWhile((line) => !walker.atHunk() && line !== 'GIT binary patch'),
+    ];
+    for (const line of header.slice(1))
+        readHeaderLine(line, fields, encoding);
+    const hunks = [];
+    let binaryPatch = [];
+    if (walker.line === 'GIT binary patch') {
+        fields.binary = 'patch';
+        binaryPatch = walker.takeWhile(() => true);
+    }
+    else {
+        while (walker.atHunk())
+            hunks.push(readHunk(walker));
+    }
+    return {
+        ...fields,
+        path: fields.status === 'deleted' ? fields.oldPath : fields.newPath,
+        header,
+        hunks,
+        binaryPatch,
+        encoding,
+    };
+}
+/**
+ * Parses a patch. Never throws: what it cannot read is kept verbatim as
+ * preamble, header or trailing lines.
+ *
+ * @param input - The patch bytes, or text already decoded (taken as UTF-8)
+ */
+export function parsePatch(input) {
+    const { text, encoding } = typeof input === 'string' ? { text: input, encoding: 'utf8' } : decode(input);
+    const lines = text === '' ? [] : text.split('\n');
+    const finalNewline = lines.at(-1) === '' || lines.length === 0;
+    if (lines.at(-1) === '')
+        lines.pop();
+    const crlf = finalNewline && lines.length > 0 && lines.every((line) => line.endsWith('\r'));
+    const walker = new Walker(crlf ? lines.map((line) => line.slice(0, -1)) : lines, encoding);
+    const preamble = walker.takeWhile(() => true);
+    const files = [];
+    while (walker.atSection())
+        files.push(readSection(walker));
+    return { preamble, files, encoding, eol: crlf ? '\r\n' : '\n', finalNewline };
+}
+/** Every line of a section, in order. */
+function sectionLines(file) {
+    return [
+        ...file.header,
+        ...file.hunks.flatMap((hunk) => [hunk.header, ...hunk.lines, ...hunk.trailing]),
+        ...file.binaryPatch,
+    ];
+}
+/**
+ * Writes a patch back to bytes: the exact input of {@link parsePatch} for a
+ * parsed patch. A patch assembled from other patches' sections encodes each
+ * section by its own `encoding`.
+ *
+ * @param patch - The patch
+ */
+export function formatPatch(patch) {
+    const groups = [
+        { lines: patch.preamble, encoding: patch.encoding },
+        ...patch.files.map((file) => ({ lines: sectionLines(file), encoding: file.encoding })),
+    ];
+    const chunks = groups
+        .filter((group) => group.lines.length > 0)
+        .map((group) => Buffer.from(group.lines.join(patch.eol) + patch.eol, group.encoding));
+    const bytes = Buffer.concat(chunks);
+    return patch.finalNewline || bytes.length === 0
+        ? bytes
+        : bytes.subarray(0, bytes.length - patch.eol.length);
+}

package/dist/src/diff/query.js

@@ -0,0 +1,65 @@
+/**
+ * Splits a hunk into its old and new lines. A ``
+ * marker applies to the side of the line before it: a removed line's marks
+ * the old side, an added line's the new side, a context line's both.
+ *
+ * @param hunk - The hunk
+ */
+export function hunkSides(hunk) {
+    const old = [];
+    const next = [];
+    let oldNoNewline = false;
+    let newNoNewline = false;
+    let previous = '';
+    for (const line of hunk.lines) {
+        const marker = line.charAt(0);
+        if (marker === '\\') {
+            if (previous !== '+')
+                oldNoNewline = true;
+            if (previous !== '-')
+                newNoNewline = true;
+            continue;
+        }
+        const text = line.slice(1);
+        if (marker !== '+')
+            old.push(text);
+        if (marker !== '-')
+            next.push(text);
+        previous = marker === '-' || marker === '+' ? marker : ' ';
+    }
+    return { old, new: next, oldNoNewline, newNoNewline };
+}
+/**
+ * Every path a patch touches, sorted and unique: both sides of a rename, the
+ * new side of a copy, the path of anything else.
+ *
+ * @param patch - The patch
+ */
+export function affectedPaths(patch) {
+    const paths = new Set();
+    for (const file of patch.files) {
+        paths.add(file.path);
+        if (file.status === 'renamed')
+            paths.add(file.oldPath);
+    }
+    return [...paths].sort();
+}
+/**
+ * The lines a section adds, with their line numbers in the new file.
+ *
+ * @param file - The section
+ */
+export function addedLines(file) {
+    const added = [];
+    for (const hunk of file.hunks) {
+        let line = hunk.newStart;
+        for (const body of hunk.lines) {
+            const marker = body.charAt(0);
+            if (marker === '+')
+                added.push({ line, text: body.slice(1) });
+            if (marker === '+' || marker === ' ' || body === '')
+                line++;
+        }
+    }
+    return added;
+}

package/dist/src/doctor/index.js

@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `doctor`: a table of small checks over the project and the host, each
+ * answering ok, warn or fail with what to do about it, and one row per tool
+ * the project declares in `externalToolchains`. Nothing here repairs
+ * anything except, on request, undoing transactions a dead process left
+ * unfinished.
+ */
+import { join, resolve } from 'node:path';
+import { engineLockPath, listWorkspaces } from '../engine/index.js';
+import { loadFurnaceConfig, typingDrift } from '../furnace/index.js';
+import { FireForgeError, toError } from '../kernel/errors.js';
+import { exists, freeDiskSpace, listDir } from '../kernel/fs.js';
+import { inspectJournal, recoverJournal } from '../kernel/journal.js';
+import { readLockStatus } from '../kernel/lock.js';
+import { findExecutable, run } from '../kernel/process/index.js';
+import { diagnose, trackedFiles } from '../mode/index.js';
+import { hostPaths, loadProject, } from '../project/index.js';
+/** A full build writes about 20 GiB; below this a build is likely to run out. */
+const LOW_DISK_BYTES = 25 * 1024 ** 3;
+const GIB = 1024 ** 3;
+const failed = (error) => ({
+    status: 'fail',
+    detail: toError(error).message,
+    ...(error instanceof FireForgeError && error.hint !== undefined ? { fix: error.hint } : {}),
+});
+async function python() {
+    const found = await findExecutable('python3');
+    return found === undefined
+        ? {
+            status: 'fail',
+            detail: 'python3 is not on PATH, and mach needs it',
+            fix: 'Install Python 3, then run "fireforge bootstrap".',
+        }
+        : { status: 'ok', detail: found };
+}
+/** Where transactions keep their journals: the project state and every pool workspace. */
+async function journalPaths({ host, project }) {
+    const directories = [
+        ...(project === undefined ? [] : [project.paths.stateDir]),
+        ...(await listWorkspaces(host)).map((workspace) => workspace.dir),
+    ];
+    const paths = [];
+    for (const directory of directories) {
+        for (const entry of await listDir(directory)) {
+            if (entry.kind === 'file' && entry.name.endsWith('.journal')) {
+                paths.push(join(directory, entry.name));
+            }
+        }
+        for (const entry of await listDir(join(directory, 'journals'))) {
+            if (entry.kind === 'file')
+                paths.push(join(directory, 'journals', entry.name));
+        }
+    }
+    return paths;
+}
+async function journals(context) {
+    const interrupted = [];
+    let recovered = 0;
+    for (const path of await journalPaths(context)) {
+        const pending = await inspectJournal(path);
+        if (pending === undefined || pending.ownerAlive)
+            continue;
+        if (context.recover && (await recoverJournal(path)))
+            recovered += 1;
+        else
+            interrupted.push(`${pending.label} (${pending.paths.length} path(s), ${path})`);
+    }
+    if (interrupted.length > 0) {
+        return {
+            status: 'fail',
+            detail: `Interrupted and not undone: ${interrupted.join('; ')}`,
+            fix: 'Run "fireforge doctor --recover" to restore the files those runs were changing.',
+        };
+    }
+    return {
+        status: 'ok',
+        detail: recovered > 0 ? `Undid ${recovered} interrupted run(s)` : 'No interrupted run left anything',
+    };
+}
+async function locks({ host, project }) {
+    const paths = [
+        ...(project === undefined ? [] : [engineLockPath(project)]),
+        join(host.locks, 'display'),
+        join(host.locks, 'build'),
+    ];
+    const held = [];
+    const unreadable = [];
+    for (const path of paths) {
+        const lock = await readLockStatus(path);
+        if (lock.unidentified > 0)
+            unreadable.push(path);
+        for (const holder of lock.holders) {
+            const command = holder.info['command'];
+            held.push(`${path} by PID ${holder.pid}${command === undefined ? '' : ` (${command})`} since ${holder.requestedAt}`);
+        }
+    }
+    if (unreadable.length > 0) {
+        return {
+            status: 'warn',
+            detail: `Held by something that left no readable record: ${unreadable.join(', ')}`,
+            fix: 'When no fireforge command is running, delete those directories.',
+        };
+    }
+    return { status: 'ok', detail: held.length === 0 ? 'None held' : `Held: ${held.join('; ')}` };
+}
+async function disk({ host, project }) {
+    const where = (await exists(host.root)) ? host.root : project?.root;
+    const free = where === undefined ? undefined : await freeDiskSpace(where);
+    if (free === undefined)
+        return undefined;
+    const detail = `${(free / GIB).toFixed(1)} GiB free at ${where ?? ''}`;
+    return free >= LOW_DISK_BYTES
+        ? { status: 'ok', detail }
+        : {
+            status: 'warn',
+            detail: `${detail}; a full build writes about 20 GiB`,
+            fix: 'Free space, or remove workspaces you no longer use with "fireforge workspace remove <name>".',
+        };
+}
+async function typing({ project }) {
+    if (project === undefined || !(await exists(project.paths.furnace)))
+        return undefined;
+    const drift = await typingDrift(project, await loadFurnaceConfig(project), await trackedFiles(project));
+    return drift.length === 0
+        ? { status: 'ok', detail: 'Generated typing files are current' }
+        : {
+            status: 'warn',
+            detail: `Out of date: ${drift.map((file) => file.file).join(', ')}`,
+            fix: 'Run "fireforge furnace types".',
+        };
+}
+/** How long `xcrun -find` may take before the tool counts as missing. */
+const XCRUN_TIMEOUT_MS = 5000;
+/** Where a declared tool is: its `path`, what `xcrun -find` prints, or its place on PATH. */
+async function locateTool(project, tool) {
+    if (tool.path !== undefined) {
+        const candidate = resolve(project.root, tool.path);
+        return (await exists(candidate)) ? candidate : undefined;
+    }
+    if (tool.xcrun !== true)
+        return findExecutable(tool.name);
+    try {
+        const found = await run('xcrun', ['-find', tool.name], { timeoutMs: XCRUN_TIMEOUT_MS });
+        const line = found.stdout.split(/\r?\n/).find((entry) => entry.trim() !== '');
+        return found.exitCode === 0 ? line?.trim() : undefined;
+    }
+    catch {
+        // No xcrun on this host, or it did not answer: the tool has no path either way.
+        return undefined;
+    }
+}
+/** One row per tool of `externalToolchains`: found, or missing as a failure or a warning. */
+async function toolchains(project) {
+    const rows = [];
+    for (const toolchain of project.config.externalToolchains ?? []) {
+        for (const tool of toolchain.tools) {
+            const row = {
+                id: `toolchain:${toolchain.name}/${tool.name}`,
+                title: `Toolchain ${toolchain.name}: ${tool.name}`,
+            };
+            const found = await locateTool(project, tool);
+            if (found !== undefined) {
+                rows.push({ ...row, status: 'ok', detail: found });
+                continue;
+            }
+            const where = tool.path !== undefined
+                ? `at ${tool.path}`
+                : tool.xcrun === true
+                    ? `by "xcrun -find ${tool.name}"`
+                    : 'on PATH';
+            rows.push({
+                ...row,
+                status: tool.required ? 'fail' : 'warn',
+                detail: `${tool.name}, which toolchain "${toolchain.name}" ${tool.required ? 'requires' : 'uses'}, was not found ${where}`,
+                fix: `Install ${tool.name}, or correct the "${toolchain.name}" entry of externalToolchains in fireforge.json.`,
+            });
+        }
+    }
+    return rows;
+}
+const HOST_CHECKS = [
+    { id: 'python', title: 'Python for mach', run: python },
+    { id: 'journals', title: 'Interrupted runs', run: journals },
+    { id: 'locks', title: 'Locks', run: locks },
+    { id: 'disk', title: 'Disk space', run: disk },
+    { id: 'typing', title: 'Component typing files', run: typing },
+];
+/**
+ * Diagnoses the project containing `cwd` and the host.
+ *
+ * @param cwd - Where the command was run
+ * @param env - The environment of the invocation
+ * @param options - See {@link DoctorOptions}
+ */
+export async function runDoctor(cwd, env, options = {}) {
+    const checks = [];
+    let project;
+    try {
+        project = await loadProject(cwd, env);
+        checks.push({
+            id: 'config',
+            title: 'Configuration',
+            status: 'ok',
+            detail: `${project.paths.config} (${project.mode} mode)`,
+        });
+    }
+    catch (error) {
+        checks.push({ id: 'config', title: 'Configuration', ...failed(error) });
+    }
+    if (project !== undefined)
+        checks.push(...(await diagnose(project)));
+    const context = { host: hostPaths(env), project, recover: options.recover === true };
+    for (const check of HOST_CHECKS) {
+        const answer = await check.run(context).catch(failed);
+        if (answer !== undefined)
+            checks.push({ id: check.id, title: check.title, ...answer });
+    }
+    if (project !== undefined)
+        checks.push(...(await toolchains(project)));
+    return { checks, healthy: checks.every((check) => check.status !== 'fail') };
+}
+/**
+ * The report for a person: one line per check, with the fix under anything
+ * that is not ok.
+ *
+ * @param report - The report
+ */
+export function renderDoctor(report) {
+    const width = Math.max(...report.checks.map((check) => check.title.length));
+    const lines = [];
+    for (const check of report.checks) {
+        lines.push(`${check.status.padEnd(4)}  ${check.title.padEnd(width)}  ${check.detail}`);
+        if (check.fix !== undefined)
+            lines.push(`      ${check.fix}`);
+    }
+    const count = (status) => report.checks.filter((check) => check.status === status).length;
+    lines.push(`${count('ok')} ok, ${count('warn')} warning(s), ${count('fail')} failed.`);
+    return lines;
+}