@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/queue/attribute.js

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Which patch an edit belongs to, when several patches change the edited
+ * file: the one whose lines the edit touches.
+ *
+ * Each patch's lines are the lines it adds that survive into the file the
+ * queue produces, found by diffing the file's state before and after each
+ * patch and following each added line through the later patches. An edit
+ * (the diff from that file to the engine's) touches the lines it removes or
+ * replaces, and for a pure insertion the lines on either side of it. When
+ * every touched line that any patch owns belongs to one patch, the edit is
+ * that patch's; otherwise (no patch's lines, or several) there is no answer
+ * and the caller falls back to its default owner. An absent file reads as
+ * empty. Binary content has no lines and never has an answer.
+ */
+import { parsePatch } from '../diff/index.js';
+import { diffTrees, writeTree } from '../git/index.js';
+/** Line numbers are 1-based. A hunk with no old lines names the line before it. */
+function oldStartOf(hunk) {
+    return hunk.oldCount === 0 ? hunk.oldStart + 1 : hunk.oldStart;
+}
+/** Where old line `line` is in the new file, or undefined when the hunks remove or replace it. */
+function follow(hunks, line) {
+    let offset = 0;
+    for (const hunk of hunks) {
+        const start = oldStartOf(hunk);
+        if (line < start)
+            break;
+        if (line >= start + hunk.oldCount) {
+            offset += hunk.newCount - hunk.oldCount;
+            continue;
+        }
+        let old = start;
+        let next = hunk.newCount === 0 ? hunk.newStart + 1 : hunk.newStart;
+        for (const body of hunk.lines) {
+            const marker = body.charAt(0);
+            if (marker === '+')
+                next += 1;
+            else if (marker === '-') {
+                if (old === line)
+                    return undefined;
+                old += 1;
+            }
+            else if (marker !== '\\') {
+                if (old === line)
+                    return next;
+                old += 1;
+                next += 1;
+            }
+        }
+        return undefined;
+    }
+    return line + offset;
+}
+/** The new-file line numbers of the lines the hunks add. */
+function addedLines(hunks) {
+    const added = [];
+    for (const hunk of hunks) {
+        let next = hunk.newCount === 0 ? hunk.newStart + 1 : hunk.newStart;
+        for (const body of hunk.lines) {
+            const marker = body.charAt(0);
+            if (marker === '+')
+                added.push(next);
+            if (marker !== '-' && marker !== '\\')
+                next += 1;
+        }
+    }
+    return added;
+}
+/** The old-file lines an edit touches: those it removes, and the neighbours of an insertion. */
+function touchedLines(hunks) {
+    const touched = new Set();
+    for (const hunk of hunks) {
+        let old = oldStartOf(hunk);
+        let previous = '';
+        for (const body of hunk.lines) {
+            const marker = body.charAt(0);
+            if (marker === '\\')
+                continue;
+            if (marker === '-') {
+                touched.add(old);
+                old += 1;
+            }
+            else if (marker === '+') {
+                if (previous !== '+' && previous !== '-') {
+                    touched.add(old - 1);
+                    touched.add(old);
+                }
+            }
+            else
+                old += 1;
+            previous = marker;
+        }
+    }
+    return touched;
+}
+/** Diffs one path between two states (absent reads as empty); undefined for binary content. */
+async function lineHunks(engine, path, from, to) {
+    const tree = (state) => writeTree(engine, state === null ? [] : [{ path, oid: state.oid, mode: state.mode }]);
+    const body = await diffTrees(engine, await tree(from), await tree(to), { paths: [path] });
+    if (body.length === 0)
+        return [];
+    const [file] = parsePatch(body).files;
+    return file === undefined || file.binary !== undefined ? undefined : [...file.hunks];
+}
+/** The patch whose lines an edit to one path touches, or undefined. */
+async function ownerOf(engine, path, history, now) {
+    const steps = [];
+    for (let index = 1; index < history.length; index++) {
+        const step = await lineHunks(engine, path, history[index - 1]?.state ?? null, history[index]?.state ?? null);
+        if (step === undefined)
+            return undefined;
+        steps.push(step);
+    }
+    const owners = new Map();
+    for (const [index, step] of steps.entries()) {
+        const patch = history[index + 1]?.patch;
+        if (patch === undefined)
+            continue;
+        for (const added of addedLines(step)) {
+            let line = added;
+            for (const later of steps.slice(index + 1)) {
+                if (line === undefined)
+                    break;
+                line = follow(later, line);
+            }
+            if (line !== undefined)
+                owners.set(line, patch);
+        }
+    }
+    const edit = await lineHunks(engine, path, history.at(-1)?.state ?? null, now);
+    if (edit === undefined)
+        return undefined;
+    const touched = new Set([...touchedLines(edit)].flatMap((line) => {
+        const owner = owners.get(line);
+        return owner === undefined ? [] : [owner];
+    }));
+    return touched.size === 1 ? [...touched][0] : undefined;
+}
+/**
+ * For each edited path more than one patch changes, the patch (by filename)
+ * whose lines the edit touches, where exactly one does.
+ *
+ * @param engine - The engine checkout
+ * @param projection - The queue's projection
+ * @param edited - The engine's state of each edited path
+ */
+export async function attributeEdits(engine, projection, edited) {
+    const attributed = new Map();
+    for (const [path, now] of edited) {
+        const history = projection.history(path);
+        if (new Set(history.flatMap((entry) => entry.patch ?? [])).size < 2)
+            continue;
+        const owner = await ownerOf(engine, path, history, now);
+        if (owner !== undefined)
+            attributed.set(path, owner);
+    }
+    return attributed;
+}

