@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/source/changes.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The source tree as the owned-change model: one step per owned path
+ * against its pristine blob, in the groups an export would write. Lint,
+ * policy, typecheck scope, `status` and `verify` read this and never learn
+ * the storage.
+ */
+import { readBytes } from '../kernel/fs.js';
+import { mapLimit } from '../kernel/time.js';
+import { createChangeSet, textContent, } from '../project/index.js';
+import { planGroups } from './groups.js';
+import { diffSections, readPristineBlobs, writeDeltaTrees } from './objects.js';
+import { readSourceTree } from './tree.js';
+/** Files read at once while classifying content. */
+const READ_CONCURRENCY = 32;
+function isBinary(bytes) {
+    return bytes !== undefined && textContent(bytes) === undefined;
+}
+function changeMeta(entry) {
+    if (entry.kind === 'create')
+        return {};
+    return {
+        component: entry.component,
+        declared: entry.record !== undefined,
+        ...(entry.record === undefined
+            ? {}
+            : {
+                classification: entry.record.classification,
+                ...(entry.record.adr === undefined ? {} : { adr: entry.record.adr }),
+            }),
+    };
+}
+/** The steps of a tree's entries, their binary flag read from both sides once. */
+async function changesOf(tree, groupOf) {
+    const upstreamReader = (blob) => async () => (await readPristineBlobs(tree.pristine, [blob])).get(blob) ?? Buffer.alloc(0);
+    const upstreamBlobs = tree.entries.flatMap((entry) => entry.upstream === undefined ? [] : [entry.upstream.blob]);
+    const upstreamBinary = new Set([...(await readPristineBlobs(tree.pristine, upstreamBlobs))].flatMap(([blob, bytes]) => isBinary(bytes) ? [blob] : []));
+    return mapLimit(tree.entries, READ_CONCURRENCY, async (entry) => {
+        const owned = entry.file === undefined ? undefined : await readBytes(entry.file.absolute);
+        const group = groupOf.get(entry.path);
+        const base = {
+            path: entry.path,
+            binary: isBinary(owned) ||
+                (entry.upstream !== undefined && upstreamBinary.has(entry.upstream.blob)),
+            meta: changeMeta(entry),
+            ...(group === undefined ? {} : { group }),
+        };
+        const after = () => readBytes(entry.file?.absolute ?? '');
+        if (entry.upstream === undefined) {
+            return { ...base, kind: 'create', after, mode: entry.file?.mode ?? '100644' };
+        }
+        const before = upstreamReader(entry.upstream.blob);
+        if (entry.file === undefined) {
+            return { ...base, kind: 'delete', before, previousMode: entry.upstream.mode };
+        }
+        return {
+            ...base,
+            kind: 'modify',
+            before,
+            after,
+            previousMode: entry.upstream.mode,
+            mode: entry.file.mode,
+        };
+    });
+}
+/**
+ * The owned changes of a source-mode checkout: one step per owned path
+ * against the pristine blob, in the groups of `groups.ts`: a component of
+ * upstream changes, or a group of created files. Paths with a blocking problem are left out; {@link verifySource}
+ * reports them. The diff provider produces the bytes an export would write.
+ *
+ * @param project - A source-mode project
+ * @param pristine - The pinned pristine repository
+ * @throws `source-group-name-collision` when two groups would share an ID
+ */
+export async function sourceChanges(project, pristine) {
+    const tree = await readSourceTree(project, pristine);
+    const planned = planGroups(tree.entries, project.config.exportQueue);
+    const groupOf = new Map(planned.flatMap((group) => group.paths.map((path) => [path, group.id])));
+    const groups = planned.map((group) => ({
+        id: group.id,
+        // How created files group shapes an export; it says nothing about scope.
+        ...(group.kind === 'created' ? { sized: false } : {}),
+        meta: { kind: group.kind, description: group.description },
+    }));
+    let sections;
+    return createChangeSet({
+        groups,
+        changes: await changesOf(tree, groupOf),
+        diff: async (change) => {
+            sections ??= writeDeltaTrees(tree, tree.entries).then(diffSections);
+            return (await sections).get(change.path)?.toString('utf8') ?? '';
+        },
+    });
+}
+/**
+ * The owned paths of a source-mode checkout, their groups, and everything
+ * unaccounted for.
+ *
+ * @param project - A source-mode project
+ * @param pristine - The pinned pristine repository
+ * @throws `source-group-name-collision` when two groups would share an ID
+ */
+export async function sourceStatus(project, pristine) {
+    const tree = await readSourceTree(project, pristine);
+    const planned = planGroups(tree.entries, project.config.exportQueue);
+    const groupOf = new Map(planned.flatMap((group) => group.paths.map((path) => [path, group.id])));
+    return {
+        owned: tree.entries.map((entry) => ({
+            path: entry.path,
+            kind: entry.kind,
+            group: groupOf.get(entry.path) ?? entry.component,
+        })),
+        groups: planned.map((group) => ({
+            id: group.id,
+            kind: group.kind,
+            paths: group.paths.length,
+        })),
+        problems: tree.problems,
+    };
+}
+/**
+ * The integrity of a source-mode checkout's storage: every override record
+ * against the pristine repository, every owned file's kind, path and
+ * attributes. Empty when everything holds.
+ *
+ * @param project - A source-mode project
+ * @param pristine - The pinned pristine repository
+ */
+export async function verifySource(project, pristine) {
+    return (await readSourceTree(project, pristine)).problems;
+}

