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

package/dist/survey/survey-harness.js

@@ -1,12 +1,15 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Collects the whole `.claude/` surface of an existing project -- hook
  * wiring, agent/skill/rule frontmatter, commands, and `CLAUDE.md`'s heading
  * outline -- so `/customize`'s harness sweep starts from what is actually
  * there instead of assuming the m3l-groundwork baseline.
  */
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { fieldText, parseFrontmatter } from "../harness/frontmatter.js";
+import { guardedExists, guardedRead } from "./internal/read-guard.js";
 /**
  * Reads one frontmatter field as text (a list is joined with `, `), or
  * `undefined` when the file has no frontmatter, the field is absent, or its
@@ -21,33 +24,48 @@ function extractFrontmatterField(content, field) {
     const text = fieldText(parsed.fields, field);
     return text === undefined || text === "" ? undefined : text;
 }
-function listMarkdownFiles(dir) {
-    if (!existsSync(dir))
+/** Reads `path` as UTF-8 text, or `undefined` (recorded) when it is unreadable. */
+function readText(path, undetermined) {
+    return guardedRead(path, () => readFileSync(path, "utf8"), undetermined);
+}
+/** Lists `dir`'s entry names: `[]` when it is absent, or unreadable (recorded). */
+function listNames(dir, undetermined) {
+    if (!guardedExists(dir, undetermined))
         return [];
-    return readdirSync(dir).filter((name) => name.endsWith(".md"));
+    return guardedRead(dir, () => readdirSync(dir), undetermined) ?? [];
+}
+function listMarkdownFiles(dir, undetermined) {
+    return listNames(dir, undetermined).filter((name) => name.endsWith(".md"));
 }
