@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/mozbuild/testManifest.js

@@ -0,0 +1,343 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Test manifests (`browser.toml`, `xpcshell.toml`, `mochitest.toml`,
+ * `chrome.toml`, `a11y.toml` and their `.ini` forms): sections, keys, the
+ * tests a manifest lists and the files its tests read.
+ *
+ * Only what the tools need is read: `[DEFAULT]` and per-test sections, and
+ * each key's string items. A value this does not understand yields no items
+ * instead of a guess, so a file it misses is reported as unlisted rather than
+ * attributed to the wrong test.
+ */
+import { posix } from 'node:path';
+import { resolveManifestPath } from './paths.js';
+import { joinSource, scanStringList, sortedInsertIndex, spliceLines, splitSource, } from './text.js';
+const HEADER = /^\s*\[\s*(.+?)\s*\]\s*(?:[#;].*)?$/;
+const KEY = /^\s*([A-Za-z0-9_.-]+|"[^"]+")\s*=\s*(.*)$/;
+const unquote = (text) => text.replace(/^(["'])(.*)\1$/, '$2');
+function sectionKind(name) {
+    if (name.toUpperCase() === 'DEFAULT')
+        return 'default';
+    return name.startsWith('include:') ? 'include' : 'test';
+}
+function words(text, line) {
+    return text
+        .replace(/\s[#;].*$/, '')
+        .split(/\s+/)
+        .filter((word) => word !== '')
+        .map((value) => ({ value, line }));
+}
+function parseKey(lines, index, format) {
+    const text = lines[index]?.text ?? '';
+    const match = KEY.exec(text);
+    if (match === null)
+        return undefined;
+    const name = unquote(match[1] ?? '');
+    const value = match[2] ?? '';
+    if (format === 'toml' && value.startsWith('[')) {
+        const scan = scanStringList(lines, index, text.length - value.length + 1);
+        if (scan === undefined)
+            return { name, line: index, endLine: index, raw: value, items: [] };
+        const raw = lines
+            .slice(index, scan.endLine + 1)
+            .map((line) => line.text.trim())
+            .join(' ');
+        return {
+            name,
+            line: index,
+            endLine: scan.endLine,
+            raw: raw.slice(raw.indexOf('[')),
+            items: scan.items.map((item) => ({ value: item.value, line: item.line })),
+        };
+    }
+    if (format === 'toml') {
+        const quoted = /^(["'])(.*?)\1/.exec(value);
+        const bare = value.replace(/\s*[#;].*$/, '').trim();
+        return {
+            name,
+            line: index,
+            endLine: index,
+            raw: bare,
+            items: quoted === null ? words(bare, index) : [{ value: quoted[2] ?? '', line: index }],
+        };
+    }
+    let end = index;
+    const parts = [value];
+    while (/^\s+\S/.test(lines[end + 1]?.text ?? '') &&
+        !(lines[end + 1]?.text ?? '').trimStart().startsWith('#')) {
+        end++;
+        parts.push((lines[end]?.text ?? '').trim());
+    }
+    return {
+        name,
+        line: index,
+        endLine: end,
+        raw: parts.join(' ').replace(/\s[#;].*$/, ''),
+        items: parts.flatMap((part, offset) => words(part, index + offset)),
+    };
+}
+/**
+ * Parses a test manifest. Never throws, and accepts fragments.
+ *
+ * @param path - The manifest's path; `.ini` selects the INI reading, anything else TOML
+ * @param text - Manifest text
+ */
+export function parseTestManifest(path, text) {
+    const format = path.endsWith('.ini') ? 'ini' : 'toml';
+    const lines = splitSource(text);
+    const sections = [
+        { name: undefined, kind: 'preamble', line: -1, start: 0, end: lines.length, keys: [] },
+    ];
+    for (let index = 0; index < lines.length; index++) {
+        const header = HEADER.exec(lines[index]?.text ?? '');
+        const current = sections.at(-1);
+        if (header !== null) {
+            const name = unquote(header[1] ?? '');
+            let start = index;
+            while (start > 0 && (lines[start - 1]?.text ?? '').trimStart().startsWith('#'))
+                start--;
+            if (current !== undefined)
+                current.end = Math.max(start, current.start);
+            sections.push({
+                name,
+                kind: sectionKind(name),
+                line: index,
+                start,
+                end: lines.length,
+                keys: [],
+            });
+            continue;
+        }
+        const key = parseKey(lines, index, format);
+        if (key !== undefined && current !== undefined) {
+            current.keys.push(key);
+            index = key.endLine;
+        }
+    }
+    return { format, lines, sections };
+}
+/**
+ * The tests a manifest lists, as engine-relative paths.
+ *
+ * @param manifestPath - Engine-relative path of the manifest
+ * @param text - Manifest text
+ */
+export function listTests(manifestPath, text) {
+    const dir = posix.dirname(manifestPath);
+    return parseTestManifest(manifestPath, text)
+        .sections.filter((section) => section.kind === 'test')
+        .map((section) => posix.normalize(posix.join(dir, section.name ?? '')));
+}
+/** The keys whose items are files a test reads. */
+export const FILE_KEYS = ['support-files', 'head', 'tail'];
+/**
+ * The `support-files`, `head` and `tail` entries of a manifest, in file order.
+ *
+ * @param manifestPath - Engine-relative path of the manifest
+ * @param text - Manifest text
+ * @param keys - Which keys to read
+ */
+export function supportEntries(manifestPath, text, keys = FILE_KEYS) {
+    const dir = posix.dirname(manifestPath);
+    const manifest = parseTestManifest(manifestPath, text);
+    return manifest.sections.flatMap((section) => {
+        const test = section.kind === 'test' ? posix.normalize(posix.join(dir, section.name ?? '')) : undefined;
+        return section.kind === 'include'
+            ? []
+            : section.keys.flatMap((key) => keys.some((wanted) => wanted === key.name)
+                ? key.items.map(({ value, line }) => ({
+                    key: key.name,
+                    entry: value,
+                    line,
+                    text: (manifest.lines[line]?.text ?? '').trim(),
+                    test,
+                }))
+                : []);
+    });
+}
+/**
+ * The tests whose manifests list `path` as a file they read, sorted. A
+ * manifest's own tests are never counted as their own support.
+ *
+ * @param path - Engine-relative path of the file
+ * @param manifests - The manifests to read
+ */
+export function supportUsers(path, manifests) {
+    const users = new Set();
+    for (const manifest of manifests) {
+        const tests = listTests(manifest.path, manifest.text);
+        if (tests.includes(path))
+            continue;
+        for (const { entry, test } of supportEntries(manifest.path, manifest.text)) {
+            if (resolveManifestPath(manifest.path, entry, { directories: true })?.matches(path) !== true)
+                continue;
+            for (const user of test === undefined ? tests : [test])
+                users.add(user);
+        }
+    }
+    return [...users].sort();
+}
+/**
+ * Every path a test manifest names: its tests and its support entries.
+ *
+ * @param manifestPath - Engine-relative path of the manifest
+ * @param text - Manifest text
+ */
+export function testManifestReferences(manifestPath, text) {
+    const manifest = parseTestManifest(manifestPath, text);
+    const references = [];
+    const add = (kind, token, line, directories) => {
+        const matcher = resolveManifestPath(manifestPath, token, { directories });
+        if (matcher === undefined)
+            return;
+        references.push({
+            kind,
+            token,
+            line,
+            text: (manifest.lines[line]?.text ?? '').trim(),
+            matcher,
+        });
+    };
+    for (const section of manifest.sections) {
+        if (section.kind === 'test')
+            add('test', section.name ?? '', section.line, false);
+    }
+    for (const entry of supportEntries(manifestPath, text))
+        add(entry.key, entry.entry, entry.line, true);
+    return references;
+}
+/**
+ * The value of a scalar key in `[DEFAULT]` (or before the first section,
+ * which the harness reads as defaults).
+ *
+ * @param manifestPath - Path of the manifest
+ * @param text - Manifest text
+ * @param key - The key, such as `firefox-appdir`
+ */
+export function defaultValue(manifestPath, text, key) {
+    for (const section of parseTestManifest(manifestPath, text).sections) {
+        if (section.kind !== 'preamble' && section.kind !== 'default')
+            continue;
+        const found = section.keys.find((candidate) => candidate.name === key);
+        const value = found?.items[0]?.value;
+        if (found !== undefined && value !== undefined && value !== '')
+            return { value, line: found.line };
+    }
+    return undefined;
+}
+function sectionLines(format, name, keys) {
+    const rows = Object.entries(keys ?? {}).map(([key, value]) => {
+        if (typeof value === 'string')
+            return format === 'toml' ? `${key} = "${value}"` : `${key} = ${value}`;
+        return format === 'toml'
+            ? `${key} = [${value.map((item) => `"${item}"`).join(', ')}]`
+            : `${key} = ${value.join(' ')}`;
+    });
+    return [format === 'toml' ? `["${name}"]` : `[${name}]`, ...rows];
+}
+/**
+ * A new test manifest listing one test: the `[DEFAULT]` section and the
+ * test's section.
+ *
+ * @param manifestPath - Path of the manifest; `.ini` picks that format, anything else TOML
+ * @param name - The test, as written in the header (relative to the manifest)
+ * @param options - Header and defaults
+ */
+export function newTestManifest(manifestPath, name, options = {}) {
+    const format = manifestPath.endsWith('.ini') ? 'ini' : 'toml';
+    const [, ...defaults] = sectionLines(format, 'DEFAULT', options.defaults);
+    return [
+        ...(options.header === undefined ? [] : [options.header, '']),
+        '[DEFAULT]',
+        ...defaults,
+        '',
+        ...sectionLines(format, name, undefined),
+        '',
+    ].join('\n');
+}
+/**
+ * Adds a test section. In sort order (byte order, or case-insensitive when
+ * that is how the existing sections are sorted) when the existing tests are
+ * sorted, otherwise last. It goes ahead of the comments that introduce the
+ * next section, with one blank line between sections. A test already listed
+ * changes nothing.
+ *
+ * @param manifestPath - Path of the manifest
+ * @param text - Manifest text
+ * @param name - The test, as written in the header (relative to the manifest)
+ * @param options - Keys for the section and an anchor
+ */
+export function addTest(manifestPath, text, name, options = {}) {
+    const manifest = parseTestManifest(manifestPath, text);
+    const tests = manifest.sections.filter((section) => section.kind === 'test');
+    const present = tests.find((section) => section.name === name);
+    if (present !== undefined)
+        return { text, changed: false, line: present.line };
+    const block = sectionLines(manifest.format, name, options.keys);
+    let previous;
+    let next;
+    let afterFallback = false;
+    const anchor = options.after;
+    if (anchor !== undefined) {
+        const found = manifest.sections.find((section) => section.line >= 0 && section.name === anchor) ??
+            manifest.sections.find((section) => section.line >= 0 && (manifest.lines[section.line]?.text ?? '').includes(anchor));
+        if (found === undefined)
+            afterFallback = true;
+        else
+            previous = found;
+    }
+    if (previous === undefined) {
+        const index = sortedInsertIndex(tests.map((section) => section.name ?? ''), name, 'bytes');
+        next = tests[index];
+        previous = tests[index - 1];
+    }
+    else {
+        next = manifest.sections[manifest.sections.indexOf(previous) + 1];
+    }
+    let lines;
+    let at;
+    if (next !== undefined) {
+        at = next.start;
+        lines = spliceLines(manifest.lines, at, 0, [...block, '']);
+    }
+    else {
+        let last = manifest.lines.length;
+        while (last > 0 && (manifest.lines[last - 1]?.text ?? '').trim() === '')
+            last--;
+        at = last + (last > 0 ? 1 : 0);
+        lines = spliceLines(manifest.lines, last, manifest.lines.length - last, [
+            ...(last > 0 ? [''] : []),
+            ...block,
+        ]);
+    }
+    const result = { text: joinSource(lines), changed: true, line: at };
+    if (previous !== undefined && previous.line >= 0)
+        result.previous = (manifest.lines[previous.line]?.text ?? '').trim();
+    if (afterFallback)
+        result.afterFallback = true;
+    return result;
+}
+/**
+ * Removes a test's section: its header, its keys, the comments directly
+ * above it and the blank lines that separated it from the next section.
+ *
+ * @param manifestPath - Path of the manifest
+ * @param text - Manifest text
+ * @param name - The test, as written in the header
+ */
+export function removeTest(manifestPath, text, name) {
+    const manifest = parseTestManifest(manifestPath, text);
+    const index = manifest.sections.findIndex((section) => section.kind === 'test' && section.name === name);
+    const section = manifest.sections[index];
+    if (section === undefined)
+        return { text, changed: false };
+    let start = section.start;
+    if (index === manifest.sections.length - 1) {
+        while (start > 0 && (manifest.lines[start - 1]?.text ?? '').trim() === '')
+            start--;
+    }
+    return {
+        text: joinSource(spliceLines(manifest.lines, start, section.end - start, [])),
+        changed: true,
+    };
+}

package/dist/src/mozbuild/text.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The line model every manifest format is parsed into and edited through: a
+ * file is a list of lines that each remember their own line ending, so an
+ * edit that does not touch a line leaves its bytes alone.
+ */
+import { FireForgeError } from '../kernel/errors.js';
+/**
+ * Splits text into lines that keep their endings.
+ *
+ * @param text - Manifest text
+ */
+export function splitSource(text) {
+    const lines = [];
+    const pattern = /([^\r\n]*)(\r\n|\n|\r|$)/gy;
+    while (pattern.lastIndex < text.length) {
+        const match = pattern.exec(text);
+        if (match === null)
+            break;
+        lines.push({ text: match[1] ?? '', eol: match[2] ?? '' });
+    }
+    return lines;
+}
+/**
+ * Joins lines back into text.
+ *
+ * @param lines - Lines from {@link splitSource} or {@link spliceLines}
+ */
+export function joinSource(lines) {
+    return lines.map((line) => line.text + line.eol).join('');
+}
+/**
+ * Replaces `deleteCount` lines at `index` with new lines that use the file's
+ * own line ending. A file without a final line ending stays that way.
+ *
+ * @param lines - The current lines (not modified)
+ * @param index - Where to splice
+ * @param deleteCount - How many lines to drop
+ * @param inserted - Text of the new lines
+ */
+export function spliceLines(lines, index, deleteCount, inserted) {
+    const eol = lines.find((line) => line.eol !== '')?.eol ?? '\n';
+    const unterminated = lines.at(-1)?.eol === '';
+    const next = [...lines];
+    next.splice(index, deleteCount, ...inserted.map((text) => ({ text, eol })));
+    return next.map((line, position) => ({
+        text: line.text,
+        eol: position === next.length - 1 && unterminated ? '' : line.eol || eol,
+    }));
+}
+/**
+ * A manifest edit that its file's structure does not allow.
+ *
+ * @param message - What is wrong
+ * @param hint - What to do about it
+ */
+export function manifestError(message, hint) {
+    return new FireForgeError('manifest-edit', message, hint === undefined ? {} : { hint });
+}
+/** Mozbuild's list order: case-insensitive, ties broken by bytes. */
+export function compareInsensitive(a, b) {
+    const x = a.toLowerCase();
+    const y = b.toLowerCase();
+    if (x !== y)
+        return x < y ? -1 : 1;
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/** Plain byte order, the order test manifests are written in. */
+export function compareBytes(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/**
+ * Where `key` goes in a list of keys. When the list is sorted under one of
+ * the two orders (the preferred one first), the key goes before the first
+ * greater key; when the list follows neither, order means nothing and the key
+ * goes last.
+ *
+ * @param keys - Existing keys in file order
+ * @param key - The key to place
+ * @param prefer - The order to try first
+ * @returns An index from 0 to `keys.length`
+ */
+export function sortedInsertIndex(keys, key, prefer = 'insensitive') {
+    const orders = prefer === 'insensitive'
+        ? [compareInsensitive, compareBytes]
+        : [compareBytes, compareInsensitive];
+    const order = orders.find((compare) => keys.every((item, i) => i === 0 || compare(keys[i - 1] ?? '', item) <= 0));
+    if (order === undefined)
+        return keys.length;
+    const index = keys.findIndex((item) => order(item, key) > 0);
+    return index === -1 ? keys.length : index;
+}
+/**
+ * Reads a bracketed list from just after its `[` and returns its string items
+ * (nested lists excluded) and the line of the closing bracket. Comments and
+ * brackets inside strings are not structure. Undefined when the list never closes.
+ *
+ * @param lines - The file's lines
+ * @param line - The line of the opening bracket
+ * @param column - The column just after the bracket
+ */
+export function scanStringList(lines, line, column) {
+    const items = [];
+    let depth = 1;
+    for (let at = line; at < lines.length; at++) {
+        const text = lines[at]?.text ?? '';
+        for (let c = at === line ? column : 0; c < text.length; c++) {
+            const char = text.charAt(c);
+            if (char === '#')
+                break;
+            if (char === '"' || char === "'") {
+                let end = c + 1;
+                while (end < text.length && text.charAt(end) !== char)
+                    end += text.charAt(end) === '\\' ? 2 : 1;
+                if (end >= text.length)
+                    return undefined;
+                if (depth === 1) {
+                    items.push({
+                        value: text.slice(c + 1, end),
+                        line: at,
+                        start: c,
+                        end: end + 1,
+                        quote: char,
+                        ownLine: text.slice(0, c).trim() === '' && /^\s*,?\s*(?:#.*)?$/.test(text.slice(end + 1)),
+                    });
+                }
+                c = end;
+            }
+            else if (char === '[') {
+                depth++;
+            }
+            else if (char === ']' && --depth === 0) {
+                return { items, endLine: at };
+            }
+        }
+    }
+    return undefined;
+}

package/dist/src/project/changes.js

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The owned-change model both modes produce and every quality rule consumes.
+ *
+ * An owned change is one engine path the project creates, modifies or
+ * deletes relative to the pin. A provider (the patch queue, or the source
+ * tree against the pristine repository) turns its storage into a
+ * {@link ChangeSet}; lint, typecheck scope, policy and size rules read the
+ * set and never learn which mode produced it.
+ *
+ * Steps and net changes. A change set is an ordered list of groups (patches
+ * in queue order, or components), and each change is one group's step on one
+ * path, relative to the state the earlier groups left. In patch mode a path
+ * can therefore have several steps: one patch creates a file and a later one
+ * modifies it. In source mode every path has exactly one step. A rule about a
+ * group's own work (patch size, add-only markers, per-patch waivers) reads
+ * the group's steps with {@link ChangeSet.inGroup}; a rule about what the
+ * engine ends up holding (file size, JSDoc, strict typing, the set of owned
+ * paths) reads one net change per path with {@link ChangeSet.net}.
+ *
+ * Content is read lazily, so a set over thousands of paths costs nothing
+ * until a rule asks for bytes.
+ */
+import { invariant } from '../kernel/errors.js';
+const NEXT_KINDS = {
+    create: ['modify', 'delete'],
+    modify: ['modify', 'delete'],
+    delete: ['create'],
+};
+/**
+ * Combines the steps on one path into the change from the pin to the result.
+ * A create followed eventually by a delete cancels out. The net change keeps
+ * the earliest step's group and meta: the group that brought the path in.
+ * A modify whose steps restore the upstream bytes is still a modify; only
+ * reading the content can tell.
+ *
+ * @param steps - The steps on one path, in application order, at least one
+ */
+export function netChange(steps) {
+    const first = steps[0];
+    const last = steps.at(-1);
+    invariant(first !== undefined && last !== undefined, 'a net change needs at least one step');
+    if (steps.length === 1)
+        return first;
+    const base = {
+        path: first.path,
+        binary: steps.some((step) => step.binary),
+        ...(first.group === undefined ? {} : { group: first.group }),
+        meta: first.meta,
+    };
+    if (first.kind === 'create') {
+        return last.kind === 'delete'
+            ? undefined
+            : { ...base, kind: 'create', after: last.after, mode: last.mode };
+    }
+    if (last.kind === 'delete') {
+        return { ...base, kind: 'delete', before: first.before, previousMode: first.previousMode };
+    }
+    return {
+        ...base,
+        kind: 'modify',
+        before: first.before,
+        previousMode: first.previousMode,
+        after: last.after,
+        mode: last.mode,
+    };
+}
+/**
+ * Decodes content as text: UTF-8 without a byte-order mark, or undefined when
+ * it is not valid UTF-8 or holds a NUL byte, as binary content does.
+ *
+ * @param bytes - Content from a {@link ContentReader}
+ */
+export function textContent(bytes) {
+    if (bytes.includes(0))
+        return undefined;
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+function comparePaths(a, b) {
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+/** Refuses an input no consistent storage can produce: these are provider bugs. */
+function assertConsistent(groups, byPath) {
+    const ids = new Set(groups.map((group) => group.id));
+    invariant(ids.size === groups.length, 'change groups have duplicate IDs');
+    for (const [path, steps] of byPath) {
+        for (const [index, step] of steps.entries()) {
+            invariant(step.group === undefined || ids.has(step.group), () => `change to ${path} names unknown group "${step.group ?? ''}"`);
+            invariant(steps.length === 1 || step.group !== undefined, () => `${path} has several steps, so every step needs a group`);
+            const previous = steps[index - 1];
+            if (previous === undefined)
+                continue;
+            invariant(previous.group !== step.group, () => `group "${step.group ?? ''}" has two steps on ${path}`);
+            invariant(NEXT_KINDS[previous.kind].includes(step.kind), () => `${path}: a ${step.kind} cannot follow a ${previous.kind}`);
+        }
+    }
+}
+/**
+ * Builds a change set from a provider's steps, ordering them by group and
+ * indexing them by path and group.
+ *
+ * @param input - See {@link ChangeSetInput}
+ * @throws An internal error when the steps are inconsistent: duplicate group
+ *   IDs, a step naming an unknown group, two steps of one group on one path,
+ *   an ungrouped step beside others on its path, or an impossible sequence
+ *   (a modify after a delete, a create after a create)
+ */
+export function createChangeSet(input) {
+    const groups = [...(input.groups ?? [])];
+    const order = new Map(groups.map((group, index) => [group.id, index]));
+    const rank = (change) => change.group === undefined ? groups.length : (order.get(change.group) ?? groups.length);
+    const changes = [...input.changes].sort((a, b) => rank(a) - rank(b) || comparePaths(a, b));
+    const byPath = new Map();
+    const byGroup = new Map();
+    for (const change of changes) {
+        byPath.set(change.path, [...(byPath.get(change.path) ?? []), change]);
+        if (change.group !== undefined) {
+            byGroup.set(change.group, [...(byGroup.get(change.group) ?? []), change]);
+        }
+    }
+    assertConsistent(groups, byPath);
+    const net = new Map();
+    for (const [path, steps] of [...byPath].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        const change = netChange(steps);
+        if (change !== undefined)
+            net.set(path, change);
+    }
+    const groupById = new Map(groups.map((group) => [group.id, group]));
+    const netList = [...net.values()];
+    return {
+        groups,
+        changes,
+        diff: input.diff,
+        group: (id) => groupById.get(id),
+        inGroup: (id) => byGroup.get(id) ?? [],
+        at: (path) => byPath.get(path) ?? [],
+        final: (path) => net.get(path),
+        net: () => netList,
+    };
+}

package/dist/src/project/checkout.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Which git checkout a project sits in. Parallel sessions are separate
+ * worktrees of one repository, so "this checkout" is a worktree: its key
+ * stays the same across commands, branch switches and `git worktree move`,
+ * and differs between worktrees. It is read from the `.git` entry on disk,
+ * without running git.
+ */
+import { dirname, join, resolve } from 'node:path';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { pathInfo, readTextIfExists, realPath } from '../kernel/fs.js';
+import { hash } from '../kernel/hash.js';
+function keyOf(path) {
+    return hash(path).slice(0, 16);
+}
+/** The nearest directory at or above `start` holding a `.git` entry. */
+async function findWorktree(start) {
+    for (let current = resolve(start);; current = dirname(current)) {
+        const info = await pathInfo(join(current, '.git'));
+        if (info !== undefined)
+            return { root: current, isDirectory: info.kind === 'directory' };
+        if (dirname(current) === current)
+            return undefined;
+    }
+}
+function brokenCheckout(worktree, why) {
+    return new FireForgeError('checkout-broken', `The git checkout at ${worktree} ${why}`, {
+        exitCode: ExitCode.GIT_ERROR,
+        hint: 'Run "git worktree repair" in the main checkout.',
+    });
+}
+/**
+ * Describes the git checkout a project sits in.
+ *
+ * @param projectRoot - The project directory
+ * @throws `checkout-broken` (exit code 4) when a `.git` file points nowhere
+ */
+export async function readCheckout(projectRoot) {
+    const found = await findWorktree(projectRoot);
+    if (found === undefined) {
+        const key = keyOf(await realPath(projectRoot));
+        return { worktree: undefined, gitDir: undefined, commonDir: undefined, linked: false, key };
+    }
+    const dotGit = join(found.root, '.git');
+    if (found.isDirectory) {
+        const gitDir = await realPath(dotGit);
+        return { worktree: found.root, gitDir, commonDir: gitDir, linked: false, key: keyOf(gitDir) };
+    }
+    const pointer = /^gitdir:\s*(.+?)\s*$/m.exec((await readTextIfExists(dotGit)) ?? '')?.[1];
+    if (pointer === undefined)
+        throw brokenCheckout(found.root, 'has a .git file without a gitdir line');
+    const target = resolve(found.root, pointer);
+    if ((await pathInfo(target))?.kind !== 'directory') {
+        throw brokenCheckout(found.root, `points at ${target}, which does not exist`);
+    }
+    const gitDir = await realPath(target);
+    const common = (await readTextIfExists(join(gitDir, 'commondir')))?.trim();
+    const commonDir = common === undefined ? gitDir : await realPath(resolve(gitDir, common));
+    return {
+        worktree: found.root,
+        gitDir,
+        commonDir,
+        linked: common !== undefined,
+        key: keyOf(gitDir),
+    };
+}