package/dist/src/source/edit.js

@@ -0,0 +1,278 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Changing what the checkout owns: declaring the first touch of an upstream
+ * file (`override`), giving one back (`restore`), and the one way helpers
+ * that edit owned files (registration, wiring, tokens, components) write
+ * them. Writers in one checkout take the source lock, so two FireForge
+ * commands never interleave a read-check-write of the same file; editors
+ * do not take it.
+ */
+import { join } from 'node:path';
+import { listTree, objectFormat, resolveRevision } from '../git/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { pathInfo, readBytesIfExists, readTextIfExists, writeFile } from '../kernel/fs.js';
+import { transaction } from '../kernel/journal.js';
+import { readJsonIfExists } from '../kernel/json.js';
+import { withLock } from '../kernel/lock.js';
+import { attributesFile, completedAttributes, installMergeDriver } from './merge.js';
+import { blobId, readPristineBlobs } from './objects.js';
+import { assertEnginePath, COMPONENT_PATTERN, defaultComponent, encodeRecord, overrideRecordSchema, unownableReason, } from './records.js';
+import { layoutOf, recordFile } from './tree.js';
+/**
+ * The project as a source-mode project.
+ *
+ * @param project - A loaded project
+ * @throws `source-mode-required` (exit code 2) for a patch-mode project
+ */
+export function requireSourceMode(project) {
+    if (project.mode === 'source')
+        return project;
+    throw new FireForgeError('source-mode-required', 'This command works on source-mode projects; this project keeps a patch queue.', {
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint: 'Edit engine/ directly and capture with "fireforge export".',
+    });
+}
+/** Serialises writers of owned files and records in one checkout. */
+export function withSourceLock(project, body) {
+    return withLock(join(project.paths.stateDir, 'source.lock'), { label: 'source' }, body);
+}
+/** The journal of changes to owned files and records in one checkout. */
+export function journalOf(project) {
+    return join(project.paths.stateDir, 'source.journal');
+}
+function locate(project, path) {
+    assertEnginePath(path);
+    const unownable = unownableReason(path);
+    if (unownable !== undefined) {
+        throw new FireForgeError('source-unownable-path', `${path} ${unownable}.`, {
+            exitCode: ExitCode.INVALID_ARGUMENT,
+            hint: 'Keep that change out of the source root, or make it in a file of the fork itself.',
+        });
+    }
+    const layout = layoutOf(project);
+    return {
+        file: join(project.paths.source, path),
+        record: join(layout.worktree, recordFile(layout, path)),
+    };
+}
+async function readRecordAt(file) {
+    return readJsonIfExists(file, overrideRecordSchema, {
+        code: 'source-record-invalid',
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint: 'Correct the record, or remove it with "fireforge restore".',
+    });
+}
+async function upstreamEntry(pristine, path) {
+    const [entry] = await listTree(pristine.repo, pristine.commit, {
+        paths: [path],
+        recursive: false,
+    });
+    if (entry === undefined)
+        return undefined;
+    return entry.type === 'blob' && (entry.mode === '100644' || entry.mode === '100755')
+        ? { blob: entry.oid, mode: entry.mode }
+        : 'other';
+}
+async function checkedOptions(project, path, options) {
+    const component = options.component ?? defaultComponent(path);
+    if (!COMPONENT_PATTERN.test(component)) {
+        throw new FireForgeError('source-invalid-component', `"${component}" is not a component name.`, {
+            exitCode: ExitCode.INVALID_ARGUMENT,
+            hint: 'Name one with --component, using letters, digits, ".", "_" and "-", starting with a letter or digit.',
+        });
+    }
+    const classification = options.classification ?? 'registration';
+    if (classification === 'exception' && options.adr === undefined) {
+        throw new FireForgeError('source-adr-required', 'An exception needs its decision record.', {
+            exitCode: ExitCode.INVALID_ARGUMENT,
+            hint: 'Pass --adr <path> naming the approved decision record.',
+        });
+    }
+    if (options.adr !== undefined &&
+        (await pathInfo(join(project.root, options.adr)))?.kind !== 'file') {
+        throw new FireForgeError('source-adr-missing', `The decision record ${options.adr} does not exist.`, {
+            exitCode: ExitCode.INVALID_ARGUMENT,
+            hint: 'Write the record first, or name an existing one with --adr.',
+        });
+    }
+    return { component, classification, ...(options.adr === undefined ? {} : { adr: options.adr }) };
+}
+/**
+ * Declares the first touch of an upstream file: writes its override record
+ * and, for an edit, seeds the owned file with the pristine bytes to edit.
+ * An existing owned file is refused unless it already holds the pristine
+ * bytes, so no edit escapes its record. Also installs the merge driver.
+ *
+ * @param project - A source-mode project
+ * @param pristine - The pinned pristine repository
+ * @param path - The engine path
+ * @param options - See {@link OverrideOptions}
+ * @throws `source-not-upstream`, `source-override-exists`, `source-undeclared-edit`,
+ *   `source-unownable-path`, `source-invalid-component`, `source-adr-required`,
+ *   `source-adr-missing`
+ */
+export async function override(project, pristine, path, options = {}) {
+    const located = locate(project, path);
+    const declared = await checkedOptions(project, path, options);
+    const upstream = await upstreamEntry(pristine, path);
+    if (upstream === undefined || upstream === 'other') {
+        throw new FireForgeError('source-not-upstream', upstream === undefined
+            ? `${path} is not an upstream file at the pinned commit.`
+            : `${path} is not a regular file upstream, so it cannot be overridden.`, {
+            exitCode: ExitCode.INVALID_ARGUMENT,
+            ...(upstream === undefined
+                ? { hint: `To add it, create ${project.config.source.root}/${path} directly.` }
+                : {}),
+        });
+    }
+    const record = {
+        kind: options.delete === true ? 'delete' : 'override',
+        base: { commit: pristine.commit, blob: upstream.blob, mode: upstream.mode },
+        ...declared,
+    };
+    const [bytes] = (await readPristineBlobs(pristine, [upstream.blob])).values();
+    const pristineBytes = bytes ?? Buffer.alloc(0);
+    await withSourceLock(project, async () => {
+        const existing = await readRecordAt(located.record);
+        if (existing !== undefined) {
+            if (encodeRecord(existing) === encodeRecord(record))
+                return;
+            throw new FireForgeError('source-override-exists', `${path} already has an override record.`, {
+                exitCode: ExitCode.INVALID_ARGUMENT,
+                hint: 'Edit the record to change it, or remove it with "fireforge restore" first.',
+            });
+        }
+        const current = await readBytesIfExists(located.file);
+        const untouched = current !== undefined &&
+            options.delete !== true &&
+            blobId(current, upstream.blob.length === 64 ? 'sha256' : 'sha1') === upstream.blob;
+        if (current !== undefined && !untouched) {
+            throw new FireForgeError('source-undeclared-edit', `${project.config.source.root}/${path} already exists without an override record.`, {
+                exitCode: ExitCode.INVALID_ARGUMENT,
+                hint: options.delete === true
+                    ? 'Delete the owned file first.'
+                    : `Move it aside, run "fireforge override ${path}", then reapply the edit.`,
+            });
+        }
+        const attributes = completedAttributes(await readTextIfExists(attributesFile(project)));
+        const declare = async (tx) => {
+            await tx.write(located.record, encodeRecord(record));
+            if (record.kind === 'override' && current === undefined) {
+                await tx.write(located.file, pristineBytes, {
+                    mode: upstream.mode === '100755' ? 0o755 : 0o644,
+                });
+            }
+            if (attributes !== undefined)
+                await tx.write(attributesFile(project), attributes);
+        };
+        if (options.tx !== undefined)
+            await declare(options.tx);
+        else
+            await transaction(journalOf(project), `the override of ${path}`, declare);
+    });
+    const driver = await installMergeDriver(project);
+    return { record, driverInstalled: driver.changed };
+}
+/**
+ * Gives an upstream file back: removes its override record and owned file,
+ * so the next materialization restores the upstream bytes. Uncommitted
+ * edits of the owned file are refused unless `discard`.
+ *
+ * @param project - A source-mode project
+ * @param path - The engine path
+ * @param options - `discard` drops uncommitted edits
+ * @throws `source-not-overridden`, `source-uncommitted-edit`
+ */
+export async function restore(project, path, options = {}) {
+    const located = locate(project, path);
+    const layout = layoutOf(project);
+    return withSourceLock(project, async () => {
+        const record = await readRecordAt(located.record);
+        if (record === undefined) {
+            throw new FireForgeError('source-not-overridden', `${path} has no override record.`, {
+                exitCode: ExitCode.INVALID_ARGUMENT,
+            });
+        }
+        const current = await readBytesIfExists(located.file);
+        if (current !== undefined && options.discard !== true) {
+            const pristineFormat = record.base.blob.length === 64 ? 'sha256' : 'sha1';
+            const committed = await resolveRevision(layout.worktree, `HEAD:${layout.source}/${path}`);
+            const expendable = blobId(current, pristineFormat) === record.base.blob ||
+                (committed !== undefined &&
+                    blobId(current, await objectFormat(layout.worktree)) === committed);
+            if (!expendable) {
+                throw new FireForgeError('source-uncommitted-edit', `${project.config.source.root}/${path} has uncommitted edits a restore would lose.`, { exitCode: ExitCode.INVALID_ARGUMENT, hint: 'Commit them, or pass --discard.' });
+            }
+        }
+        await transaction(journalOf(project), `the restore of ${path}`, async (tx) => {
+            await tx.remove(located.file);
+            await tx.remove(located.record);
+        });
+        return { path, wasDeletion: record.kind === 'delete', removedFile: current !== undefined };
+    });
+}
+/**
+ * Reads an engine path as the checkout would build it: the owned file, or
+ * the pristine bytes when the path is not owned.
+ *
+ * @param project - A source-mode project
+ * @param pristine - The pinned pristine repository
+ * @param path - The engine path
+ * @returns The bytes, or undefined when the path is absent or deleted by a record
+ */
+export async function readSourceFile(project, pristine, path) {
+    const located = locate(project, path);
+    const owned = await readBytesIfExists(located.file);
+    if (owned !== undefined)
+        return owned;
+    if ((await readRecordAt(located.record))?.kind === 'delete')
+        return undefined;
+    const upstream = await upstreamEntry(pristine, path);
+    if (upstream === undefined || upstream === 'other')
+        return undefined;
+    return (await readPristineBlobs(pristine, [upstream.blob])).get(upstream.blob);
+}
+/**
+ * Writes an owned file for a helper that edits engine paths. An upstream
+ * path must have a current override record first. With `expected`, the
+ * write happens only if the file still holds those bytes (null: only if it
+ * does not exist), so a helper never overwrites an edit made after it read.
+ *
+ * @param project - A source-mode project
+ * @param pristine - The pinned pristine repository
+ * @param path - The engine path
+ * @param content - The new bytes
+ * @param options - `expected`; `mode` (default: the current mode, else upstream's, else
+ *   regular); `tx` makes the write part of the caller's transaction
+ * @throws `source-override-required`, `source-file-moved`
+ */
+export async function writeSourceFile(project, pristine, path, content, options = {}) {
+    const located = locate(project, path);
+    const upstream = await upstreamEntry(pristine, path);
+    const upstreamMode = upstream === undefined || upstream === 'other' ? undefined : upstream.mode;
+    await withSourceLock(project, async () => {
+        if (upstream !== undefined) {
+            const record = await readRecordAt(located.record);
+            const current = upstream !== 'other' &&
+                record?.kind === 'override' &&
+                record.base.commit === pristine.commit &&
+                record.base.blob === upstream.blob;
+            if (!current) {
+                throw new FireForgeError('source-override-required', `${path} is an upstream file without a current override record.`, { exitCode: ExitCode.GENERAL_ERROR, hint: `Run "fireforge override ${path}" first.` });
+            }
+        }
+        const existing = await readBytesIfExists(located.file);
+        const { expected } = options;
+        const matches = expected === undefined ||
+            (expected === null ? existing === undefined : existing?.equals(expected) === true);
+        if (!matches) {
+            throw new FireForgeError('source-file-moved', `${project.config.source.root}/${path} changed since it was read.`, { hint: 'Run the command again.' });
+        }
+        const mode = options.mode ?? (existing === undefined ? (upstreamMode ?? '100644') : undefined);
+        const permissions = mode === undefined ? {} : { mode: mode === '100755' ? 0o755 : 0o644 };
+        if (options.tx === undefined)
+            await writeFile(located.file, content, permissions);
+        else
+            await options.tx.write(located.file, content, permissions);
+    });
+}

