@monte3l/groundwork 0.1.0-next.1 → 1.0.0-rc.3

package/dist/staging.js

@@ -0,0 +1,375 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * The staging machinery adopt mode's two stagers share --
+ * `baseline-stage.ts` (`.groundwork/baseline/`) and `pack-stage.ts`
+ * (`.groundwork/packs/`): the inert `.staged` naming convention, the
+ * template-tree walk that maps a source file to its install path, the
+ * stale-work-dir sweep, and the atomic write-then-swap lifecycle. Each
+ * stager owns its own plan validation and its own result shape; everything
+ * here is parameterized by the staging directory's name and a noun for
+ * messages, so both stagers' failures read the same way.
+ */
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { restoreDotfilePath } from "./assets.js";
+import { isPathContained } from "./emit.js";
+import { assertNotSymlink } from "./fs-guard.js";
+import { applyTokens } from "./tokens.js";
+// `toPosixPath` lives in assets.ts, so inventory.ts can use it without
+// pulling in this stager; re-exported for this module's existing consumers.
+export { toPosixPath } from "./assets.js";
+/**
+ * The suffix every staged file carries, so no extension-based glob
+ * (`**\/*.ts`, `**\/*.md`, `vitest.config.*`) ever matches a staged copy.
+ *
+ * @example
+ * ```ts
+ * const staged = `eslint.config.js${STAGED_SUFFIX}`; // "eslint.config.js.staged"
+ * ```
+ */
+export const STAGED_SUFFIX = ".staged";
+/**
+ * The staged name for a project-relative `path`: `path` + {@link STAGED_SUFFIX}.
+ * The single derivation every stager and adopt mode's write-scope check use.
+ *
+ * @example
+ * ```ts
+ * stagedNameFor("src/index.ts"); // "src/index.ts.staged"
+ * ```
+ */
+export function stagedNameFor(path) {
+    return `${path}${STAGED_SUFFIX}`;
+}
+/**
+ * Finds the first pair of staged paths that would land on the same file on
+ * some supported file system: two paths equal once folded -- NFC-normalized
+ * (macOS's APFS treats a precomposed `é` and `e` + U+0301 as one name) and
+ * case-folded (macOS and Windows default to case-insensitive) -- or one path
+ * a proper directory prefix of another once folded (`x.staged` as both a
+ * file and the directory holding `x.staged/y.staged`). Either collision
+ * makes the second exclusive (`wx`) write fail mid-staging; a plan checks
+ * for it first so the defect surfaces as its own error instead. Folding is
+ * `toLowerCase()` after `normalize("NFC")`, not a full Unicode case fold, so
+ * it is a best-effort approximation of each file system's own rules. Paths
+ * are otherwise compared as given -- pass them `/`-separated
+ * ({@link toPosixPath}).
+ *
+ * @returns A description naming both colliding paths, or `undefined` when
+ * none collide.
+ *
+ * @example
+ * ```ts
+ * findStagedPathCollision(["README.md.staged", "readme.md.staged"]); // "README.md.staged and readme.md.staged …"
+ * findStagedPathCollision(["a.staged", "b.staged"]); // undefined
+ * ```
+ */
+export function findStagedPathCollision(stagedPaths) {
+    const fold = (p) => p.normalize("NFC").toLowerCase();
+    const byFolded = new Map();
+    for (const path of stagedPaths) {
+        const folded = fold(path);
+        const previous = byFolded.get(folded);
+        if (previous !== undefined) {
+            return previous.toLowerCase() === path.toLowerCase()
+                ? `${previous} and ${path} differ only by letter case, so they are the same file on a case-insensitive file system`
+                : `${previous} and ${path} differ only by Unicode normalization (and possibly letter case), so they are the same file on a normalization-insensitive file system`;
+        }
+        byFolded.set(folded, path);
+    }
+    for (const path of stagedPaths) {
+        const segments = fold(path).split("/");
+        for (let i = 1; i < segments.length; i++) {
+            const ancestor = byFolded.get(segments.slice(0, i).join("/"));
+            if (ancestor !== undefined) {
+                return `${ancestor} would be both a file and the directory holding ${path}`;
+            }
+        }
+    }
+    return undefined;
+}
+function collectInto(root, currentDir, tokens, results) {
+    for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+        const sourcePath = join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            collectInto(root, sourcePath, tokens, results);
+            continue;
+        }
+        const installPath = restoreDotfilePath(applyTokens(relative(root, sourcePath), tokens));
+        const previous = results.get(installPath);
+        if (previous !== undefined) {
+            throw new Error(`template files ${previous} and ${sourcePath} both install to ${installPath} under ${root}; remove one of them`);
+        }
+        results.set(installPath, sourcePath);
+    }
+}
+/**
+ * Maps every file under `root` to its install path (tokens applied, dotfile
+ * name restored) -- the same derivation `planConflicts` uses -- keyed by
+ * install path, valued by absolute source path.
+ *
+ * @throws `Error` (no `cause`) naming the install path and both sources when
+ * two files map to the same install path (`_gitignore` beside `.gitignore`),
+ * rather than silently letting the later one win.
+ *
+ * @example
+ * ```ts
+ * const files = collectTemplateFiles("/repo/templates/core", { PROJECT_NAME: "acme" });
+ * files.get(".gitignore"); // "/repo/templates/core/_gitignore"
+ * ```
+ */
+export function collectTemplateFiles(root, tokens) {
+    const results = new Map();
+    collectInto(root, root, tokens, results);
+    return results;
+}
+/**
+ * `rmSync` options for a staging directory: recursive, tolerant of absence,
+ * and retried on a transient EBUSY/EPERM.
+ */
+const RM_DIR_OPTIONS = {
+    recursive: true,
+    force: true,
+    maxRetries: 3,
+};
+/**
+ * Removes `path` recursively; a failure only warns, naming the path, so it
+ * can never shadow the outcome it is cleaning up after.
+ */
+function removeBestEffort(path) {
+    try {
+        rmSync(path, RM_DIR_OPTIONS);
+    }
+    catch (error) {
+        console.warn(`warning: could not remove the temporary staging directory ${path} -- delete it by hand (${error instanceof Error ? error.message : String(error)})`);
+    }
+}
+/**
+ * The swap's final rename and the restore of the parked previous staging
+ * both failed: the parked copy is the only one left. Its `errors` are
+ * `[swapError, restoreError]`.
+ */
+class ParkedStagingError extends AggregateError {
+}
+/**
+ * The standard staging failure: `.groundwork/` is incomplete and the CLI
+ * should be re-run. The message embeds the cause's own message so it stands
+ * alone; `formatErrorChain` skips the then-redundant `caused by:` line.
+ */
+function incompleteStagingError(noun, destDir, cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    return new Error(`staging the ${noun} into ${destDir} failed (${reason}), so .groundwork/ is incomplete -- fix the cause and re-run the CLI`, { cause });
+}
+/**
+ * Removes every entry of `groundworkDir` whose name starts with
+ * `.<dirName>-`, best effort (a removal failure only warns). Its purpose is
+ * reclaiming work directories a crashed earlier run left behind, but there
+ * is no PID or age check: any matching entry is removed, whatever made it,
+ * because `.groundwork/` is CLI-owned. So two concurrent runs against the
+ * same directory can delete each other's in-progress work directory; the
+ * run that loses fails with the generic {@link incompleteStagingError}
+ * ("`.groundwork/` is incomplete -- re-run the CLI"). Nothing else in
+ * `groundworkDir` is touched; a missing `groundworkDir` is a no-op. Failing
+ * to list `groundworkDir` at all throws {@link incompleteStagingError}.
+ */
+function removeStaleWorkDirs(target) {
+    const { groundworkDir, dirName, noun } = target;
+    if (!existsSync(groundworkDir)) {
+        return;
+    }
+    let names;
+    try {
+        names = readdirSync(groundworkDir);
+    }
+    catch (cause) {
+        throw incompleteStagingError(noun, join(groundworkDir, dirName), cause);
+    }
+    const prefix = `.${dirName}-`;
+    for (const name of names) {
+        if (name.startsWith(prefix)) {
+            removeBestEffort(join(groundworkDir, name));
+        }
+    }
+}
+/**
+ * Moves `newDir` into place at `destDir`, parking any previous `destDir` at
+ * `parkedDir` first. If the final rename fails the parked copy is renamed
+ * back and the rename failure rethrown; if that restore fails too, throws a
+ * {@link ParkedStagingError} carrying both errors, naming `parkedDir`, and
+ * telling the user to re-run the CLI -- the staging is derived data, so the
+ * next run's stale-dir sweep removes the parked copy and regenerates
+ * `destDir`.
+ */
+function swapInto(target, newDir, destDir, parkedDir) {
+    const { noun } = target;
+    const was = target.plural ? "were" : "was";
+    const hadPrevious = existsSync(destDir);
+    if (hadPrevious) {
+        renameSync(destDir, parkedDir);
+    }
+    try {
+        renameSync(newDir, destDir);
+    }
+    catch (error) {
+        if (!hadPrevious) {
+            throw error;
+        }
+        try {
+            renameSync(parkedDir, destDir);
+        }
+        catch (restoreError) {
+            throw new ParkedStagingError([error, restoreError], `moving the new ${noun} into ${destDir} failed and restoring the previous one failed too; the previous ${noun} ${was} parked at ${parkedDir} -- fix the cause and re-run the CLI: the staging is derived data, regenerated from the template, and the next run removes the parked copy`);
+        }
+        throw error;
+    }
+}
+/**
+ * Refuses a staging plan computed for a different `.groundwork/` than the
+ * one a stager was handed: the plan's scope-checked paths would otherwise
+ * not be the paths written. Directories are compared after `path.resolve`,
+ * so two spellings of one directory match. A caller defect, so a plain
+ * `Error` (never an `AssertionError`), thrown before anything is written.
+ *
+ * @throws `Error` naming both directories when they differ.
+ *
+ * @example
+ * ```ts
+ * assertPlanBuiltFor("stagePacks", plan.groundworkDir, groundworkDir);
+ * ```
+ */
+export function assertPlanBuiltFor(caller, planGroundworkDir, groundworkDir) {
+    const planned = resolve(planGroundworkDir);
+    const actual = resolve(groundworkDir);
+    if (planned !== actual) {
+        throw new Error(`${caller}: the plan was built for ${planned}, not ${actual} -- compute the plan for the same .groundwork/ directory it is staged into`);
+    }
+}
+/**
+ * The first step of every staging run: refuses a symlinked `groundworkDir`
+ * or `<groundworkDir>/<dirName>` (before anything is deleted or written),
+ * then sweeps the `.<dirName>-*` work directories a crashed earlier run
+ * left. The sweep removes **every** entry of the CLI-owned `.groundwork/`
+ * whose name matches `.<dirName>-*`, whatever created it -- including a
+ * concurrent run's in-progress work directory, so two runs against the same
+ * directory can fail each other with the standard incomplete/re-run error;
+ * a failure to remove one only warns. Returns the staging directory's path.
+ *
+ * @throws `Error` naming the path when either directory is a symlink; the
+ * standard `.groundwork/ is incomplete -- re-run` `Error`, with `cause`, when
+ * `groundworkDir` cannot be listed for the sweep.
+ *
+ * @example
+ * ```ts
+ * const destDir = prepareStaging({ groundworkDir, dirName: "packs", noun: "packs", plural: true });
+ * ```
+ */
+export function prepareStaging(target) {
+    const destDir = join(target.groundworkDir, target.dirName);
+    assertNotSymlink(target.groundworkDir);
+    assertNotSymlink(destDir);
+    removeStaleWorkDirs(target);
+    return destDir;
+}
+/**
+ * Removes the staging directory outright -- what a run with nothing to
+ * stage does, so no previous staging outlives it.
+ *
+ * @throws {@link incompleteStagingError}, with the removal failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * clearStaging({ groundworkDir, dirName: "packs", noun: "packs" });
+ * ```
+ */
+export function clearStaging(target) {
+    const destDir = join(target.groundworkDir, target.dirName);
+    try {
+        rmSync(destDir, RM_DIR_OPTIONS);
+    }
+    catch (cause) {
+        throw incompleteStagingError(target.noun, destDir, cause);
+    }
+}
+/**
+ * Writes `bytes` to `<rootDir>/<stagedName>` with the exclusive `wx` flag
+ * (creating parent directories) and returns their lowercase hex sha256.
+ * Re-asserts the CWE-22 containment invariant (docs/assurance-case.md)
+ * against the directory actually written to; the caller's plan must already
+ * have refused an escaping name.
+ *
+ * @throws `AssertionError` (message prefixed by `caller`) when the staged
+ * path escapes `rootDir`; any write error unchanged.
+ *
+ * @example
+ * ```ts
+ * const sha256 = writeStagedBytes("stagePacks", bytes, newDir, "pack.json.staged");
+ * ```
+ */
+export function writeStagedBytes(caller, bytes, rootDir, stagedName) {
+    const destPath = join(rootDir, stagedName);
+    assert.ok(isPathContained(destPath, rootDir), `${caller}: staged path ${resolve(destPath)} escapes ${resolve(rootDir)}`);
+    mkdirSync(dirname(destPath), { recursive: true });
+    writeFileSync(destPath, bytes, { flag: "wx" });
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Runs `write` against a fresh `<groundworkDir>/.<dirName>-XXXXXX/<dirName>`
+ * directory and, only once it returns, swaps that directory over
+ * `<groundworkDir>/<dirName>` by rename -- so a failure part-way through
+ * leaves any previous staging intact, and a previous staging is replaced
+ * wholesale. Call {@link prepareStaging} first.
+ *
+ * - If the swap's final rename fails, the previous staging is renamed back.
+ *   Only if that restore also fails is the staging directory left absent:
+ *   the previous staging then survives, parked inside the work directory,
+ *   which is deliberately not removed (a later run's stale-dir sweep does).
+ * - The work directory is otherwise always removed; a failure to remove it
+ *   only warns, naming its path.
+ *
+ * @throws {@link ParkedStagingError} when both renames fail; an
+ * `AssertionError` unwrapped (a broken invariant is a bug, not something a
+ * re-run fixes); otherwise {@link incompleteStagingError} with `cause`.
+ *
+ * @example
+ * ```ts
+ * const files = stageAtomically(target, (newDir) =>
+ *   [writeStagedBytes("stagePacks", bytes, newDir, "a.txt.staged")],
+ * );
+ * ```
+ */
+export function stageAtomically(target, write) {
+    const destDir = join(target.groundworkDir, target.dirName);
+    let workDir;
+    // Set only when the previous staging is parked inside workDir and could
+    // not be restored: workDir then holds its only copy and must survive.
+    let keepWorkDir = false;
+    try {
+        mkdirSync(target.groundworkDir, { recursive: true });
+        workDir = mkdtempSync(join(target.groundworkDir, `.${target.dirName}-`));
+        const newDir = join(workDir, target.dirName);
+        mkdirSync(newDir);
+        const result = write(newDir);
+        swapInto(target, newDir, destDir, join(workDir, "previous"));
+        return result;
+    }
+    catch (cause) {
+        if (cause instanceof ParkedStagingError) {
+            keepWorkDir = true;
+            throw cause;
+        }
+        if (cause instanceof assert.AssertionError) {
+            // A broken CWE-22 invariant is a bug in the stager, not a transient
+            // failure a re-run could fix: surface it as itself.
+            throw cause;
+        }
+        throw incompleteStagingError(target.noun, destDir, cause);
+    }
+    finally {
+        if (workDir !== undefined && !keepWorkDir) {
+            removeBestEffort(workDir);
+        }
+    }
+}
+//# sourceMappingURL=staging.js.map

package/dist/survey/fs-walk.d.ts

@@ -8,7 +8,39 @@ export interface WalkEntry {
 /**
  * Recursively lists `root`, skipping known dependency/build directories and
  * stopping once a descendant is more than `maxDepth` directories below
- * `root`. Missing or unreadable directories are skipped, not thrown.
+ * `root`. A missing directory (`ENOENT`/`ENOTDIR`, the same absent set
+ * `guardedExists` uses) is skipped silently. An unreadable or unresolvable
+ * one (`EACCES`/`EPERM`, or a symlink loop's `ELOOP`) is skipped too, but
+ * recorded in `undetermined`. Any other listing
+ * failure (`EIO`, `EMFILE`, ...) throws an `Error` naming the directory, with
+ * the original as `cause`. For the survey collectors; the graders use
+ * {@link walkBoundedForGrading} instead.
+ *
+ * @example
+ * ```ts
+ * const undetermined: string[] = [];
+ * const markdown = walkBounded("/path/to/project", 2, undetermined).filter(
+ *   (entry) => !entry.isDirectory && entry.relPath.endsWith(".md"),
+ * );
+ * ```
  */
-export declare function walkBounded(root: string, maxDepth: number): WalkEntry[];
+export declare function walkBounded(root: string, maxDepth: number, undetermined: string[]): WalkEntry[];
+/**
+ * The same bounded listing as {@link walkBounded}, but a directory whose
+ * listing fails for ANY reason is skipped silently, never thrown. For the
+ * harness and toolchain graders (`harness/grade.ts`, `toolchain/grade.ts`)
+ * only: a grader never throws, and its emitted `.mjs` twins
+ * (`templates/core/bin/lib/{harness,toolchain}-rules.mjs`) swallow every
+ * listing failure in their own `walkBounded` -- this keeps both sides' grades
+ * identical for the same tree. The survey keeps {@link walkBounded}'s errno
+ * discrimination.
+ *
+ * @example
+ * ```ts
+ * const files = walkBoundedForGrading("/path/to/project", 4).filter(
+ *   (entry) => !entry.isDirectory,
+ * );
+ * ```
+ */
+export declare function walkBoundedForGrading(root: string, maxDepth: number): WalkEntry[];
 //# sourceMappingURL=fs-walk.d.ts.map

package/dist/survey/fs-walk.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * A bounded directory walk shared by every survey collector. Adopt mode may
  * run against an arbitrarily large pre-existing repository (dependency
@@ -7,6 +9,7 @@
  */
 import { readdirSync } from "node:fs";
 import { join, relative } from "node:path";
+import { isAbsentError, readFailure, unreadableNote, unresolvableCode, } from "./internal/read-guard.js";
 const SKIP_DIR_NAMES = new Set([
     "node_modules",
     ".git",
@@ -20,12 +23,17 @@ const SKIP_DIR_NAMES = new Set([
     "out",
     ".nx",
 ]);
+// Claude Code creates git worktrees at `.claude/worktrees/<name>/` -- each a
+// full second checkout that must not be walked twice. Matched as an exact
+// path relative to the walk root, never by bare name: a directory literally
+// named `worktrees` elsewhere (`src/worktrees/`, `.claude/skills/worktrees/`)
+// is real project content and must stay visible to every survey.
+const SKIP_REL_DIR_PATHS = new Set([".claude/worktrees"]);
 /**
- * Recursively lists `root`, skipping known dependency/build directories and
- * stopping once a descendant is more than `maxDepth` directories below
- * `root`. Missing or unreadable directories are skipped, not thrown.
+ * The shared bounded walk. `onListFailure` decides what a failed directory
+ * listing means: it returns normally to skip the directory, or throws.
  */
-export function walkBounded(root, maxDepth) {
+function walk(root, maxDepth, onListFailure) {
     const results = [];
     const visit = (dir, depth) => {
         if (depth > maxDepth) {
@@ -35,7 +43,8 @@ export function walkBounded(root, maxDepth) {
         try {
             entries = readdirSync(dir, { withFileTypes: true });
         }
-        catch {
+        catch (error) {
+            onListFailure(dir, error);
             return;
         }
         for (const entry of entries) {
@@ -44,6 +53,9 @@ export function walkBounded(root, maxDepth) {
             }
             const absPath = join(dir, entry.name);
             const relPath = relative(root, absPath).split("\\").join("/");
+            if (entry.isDirectory() && SKIP_REL_DIR_PATHS.has(relPath)) {
+                continue;
+            }
             results.push({
                 path: absPath,
                 relPath,
@@ -57,4 +69,57 @@ export function walkBounded(root, maxDepth) {
     visit(root, 0);
     return results;
 }
+/**
+ * Recursively lists `root`, skipping known dependency/build directories and
+ * stopping once a descendant is more than `maxDepth` directories below
+ * `root`. A missing directory (`ENOENT`/`ENOTDIR`, the same absent set
+ * `guardedExists` uses) is skipped silently. An unreadable or unresolvable
+ * one (`EACCES`/`EPERM`, or a symlink loop's `ELOOP`) is skipped too, but
+ * recorded in `undetermined`. Any other listing
+ * failure (`EIO`, `EMFILE`, ...) throws an `Error` naming the directory, with
+ * the original as `cause`. For the survey collectors; the graders use
+ * {@link walkBoundedForGrading} instead.
+ *
+ * @example
+ * ```ts
+ * const undetermined: string[] = [];
+ * const markdown = walkBounded("/path/to/project", 2, undetermined).filter(
+ *   (entry) => !entry.isDirectory && entry.relPath.endsWith(".md"),
+ * );
+ * ```
+ */
+export function walkBounded(root, maxDepth, undetermined) {
+    return walk(root, maxDepth, (dir, error) => {
+        const code = unresolvableCode(error);
+        if (code !== undefined) {
+            undetermined.push(unreadableNote(dir, code));
+            return;
+        }
+        if (isAbsentError(error))
+            return;
+        throw readFailure(dir, error);
+    });
+}
+/**
+ * The same bounded listing as {@link walkBounded}, but a directory whose
+ * listing fails for ANY reason is skipped silently, never thrown. For the
+ * harness and toolchain graders (`harness/grade.ts`, `toolchain/grade.ts`)
+ * only: a grader never throws, and its emitted `.mjs` twins
+ * (`templates/core/bin/lib/{harness,toolchain}-rules.mjs`) swallow every
+ * listing failure in their own `walkBounded` -- this keeps both sides' grades
+ * identical for the same tree. The survey keeps {@link walkBounded}'s errno
+ * discrimination.
+ *
+ * @example
+ * ```ts
+ * const files = walkBoundedForGrading("/path/to/project", 4).filter(
+ *   (entry) => !entry.isDirectory,
+ * );
+ * ```
+ */
+export function walkBoundedForGrading(root, maxDepth) {
+    return walk(root, maxDepth, () => {
+        // Deliberately swallowed: parity with the emitted twins' bare `catch`.
+    });
+}
 //# sourceMappingURL=fs-walk.js.map

package/dist/survey/internal/blocked-path.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Why a path `probePath` reported `absent` is not really absent, or
+ * `undefined` when nothing is there at all. A symlink at the path itself is
+ * named as dangling whenever `stat` through it failed -- its target missing
+ * (`ENOENT`) or resolving through a regular file (`ENOTDIR`) alike, since
+ * `lstat` finding a link is all this checks. A dangling symlink at an
+ * ancestor below `root` is named the same way, but only for a missing target
+ * (`ENOENT`); an ancestor link resolving through a regular file surfaces as
+ * `ENOTDIR` instead, named by the nearest non-directory ancestor that can be
+ * established, else the path itself. A regular file blocking an
+ * ancestor is named with `ENOTDIR`; an `lstat` that succeeds on a
+ * non-symlink right after `stat` said absent means the tree changed during
+ * the survey, and the path is recorded unreadable (`ENOENT`). Any other
+ * `lstat` errno throws a `SurveyReadError` naming the path, with the
+ * original as `cause`.
+ *
+ * @example
+ * ```ts
+ * const probe = probePath(targetPath);
+ * if (probe.kind === "absent") {
+ *   const note = blockedAbsentNote(targetPath, targetDir);
+ *   if (note !== undefined) undetermined.push(note);
+ * }
+ * ```
+ */
+export declare function blockedAbsentNote(path: string, root: string): string | undefined;
+//# sourceMappingURL=blocked-path.d.ts.map

package/dist/survey/internal/blocked-path.js

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * Tells a genuinely absent path apart from one `probePath` merely folded into
+ * "absent". `probePath` answers `absent` for `ENOENT`/`ENOTDIR` -- correct for
+ * the survey's own exists-probes -- but that also covers a dangling symlink at
+ * the path or at one of its ancestors (`ENOENT`) and a regular file where an
+ * ancestor directory should be (`ENOTDIR`). A plan (`conflicts.ts`) or a
+ * wiring observation (`packs.ts`) must never read either as "nothing there":
+ * both are something in the project's tree a write would have to go through.
+ * Shared so the two modules record the same note for the same path.
+ */
+import { lstatSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { errnoCode, readFailure, unreadableNote } from "./read-guard.js";
+// "its target does not exist" reads loosely for a link at the path itself
+// whose target resolves through a regular file (`ENOTDIR`) -- that target
+// does not exist as a reachable path either. Wording kept as-is: tests
+// match on "dangling symlink".
+function danglingNote(path) {
+    return `${path} is a dangling symlink -- its target does not exist, so its contents are not in this survey`;
+}
+/**
+ * The nearest ancestor of `path`, walking up no further than `root`, that
+ * exists and is not a directory -- the component that made a `stat` of
+ * `path` fail with `ENOTDIR` -- or `undefined` if none can be established
+ * (the tree changed underneath, or the ancestor cannot itself be stat'd).
+ */
+function blockedAncestor(path, root) {
+    let current = dirname(path);
+    for (;;) {
+        try {
+            if (!statSync(current).isDirectory())
+                return current;
+        }
+        catch {
+            // This component is itself absent or unreachable: it is not the file
+            // blocking the path, so keep walking up. Best effort -- the caller
+            // still records the entry with `ENOTDIR` on the path itself.
+        }
+        const parent = dirname(current);
+        if (current === root || parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+/**
+ * The nearest strict ancestor of `path`, below `root`, that is a symlink
+ * whose target does not exist -- the component that made an `lstat` of
+ * `path` fail with `ENOENT` -- or `undefined` when every ancestor that
+ * exists resolves (the path is genuinely absent).
+ */
+function danglingAncestor(path, root) {
+    for (let current = dirname(path); current !== root && dirname(current) !== current; current = dirname(current)) {
+        if (isDanglingSymlink(current))
+            return current;
+    }
+    return undefined;
+}
+/**
+ * Whether `path` itself is a symlink whose target does not exist (`lstat`
+ * finds a link, `stat` through it fails `ENOENT`). Best effort: the caller
+ * only walks here after an `lstat` of a descendant already traversed every
+ * existing ancestor, so an ancestor this cannot classify is not the dangling
+ * one and answers `false`.
+ */
+function isDanglingSymlink(path) {
+    try {
+        if (!lstatSync(path).isSymbolicLink())
+            return false;
+    }
+    catch {
+        // Absent or unclassifiable at the link itself: not a dangling symlink.
+        return false;
+    }
+    try {
+        statSync(path);
+        return false;
+    }
+    catch (error) {
+        return errnoCode(error) === "ENOENT";
+    }
+}
+/**
+ * Why a path `probePath` reported `absent` is not really absent, or
+ * `undefined` when nothing is there at all. A symlink at the path itself is
+ * named as dangling whenever `stat` through it failed -- its target missing
+ * (`ENOENT`) or resolving through a regular file (`ENOTDIR`) alike, since
+ * `lstat` finding a link is all this checks. A dangling symlink at an
+ * ancestor below `root` is named the same way, but only for a missing target
+ * (`ENOENT`); an ancestor link resolving through a regular file surfaces as
+ * `ENOTDIR` instead, named by the nearest non-directory ancestor that can be
+ * established, else the path itself. A regular file blocking an
+ * ancestor is named with `ENOTDIR`; an `lstat` that succeeds on a
+ * non-symlink right after `stat` said absent means the tree changed during
+ * the survey, and the path is recorded unreadable (`ENOENT`). Any other
+ * `lstat` errno throws a `SurveyReadError` naming the path, with the
+ * original as `cause`.
+ *
+ * @example
+ * ```ts
+ * const probe = probePath(targetPath);
+ * if (probe.kind === "absent") {
+ *   const note = blockedAbsentNote(targetPath, targetDir);
+ *   if (note !== undefined) undetermined.push(note);
+ * }
+ * ```
+ */
+export function blockedAbsentNote(path, root) {
+    let isSymlink;
+    try {
+        isSymlink = lstatSync(path).isSymbolicLink();
+    }
+    catch (error) {
+        const code = errnoCode(error);
+        if (code === "ENOTDIR") {
+            return unreadableNote(blockedAncestor(path, root) ?? path, "ENOTDIR");
+        }
+        if (code !== "ENOENT")
+            throw readFailure(path, error);
+        const ancestor = danglingAncestor(path, root);
+        return ancestor === undefined ? undefined : danglingNote(ancestor);
+    }
+    // `lstat` succeeded after `stat` said absent. A symlink means `stat` could
+    // not resolve through it (`ENOENT` or `ENOTDIR`): dangling. A non-symlink
+    // means the tree changed during the survey: present, contents unknown.
+    return isSymlink ? danglingNote(path) : unreadableNote(path, "ENOENT");
+}
+//# sourceMappingURL=blocked-path.js.map