-function surveyAgents(claudeDir) {
+function surveyAgents(claudeDir, undetermined) {
     const agentsDir = join(claudeDir, "agents");
-    return listMarkdownFiles(agentsDir).map((name) => {
-        const content = readFileSync(join(agentsDir, name), "utf8");
-        return {
+    const results = [];
+    for (const name of listMarkdownFiles(agentsDir, undetermined)) {
+        const content = readText(join(agentsDir, name), undetermined);
+        if (content === undefined)
+            continue;
+        results.push({
             name: name.replace(/\.md$/, ""),
             model: extractFrontmatterField(content, "model"),
-        };
-    });
+        });
+    }
+    return results;
 }
-function surveySkills(claudeDir) {
+function surveySkills(claudeDir, undetermined) {
     const skillsDir = join(claudeDir, "skills");
-    if (!existsSync(skillsDir))
+    if (!guardedExists(skillsDir, undetermined))
         return [];
+    const entries = guardedRead(skillsDir, () => readdirSync(skillsDir, { withFileTypes: true }), undetermined) ?? [];
     const results = [];
-    for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    for (const entry of entries) {
         if (!entry.isDirectory())
             continue;
         const skillFile = join(skillsDir, entry.name, "SKILL.md");
-        if (!existsSync(skillFile))
+        if (!guardedExists(skillFile, undetermined))
+            continue;
+        const content = readText(skillFile, undetermined);
+        if (content === undefined)
             continue;
-        const content = readFileSync(skillFile, "utf8");
         results.push({
             name: extractFrontmatterField(content, "name") ?? entry.name,
             description: extractFrontmatterField(content, "description"),
@@ -55,25 +73,25 @@ function surveySkills(claudeDir) {
     }
     return results;
 }
-function surveyHooks(claudeDir) {
-    const hooksDir = join(claudeDir, "hooks");
-    if (!existsSync(hooksDir))
-        return [];
-    return readdirSync(hooksDir).filter((name) => name.endsWith(".mjs") || name.endsWith(".js"));
+function surveyHooks(claudeDir, undetermined) {
+    return listNames(join(claudeDir, "hooks"), undetermined).filter((name) => name.endsWith(".mjs") || name.endsWith(".js"));
 }
-function surveyRules(claudeDir) {
+function surveyRules(claudeDir, undetermined) {
     const rulesDir = join(claudeDir, "rules");
-    return listMarkdownFiles(rulesDir).map((name) => {
-        const content = readFileSync(join(rulesDir, name), "utf8");
-        return {
+    const results = [];
+    for (const name of listMarkdownFiles(rulesDir, undetermined)) {
+        const content = readText(join(rulesDir, name), undetermined);
+        if (content === undefined)
+            continue;
+        results.push({
             name: name.replace(/\.md$/, ""),
             paths: extractFrontmatterField(content, "paths"),
-        };
-    });
+        });
+    }
+    return results;
 }
-function surveyCommands(claudeDir) {
-    const commandsDir = join(claudeDir, "commands");
-    return listMarkdownFiles(commandsDir);
+function surveyCommands(claudeDir, undetermined) {
+    return listMarkdownFiles(join(claudeDir, "commands"), undetermined);
 }
 function extractHeadings(content) {
     return content
@@ -81,12 +99,37 @@ function extractHeadings(content) {
         .filter((line) => /^#{1,3}\s/.test(line))
         .map((line) => line.replace(/^#{1,3}\s*/, "").trim());
 }
-/** Surveys the `.claude/` harness and `CLAUDE.md` at `dir`. Offline, read-only. */
-export function surveyHarness(dir) {
+/** `CLAUDE.md`'s heading outline: `[]` when it is absent, or unreadable (recorded). */
+function claudeMdHeadings(path, undetermined) {
+    if (!guardedExists(path, undetermined))
+        return [];
+    const content = readText(path, undetermined);
+    return content === undefined ? [] : extractHeadings(content);
+}
+/**
+ * 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 function surveyHarness(dir, undetermined) {
     const claudeDir = join(dir, ".claude");
     const claudeMdPath = join(dir, "CLAUDE.md");
-    const hasClaudeMd = existsSync(claudeMdPath);
-    if (!existsSync(claudeDir)) {
+    const hasClaudeMd = guardedExists(claudeMdPath, undetermined);
+    if (!guardedExists(claudeDir, undetermined)) {
         return {
             present: false,
             settingsFile: undefined,
@@ -97,25 +140,23 @@ export function surveyHarness(dir) {
             commands: [],
             hasSettingsLocal: false,
             hasClaudeMd,
-            claudeMdHeadings: hasClaudeMd
-                ? extractHeadings(readFileSync(claudeMdPath, "utf8"))
-                : [],
+            claudeMdHeadings: claudeMdHeadings(claudeMdPath, undetermined),
         };
     }
     const settingsPath = join(claudeDir, "settings.json");
     return {
         present: true,
-        settingsFile: existsSync(settingsPath) ? "settings.json" : undefined,
-        agents: surveyAgents(claudeDir),
-        skills: surveySkills(claudeDir),
-        hooks: surveyHooks(claudeDir),
-        rules: surveyRules(claudeDir),
-        commands: surveyCommands(claudeDir),
-        hasSettingsLocal: existsSync(join(claudeDir, "settings.local.json")),
+        settingsFile: guardedExists(settingsPath, undetermined)
+            ? "settings.json"
+            : undefined,
+        agents: surveyAgents(claudeDir, undetermined),
+        skills: surveySkills(claudeDir, undetermined),
+        hooks: surveyHooks(claudeDir, undetermined),
+        rules: surveyRules(claudeDir, undetermined),
+        commands: surveyCommands(claudeDir, undetermined),
+        hasSettingsLocal: guardedExists(join(claudeDir, "settings.local.json"), undetermined),
         hasClaudeMd,
-        claudeMdHeadings: hasClaudeMd
-            ? extractHeadings(readFileSync(claudeMdPath, "utf8"))
-            : [],
+        claudeMdHeadings: claudeMdHeadings(claudeMdPath, undetermined),
     };
 }
 //# sourceMappingURL=survey-harness.js.map

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

@@ -1,4 +1,19 @@
 import type { ShapeSurvey } from "./types.js";
-/** Surveys codebase shape at `dir`. Offline, read-only, records evidence rather than verdicts. */
-export declare function surveyShape(dir: string): ShapeSurvey;
+/**
+ * Surveys codebase shape at `dir`. Offline, read-only, records evidence
+ * rather than verdicts. Appends anything it could not parse (a malformed
+ * `package.json`) or could not read (`EACCES`/`EPERM`) to `undetermined`;
+ * an absent file is not recorded. Any other read failure throws, naming the
+ * path, with the original failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * import { surveyShape } from "./survey-shape.js";
+ *
+ * const undetermined: string[] = [];
+ * const shape = surveyShape("/path/to/project", undetermined);
+ * console.log(shape.packageManager, undetermined);
+ * ```
+ */
+export declare function surveyShape(dir: string, undetermined: string[]): ShapeSurvey;
 //# sourceMappingURL=survey-shape.d.ts.map

package/dist/survey/survey-shape.js

@@ -1,12 +1,16 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Collects codebase-shape facts: package manager, monorepo tooling, module
  * system, pinned versions, source/test layout, and the evidence (not the
  * verdict) for what kind of project this is. `/customize`'s interview step
  * does the inferring; this module only records what is literally on disk.
  */
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { walkBounded } from "./fs-walk.js";
+import { readPackageJson } from "./internal/package-json.js";
+import { guardedExists, guardedRead } from "./internal/read-guard.js";
 const FRAMEWORK_DEP_NAMES = [
     "react",
     "vue",
@@ -20,26 +24,14 @@ const FRAMEWORK_DEP_NAMES = [
     "@nestjs/core",
     "hono",
 ];
-function readPackageJson(dir) {
-    const path = join(dir, "package.json");
-    if (!existsSync(path)) {
-        return undefined;
-    }
-    try {
-        return JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch {
-        return undefined;
-    }
-}
-function detectPackageManager(dir) {
-    if (existsSync(join(dir, "pnpm-lock.yaml")))
+function detectPackageManager(dir, undetermined) {
+    if (guardedExists(join(dir, "pnpm-lock.yaml"), undetermined))
         return "pnpm";
-    if (existsSync(join(dir, "yarn.lock")))
+    if (guardedExists(join(dir, "yarn.lock"), undetermined))
         return "yarn";
-    if (existsSync(join(dir, "bun.lockb")))
+    if (guardedExists(join(dir, "bun.lockb"), undetermined))
         return "bun";
-    if (existsSync(join(dir, "package-lock.json")))
+    if (guardedExists(join(dir, "package-lock.json"), undetermined))
         return "npm";
     return "unknown";
 }
@@ -59,22 +51,24 @@ function extractYamlStringListUnder(content, key) {
     }
     return items;
 }
-function detectMonorepo(dir, packageJson) {
+function detectMonorepo(dir, packageJson, undetermined) {
     const pnpmWorkspacePath = join(dir, "pnpm-workspace.yaml");
-    if (existsSync(pnpmWorkspacePath)) {
-        const content = readFileSync(pnpmWorkspacePath, "utf8");
+    if (guardedExists(pnpmWorkspacePath, undetermined)) {
+        const content = guardedRead(pnpmWorkspacePath, () => readFileSync(pnpmWorkspacePath, "utf8"), undetermined);
         return {
             tool: "pnpm-workspaces",
-            globs: extractYamlStringListUnder(content, "packages"),
+            globs: content === undefined
+                ? []
+                : extractYamlStringListUnder(content, "packages"),
         };
     }
-    if (existsSync(join(dir, "turbo.json"))) {
+    if (guardedExists(join(dir, "turbo.json"), undetermined)) {
         return { tool: "turbo", globs: [] };
     }
-    if (existsSync(join(dir, "nx.json"))) {
+    if (guardedExists(join(dir, "nx.json"), undetermined)) {
         return { tool: "nx", globs: [] };
     }
-    if (existsSync(join(dir, "lerna.json"))) {
+    if (guardedExists(join(dir, "lerna.json"), undetermined)) {
         return { tool: "lerna", globs: [] };
     }
     const workspaces = packageJson?.["workspaces"];
@@ -106,15 +100,18 @@ function detectTypescriptVersion(packageJson) {
     const value = fromDevDeps ?? fromDeps;
     return typeof value === "string" ? value : undefined;
 }
-function detectNodeVersionPin(dir, packageJson) {
+function detectNodeVersionPin(dir, packageJson, undetermined) {
     for (const [source, filename] of [
         [".node-version", ".node-version"],
         [".nvmrc", ".nvmrc"],
     ]) {
         const path = join(dir, filename);
-        if (existsSync(path)) {
-            return { source, value: readFileSync(path, "utf8").trim() };
-        }
+        if (!guardedExists(path, undetermined))
+            continue;
+        // An unreadable pin file falls through to the next source.
+        const content = guardedRead(path, () => readFileSync(path, "utf8"), undetermined);
+        if (content !== undefined)
+            return { source, value: content.trim() };
     }
     const engines = packageJson?.["engines"];
     const nodeEngine = typeof engines === "object" && engines !== null
@@ -125,24 +122,26 @@ function detectNodeVersionPin(dir, packageJson) {
     }
     return undefined;
 }
-function detectSourceLayout(dir) {
-    if (existsSync(join(dir, "src")))
+function detectSourceLayout(dir, undetermined) {
+    if (guardedExists(join(dir, "src"), undetermined))
         return "src";
-    if (existsSync(join(dir, "lib")))
+    if (guardedExists(join(dir, "lib"), undetermined))
         return "lib";
-    const rootEntries = readdirSync(dir).filter((name) => /\.(ts|tsx|js|mjs)$/.test(name));
+    const names = guardedRead(dir, () => readdirSync(dir), undetermined) ?? [];
+    const rootEntries = names.filter((name) => /\.(ts|tsx|js|mjs)$/.test(name));
     if (rootEntries.length > 0)
         return "root";
     return "unknown";
 }
-function hasColocatedTests(dir) {
-    return walkBounded(dir, 2).some((entry) => !entry.isDirectory && /\.(test|spec)\.[jt]sx?$/.test(entry.relPath));
+function hasColocatedTests(dir, undetermined) {
+    return walkBounded(dir, 2, undetermined).some((entry) => !entry.isDirectory && /\.(test|spec)\.[jt]sx?$/.test(entry.relPath));
 }
-function detectTestPlacement(dir) {
-    if (existsSync(join(dir, "tests")) || existsSync(join(dir, "test"))) {
+function detectTestPlacement(dir, undetermined) {
+    if (guardedExists(join(dir, "tests"), undetermined) ||
+        guardedExists(join(dir, "test"), undetermined)) {
         return "tests-dir";
     }
-    if (hasColocatedTests(dir)) {
+    if (hasColocatedTests(dir, undetermined)) {
         return "colocated";
     }
     return "unknown";
@@ -163,19 +162,34 @@ function collectKindEvidence(packageJson) {
         frameworkDeps: FRAMEWORK_DEP_NAMES.filter((name) => allDepNames.has(name)),
     };
 }
-/** Surveys codebase shape at `dir`. Offline, read-only, records evidence rather than verdicts. */
-export function surveyShape(dir) {
-    const packageJson = readPackageJson(dir);
-    const monorepo = detectMonorepo(dir, packageJson);
+/**
+ * Surveys codebase shape at `dir`. Offline, read-only, records evidence
+ * rather than verdicts. Appends anything it could not parse (a malformed
+ * `package.json`) or could not read (`EACCES`/`EPERM`) to `undetermined`;
+ * an absent file is not recorded. Any other read failure throws, naming the
+ * path, with the original failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * import { surveyShape } from "./survey-shape.js";
+ *
+ * const undetermined: string[] = [];
+ * const shape = surveyShape("/path/to/project", undetermined);
+ * console.log(shape.packageManager, undetermined);
+ * ```
+ */
+export function surveyShape(dir, undetermined) {
+    const packageJson = readPackageJson(dir, undetermined);
+    const monorepo = detectMonorepo(dir, packageJson, undetermined);
     return {
-        packageManager: detectPackageManager(dir),
+        packageManager: detectPackageManager(dir, undetermined),
         monorepoTool: monorepo.tool,
         workspaceGlobs: monorepo.globs,
         moduleType: detectModuleType(packageJson),
         typescriptVersion: detectTypescriptVersion(packageJson),
-        nodeVersionPin: detectNodeVersionPin(dir, packageJson),
-        sourceLayout: detectSourceLayout(dir),
-        testPlacement: detectTestPlacement(dir),
+        nodeVersionPin: detectNodeVersionPin(dir, packageJson, undetermined),
+        sourceLayout: detectSourceLayout(dir, undetermined),
+        testPlacement: detectTestPlacement(dir, undetermined),
         kindEvidence: collectKindEvidence(packageJson),
     };
 }

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

@@ -1,4 +1,19 @@
 import type { ToolchainSurvey } from "./types.js";
-/** Surveys toolchain enforcement at `dir`. Appends anything it could not parse to `undetermined`. */
+/**
+ * Surveys toolchain enforcement at `dir`. Appends anything it could not
+ * parse, or could not read (`EACCES`/`EPERM`, a dangling symlink, a symlink
+ * loop, a directory where a file was expected), to `undetermined`; any other
+ * read failure throws, naming the path, with the original failure as
+ * `cause`.
+ *
+ * @example
+ * ```ts
+ * import { surveyToolchain } from "./survey-toolchain.js";
+ *
+ * const undetermined: string[] = [];
+ * const toolchain = surveyToolchain("/path/to/project", undetermined);
+ * console.log(toolchain.tsconfig.effectiveFlags, undetermined);
+ * ```
+ */
 export declare function surveyToolchain(dir: string, undetermined: string[]): ToolchainSurvey;
 //# sourceMappingURL=survey-toolchain.d.ts.map

package/dist/survey/survey-toolchain.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Collects toolchain-enforcement facts: the tsconfig `extends` chain and its
  * effective strict-family flags, which eslint/test/formatter/git-hook tool
@@ -6,28 +8,19 @@
  * here, never parsed -- see `needsReading` on each -- because this package
  * carries no YAML dependency.
  */
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { STRICT_FLAGS } from "../toolchain/rules.js";
 import { loadTsconfigChain } from "../toolchain/tsconfig-chain.js";
+import { readPackageJson } from "./internal/package-json.js";
+import { guardedExists, guardedRead } from "./internal/read-guard.js";
 /** Every flag the toolchain grader judges, so `effectiveFlags` and the grade cannot disagree. */
 const STRICT_FLAG_NAMES = [...STRICT_FLAGS, "allowUnreachableCode"];
 const ESLINT_PLUGIN_PATTERN = /["']((?:eslint-plugin-|@typescript-eslint\/)[a-z0-9-]+)["']/gi;
-function readPackageJson(dir) {
-    const path = join(dir, "package.json");
-    if (!existsSync(path))
-        return undefined;
-    try {
-        return JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch {
-        return undefined;
-    }
-}
-function findTsconfigPath(dir) {
+function findTsconfigPath(dir, undetermined) {
     for (const name of ["tsconfig.json"]) {
         const path = join(dir, name);
-        if (existsSync(path))
+        if (guardedExists(path, undetermined))
             return path;
     }
     return undefined;
@@ -37,11 +30,12 @@ function findTsconfigPath(dir) {
  * shares, so the survey and the grade cannot disagree about a project's
  * effective flags. `files` are absolute and child-first. A file that fails to
  * parse, or a relative `extends` that points at nothing, is a parse failure; a
- * bare package specifier that is not installed is only a note -- the flags it
+ * file in the chain that exists but cannot be read is noted "could not read",
+ * never "could not parse"; a bare package specifier that is not installed is only a note -- the flags it
  * would contribute are simply absent.
  */
 function surveyTsconfig(dir, undetermined) {
-    const entryPath = findTsconfigPath(dir);
+    const entryPath = findTsconfigPath(dir, undetermined);
     if (entryPath === undefined) {
         return { files: [], effectiveFlags: {}, parsed: false };
     }
@@ -49,7 +43,8 @@ function surveyTsconfig(dir, undetermined) {
     let parsed = chain.parsed;
     for (const file of chain.files) {
         if (file.error !== undefined) {
-            undetermined.push(`could not parse ${file.abs}: ${file.error}`);
+            const verb = file.readFailed ? "could not read" : "could not parse";
+            undetermined.push(`${verb} ${file.abs}: ${file.error}`);
         }
     }
     for (const link of chain.links) {
@@ -71,39 +66,30 @@ function surveyTsconfig(dir, undetermined) {
     }
     return { files: chain.files.map((file) => file.abs), effectiveFlags, parsed };
 }
-function surveyEslint(dir) {
-    const flatCandidates = [
-        "eslint.config.js",
-        "eslint.config.mjs",
-        "eslint.config.ts",
-    ];
-    const legacyCandidates = [
-        ".eslintrc.js",
-        ".eslintrc.cjs",
-        ".eslintrc.json",
-        ".eslintrc",
-    ];
-    for (const name of flatCandidates) {
-        const path = join(dir, name);
-        if (existsSync(path)) {
-            const content = readFileSync(path, "utf8");
-            return {
-                configFile: name,
-                flat: true,
-                referencedPlugins: extractPluginNames(content),
-            };
-        }
-    }
-    for (const name of legacyCandidates) {
+const ESLINT_CANDIDATES = [
+    ["eslint.config.js", true],
+    ["eslint.config.mjs", true],
+    ["eslint.config.ts", true],
+    [".eslintrc.js", false],
+    [".eslintrc.cjs", false],
+    [".eslintrc.json", false],
+    [".eslintrc", false],
+];
+/**
+ * The first ESLint config present, flat configs first. An unreadable config
+ * is still reported (its presence is known) with no plugins, and recorded.
+ */
+function surveyEslint(dir, undetermined) {
+    for (const [name, flat] of ESLINT_CANDIDATES) {
         const path = join(dir, name);
-        if (existsSync(path)) {
-            const content = readFileSync(path, "utf8");
-            return {
-                configFile: name,
-                flat: false,
-                referencedPlugins: extractPluginNames(content),
-            };
-        }
+        if (!guardedExists(path, undetermined))
+            continue;
+        const content = guardedRead(path, () => readFileSync(path, "utf8"), undetermined);
+        return {
+            configFile: name,
+            flat,
+            referencedPlugins: content === undefined ? [] : extractPluginNames(content),
+        };
     }
     return { configFile: undefined, flat: false, referencedPlugins: [] };
 }
@@ -116,7 +102,7 @@ function extractPluginNames(content) {
     }
     return [...names];
 }
-function surveyTestRunner(dir, scripts) {
+function surveyTestRunner(dir, scripts, undetermined) {
     const candidates = [
         ["vitest.config.ts", "vitest"],
         ["vitest.config.js", "vitest"],
@@ -128,7 +114,7 @@ function surveyTestRunner(dir, scripts) {
         [".mocharc.js", "mocha"],
     ];
     for (const [name, tool] of candidates) {
-        if (existsSync(join(dir, name))) {
+        if (guardedExists(join(dir, name), undetermined)) {
             return { tool, configFile: name };
         }
     }
@@ -138,7 +124,7 @@ function surveyTestRunner(dir, scripts) {
     }
     return { tool: "unknown", configFile: undefined };
 }
-function surveyFormatter(dir) {
+function surveyFormatter(dir, undetermined) {
     const prettierCandidates = [
         ".prettierrc.json",
         ".prettierrc.js",
@@ -147,29 +133,29 @@ function surveyFormatter(dir) {
         ".prettierrc.yml",
     ];
     for (const name of prettierCandidates) {
-        if (existsSync(join(dir, name))) {
+        if (guardedExists(join(dir, name), undetermined)) {
             return { tool: "prettier", configFile: name };
         }
     }
-    if (existsSync(join(dir, "biome.json"))) {
+    if (guardedExists(join(dir, "biome.json"), undetermined)) {
         return { tool: "biome", configFile: "biome.json" };
     }
     return { tool: "unknown", configFile: undefined };
 }
 function surveyGitHooks(dir, undetermined) {
-    if (existsSync(join(dir, "lefthook.yml")) ||
-        existsSync(join(dir, "lefthook.yaml"))) {
-        const configFile = existsSync(join(dir, "lefthook.yml"))
+    if (guardedExists(join(dir, "lefthook.yml"), undetermined) ||
+        guardedExists(join(dir, "lefthook.yaml"), undetermined)) {
+        const configFile = guardedExists(join(dir, "lefthook.yml"), undetermined)
             ? "lefthook.yml"
             : "lefthook.yaml";
         undetermined.push(`${configFile} found -- its stage commands need reading, not parsing`);
         return { manager: "lefthook", configFile, needsReading: true };
     }
-    if (existsSync(join(dir, ".husky"))) {
+    if (guardedExists(join(dir, ".husky"), undetermined)) {
         undetermined.push(".husky/ found -- its hook scripts need reading, not parsing");
         return { manager: "husky", configFile: ".husky", needsReading: true };
     }
-    if (existsSync(join(dir, "simple-git-hooks.json"))) {
+    if (guardedExists(join(dir, "simple-git-hooks.json"), undetermined)) {
         return {
             manager: "simple-git-hooks",
             configFile: "simple-git-hooks.json",
@@ -180,10 +166,12 @@ function surveyGitHooks(dir, undetermined) {
 }
 function surveyWorkflows(dir, undetermined) {
     const workflowsDir = join(dir, ".github", "workflows");
-    if (!existsSync(workflowsDir)) {
+    if (!guardedExists(workflowsDir, undetermined)) {
         return { files: [], needsReading: false };
     }
-    const files = readdirSync(workflowsDir).filter((name) => /\.ya?ml$/.test(name));
+    const names = guardedRead(workflowsDir, () => readdirSync(workflowsDir), undetermined) ??
+        [];
+    const files = names.filter((name) => /\.ya?ml$/.test(name));
     if (files.length > 0) {
         undetermined.push(`${files.length} workflow file(s) under .github/workflows -- their job steps need reading, not parsing`);
     }
@@ -200,15 +188,30 @@ function surveyScripts(packageJson) {
     }
     return result;
 }
-/** Surveys toolchain enforcement at `dir`. Appends anything it could not parse to `undetermined`. */
+/**
+ * Surveys toolchain enforcement at `dir`. Appends anything it could not
+ * parse, or could not read (`EACCES`/`EPERM`, a dangling symlink, a symlink
+ * loop, a directory where a file was expected), to `undetermined`; any other
+ * read failure throws, naming the path, with the original failure as
+ * `cause`.
+ *
+ * @example
+ * ```ts
+ * import { surveyToolchain } from "./survey-toolchain.js";
+ *
+ * const undetermined: string[] = [];
+ * const toolchain = surveyToolchain("/path/to/project", undetermined);
+ * console.log(toolchain.tsconfig.effectiveFlags, undetermined);
+ * ```
+ */
 export function surveyToolchain(dir, undetermined) {
-    const packageJson = readPackageJson(dir);
+    const packageJson = readPackageJson(dir, undetermined);
     const scripts = surveyScripts(packageJson);
     return {
         tsconfig: surveyTsconfig(dir, undetermined),
-        eslint: surveyEslint(dir),
-        testRunner: surveyTestRunner(dir, scripts),
-        formatter: surveyFormatter(dir),
+        eslint: surveyEslint(dir, undetermined),
+        testRunner: surveyTestRunner(dir, scripts, undetermined),
+        formatter: surveyFormatter(dir, undetermined),
         gitHooks: surveyGitHooks(dir, undetermined),
         workflows: surveyWorkflows(dir, undetermined),
         scripts,