package/dist/src/queue/baseline.js

@@ -0,0 +1,409 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The queue baseline: what every engine path holds when the queue is cleanly
+ * applied, and how the engine's actual state compares with it.
+ *
+ * The projection is the queue replayed index-only onto the engine's HEAD
+ * ({@link projectQueue}). It records, for every path the queue touches, the
+ * state at the base and after each patch that changes it, so a path is
+ * judged against every state the queue can leave it in, binary files
+ * included (states are blob ids). It is cached under `.fireforge/` by queue
+ * digest and base commit.
+ *
+ * The engine's state is read through a private index (`captureWorktree`),
+ * so judging it never writes the engine's own index.
+ *
+ * Every write of engine files (import, rebase, discard, reset) is one
+ * `kernel/journal` transaction on the engine journal, and records in the
+ * project state the state it left each path in (the applied record). A path
+ * still holding that state is not an edit: when the queue changes underneath
+ * (a pulled patch, another branch of the project), the engine is merely
+ * behind, and the next import brings it up to date.
+ */
+import { basename, dirname, join } from 'node:path';
+import { captureWorktree, diffTrees, isRepository, readBlobs, resolveRevision, status, } from '../git/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { listDir, resolveContained, writeLink } from '../kernel/fs.js';
+import { readJsonIfExists, writeJson } from '../kernel/json.js';
+import { verbose } from '../kernel/log.js';
+import { s } from '../kernel/schema.js';
+import { defineStateSection, readState, updateState } from '../project/index.js';
+import { covers, replay, sparseTree, statesIn, } from './apply.js';
+import { pathsOf, queueError } from './queue.js';
+/**
+ * The engine's HEAD commit, the pristine Firefox the queue applies to.
+ *
+ * @param project - A patch-mode project
+ * @throws `engine-missing` (exit code 2) when `engine/` is not a git checkout with a commit
+ */
+export async function engineHead(project) {
+    const engine = project.paths.engine;
+    const head = (await isRepository(engine))
+        ? await resolveRevision(engine, 'HEAD', 'commit')
+        : undefined;
+    if (head === undefined) {
+        throw new FireForgeError('engine-missing', `${engine} is not a Firefox checkout.`, {
+            exitCode: ExitCode.CONFIG_ERROR,
+            hint: 'Run "fireforge download" to fetch the pinned Firefox into engine/.',
+        });
+    }
+    return head;
+}
+const stateSchema = s.object({ oid: s.string({ min: 1 }), mode: s.string({ min: 1 }) });
+/** The state the last engine write left each path in, where that differs from HEAD. */
+const appliedSchema = s.object({
+    /** The engine commit the record belongs to. */
+    base: s.string({ min: 1 }),
+    states: s.record(s.union(stateSchema, s.literal(null))),
+});
+const APPLIED = defineStateSection('queueApplied', appliedSchema, 'fireforge reset');
+/**
+ * The engine journal: one transaction at a time changes engine files, under
+ * the engine lock.
+ *
+ * @param project - A patch-mode project
+ */
+export function engineJournal(project) {
+    return join(project.paths.stateDir, 'engine.journal');
+}
+/**
+ * The states the last engine write left paths in, for an engine still at
+ * `base`. A path not listed holds (or was left at) its HEAD state.
+ *
+ * @param project - A patch-mode project
+ * @param base - The engine's HEAD commit
+ */
+export async function readApplied(project, base) {
+    const record = await readState(project, APPLIED);
+    return new Map(record?.base === base ? Object.entries(record.states) : []);
+}
+/**
+ * Records, inside the engine transaction, the states an engine write left
+ * paths in. A path left at its HEAD state is dropped from the record.
+ *
+ * @param tx - The engine transaction
+ * @param project - A patch-mode project
+ * @param written - `base`, and for each path its new state and its HEAD state
+ */
+export async function recordApplied(tx, project, written) {
+    await tx.change([project.paths.state], async () => {
+        await updateState(project, APPLIED, (record) => {
+            const states = record?.base === written.base ? { ...record.states } : {};
+            for (const [path, state] of written.states) {
+                if (sameState(state, written.head.get(path)))
+                    Reflect.deleteProperty(states, path);
+                else
+                    states[path] = state;
+            }
+            return Object.keys(states).length === 0 ? undefined : { base: written.base, states };
+        });
+    });
+}
+/**
+ * Forgets paths from the applied record (every path, without `paths`): they
+ * are no longer the queue's, and what they hold is the user's to keep or
+ * export.
+ *
+ * @param project - A patch-mode project
+ * @param paths - Engine paths; omitted, the whole record
+ */
+export async function forgetApplied(project, paths) {
+    await updateState(project, APPLIED, (record) => {
+        if (record === undefined || paths === undefined)
+            return undefined;
+        const states = { ...record.states };
+        for (const path of paths)
+            Reflect.deleteProperty(states, path);
+        return Object.keys(states).length === 0 ? undefined : { base: record.base, states };
+    });
+}
+const cacheSchema = s.object({
+    version: s.literal(1),
+    digest: s.string(),
+    base: s.string(),
+    start: s.string(),
+    baseStates: s.record(stateSchema),
+    steps: s.array(s.object({
+        patch: s.string(),
+        tree: s.string(),
+        fuzz: s.int({ min: 0 }),
+        replaced: s.array(s.string()),
+        changes: s.array(s.object({ path: s.string(), state: s.union(stateSchema, s.literal(null)) })),
+    })),
+    failure: s
+        .object({
+        index: s.int({ min: 0 }),
+        patch: s.string(),
+        conflicts: s.array(s.object({ path: s.string(), reason: s.string(), line: s.int().optional() })),
+        message: s.string(),
+    })
+        .optional(),
+});
+function cachePath(project) {
+    return join(project.paths.stateDir, 'queue-projection.json');
+}
+function buildProjection(queue, cache) {
+    const owners = new Map();
+    for (const patch of queue.patches) {
+        for (const path of patch.files)
+            owners.set(path, [...(owners.get(path) ?? []), patch.filename]);
+    }
+    const histories = new Map();
+    for (const path of owners.keys()) {
+        histories.set(path, [{ patch: undefined, state: cache.baseStates[path] ?? null }]);
+    }
+    for (const step of cache.steps) {
+        for (const change of step.changes) {
+            histories.get(change.path)?.push({ patch: step.patch, state: change.state });
+        }
+    }
+    return {
+        base: cache.base,
+        digest: cache.digest,
+        start: cache.start,
+        steps: cache.steps,
+        failure: cache.failure,
+        paths: [...owners.keys()].sort(),
+        treeBefore: (index) => index === 0 ? cache.start : (cache.steps[index - 1]?.tree ?? cache.start),
+        history: (path) => histories.get(path) ?? [{ patch: undefined, state: null }],
+        final: (path) => histories.get(path)?.at(-1)?.state ?? null,
+        owners: (path) => owners.get(path) ?? [],
+    };
+}
+async function readCache(project) {
+    try {
+        return await readJsonIfExists(cachePath(project), cacheSchema);
+    }
+    catch (error) {
+        verbose(`Ignoring an unreadable queue projection cache: ${String(error)}`);
+        return undefined;
+    }
+}
+/**
+ * Replays the queue onto the engine's HEAD (exactly, no reduced context) and
+ * records every state each path takes. Cached by queue digest and base.
+ *
+ * @param project - A patch-mode project
+ * @param queue - The project's queue
+ * @param options - `cache: false` leaves the cache as it is, for a queue
+ *   that is not (yet) the stored one
+ */
+export async function projectQueue(project, queue, options = {}) {
+    const engine = project.paths.engine;
+    const base = await engineHead(project);
+    const cached = await readCache(project);
+    if (cached?.digest === queue.digest &&
+        cached.base === base &&
+        (await resolveRevision(engine, cached.steps.at(-1)?.tree ?? cached.start, 'tree')) !== undefined) {
+        return buildProjection(queue, cached);
+    }
+    const paths = pathsOf(queue.patches);
+    const start = await sparseTree(engine, base, paths);
+    const result = await replay(engine, start, queue.patches);
+    const baseStates = {};
+    for (const [path, state] of await statesIn(engine, start, paths)) {
+        if (state !== null)
+            baseStates[path] = state;
+    }
+    const failure = result.failures[0];
+    const cache = {
+        version: 1,
+        digest: queue.digest,
+        base,
+        start,
+        baseStates,
+        steps: result.steps.map((step) => ({
+            ...step,
+            replaced: [...step.replaced],
+            changes: [...step.changes],
+        })),
+        ...(failure === undefined
+            ? {}
+            : { failure: { ...failure, conflicts: [...failure.conflicts] } }),
+    };
+    if (options.cache !== false)
+        await writeJson(cachePath(project), cache);
+    return buildProjection(queue, cache);
+}
+/**
+ * The engine's current state of each path, read through a private index.
+ *
+ * @param engine - The engine checkout
+ * @param base - A tree holding the paths' expected states (a sparse tree)
+ * @param paths - Engine paths
+ */
+export async function engineStates(engine, base, paths) {
+    if (paths.length === 0)
+        return new Map();
+    const tree = await captureWorktree(engine, { base, paths });
+    return statesIn(engine, tree, paths);
+}
+/** Whether two path states are the same: both absent, or the same blob and mode. */
+export function sameState(a, b) {
+    return (a ?? null) === null ? (b ?? null) === null : a?.oid === b?.oid && a?.mode === b?.mode;
+}
+function inScope(path, scope) {
+    return scope === undefined || scope.some((root) => covers(root, path));
+}
+/**
+ * Compares the engine with the queue baseline: every path the queue touches,
+ * and every other path that differs from HEAD.
+ *
+ * @param project - A patch-mode project
+ * @param projection - The queue's projection
+ * @param scope - Limit to these engine paths (files or directories)
+ * @returns One entry per path, sorted by path
+ */
+export async function classifyEngine(project, projection, scope) {
+    const engine = project.paths.engine;
+    const applied = await readApplied(project, projection.base);
+    const owned = projection.paths.filter((path) => inScope(path, scope));
+    const ownedSet = new Set(projection.paths);
+    const changed = (await status(engine, scope === undefined ? {} : { paths: scope.map((root) => root || '.') }))
+        .map((entry) => entry.path)
+        .filter((path) => !ownedSet.has(path));
+    const current = await engineStates(engine, projection.start, [
+        ...owned,
+        ...changed.filter((path) => applied.has(path)),
+    ]);
+    const outdated = (path) => applied.has(path) && sameState(current.get(path), applied.get(path));
+    const result = [];
+    for (const path of owned) {
+        const state = current.get(path) ?? null;
+        const verdict = sameState(state, projection.final(path))
+            ? 'clean'
+            : sameState(state, projection.history(path)[0]?.state)
+                ? 'unapplied'
+                : outdated(path)
+                    ? 'outdated'
+                    : state === null
+                        ? 'missing'
+                        : 'modified';
+        result.push({ path, state: verdict, owners: projection.owners(path) });
+    }
+    for (const path of changed) {
+        result.push({ path, state: outdated(path) ? 'outdated' : 'unmanaged', owners: [] });
+    }
+    return result.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+/**
+ * The paths whose current state is none the queue can leave them in, given
+ * what each path may hold.
+ *
+ * @param current - The engine's state of each path
+ * @param accepted - The states each path may hold
+ */
+export function unaccountedPaths(current, accepted) {
+    return [...current]
+        .filter(([path, state]) => !accepted(path).some((candidate) => sameState(candidate, state)))
+        .map(([path]) => path)
+        .sort();
+}
+/** The permission bits a regular file of git mode `mode` gets, or 'symlink'. */
+function writableMode(path, mode) {
+    if (mode === '100755')
+        return 0o755;
+    if (mode === '100644')
+        return 0o644;
+    if (mode === '120000')
+        return 'symlink';
+    throw queueError('queue-unsupported-mode', `${path} has git mode ${mode}; only files, executables and symlinks can be written into the engine.`);
+}
+/**
+ * An engine path's absolute location, refusing one that leaves the engine
+ * or passes through a symlink. The path itself may be a symlink: writes
+ * replace it and the journal saves it as a link, never following it.
+ *
+ * @param engine - The engine checkout
+ * @param path - Engine path
+ */
+export async function locate(engine, path) {
+    const parent = dirname(path);
+    return join(await resolveContained(engine, parent === '.' ? '' : parent), basename(path));
+}
+/**
+ * Removes, inside the transaction, the directories above a removed path
+ * that are now empty, up to the engine root.
+ *
+ * @param tx - The engine transaction
+ * @param engine - The engine checkout
+ * @param path - Engine path of what was removed
+ */
+export async function pruneEmptyParents(tx, engine, path) {
+    const segments = path.split('/').slice(0, -1);
+    while (segments.length > 0) {
+        const directory = join(engine, ...segments);
+        if ((await listDir(directory)).length > 0)
+            return;
+        await tx.remove(directory);
+        segments.pop();
+    }
+}
+/**
+ * Writes target states into the engine inside a transaction: the blob's
+ * bytes and mode, a symlink, or removal (pruning directories that empties).
+ * Only paths whose current state differs are touched. Every mode, location
+ * and blob is checked before the first write, so a refusal changes nothing.
+ *
+ * @param tx - The engine transaction
+ * @param engine - The engine checkout
+ * @param target - The state each path should hold
+ * @param current - The state each path holds now
+ * @returns The paths written or removed, sorted
+ */
+export async function writeStates(tx, engine, target, current) {
+    const changed = [...target]
+        .filter(([path, state]) => !sameState(state, current.get(path)))
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const blobs = await readBlobs(engine, changed.flatMap(([, state]) => (state === null ? [] : [state.oid])));
+    const plan = [];
+    for (const [path, state] of changed) {
+        const absolute = await locate(engine, path);
+        if (state === null) {
+            plan.push({ path, absolute, write: undefined });
+            continue;
+        }
+        const mode = writableMode(path, state.mode);
+        const bytes = blobs.get(state.oid);
+        if (bytes === undefined) {
+            throw new FireForgeError('queue-blob-missing', `Blob ${state.oid} for ${path} is missing from the engine.`, {
+                exitCode: ExitCode.GIT_ERROR,
+                hint: 'Run the command again; the queue projection will be recomputed.',
+            });
+        }
+        plan.push({ path, absolute, write: { mode, bytes } });
+    }
+    for (const { path, absolute, write } of plan) {
+        if (write === undefined) {
+            await tx.remove(absolute);
+            await pruneEmptyParents(tx, engine, path);
+        }
+        else if (write.mode === 'symlink') {
+            await tx.change([absolute], () => writeLink(absolute, write.bytes.toString('utf8')));
+        }
+        else {
+            await tx.write(absolute, write.bytes, { mode: write.mode });
+        }
+    }
+    return changed.map(([path]) => path);
+}
+/**
+ * The one way a patch body is produced from an engine: the diff, in the
+ * pinned format (`git/diff.ts`), between the state before the patch and the
+ * state after it, limited to `paths`. Deleted files, binary files and file
+ * modes survive; renames are a deletion and an addition.
+ *
+ * @param engine - The engine checkout
+ * @param options - `before`: a tree holding the paths' states before the
+ *   patch. `after`: a tree holding them after; default the working tree,
+ *   captured through a private index. `paths`: the paths the body covers
+ * @returns The body and the tree it was taken from
+ */
+export async function regeneratePatchBody(engine, options) {
+    const after = options.after ??
+        (await captureWorktree(engine, { base: options.before, paths: options.paths }));
+    const body = options.paths.length === 0
+        ? Buffer.alloc(0)
+        : await diffTrees(engine, options.before, after, { paths: options.paths });
+    return { body, after };
+}