@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/export-moved-code-shape.d.ts

@@ -1,98 +0,0 @@
-/**
- * Detects the new-file-plus-moved-code slice shape and names the working
- * sequence through it.
- *
- * A slice that adds new files and moves lines into them from an existing
- * patch has no path through the two refusal flags:
- *
- *  - `re-export --refuse-adjacent-unmanaged` refuses while the new files are
- *    still unmanaged, and
- *  - exporting the new files as their own patch fails cross-patch lint,
- *    because at the projected placement the old patch still contains the
- *    moved code.
- *
- * Each guard is individually correct. Together they dead-end, and the way out
- * is non-obvious: adopt the new files into the old patch first
- * (`re-export --scan --scan-file`), then split them out into a patch of their
- * own (`patch move-files --create --order N`).
- *
- * This module recognises the shape from evidence FireForge already has (the
- * pending diff's new-file content versus the added lines the existing patches
- * carry), so the refusal can name the sequence instead of leaving the
- * operator to derive it.
- */
-/** One run of consecutive lines a new file shares with an existing patch. */
-export interface MovedCodeBlock {
-    /** New-file path in the pending diff. */
-    file: string;
-    /** File in the source patch that carries the same run. */
-    sourceFile: string;
-    /** The matched substantive lines, trimmed, in order. */
-    lines: string[];
-}
-/** One existing patch that already carries lines the new files would add. */
-export interface MovedCodeOverlap {
-    /** Filename of the patch that still contains the moved lines. */
-    sourcePatch: string;
-    /** New-file paths in the pending diff whose lines it overlaps. */
-    files: string[];
-    /** Count of substantive lines inside the matched blocks. */
-    sharedLines: number;
-    /** The matched blocks, so the claim can be checked line by line. */
-    blocks: MovedCodeBlock[];
-}
-/** Minimal queue view this detector needs. */
-export interface MovedCodeQueueEntry {
-    filename: string;
-    diff: string;
-}
-/**
- * Finds existing patches that still carry a block of substantive lines the
- * pending diff's new files would add, the fingerprint of code moved out of
- * an existing patch into a new file.
- *
- * Pure. Overlaps are returned strongest-first so the message names the
- * most likely source patch.
- *
- * @param pendingDiff - The diff the export would write
- * @param entries - The existing queue's patches
- * @returns Overlaps, or an empty list when the shape is not present
- */
-export declare function detectMovedCodeOverlaps(pendingDiff: string, entries: readonly MovedCodeQueueEntry[]): MovedCodeOverlap[];
-/** What the placement projection learned about the pending export. */
-export interface MovedCodeAdviceInput {
-    /** Result of {@link detectMovedCodeOverlaps}. */
-    overlaps: readonly MovedCodeOverlap[];
-    /** The filename the pending export would take. */
-    newPatchName: string;
-    /** The order the pending export would take. */
-    insertionOrder: number;
-    /**
-     * New system modules in the pending diff that no patch registers
-     * (`unregistered-system-module` findings on the new patch).
-     */
-    unregisteredModules?: readonly string[];
-    /**
-     * True when every error in the exported content is a missing
-     * registration: registering is then the whole fix, and adopt-then-split
-     * is not offered at all.
-     */
-    registrationResolvesAll?: boolean;
-    /**
-     * Why adopting the new files into the strongest overlap's source patch
-     * would itself be refused (forward imports, size limit). Empty when the
-     * adopt is clean.
-     */
-    adoptBlockers?: readonly string[];
-}
-/**
- * Renders the remedy lines appended to a placement refusal: "register
- * first" when new modules lack their moz.build registration, then the
- * adopt-then-split sequence for a real moved-code block, but only when the
- * adopt itself would pass. Each claim names its evidence (the matched
- * lines, the blocking findings) so it can be checked.
- *
- * @param input - See {@link MovedCodeAdviceInput}
- * @returns Detail lines, or an empty list when neither shape is present
- */
-export declare function formatMovedCodeAdvice(input: MovedCodeAdviceInput): string[];

package/dist/src/core/export-moved-code-shape.js

