@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.3

package/dist/survey/internal/package-json.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reads `dir/package.json` as an object. Absent is `undefined` with nothing
+ * recorded; unreadable (`EACCES`/`EPERM`) or unparseable is `undefined` with
+ * an `undetermined` entry; any other read failure throws.
+ *
+ * @example
+ * ```ts
+ * const undetermined: string[] = [];
+ * const manifest = readPackageJson("/path/to/project", undetermined);
+ * ```
+ */
+export declare function readPackageJson(dir: string, undetermined: string[]): Record<string, unknown> | undefined;
+//# sourceMappingURL=package-json.d.ts.map

package/dist/survey/internal/package-json.js

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * The `package.json` read `survey-shape.ts` and `survey-toolchain.ts` share,
+ * so the two collectors cannot disagree about what an unreadable or
+ * malformed manifest means.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { guardedExists, guardedRead } from "./read-guard.js";
+/**
+ * Reads `dir/package.json` as an object. Absent is `undefined` with nothing
+ * recorded; unreadable (`EACCES`/`EPERM`) or unparseable is `undefined` with
+ * an `undetermined` entry; any other read failure throws.
+ *
+ * @example
+ * ```ts
+ * const undetermined: string[] = [];
+ * const manifest = readPackageJson("/path/to/project", undetermined);
+ * ```
+ */
+export function readPackageJson(dir, undetermined) {
+    const path = join(dir, "package.json");
+    if (!guardedExists(path, undetermined))
+        return undefined;
+    const content = guardedRead(path, () => readFileSync(path, "utf8"), undetermined);
+    if (content === undefined)
+        return undefined;
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        undetermined.push(`could not parse ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=package-json.js.map

package/dist/survey/internal/read-guard.d.ts

@@ -0,0 +1,178 @@
+/**
+ * A survey read that failed for a reason other than permission. Carries the
+ * original failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * throw new SurveyReadError("could not read /p/README.md", { cause });
+ * ```
+ */
+export declare class SurveyReadError extends Error {
+    name: string;
+}
+/**
+ * The `code` of a Node system error, or `undefined` for anything without a
+ * string `code`.
+ *
+ * @example
+ * ```ts
+ * errnoCode(Object.assign(new Error("x"), { code: "ENOENT" })); // "ENOENT"
+ * ```
+ */
+export declare function errnoCode(error: unknown): string | undefined;
+/**
+ * The permission errno carried by `error` (`EACCES`/`EPERM`), or `undefined`
+ * when `error` is anything else.
+ *
+ * @example
+ * ```ts
+ * permissionCode(Object.assign(new Error("x"), { code: "EACCES" })); // "EACCES"
+ * permissionCode(Object.assign(new Error("x"), { code: "EIO" })); // undefined
+ * ```
+ */
+export declare function permissionCode(error: unknown): string | undefined;
+/**
+ * The `undetermined` entry recorded for an unreadable path. Identical text
+ * for a file and a directory, so two collectors that hit the same
+ * unreadable path produce one entry once the aggregate de-duplicates.
+ *
+ * @example
+ * ```ts
+ * unreadableNote("/p/CLAUDE.md", "EACCES");
+ * // "/p/CLAUDE.md is unreadable (EACCES) -- its contents are not in this survey"
+ * ```
+ */
+export declare function unreadableNote(path: string, code: string): string;
+/**
+ * Wraps a non-permission read failure on `path` in a {@link SurveyReadError}
+ * naming the path, with `cause` as the original failure (which carries the
+ * errno code itself).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   readFileSync(path, "utf8");
+ * } catch (cause) {
+ *   throw readFailure(path, cause);
+ * }
+ * ```
+ */
+export declare function readFailure(path: string, cause: unknown): SurveyReadError;
+/**
+ * Whether `error` carries an errno that means "nothing is at this path"
+ * (`ENOENT`/`ENOTDIR`).
+ *
+ * @example
+ * ```ts
+ * isAbsentError(Object.assign(new Error("x"), { code: "ENOENT" })); // true
+ * isAbsentError(Object.assign(new Error("x"), { code: "ELOOP" })); // false
+ * ```
+ */
+export declare function isAbsentError(error: unknown): boolean;
+/**
+ * The errno to record when `error` says the path holds something this
+ * process cannot read or resolve -- a permission code (`EACCES`/`EPERM`) or
+ * a symlink loop (`ELOOP`) -- or `undefined` for anything else.
+ *
+ * @example
+ * ```ts
+ * unresolvableCode(Object.assign(new Error("x"), { code: "ELOOP" })); // "ELOOP"
+ * unresolvableCode(Object.assign(new Error("x"), { code: "EIO" })); // undefined
+ * ```
+ */
+export declare function unresolvableCode(error: unknown): string | undefined;
+/**
+ * What a `stat` on a path established: something is there, nothing is there,
+ * or something is there (or may be) that this process cannot reach --
+ * carrying the errno that says why.
+ */
+export type PathProbe = {
+    readonly kind: "present";
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "unresolvable";
+    readonly code: string;
+};
+/**
+ * Probes `path` with a real `stat`, never `existsSync` (which answers
+ * `false` for ANY failure, so a file under a `chmod 000` directory reads as
+ * absent). `ENOENT`/`ENOTDIR` is `absent`; `EACCES`/`EPERM`/`ELOOP` is
+ * `unresolvable` with the errno -- never folded into `absent`. Any other
+ * failure throws a {@link SurveyReadError} naming `path`, with the original
+ * as `cause`.
+ *
+ * @example
+ * ```ts
+ * const probe = probePath(targetPath);
+ * if (probe.kind === "unresolvable") undetermined.push(unreadableNote(targetPath, probe.code));
+ * ```
+ */
+export declare function probePath(path: string): PathProbe;
+/**
+ * The path an `undetermined` note names when a `stat` of `path` failed with
+ * `code` (from {@link probePath}'s `unresolvable` result). A `stat` needs
+ * search permission on the path's ancestors, never on the path itself, so a
+ * permission failure names the enclosing directory -- one entry for every
+ * probe under it once the caller de-duplicates. A symlink loop (`ELOOP`) is
+ * a property of the path itself, so it names `path`.
+ *
+ * @example
+ * ```ts
+ * const probe = probePath(targetPath);
+ * if (probe.kind === "unresolvable") {
+ *   undetermined.push(unreadableNote(probeSubject(targetPath, probe.code), probe.code));
+ * }
+ * ```
+ */
+export declare function probeSubject(path: string, code: string): string;
+/**
+ * Whether `path` exists, without `existsSync`'s blind spot: `existsSync`
+ * answers `false` for ANY `stat` failure, so a path under a directory this
+ * process may not enter (`chmod 000`) reads as silently absent. A `stat`
+ * needs search permission on the path's ancestors, never on the path
+ * itself, so a permission failure here is recorded in `undetermined` naming
+ * the enclosing directory (one entry for every probe under it once the
+ * aggregate de-duplicates) and answers `false`; the survey carries on. A
+ * symlink loop (`ELOOP`) is a property of the path itself, so it is
+ * recorded naming `path` and answers `false`. A genuinely absent path
+ * (`ENOENT`/`ENOTDIR`) answers `false` with nothing recorded. Any other
+ * failure throws a {@link SurveyReadError} naming `path`, with the original
+ * as `cause`.
+ *
+ * @example
+ * ```ts
+ * if (!guardedExists(settingsPath, undetermined)) return undefined;
+ * ```
+ */
+export declare function guardedExists(path: string, undetermined: string[]): boolean;
+/**
+ * The errno to record when a read of an already-discovered path failed for a
+ * reason that is a property of the project's own tree -- `EACCES`/`EPERM`,
+ * `ENOENT` (a dangling symlink), `ELOOP`, `EISDIR` or `ENOTDIR` -- or `undefined` for
+ * anything else (`EIO`, `EMFILE`, ...), which the caller throws.
+ *
+ * @example
+ * ```ts
+ * recordedReadCode(Object.assign(new Error("x"), { code: "EISDIR" })); // "EISDIR"
+ * recordedReadCode(Object.assign(new Error("x"), { code: "EIO" })); // undefined
+ * ```
+ */
+export declare function recordedReadCode(error: unknown): string | undefined;
+/**
+ * Runs `read` against `path`. On a failure that is a property of the
+ * project's own tree -- a permission failure (`EACCES`/`EPERM`), a dangling
+ * symlink (`ENOENT`), a symlink loop (`ELOOP`), a directory where a file
+ * was expected (`EISDIR`), or a file where a directory was expected
+ * (`ENOTDIR`) -- records the path and errno in `undetermined`
+ * and returns `undefined`. On any other failure (`EIO`, `EMFILE`, ...),
+ * throws a {@link SurveyReadError} chaining the original as `cause`.
+ *
+ * @example
+ * ```ts
+ * const content = guardedRead(path, () => readFileSync(path, "utf8"), undetermined);
+ * const headings = content === undefined ? [] : extractHeadings(content);
+ * ```
+ */
+export declare function guardedRead<T>(path: string, read: () => T, undetermined: string[]): T | undefined;
+//# sourceMappingURL=read-guard.d.ts.map

package/dist/survey/internal/read-guard.js

@@ -0,0 +1,276 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * The one errno discrimination every adopt-mode survey read goes through.
+ * A permission failure (`EACCES`/`EPERM`) is a property of the project file
+ * itself -- a `chmod 000` left behind, a root-owned file -- so it is recorded
+ * in the survey's `undetermined` list and the survey carries on; so is a
+ * dangling symlink (`ENOENT`), a symlink loop (`ELOOP`), a directory where
+ * a file was expected (`EISDIR`) or a file where a directory was expected
+ * (`ENOTDIR`) met on a read. Anything
+ * else (`EIO`, `EMFILE`, ...) says something about the machine, not the
+ * project, and is thrown with the path named and the original chained as
+ * `cause`, never folded silently in beside a genuine permission problem.
+ */
+import { statSync } from "node:fs";
+import { dirname } from "node:path";
+/** The errno codes that mean "this entry exists but this process may not read it". */
+const PERMISSION_CODES = new Set(["EACCES", "EPERM"]);
+/**
+ * A survey read that failed for a reason other than permission. Carries the
+ * original failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * throw new SurveyReadError("could not read /p/README.md", { cause });
+ * ```
+ */
+export class SurveyReadError extends Error {
+    name = "SurveyReadError";
+}
+/**
+ * The `code` of a Node system error, or `undefined` for anything without a
+ * string `code`.
+ *
+ * @example
+ * ```ts
+ * errnoCode(Object.assign(new Error("x"), { code: "ENOENT" })); // "ENOENT"
+ * ```
+ */
+export function errnoCode(error) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    // One read into a local, so the value checked is the value returned.
+    const code = Reflect.get(error, "code");
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * The permission errno carried by `error` (`EACCES`/`EPERM`), or `undefined`
+ * when `error` is anything else.
+ *
+ * @example
+ * ```ts
+ * permissionCode(Object.assign(new Error("x"), { code: "EACCES" })); // "EACCES"
+ * permissionCode(Object.assign(new Error("x"), { code: "EIO" })); // undefined
+ * ```
+ */
+export function permissionCode(error) {
+    const code = errnoCode(error);
+    return code !== undefined && PERMISSION_CODES.has(code) ? code : undefined;
+}
+/**
+ * The `undetermined` entry recorded for an unreadable path. Identical text
+ * for a file and a directory, so two collectors that hit the same
+ * unreadable path produce one entry once the aggregate de-duplicates.
+ *
+ * @example
+ * ```ts
+ * unreadableNote("/p/CLAUDE.md", "EACCES");
+ * // "/p/CLAUDE.md is unreadable (EACCES) -- its contents are not in this survey"
+ * ```
+ */
+export function unreadableNote(path, code) {
+    return `${path} is unreadable (${code}) -- its contents are not in this survey`;
+}
+/**
+ * Wraps a non-permission read failure on `path` in a {@link SurveyReadError}
+ * naming the path, with `cause` as the original failure (which carries the
+ * errno code itself).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   readFileSync(path, "utf8");
+ * } catch (cause) {
+ *   throw readFailure(path, cause);
+ * }
+ * ```
+ */
+export function readFailure(path, cause) {
+    return new SurveyReadError(`could not read ${path}`, { cause });
+}
+/**
+ * The errno codes that mean "nothing is at this path": nothing there
+ * (`ENOENT`) or an ancestor is a file (`ENOTDIR`). The one definition every
+ * survey probe (`guardedExists`, `fs-walk.ts`'s `walkBounded`) and
+ * `jsonc.ts`'s `readJsoncFile` share, so they cannot disagree on what
+ * "absent" means. `ELOOP` is deliberately NOT here: a symlink loop is
+ * something at the path this process cannot resolve, not an absence -- see
+ * {@link UNRESOLVABLE_CODE}.
+ */
+const ABSENT_CODES = new Set(["ENOENT", "ENOTDIR"]);
+/**
+ * The errno a symlink loop raises: an entry exists at the path, but it never
+ * resolves. Recorded like a permission failure, never folded into "absent".
+ */
+const UNRESOLVABLE_CODE = "ELOOP";
+/**
+ * Whether `error` carries an errno that means "nothing is at this path"
+ * (`ENOENT`/`ENOTDIR`).
+ *
+ * @example
+ * ```ts
+ * isAbsentError(Object.assign(new Error("x"), { code: "ENOENT" })); // true
+ * isAbsentError(Object.assign(new Error("x"), { code: "ELOOP" })); // false
+ * ```
+ */
+export function isAbsentError(error) {
+    const code = errnoCode(error);
+    return code !== undefined && ABSENT_CODES.has(code);
+}
+/**
+ * The errno to record when `error` says the path holds something this
+ * process cannot read or resolve -- a permission code (`EACCES`/`EPERM`) or
+ * a symlink loop (`ELOOP`) -- or `undefined` for anything else.
+ *
+ * @example
+ * ```ts
+ * unresolvableCode(Object.assign(new Error("x"), { code: "ELOOP" })); // "ELOOP"
+ * unresolvableCode(Object.assign(new Error("x"), { code: "EIO" })); // undefined
+ * ```
+ */
+export function unresolvableCode(error) {
+    const permission = permissionCode(error);
+    if (permission !== undefined)
+        return permission;
+    return errnoCode(error) === UNRESOLVABLE_CODE ? UNRESOLVABLE_CODE : undefined;
+}
+/**
+ * Probes `path` with a real `stat`, never `existsSync` (which answers
+ * `false` for ANY failure, so a file under a `chmod 000` directory reads as
+ * absent). `ENOENT`/`ENOTDIR` is `absent`; `EACCES`/`EPERM`/`ELOOP` is
+ * `unresolvable` with the errno -- never folded into `absent`. Any other
+ * failure throws a {@link SurveyReadError} naming `path`, with the original
+ * as `cause`.
+ *
+ * @example
+ * ```ts
+ * const probe = probePath(targetPath);
+ * if (probe.kind === "unresolvable") undetermined.push(unreadableNote(targetPath, probe.code));
+ * ```
+ */
+export function probePath(path) {
+    try {
+        statSync(path);
+        return { kind: "present" };
+    }
+    catch (error) {
+        if (isAbsentError(error))
+            return { kind: "absent" };
+        const code = unresolvableCode(error);
+        if (code !== undefined)
+            return { kind: "unresolvable", code };
+        throw new SurveyReadError(`could not check whether ${path} exists`, {
+            cause: error,
+        });
+    }
+}
+/**
+ * The path an `undetermined` note names when a `stat` of `path` failed with
+ * `code` (from {@link probePath}'s `unresolvable` result). A `stat` needs
+ * search permission on the path's ancestors, never on the path itself, so a
+ * permission failure names the enclosing directory -- one entry for every
+ * probe under it once the caller de-duplicates. A symlink loop (`ELOOP`) is
+ * a property of the path itself, so it names `path`.
+ *
+ * @example
+ * ```ts
+ * const probe = probePath(targetPath);
+ * if (probe.kind === "unresolvable") {
+ *   undetermined.push(unreadableNote(probeSubject(targetPath, probe.code), probe.code));
+ * }
+ * ```
+ */
+export function probeSubject(path, code) {
+    return code === UNRESOLVABLE_CODE ? path : dirname(path);
+}
+/**
+ * Whether `path` exists, without `existsSync`'s blind spot: `existsSync`
+ * answers `false` for ANY `stat` failure, so a path under a directory this
+ * process may not enter (`chmod 000`) reads as silently absent. A `stat`
+ * needs search permission on the path's ancestors, never on the path
+ * itself, so a permission failure here is recorded in `undetermined` naming
+ * the enclosing directory (one entry for every probe under it once the
+ * aggregate de-duplicates) and answers `false`; the survey carries on. A
+ * symlink loop (`ELOOP`) is a property of the path itself, so it is
+ * recorded naming `path` and answers `false`. A genuinely absent path
+ * (`ENOENT`/`ENOTDIR`) answers `false` with nothing recorded. Any other
+ * failure throws a {@link SurveyReadError} naming `path`, with the original
+ * as `cause`.
+ *
+ * @example
+ * ```ts
+ * if (!guardedExists(settingsPath, undetermined)) return undefined;
+ * ```
+ */
+export function guardedExists(path, undetermined) {
+    const probe = probePath(path);
+    if (probe.kind === "present")
+        return true;
+    if (probe.kind === "absent")
+        return false;
+    undetermined.push(unreadableNote(probeSubject(path, probe.code), probe.code));
+    return false;
+}
+/**
+ * The non-permission errnos a read of an already-discovered path records
+ * rather than throws: the entry is a dangling symlink (`ENOENT`), a symlink
+ * loop (`ELOOP`), a directory where a file was expected (`EISDIR`), or a
+ * file where a directory was expected (`ENOTDIR`, e.g. a `readdirSync` of a
+ * path a prior `stat` found present). Each
+ * is a property of the project's own tree, like a permission failure -- not
+ * of the machine, like `EIO`/`EMFILE`.
+ */
+const RECORDED_READ_CODES = new Set([
+    "ENOENT",
+    UNRESOLVABLE_CODE,
+    "EISDIR",
+    "ENOTDIR",
+]);
+/**
+ * The errno to record when a read of an already-discovered path failed for a
+ * reason that is a property of the project's own tree -- `EACCES`/`EPERM`,
+ * `ENOENT` (a dangling symlink), `ELOOP`, `EISDIR` or `ENOTDIR` -- or `undefined` for
+ * anything else (`EIO`, `EMFILE`, ...), which the caller throws.
+ *
+ * @example
+ * ```ts
+ * recordedReadCode(Object.assign(new Error("x"), { code: "EISDIR" })); // "EISDIR"
+ * recordedReadCode(Object.assign(new Error("x"), { code: "EIO" })); // undefined
+ * ```
+ */
+export function recordedReadCode(error) {
+    const permission = permissionCode(error);
+    if (permission !== undefined)
+        return permission;
+    const code = errnoCode(error);
+    return code !== undefined && RECORDED_READ_CODES.has(code) ? code : undefined;
+}
+/**
+ * Runs `read` against `path`. On a failure that is a property of the
+ * project's own tree -- a permission failure (`EACCES`/`EPERM`), a dangling
+ * symlink (`ENOENT`), a symlink loop (`ELOOP`), a directory where a file
+ * was expected (`EISDIR`), or a file where a directory was expected
+ * (`ENOTDIR`) -- records the path and errno in `undetermined`
+ * and returns `undefined`. On any other failure (`EIO`, `EMFILE`, ...),
+ * throws a {@link SurveyReadError} chaining the original as `cause`.
+ *
+ * @example
+ * ```ts
+ * const content = guardedRead(path, () => readFileSync(path, "utf8"), undetermined);
+ * const headings = content === undefined ? [] : extractHeadings(content);
+ * ```
+ */
+export function guardedRead(path, read, undetermined) {
+    try {
+        return read();
+    }
+    catch (error) {
+        const code = recordedReadCode(error);
+        if (code === undefined)
+            throw readFailure(path, error);
+        undetermined.push(unreadableNote(path, code));
+        return undefined;
+    }
+}
+//# sourceMappingURL=read-guard.js.map

package/dist/survey/survey-docs.d.ts

@@ -1,4 +1,19 @@
 import type { DocsSurvey } from "./types.js";
-/** Indexes docs/guideline files at `dir`. Offline, read-only, index-only -- no full content. */
-export declare function surveyDocs(dir: string): DocsSurvey;
+/**
+ * Indexes docs/guideline files at `dir`. Offline, read-only, index-only --
+ * no full content. A doc or doc directory that exists but cannot be read
+ * (`EACCES`/`EPERM`) is recorded in `undetermined` (an unreadable doc keeps
+ * its entry with empty `headings`); any other read failure throws, naming
+ * the path, with the original failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * import { surveyDocs } from "./survey-docs.js";
+ *
+ * const undetermined: string[] = [];
+ * const docs = surveyDocs("/path/to/project", undetermined);
+ * console.log(docs.files.map((file) => file.path), undetermined);
+ * ```
+ */
+export declare function surveyDocs(dir: string, undetermined: string[]): DocsSurvey;
 //# sourceMappingURL=survey-docs.d.ts.map

package/dist/survey/survey-docs.js

@@ -1,14 +1,18 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Indexes human-facing docs and guidelines: `CONTRIBUTING.md`, a
  * `docs/contributing/` tree, ADR/decision/RFC directories, style guides, and
  * the README's own heading outline. This is an index (path, size, headings)
- * so `/customize`'s Step 0 knows what exists and where to read it in full --
+ * so `/customize`'s Step 0 (the adopt-mode reconcile step in `/customize`)
+ * knows what exists and where to read it in full --
  * it never inlines a doc's content itself, which would make the survey's
  * own output as large as the docs it's indexing.
  */
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { walkBounded } from "./fs-walk.js";
+import { guardedExists, guardedRead } from "./internal/read-guard.js";
 const NAMED_ROOT_CANDIDATES = ["README.md", "CONTRIBUTING.md"];
 const NAMED_DIR_CANDIDATES = [
     "docs/contributing",
@@ -24,46 +28,82 @@ function extractHeadings(content) {
         .filter((line) => /^#{1,3}\s/.test(line))
         .map((line) => line.replace(/^#{1,3}\s*/, "").trim());
 }
-function indexFile(path) {
-    const content = readFileSync(path, "utf8");
+/**
+ * Indexes one doc. Its size comes from `statSync`, which needs no read
+ * permission on the file itself, so an unreadable doc keeps its entry with
+ * empty `headings` (and is recorded); a doc that cannot even be stat'ed is
+ * left out (and recorded).
+ */
+function indexFile(path, undetermined) {
+    const sizeBytes = guardedRead(path, () => statSync(path).size, undetermined);
+    if (sizeBytes === undefined)
+        return undefined;
+    const content = guardedRead(path, () => readFileSync(path, "utf8"), undetermined);
     return {
         path,
-        sizeBytes: statSync(path).size,
-        headings: extractHeadings(content),
+        sizeBytes,
+        headings: content === undefined ? [] : extractHeadings(content),
     };
 }
-function collectRootMarkdown(dir) {
-    const found = [];
+function collectRootMarkdown(dir, undetermined) {
+    const paths = [];
     for (const name of NAMED_ROOT_CANDIDATES) {
         const path = join(dir, name);
-        if (existsSync(path))
-            found.push(indexFile(path));
+        if (guardedExists(path, undetermined))
+            paths.push(path);
     }
-    for (const entry of walkBounded(dir, 0)) {
+    for (const entry of walkBounded(dir, 0, undetermined)) {
         if (!entry.isDirectory && /^STYLE.*\.md$/i.test(entry.relPath)) {
-            found.push(indexFile(entry.path));
+            paths.push(entry.path);
         }
     }
-    return found;
+    return indexAll(paths, undetermined);
 }
-function collectNamedDirectories(dir) {
-    const found = [];
+function collectNamedDirectories(dir, undetermined) {
+    const paths = [];
     for (const relDir of NAMED_DIR_CANDIDATES) {
         const absDir = join(dir, relDir);
-        if (!existsSync(absDir))
+        if (!guardedExists(absDir, undetermined))
             continue;
-        for (const entry of walkBounded(absDir, 2)) {
+        for (const entry of walkBounded(absDir, 2, undetermined)) {
             if (!entry.isDirectory && entry.relPath.endsWith(".md")) {
-                found.push(indexFile(entry.path));
+                paths.push(entry.path);
             }
         }
     }
+    return indexAll(paths, undetermined);
+}
+function indexAll(paths, undetermined) {
+    const found = [];
+    for (const path of paths) {
+        const file = indexFile(path, undetermined);
+        if (file !== undefined)
+            found.push(file);
+    }
     return found;
 }
-/** Indexes docs/guideline files at `dir`. Offline, read-only, index-only -- no full content. */
-export function surveyDocs(dir) {
+/**
+ * Indexes docs/guideline files at `dir`. Offline, read-only, index-only --
+ * no full content. A doc or doc directory that exists but cannot be read
+ * (`EACCES`/`EPERM`) is recorded in `undetermined` (an unreadable doc keeps
+ * its entry with empty `headings`); any other read failure throws, naming
+ * the path, with the original failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * import { surveyDocs } from "./survey-docs.js";
+ *
+ * const undetermined: string[] = [];
+ * const docs = surveyDocs("/path/to/project", undetermined);
+ * console.log(docs.files.map((file) => file.path), undetermined);
+ * ```
+ */
+export function surveyDocs(dir, undetermined) {
     return {
-        files: [...collectRootMarkdown(dir), ...collectNamedDirectories(dir)],
+        files: [
+            ...collectRootMarkdown(dir, undetermined),
+            ...collectNamedDirectories(dir, undetermined),
+        ],
     };
 }
 //# sourceMappingURL=survey-docs.js.map

package/dist/survey/survey-harness.d.ts

@@ -1,4 +1,22 @@
 import type { HarnessSurvey } from "./types.js";
-/** Surveys the `.claude/` harness and `CLAUDE.md` at `dir`. Offline, read-only. */
-export declare function surveyHarness(dir: string): HarnessSurvey;
+/**
+ * Surveys the `.claude/` harness and `CLAUDE.md` at `dir`. Offline,
+ * read-only. A file or directory that exists but cannot be read
+ * (`EACCES`/`EPERM`) is left out of its collection and recorded in
+ * `undetermined` -- an unreadable `CLAUDE.md` still counts as present, with
+ * no headings. A `.claude/` this process may not enter is still `present`,
+ * with every collection empty and the directory recorded in `undetermined`
+ * -- never reported as an empty harness. Any other read failure throws, naming the path, with the
+ * original failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * import { surveyHarness } from "./survey-harness.js";
+ *
+ * const undetermined: string[] = [];
+ * const harness = surveyHarness("/path/to/project", undetermined);
+ * console.log(harness.agents.map((agent) => agent.name), undetermined);
+ * ```
+ */
+export declare function surveyHarness(dir: string, undetermined: string[]): HarnessSurvey;
 //# sourceMappingURL=survey-harness.d.ts.map