package/dist/src/source/export.js

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The owned changes as an ordered patch queue, for whatever consumes one: a
+ * public export whose CI runs `fireforge import`, or a move back to patch
+ * mode. This plans the queue; writing its manifest and proving that it
+ * replays belong to the patch queue's own module.
+ *
+ * Each path is in exactly one patch, so no patch depends on another's
+ * context, and the patches are the groups of `groups.ts`, each named after
+ * its group's ID. The plan is a
+ * function of the owned files and the pin: planning twice gives the same
+ * bytes, and an edit to one file changes only that file's patch and the
+ * manifest source.
+ */
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { hash } from '../kernel/hash.js';
+import { exportedPatchName, planGroups } from './groups.js';
+import { diffSections, writeDeltaTrees } from './objects.js';
+import { readSourceTree } from './tree.js';
+/**
+ * Plans the patch queue the checkout's owned changes export as.
+ *
+ * @param project - A source-mode project
+ * @param pristine - The pinned pristine repository
+ * @throws `source-invalid` (exit code 2) while `verify` reports any problem;
+ *   `source-group-name-collision` when two groups would share an ID or two
+ *   patches a name, `source-group-unexportable` for an ID no patch can be named after
+ */
+export async function planQueueExport(project, pristine) {
+    const tree = await readSourceTree(project, pristine);
+    if (tree.problems.length > 0) {
+        throw new FireForgeError('source-invalid', `The owned files cannot be exported until these are fixed:\n${tree.problems
+            .map((problem) => `  ${problem.path}: ${problem.message}`)
+            .join('\n')}`, { exitCode: ExitCode.CONFIG_ERROR, hint: 'Run "fireforge verify" for what to do.' });
+    }
+    const groups = planGroups(tree.entries, project.config.exportQueue);
+    const trees = await writeDeltaTrees(tree, tree.entries);
+    const sections = await diffSections(trees);
+    const patches = [];
+    const named = new Map();
+    for (const group of groups) {
+        const members = new Set(group.paths);
+        const files = [...sections.keys()].filter((path) => members.has(path));
+        if (files.length === 0)
+            continue;
+        const name = exportedPatchName(group.id);
+        const other = named.get(name);
+        if (other !== undefined) {
+            throw new FireForgeError('source-group-name-collision', `Groups "${other}" and "${group.id}" would both export as patch "${name}".`, {
+                exitCode: ExitCode.CONFIG_ERROR,
+                hint: 'Rename a component in its override records, or an exportQueue group.',
+            });
+        }
+        named.set(name, group.id);
+        patches.push({
+            group: group.id,
+            name,
+            description: group.description,
+            files,
+            body: Buffer.concat(files.map((path) => sections.get(path) ?? Buffer.alloc(0))),
+        });
+    }
+    return {
+        patches,
+        manifestSource: {
+            pristineCommit: pristine.commit,
+            digest: hash(`${pristine.commit}\n${trees.before}\n${trees.after}\n`),
+        },
+    };
+}