@@ -1,220 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Detects the new-file-plus-moved-code slice shape and names the working
- * sequence through it.
- *
- * A slice that adds new files and moves lines into them from an existing
- * patch has no path through the two refusal flags:
- *
- *  - `re-export --refuse-adjacent-unmanaged` refuses while the new files are
- *    still unmanaged, and
- *  - exporting the new files as their own patch fails cross-patch lint,
- *    because at the projected placement the old patch still contains the
- *    moved code.
- *
- * Each guard is individually correct. Together they dead-end, and the way out
- * is non-obvious: adopt the new files into the old patch first
- * (`re-export --scan --scan-file`), then split them out into a patch of their
- * own (`patch move-files --create --order N`).
- *
- * This module recognises the shape from evidence FireForge already has (the
- * pending diff's new-file content versus the added lines the existing patches
- * carry), so the refusal can name the sequence instead of leaving the
- * operator to derive it.
- */
-import { extractAddedLinesPerFile } from './patch-lint-diff.js';
-/**
- * Lines too generic to be evidence of a move: closing braces, blank
- * lines, bare keywords, import punctuation. Requiring substance keeps the
- * detector from firing on every patch that happens to contain a `}`.
- */
-function isSubstantiveLine(line) {
-    const trimmed = line.trim();
-    if (trimmed.length < 12)
-        return false;
-    if (/^[)\]};,]+$/.test(trimmed))
-        return false;
-    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*'))
-        return false;
-    return true;
-}
-/**
- * Minimum run of consecutive substantive lines, in the same order in both
- * the new file and the source patch, before a block counts as moved code.
- * Matching scattered single lines instead let a large unrelated patch
- * "share" a dozen common statements with any new module and sent operators
- * down an adopt-then-split sequence through a patch that only carried a
- * `<script>` line for the file.
- */
-const MOVED_CODE_BLOCK_THRESHOLD = 3;
-function substantiveSequences(diff) {
-    const sequences = new Map();
-    for (const [file, lines] of extractAddedLinesPerFile(diff)) {
-        const substantive = lines.map((line) => line.trim()).filter(isSubstantiveLine);
-        if (substantive.length > 0)
-            sequences.set(file, substantive);
-    }
-    return sequences;
-}
-/**
- * Longest-first, non-overlapping runs of `pending` that appear contiguously
- * in one of `sources`' files. Anchored on exact line matches, so the work
- * is bounded by the number of shared lines, not the product of the sizes.
- */
-function findBlocks(file, pending, sources) {
-    const positions = new Map();
-    for (const [sourceFile, lines] of sources) {
-        lines.forEach((line, index) => {
-            const list = positions.get(line) ?? [];
-            list.push([sourceFile, index]);
-            positions.set(line, list);
-        });
-    }
-    const blocks = [];
-    let i = 0;
-    while (i < pending.length) {
-        let best;
-        for (const [sourceFile, start] of positions.get(pending[i] ?? '') ?? []) {
-            const source = sources.get(sourceFile) ?? [];
-            let length = 0;
-            while (i + length < pending.length &&
-                start + length < source.length &&
-                pending[i + length] === source[start + length]) {
-                length += 1;
-            }
-            if (best === undefined || length > best.length)
-                best = { sourceFile, length };
-        }
-        if (best !== undefined && best.length >= MOVED_CODE_BLOCK_THRESHOLD) {
-            blocks.push({ file, sourceFile: best.sourceFile, lines: pending.slice(i, i + best.length) });
-            i += best.length;
-        }
-        else {
-            i += 1;
-        }
-    }
-    return blocks;
-}
-/**
- * Finds existing patches that still carry a block of substantive lines the
- * pending diff's new files would add, the fingerprint of code moved out of
- * an existing patch into a new file.
- *
- * Pure. Overlaps are returned strongest-first so the message names the
- * most likely source patch.
- *
- * @param pendingDiff - The diff the export would write
- * @param entries - The existing queue's patches
- * @returns Overlaps, or an empty list when the shape is not present
- */
-export function detectMovedCodeOverlaps(pendingDiff, entries) {
-    const pending = substantiveSequences(pendingDiff);
-    if (pending.size === 0)
-        return [];
-    const overlaps = [];
-    for (const entry of entries) {
-        const sources = substantiveSequences(entry.diff);
-        if (sources.size === 0)
-            continue;
-        const blocks = [...pending].flatMap(([file, lines]) => findBlocks(file, lines, sources));
-        if (blocks.length === 0)
-            continue;
-        overlaps.push({
-            sourcePatch: entry.filename,
-            files: [...new Set(blocks.map((block) => block.file))].sort(),
-            sharedLines: blocks.reduce((sum, block) => sum + block.lines.length, 0),
-            blocks,
-        });
-    }
-    return overlaps.sort((a, b) => b.sharedLines - a.sharedLines || a.sourcePatch.localeCompare(b.sourcePatch));
-}
-/** Lines shown per matched block, and blocks shown per overlap. */
-const SHOWN_BLOCK_LINES = 4;
-const SHOWN_BLOCKS = 3;
-/** Renders the matched blocks of one overlap, capped, as detail lines. */
-function formatMatchedBlocks(overlap) {
-    const lines = [];
-    for (const block of overlap.blocks.slice(0, SHOWN_BLOCKS)) {
-        lines.push(`  ${block.file} ← ${overlap.sourcePatch} (${block.sourceFile}), ${block.lines.length} line(s):`);
-        for (const line of block.lines.slice(0, SHOWN_BLOCK_LINES))
-            lines.push(`    | ${line}`);
-        if (block.lines.length > SHOWN_BLOCK_LINES) {
-            lines.push(`    | … ${block.lines.length - SHOWN_BLOCK_LINES} more`);
-        }
-    }
-    if (overlap.blocks.length > SHOWN_BLOCKS) {
-        lines.push(`  … ${overlap.blocks.length - SHOWN_BLOCKS} more block(s)`);
-    }
-    return lines;
-}
-/**
- * Renders the remedy lines appended to a placement refusal: "register
- * first" when new modules lack their moz.build registration, then the
- * adopt-then-split sequence for a real moved-code block, but only when the
- * adopt itself would pass. Each claim names its evidence (the matched
- * lines, the blocking findings) so it can be checked.
- *
- * @param input - See {@link MovedCodeAdviceInput}
- * @returns Detail lines, or an empty list when neither shape is present
- */
-export function formatMovedCodeAdvice(input) {
-    const lines = [];
-    const unregistered = input.unregisteredModules ?? [];
-    if (unregistered.length > 0) {
-        lines.push('', `Register first: ${unregistered.join(', ')} ${unregistered.length === 1 ? 'is a new system module' : 'are new system modules'} ` +
-            'no patch registers in moz.build. Add the moz.build line in the patch that owns that ' +
-            'moz.build; when its line is already in the working tree but unexported, declare it as a ' +
-            'staged registration on that patch, re-run this export, then re-export that patch.' +
-            (input.registrationResolvesAll === true
-                ? ' The exported content has no other cross-patch error, so once registered the new ' +
-                    'files need no adoption into another patch.'
-                : ''));
-    }
-    const strongest = input.overlaps[0];
-    if (strongest === undefined || input.registrationResolvesAll === true)
-        return lines;
-    const blockers = input.adoptBlockers ?? [];
-    const claim = `${strongest.sharedLines} substantive line(s) the new file(s) would add, in ` +
-        `${strongest.blocks.length} matching block(s), are still carried by ${strongest.sourcePatch}:`;
-    if (blockers.length > 0) {
-        lines.push('', claim, ...formatMatchedBlocks(strongest), `Adopting the new files into ${strongest.sourcePatch} first (adopt-then-split) would be refused too, so it is not offered:`, ...blockers.map((blocker) => `  - ${blocker}`));
-        return lines;
-    }
-    const adopt = formatAdoptThenSplitRemedy(strongest, input.newPatchName, input.insertionOrder);
-    if (unregistered.length > 0) {
-        adopt.splice(1, 0, 'Only if the export still fails once those modules are registered:');
-    }
-    lines.push(...adopt, `Matched lines: ${claim}`, ...formatMatchedBlocks(strongest));
-    return lines;
-}
-/**
- * Renders the adopt-then-split remedy for the strongest overlap, as lines
- * appended to the refusal's detail list.
- *
- * @param strongest - The strongest overlap {@link detectMovedCodeOverlaps} found
- * @param newPatchName - The filename the pending export would take
- * @param insertionOrder - The order the pending export would take
- * @returns Detail lines
- */
-function formatAdoptThenSplitRemedy(strongest, newPatchName, insertionOrder) {
-    const fileArgs = strongest.files.map((file) => `--scan-file ${file}`).join(' ');
-    const moveArgs = strongest.files.map((file) => `--file ${file}`).join(' ');
-    // `patch move-files --create` takes the new patch's name, not a
-    // filename: strip the order prefix and the `.patch` suffix so the
-    // suggested command is copy-pasteable.
-    const suggestedName = newPatchName.replace(/^\d+-/, '').replace(/\.patch$/, '');
-    return [
-        '',
-        `This looks like a new-file + moved-code slice: ${strongest.sharedLines} substantive ` +
-            `line(s) the new file(s) would add are still carried by ${strongest.sourcePatch}. ` +
-            'Exporting them as their own patch cannot pass cross-patch lint while the source patch ' +
-            'still owns the same code, and re-exporting cannot adopt them while they are unmanaged — ' +
-            'each guard is right, and together they dead-end.',
-        'Working sequence (adopt, then split):',
-        `  1. fireforge re-export ${strongest.sourcePatch} --scan ${fileArgs}`,
-        `  2. fireforge patch move-files ${strongest.sourcePatch} ${suggestedName} --create --order ${insertionOrder} ${moveArgs}`,
-        'Step 1 adopts the new files into the patch that already owns the moved lines; step 2 ' +
-            'splits them back out as one transaction, so the queue is never in a state where two ' +
-            'patches own the same code.',
-    ];
-}

package/dist/src/core/file-lock-owner.d.ts

@@ -1,103 +0,0 @@
-/**
- * Filename of a lock directory's owner record, relative to the lock dir.
- *
- * Re-exported by `file-lock.ts` so external readers (`tree-store.ts`) share
- * the constant instead of re-spelling `'pid'`. The file format is
- * documented on {@link readLockOwner}.
- */
-export declare const LOCK_PID_FILE = "pid";
-/**
- * Owner record read back from a lock directory's PID file.
- *
- * `token` is the per-acquisition UUID written on line 2 of the PID file,
- * `acquiredAtMs` the wall-clock time the record was written (diagnostic),
- * and `startTick` the writer's boot-relative start tick (liveness). Records
- * from releases before a field was introduced parse with it `undefined`.
- * Readers must treat that as "unknown", never as a mismatch.
- */
-export type LockOwner = {
-    present: false;
-} | {
-    present: true;
-    pid: number;
-    token?: string;
-    acquiredAtMs?: number;
-    startTick?: number;
-    metadata: string[];
-};
-/**
- * Reads the owner PID (line 1), acquisition token (line 2), the mechanical
- * `acquired-at-ms=` / `start-tick=` lines (when present), and diagnostic
- * metadata (the remaining lines 3+) from a lock directory's PID file.
- * Returns `{ present: false }` when the PID file is missing, unreadable, or
- * the PID does not parse as a finite integer (caller falls back to the
- * age-only staleness heuristic).
- *
- * File format note: external readers do `parseInt(content.trim(), 10)`,
- * which parses the leading digits of a multi-line file, so the token and
- * mechanical lines stay compatible.
- *
- * @param lockPath - Lock directory whose owner record to read
- * @returns The parsed owner record, or `{ present: false }`
- */
-export declare function readLockOwner(lockPath: string): Promise<LockOwner>;
-/**
- * Stamps this process's ownership (PID, per-acquisition token, acquisition
- * time, own start tick, diagnostic metadata) into a lock directory it has
- * just created, and reads the record back to prove it landed.
- *
- * The write is fatal rather than best-effort. Stale recovery could fall
- * back to the age heuristic, but that heuristic reaps any owner-less lock
- * after five minutes, and the build lock legitimately holds for hours. A
- * holder whose record failed to write would be reaped mid-build and a
- * second process would enter the critical section. On
- * failure the just-created lock directory is removed (nothing else can own
- * it yet) and a {@link GeneralError} names the cause.
- *
- * @param lockPath - Lock directory this process has just `mkdir`'d
- * @param token - Per-acquisition UUID, later checked by release
- * @param ownerMetadata - Extra human-diagnostic lines (see `FileLockOptions.ownerMetadata`)
- * @throws {GeneralError} When the record cannot be written or does not read back as written
- */
-export declare function writeLockOwner(lockPath: string, token: string, ownerMetadata: readonly string[] | undefined): Promise<void>;
-/**
- * Boot-relative start tick of a process, where the platform exposes it
- * cheaply.
- *
- * Linux only: field 22 of `/proc/<pid>/stat`, in USER_HZ since boot.
- * Elsewhere (macOS, Windows) obtaining a start time means spawning
- * `ps`/`wmic` per probe, which is not worth paying on every poll of a
- * contended lock. Those platforms return `undefined` and liveness stays
- * PID-only.
- *
- * Not converted to wall-clock time via `/proc/stat` `btime`, on purpose:
- * on current kernels `btime` is derived from the realtime clock and moves
- * with every clock step, so a wall-clock comparison against a recorded
- * acquisition time misjudges a live holder as a reused PID after NTP steps
- * the clock forward, and reaps a lock that is in use.
- *
- * @param pid - Process to look up
- * @param procRoot - procfs mount, overridable for tests
- * @returns Start tick, or `undefined` when unobtainable
- */
-export declare function readProcessStartTick(pid: number, procRoot?: string): number | undefined;
-/**
- * Whether the process named by a lock's owner record is the same process
- * that acquired the lock, not merely a live process wearing its PID.
- *
- * `isProcessAlive` answers "does this PID exist". After a holder crashes,
- * the kernel may hand its PID to a long-lived daemon, and a PID-only check
- * then honours the dead lock until the waiter's timeout. Where the record
- * carries the writer's start tick and the candidate's own tick is cheaply
- * obtainable (see {@link readProcessStartTick}), the two must be equal: a
- * different tick is a different process. Records without a start tick, and
- * platforms without one, keep the PID-only answer.
- *
- * @param owner - Owner record fields that identify the holder
- * @param procRoot - procfs mount, overridable for tests
- * @returns True when the original holder is still running (or cannot be proven gone)
- */
-export declare function isLockOwnerAlive(owner: {
-    pid: number;
-    startTick?: number | undefined;
-}, procRoot?: string): boolean;