package/dist/src/source/groups.js

@@ -0,0 +1,131 @@
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { matchesAnyGlob } from '../kernel/glob.js';
+import { compareText } from './records.js';
+function slug(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * The name a group's patch takes in an exported queue: the ID in lowercase
+ * with every other run of characters as one hyphen. An ID spelled like a
+ * patch file (`012-ui-sidebar.patch`) gives that patch's name (`ui-sidebar`).
+ *
+ * @param id - A group ID
+ * @throws `source-group-unexportable` (exit code 2) when what remains does
+ *   not start with a letter, which a patch name must
+ */
+export function exportedPatchName(id) {
+    const name = slug(id.replace(/\.patch$/, '').replace(/^\d+-/, ''));
+    if (!/^[a-z]/.test(name)) {
+        throw new FireForgeError('source-group-unexportable', `Group "${id}" cannot be exported: a patch name starts with a letter.`, {
+            exitCode: ExitCode.CONFIG_ERROR,
+            hint: 'Rename the component in its override records, or the exportQueue group.',
+        });
+    }
+    return name;
+}
+function append(groups, key, path) {
+    const list = groups.get(key);
+    if (list === undefined)
+        groups.set(key, [path]);
+    else
+        list.push(path);
+}
+/**
+ * Splits created files by directory: the whole subtree when it fits the
+ * budget, else the directory's own files plus each subdirectory in turn.
+ */
+function directoryGroups(directory, paths, budget, size, out) {
+    if (paths.reduce((total, path) => total + size(path), 0) <= budget) {
+        out.set(directory, [...paths]);
+        return;
+    }
+    const prefix = directory === '' ? '' : `${directory}/`;
+    const own = [];
+    const children = new Map();
+    for (const path of paths) {
+        const rest = path.slice(prefix.length);
+        const slash = rest.indexOf('/');
+        if (slash < 0)
+            own.push(path);
+        else
+            append(children, prefix + rest.slice(0, slash), path);
+    }
+    if (own.length > 0)
+        out.set(directory, own);
+    for (const [child, list] of [...children].sort(([a], [b]) => compareText(a, b))) {
+        directoryGroups(child, list, budget, size, out);
+    }
+}
+function createdGroups(entries, settings) {
+    const named = new Map();
+    const rest = [];
+    const sizes = new Map();
+    for (const entry of entries) {
+        sizes.set(entry.path, entry.file?.size ?? 0);
+        const group = settings.groups?.find((candidate) => matchesAnyGlob(entry.path, candidate.paths));
+        if (group === undefined)
+            rest.push(entry.path);
+        else
+            append(named, group.name, entry.path);
+    }
+    const byDirectory = new Map();
+    if (rest.length > 0) {
+        directoryGroups('', rest, settings.maxGroupBytes, (path) => sizes.get(path) ?? 0, byDirectory);
+    }
+    return [
+        ...[...named].map(([name, paths]) => ({
+            id: name,
+            order: 2,
+            kind: 'created',
+            description: `Created files of group ${name}`,
+            paths,
+        })),
+        ...[...byDirectory].map(([directory, paths]) => ({
+            id: `created-${slug(directory) === '' ? 'root' : slug(directory)}`,
+            order: 2,
+            kind: 'created',
+            description: directory === '' ? 'Created files' : `Created files under ${directory}/`,
+            paths,
+        })),
+    ];
+}
+/**
+ * Groups owned entries into components and created-file groups.
+ *
+ * @param entries - The owned entries
+ * @param settings - The project's `exportQueue` section
+ * @returns The groups in application order
+ * @throws `source-group-name-collision` (exit code 2) when two groups would share an ID
+ */
+export function planGroups(entries, settings) {
+    const components = new Map();
+    for (const entry of entries) {
+        if (entry.kind !== 'create')
+            append(components, entry.component, entry.path);
+    }
+    const drafts = [
+        ...[...components].map(([component, paths]) => ({
+            id: component,
+            order: 1,
+            kind: 'component',
+            description: `Upstream changes of component ${component}`,
+            paths,
+        })),
+        ...createdGroups(entries.filter((entry) => entry.kind === 'create'), settings),
+    ];
+    const planned = new Map();
+    for (const draft of drafts) {
+        const other = planned.get(draft.id);
+        if (other !== undefined) {
+            throw new FireForgeError('source-group-name-collision', `Group "${draft.id}" would hold both "${other.description}" and "${draft.description}".`, {
+                exitCode: ExitCode.CONFIG_ERROR,
+                hint: 'Give the exportQueue group another name than the component, or rename the component in its override records.',
+            });
+        }
+        planned.set(draft.id, { ...draft, paths: [...draft.paths].sort(compareText) });
+    }
+    return [...planned.values()].sort((a, b) => a.order - b.order || compareText(a.id, b.id));
+}

package/dist/src/source/index.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Source mode: the project's owned files are tracked files under the source
+ * root (`<source>/<path>` supplies engine file `<path>`), an upstream file
+ * is touched only after its override record captures its upstream identity,
+ * and the patch queue is generated output.
+ *
+ * Every function reads the checkout's working files directly (tracked files
+ * and untracked files git does not ignore) and judges them against a
+ * {@link Pristine} repository it is handed, which it only reads.
+ */
+export { adoptTrees } from './adopt.js';
+export { sourceChanges, sourceStatus, verifySource } from './changes.js';
+export { override, readSourceFile, requireSourceMode, restore, writeSourceFile } from './edit.js';
+export { planQueueExport } from './export.js';
+export { exportedPatchName } from './groups.js';
+export { materialize, recordDeployment } from './materialize.js';
+export { completedAttributes, installMergeDriver, MERGE_DRIVER, mergeDriverCommand, runMergeDriver, } from './merge.js';
+export { parsePreviousWaivers, parseScopeDecisions, PREVIOUS_MERGE_DRIVER, PREVIOUS_METADATA_FILES, upgradeAttributes, upgradeRecord, } from './previous.js';
+export { refreshPin } from './refresh.js';