package/dist/src/core/file-lock-owner.js

@@ -1,259 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Owner record of a `withFileLock` directory: the file that says which
- * process holds the lock, so stale recovery can tell a dead holder from a
- * slow one and release can refuse to remove a lock it no longer owns.
- *
- * Split out of `file-lock.ts` so the record's format, its write-and-verify
- * contract, and the PID-reuse guard live in one place with their own tests.
- */
-import { readFileSync } from 'node:fs';
-import { readFile, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { GeneralError } from '../errors/base.js';
-import { isProcessAlive, toError } from '../utils/errors.js';
-import { verbose } from '../utils/logger.js';
-import { sleep } from '../utils/sleep.js';
-/**
- * Filename of a lock directory's owner record, relative to the lock dir.
- *
- * Re-exported by `file-lock.ts` so external readers (`tree-store.ts`) share
- * the constant instead of re-spelling `'pid'`. The file format is
- * documented on {@link readLockOwner}.
- */
-export const LOCK_PID_FILE = 'pid';
-/**
- * Prefix of the mechanical owner-record line that carries the acquisition
- * wall time. It lives among the metadata lines (line 3 onward) so older
- * readers, which treat everything past line 2 as free-form diagnostics,
- * still parse the record. The current reader lifts it out of `metadata`.
- * Diagnostic only. See {@link START_TICK_PREFIX} for the liveness field.
- */
-const ACQUIRED_AT_PREFIX = 'acquired-at-ms=';
-/**
- * Prefix of the owner-record line carrying the holder's own process start
- * tick (`/proc/self/stat` field 22, in USER_HZ since boot). Written only
- * where procfs exposes it (Linux). Boot-relative ticks are what the
- * PID-reuse guard compares: unlike a wall-clock time they are immune to
- * the clock being stepped by NTP/chrony/`date -s` between acquisition and
- * probe, and a process's start tick never changes for its lifetime, so the
- * comparison is exact rather than a tolerance window.
- */
-const START_TICK_PREFIX = 'start-tick=';
-/**
- * How many times the post-write read-back is retried when the read itself
- * errors (not when the record is absent or differs). An on-access scanner
- * on Windows briefly holding the just-written file (`EBUSY`), or a FUSE
- * mount's momentary `EIO`, must not be indistinguishable from "the record
- * never landed": that verdict releases a lock this process has correctly
- * acquired and aborts the run before it starts.
- */
-const READ_BACK_ATTEMPTS = 5;
-/** Pause between read-back attempts. */
-const READ_BACK_RETRY_MS = 20;
-/**
- * Parses the on-disk record text. Returns `undefined` when the PID line
- * does not parse as a finite integer.
- */
-function parseLockOwnerRecord(pidContent) {
-    const [pidLine, tokenLine, ...trailingLines] = pidContent.split('\n');
-    const pid = parseInt((pidLine ?? '').trim(), 10);
-    if (!Number.isFinite(pid))
-        return undefined;
-    const metadata = [];
-    let acquiredAtMs;
-    let startTick;
-    for (const rawLine of trailingLines) {
-        const line = rawLine.trim();
-        if (line.length === 0)
-            continue;
-        if (line.startsWith(ACQUIRED_AT_PREFIX)) {
-            const parsed = Number.parseInt(line.slice(ACQUIRED_AT_PREFIX.length), 10);
-            if (Number.isFinite(parsed))
-                acquiredAtMs ??= parsed;
-            continue;
-        }
-        if (line.startsWith(START_TICK_PREFIX)) {
-            const parsed = Number.parseInt(line.slice(START_TICK_PREFIX.length), 10);
-            if (Number.isFinite(parsed))
-                startTick ??= parsed;
-            continue;
-        }
-        metadata.push(line);
-    }
-    const token = tokenLine?.trim();
-    const owner = { present: true, pid, metadata };
-    if (token !== undefined && token.length > 0)
-        owner.token = token;
-    if (acquiredAtMs !== undefined)
-        owner.acquiredAtMs = acquiredAtMs;
-    if (startTick !== undefined)
-        owner.startTick = startTick;
-    return owner;
-}
-/**
- * Reads the owner PID (line 1), acquisition token (line 2), the mechanical
- * `acquired-at-ms=` / `start-tick=` lines (when present), and diagnostic
- * metadata (the remaining lines 3+) from a lock directory's PID file.
- * Returns `{ present: false }` when the PID file is missing, unreadable, or
- * the PID does not parse as a finite integer (caller falls back to the
- * age-only staleness heuristic).
- *
- * File format note: external readers do `parseInt(content.trim(), 10)`,
- * which parses the leading digits of a multi-line file, so the token and
- * mechanical lines stay compatible.
- *
- * @param lockPath - Lock directory whose owner record to read
- * @returns The parsed owner record, or `{ present: false }`
- */
-export async function readLockOwner(lockPath) {
-    try {
-        const owner = parseLockOwnerRecord(await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8'));
-        if (owner !== undefined)
-            return owner;
-    }
-    catch {
-        // PID file missing or unreadable. Treat as absent.
-    }
-    return { present: false };
-}
-/**
- * Reads the just-written record back, retrying a read error a few times
- * before giving up. A missing or malformed record is returned as-is (the
- * caller treats it as a failed write). Only errno-level failures retry.
- */
-async function readBackLockOwner(lockPath) {
-    let lastError;
-    for (let attempt = 0; attempt < READ_BACK_ATTEMPTS; attempt++) {
-        try {
-            return parseLockOwnerRecord(await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8'));
-        }
-        catch (error) {
-            lastError = error;
-            if (attempt < READ_BACK_ATTEMPTS - 1)
-                await sleep(READ_BACK_RETRY_MS);
-        }
-    }
-    throw new Error(`owner record could not be read back: ${toError(lastError).message}`);
-}
-/**
- * Stamps this process's ownership (PID, per-acquisition token, acquisition
- * time, own start tick, diagnostic metadata) into a lock directory it has
- * just created, and reads the record back to prove it landed.
- *
- * The write is fatal rather than best-effort. Stale recovery could fall
- * back to the age heuristic, but that heuristic reaps any owner-less lock
- * after five minutes, and the build lock legitimately holds for hours. A
- * holder whose record failed to write would be reaped mid-build and a
- * second process would enter the critical section. On
- * failure the just-created lock directory is removed (nothing else can own
- * it yet) and a {@link GeneralError} names the cause.
- *
- * @param lockPath - Lock directory this process has just `mkdir`'d
- * @param token - Per-acquisition UUID, later checked by release
- * @param ownerMetadata - Extra human-diagnostic lines (see `FileLockOptions.ownerMetadata`)
- * @throws {GeneralError} When the record cannot be written or does not read back as written
- */
-export async function writeLockOwner(lockPath, token, ownerMetadata) {
-    const metadata = ownerMetadata
-        ?.map((line) => line.replace(/\r?\n/g, ' ').trim())
-        .filter((line) => line.length > 0 &&
-        !line.startsWith(ACQUIRED_AT_PREFIX) &&
-        !line.startsWith(START_TICK_PREFIX)) ?? [];
-    const ownStartTick = readProcessStartTick(process.pid);
-    const mechanicalLines = [
-        `${ACQUIRED_AT_PREFIX}${Date.now()}`,
-        ...(ownStartTick === undefined ? [] : [`${START_TICK_PREFIX}${ownStartTick}`]),
-    ];
-    const record = `${process.pid}\n${token}\n${[...mechanicalLines, ...metadata].map((line) => `${line}\n`).join('')}`;
-    let failure;
-    try {
-        await writeFile(join(lockPath, LOCK_PID_FILE), record, 'utf-8');
-        const readBack = await readBackLockOwner(lockPath);
-        if (readBack !== undefined && readBack.pid === process.pid && readBack.token === token) {
-            return;
-        }
-        failure = new Error('owner record did not read back as written');
-    }
-    catch (error) {
-        failure = error;
-    }
-    try {
-        await rm(lockPath, { recursive: true, force: true });
-    }
-    catch (cleanupError) {
-        verbose(`Could not remove unowned lock ${lockPath}: ${toError(cleanupError).message}`);
-    }
-    throw new GeneralError(`Could not record ownership of lock ${lockPath}: ${toError(failure).message}. ` +
-        'The lock was released without running the operation — a lock with no readable owner ' +
-        'would be reaped as stale after five minutes and a second process could enter the ' +
-        'critical section. Check permissions and free space on the lock directory, then retry.', failure);
-}
-/**
- * Boot-relative start tick of a process, where the platform exposes it
- * cheaply.
- *
- * Linux only: field 22 of `/proc/<pid>/stat`, in USER_HZ since boot.
- * Elsewhere (macOS, Windows) obtaining a start time means spawning
- * `ps`/`wmic` per probe, which is not worth paying on every poll of a
- * contended lock. Those platforms return `undefined` and liveness stays
- * PID-only.
- *
- * Not converted to wall-clock time via `/proc/stat` `btime`, on purpose:
- * on current kernels `btime` is derived from the realtime clock and moves
- * with every clock step, so a wall-clock comparison against a recorded
- * acquisition time misjudges a live holder as a reused PID after NTP steps
- * the clock forward, and reaps a lock that is in use.
- *
- * @param pid - Process to look up
- * @param procRoot - procfs mount, overridable for tests
- * @returns Start tick, or `undefined` when unobtainable
- */
-export function readProcessStartTick(pid, procRoot = '/proc') {
-    try {
-        const stat = readFileSync(join(procRoot, String(pid), 'stat'), 'utf-8');
-        // `comm` (field 2) is parenthesised and may itself contain spaces or
-        // parentheses, so split only what follows the last closing paren:
-        // field 3 (state) is then index 0 and field 22 (starttime) index 19.
-        const startTick = Number.parseInt(stat
-            .slice(stat.lastIndexOf(')') + 1)
-            .trim()
-            .split(/\s+/)[19] ?? '', 10);
-        return Number.isFinite(startTick) ? startTick : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Whether the process named by a lock's owner record is the same process
- * that acquired the lock, not merely a live process wearing its PID.
- *
- * `isProcessAlive` answers "does this PID exist". After a holder crashes,
- * the kernel may hand its PID to a long-lived daemon, and a PID-only check
- * then honours the dead lock until the waiter's timeout. Where the record
- * carries the writer's start tick and the candidate's own tick is cheaply
- * obtainable (see {@link readProcessStartTick}), the two must be equal: a
- * different tick is a different process. Records without a start tick, and
- * platforms without one, keep the PID-only answer.
- *
- * @param owner - Owner record fields that identify the holder
- * @param procRoot - procfs mount, overridable for tests
- * @returns True when the original holder is still running (or cannot be proven gone)
- */
-export function isLockOwnerAlive(owner, procRoot) {
-    if (!isProcessAlive(owner.pid))
-        return false;
-    if (owner.startTick === undefined)
-        return true;
-    const currentStartTick = readProcessStartTick(owner.pid, procRoot);
-    if (currentStartTick === undefined)
-        return true;
-    if (currentStartTick !== owner.startTick) {
-        verbose(`Lock owner PID ${owner.pid} started at tick ${currentStartTick}, but the ` +
-            `record was written by a process started at tick ${owner.startTick} — the PID was ` +
-            'reused; treating the holder as dead');
-        return false;
-    }
-    return true;
-}