@descent-vtt/spec-harness 0.19.0 → 0.21.0

package/dist/fs.d.ts

@@ -2,18 +2,41 @@
  * The edge where the harness meets the disk: the configuration, the state
  * directory outside the work tree, and paths as the filesystem spells them.
  */
+import type { BriefInputs } from './briefs.js';
 import { type HarnessConfig } from './config.js';
+/**
+ * Whether a regular file stands at a path, links followed. Only one is read
+ * where a file is expected: opened, a named pipe nothing writes to is read
+ * without end, and one read as the process waits on it, as the harness reads
+ * a few small files, stops every timer with it (ADR-0002).
+ */
+export declare function isFile(path: string): boolean;
 /**
  * Reads `.spec-harness.json` at the root, or the defaults when there is none.
  *
  * Only a file is read. A named pipe under the file's name was read without
  * end, by every command and by the hook before every write; and Node's words
- * for a directory, EISDIR, are not the harness's.
+ * for a directory, EISDIR, are not the harness's. A file that cannot be read
+ * is said as that, with the reason: one the account may not read, or one
+ * another process holds open on Windows, was said to be JSON that is not
+ * valid, which sent a person to its text. What does not load is thrown with
+ * the path it stands at, which the hook lets a write reach (ADR-0005).
  */
 export declare function loadConfig(root: string): Promise<{
     config: HarnessConfig;
     file: string | null;
 }>;
+/**
+ * Whether every path of a write names `file` and nothing else: a file that
+ * stands under that name alone, which the path names as the hook resolves a
+ * path to decide it ({@link realSpelling}), and as the filesystem resolves
+ * it to write, which on Linux and macOS follows a link before a `..` where
+ * the hook reads the `..` first. A path that only reads like it, a link to
+ * it, a second name of it, and a file of another work tree are none of
+ * these. `cwd` is what a relative path is read from, its words kept as
+ * written.
+ */
+export declare function writesOnly(paths: readonly string[], file: string, cwd: string): boolean;
 /**
  * A path where the harness keeps its state that holds something else: said
  * in a line, exit 2, where Node's ENOTDIR and a stack sent a person looking
@@ -31,6 +54,31 @@ export declare class StateError extends Error {
  * `src/db/schema.ts` on Windows or macOS, where both name one file.
  */
 export declare function realSpelling(path: string): string;
+/**
+ * The real spelling of the file a write of `given` reaches, read from `cwd`
+ * where it is relative; `null` where it reaches none, through more links
+ * than the system follows or a loop of them. Linux reads a `..` after the
+ * link before it, and macOS is read so, so `deep/../schema.ts`, `deep` a
+ * link to `lib/x`, is written as `lib/schema.ts` (measured on Linux), where
+ * {@link realSpelling} reads the `..` first and names `schema.ts`; Windows
+ * reads the `..` first, as resolve does (measured, through a junction). And
+ * a link to nothing is followed, since a write opens the file it names and
+ * makes it there (measured on Linux and on GitHub's Windows runner), where
+ * `realSpelling` names the link.
+ * The names are walked one by one from the root, each link replaced by what
+ * it names, so the directory reached holds no link, and `join` reads a `.`,
+ * a `..` and an empty name from it as the system does; what is not there
+ * yet is made as written.
+ */
+export declare function writtenSpelling(given: string, cwd: string): string | null;
+/**
+ * Every file a write of `given` may reach, each by its real spelling: the
+ * one the path reads as ({@link realSpelling}), and the one the system
+ * writes ({@link writtenSpelling}) where that is another. The hook does not
+ * know which of the two a tool writes, so it decides both (ADR-0005). A
+ * path that reaches no file is read as it reads.
+ */
+export declare function reachedBy(given: string, cwd: string): string[];
 /**
  * Whether `directory` is the one git names as the top of a work tree: the
  * two spelled alike once the filesystem has spelled the directory, links
@@ -55,6 +103,26 @@ export declare function holdsGit(directory: string): boolean;
  * real spelling - or `null` when it lies outside the root.
  */
 export declare function repositoryPath(given: string, root: string, cwd: string): string | null;
+/**
+ * The top of every work tree of the repository whose common directory is
+ * `common`, `top` among them, read with no process: the main work tree,
+ * whose `.git` the common directory is, and each linked worktree, by the
+ * `gitdir` file git keeps for it under the common directory's `worktrees`,
+ * which names the worktree's `.git` (gitrepository-layout(5)), absolute or
+ * from its own directory. `null` where they cannot all be named: a common
+ * directory of any other name, whose main work tree only its configuration
+ * names, and an entry under `worktrees` that cannot be read.
+ */
+export declare function workTrees(top: string, common: string): string[] | null;
+/**
+ * Whether every path lies outside every work tree of the repository whose
+ * top and common directory are given, as it reads and as the system writes
+ * it ({@link reachedBy}): such a path is no file of the repository's, so no
+ * brief of its decides it, whatever is wrong with the brief or the
+ * configuration (ADR-0005). Where the work trees cannot all be named, a
+ * path is not known to be outside them, and this is `false`.
+ */
+export declare function outsideEvery(paths: readonly string[], top: string, common: string, cwd: string): boolean;
 /**
  * The harness's own directory under the git common directory, created on
  * demand (ADR-0003). Where something that is no directory stands at its path,
@@ -78,6 +146,7 @@ export declare function stateDirectory(commonDir: string, ...parts: string[]): P
  */
 export declare function gitDirectories(root: string, env: Readonly<Record<string, string | undefined>>): {
     readonly top: string;
+    readonly git: string;
     readonly common: string;
     readonly exact: boolean;
 } | null;
@@ -98,6 +167,39 @@ export declare const CALL_LIFE_MS: number;
 export declare function keepCall(commonDir: string, name: string, text: string, now?: number): Promise<void>;
 /** What was kept for a call, taken away as it is read; `null` where nothing was. */
 export declare function takeCall(commonDir: string, name: string): Promise<string | null>;
+/** SHA-256 of a text or of bytes, in hex. */
+export type Hash = (data: string | Uint8Array) => string;
+/** SHA-256, loaded where something is hashed: a run that keeps no answer loads no hash (ADR-0002). */
+export declare function hasher(): Promise<Hash>;
+/**
+ * How long a session's answer of spec-brief's is kept once it was last
+ * kept (ADR-0003). A day, as a call's: an answer removed costs one start of
+ * spec-brief, and one kept is a few kilobytes.
+ */
+export declare const ANSWER_LIFE_MS: number;
+/**
+ * Keeps a session's answer of spec-brief's under the common directory, with
+ * the key it answers, and removes what was kept over a day ago. Whatever
+ * fails is passed over: the answer is the one given whether or not it is
+ * kept.
+ */
+export declare function keepAnswer(commonDir: string, name: string, key: string, answer: string, now?: number): Promise<void>;
+/**
+ * The answer kept under `name` for `key`, or `null` where there is none:
+ * nothing there, something that is not a file, a text that is not what
+ * `keepAnswer` writes, or another key's.
+ */
+export declare function keptAnswer(commonDir: string, name: string, key: string): Promise<string | null>;
+/**
+ * Whether every input of an answer reads as listed, with no process
+ * started: each file by the digest of its bytes, or as not there; each
+ * directory by its entries; and, where git was asked, the index of the work
+ * tree's git directory and each ignore file. A path is read from the work
+ * tree's top, or as it stands where it is absolute. Anything that cannot be
+ * read, and an index that is not the one git reads for the work tree, is a
+ * doubt, and answers `false` (ADR-0002).
+ */
+export declare function readsAsListed(root: string, inputs: BriefInputs, hash: Hash, env?: Readonly<Record<string, string | undefined>>): Promise<boolean>;
 /** Writes a file whole or not at all: a temporary file renamed over the target. */
 export declare function writeAtomic(file: string, content: string): Promise<void>;
 /**
@@ -110,4 +212,5 @@ export declare function writeAtomic(file: string, content: string): Promise<void
 export declare function readJsonObject(file: string): Promise<Record<string, unknown> | null | 'unreadable'>;
 /** Whether a path names a directory that is there; one that cannot be read names none. */
 export declare function isDirectory(path: string): boolean;
+/** A file's text, or `null` where it cannot be read or is no file: a brief, a document one cites, a shim. */
 export declare function readText(file: string): Promise<string | null>;

package/dist/fs.js

@@ -2,9 +2,9 @@
  * The edge where the harness meets the disk: the configuration, the state
  * directory outside the work tree, and paths as the filesystem spells them.
  */
-import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
-import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, statSync } from 'node:fs';
+import { lstat, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
 import { ConfigError, CONFIG_FILE, DEFAULT_CONFIG, parseConfig } from './config.js';
 /** What stands at a path, links followed, or `null` where nothing does: a link to nothing is nothing. */
 function standing(path) {
@@ -15,12 +15,25 @@ function standing(path) {
         return null;
     }
 }
+/**
+ * Whether a regular file stands at a path, links followed. Only one is read
+ * where a file is expected: opened, a named pipe nothing writes to is read
+ * without end, and one read as the process waits on it, as the harness reads
+ * a few small files, stops every timer with it (ADR-0002).
+ */
+export function isFile(path) {
+    return standing(path)?.isFile() === true;
+}
 /**
  * Reads `.spec-harness.json` at the root, or the defaults when there is none.
  *
  * Only a file is read. A named pipe under the file's name was read without
  * end, by every command and by the hook before every write; and Node's words
- * for a directory, EISDIR, are not the harness's.
+ * for a directory, EISDIR, are not the harness's. A file that cannot be read
+ * is said as that, with the reason: one the account may not read, or one
+ * another process holds open on Windows, was said to be JSON that is not
+ * valid, which sent a person to its text. What does not load is thrown with
+ * the path it stands at, which the hook lets a write reach (ADR-0005).
  */
 export async function loadConfig(root) {
     const file = join(root, CONFIG_FILE);
@@ -28,16 +41,65 @@ export async function loadConfig(root) {
     if (there === null)
         return { config: DEFAULT_CONFIG, file: null };
     if (!there.isFile())
-        throw new ConfigError(`${CONFIG_FILE} is ${there.isDirectory() ? 'a directory' : 'neither a file nor a directory'}, not a configuration file`);
-    let raw;
+        throw new ConfigError(`${CONFIG_FILE} is ${there.isDirectory() ? 'a directory' : 'neither a file nor a directory'}, not a configuration file`, file);
+    let text;
     try {
         // A Buffer parses as its text, so the encoding is equivalent to its mutant.
-        raw = JSON.parse(await readFile(file, 'utf8'));
+        text = await readFile(file, 'utf8');
     }
     catch (error) {
-        throw new ConfigError(`${CONFIG_FILE} is not valid JSON: ${error.message}`);
+        throw new ConfigError(`${CONFIG_FILE} cannot be read: ${error.message}`, file);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ConfigError(`${CONFIG_FILE} is not valid JSON: ${error.message}`, file);
+    }
+    try {
+        return { config: parseConfig(raw), file };
+    }
+    catch (error) {
+        // parseConfig throws nothing but its own refusal, whose words are kept.
+        throw new ConfigError(error.message, file);
     }
-    return { config: parseConfig(raw), file };
+}
+/**
+ * The real path of a file that stands at `path` under that name alone: a
+ * file, not a link to one, and with no other name, since a write to a file
+ * with two names writes both. `null` for anything else, and for nothing.
+ */
+function soleFile(path) {
+    try {
+        const entry = lstatSync(path);
+        return entry.isFile() && entry.nlink === 1 ? realpathSync.native(path) : null;
+    }
+    catch {
+        // Nothing at the path, or nothing the account may look at. Its callers
+        // compare the answer with a real path, which neither `null` nor what an
+        // empty block answers is, so that mutant is equivalent.
+        return null;
+    }
+}
+/**
+ * Whether every path of a write names `file` and nothing else: a file that
+ * stands under that name alone, which the path names as the hook resolves a
+ * path to decide it ({@link realSpelling}), and as the filesystem resolves
+ * it to write, which on Linux and macOS follows a link before a `..` where
+ * the hook reads the `..` first. A path that only reads like it, a link to
+ * it, a second name of it, and a file of another work tree are none of
+ * these. `cwd` is what a relative path is read from, its words kept as
+ * written.
+ */
+export function writesOnly(paths, file, cwd) {
+    // Where the file is none, no path's real spelling is `null`, so no path
+    // names it.
+    const own = soleFile(file);
+    return paths.every((given) => {
+        const path = isAbsolute(given) ? given : `${cwd}${sep}${given}`;
+        return soleFile(path) === own && realSpelling(path) === own;
+    });
 }
 /**
  * A path where the harness keeps its state that holds something else: said
@@ -78,6 +140,94 @@ export function realSpelling(path) {
         }
     }
 }
+/**
+ * The most links the written reading of a path follows. Linux follows at
+ * most 40 in resolving a pathname, and fails the call with ELOOP past them
+ * (path_resolution(7)), so no write reaches a file through more.
+ */
+const MOST_LINKS = 40;
+/**
+ * A path's names, separated as the system separates them: Windows takes `/`
+ * as well as `\`, where Linux and macOS take a `\` for a character of a name.
+ * The sweep runs on Linux, where the mutants that read the pattern there, or
+ * change it, are equivalent; the suite's Windows leg holds them.
+ */
+function namesOf(path) {
+    return path.split(sep === '/' ? '/' : /[\\/]/);
+}
+/**
+ * The real spelling of the file a write of `given` reaches, read from `cwd`
+ * where it is relative; `null` where it reaches none, through more links
+ * than the system follows or a loop of them. Linux reads a `..` after the
+ * link before it, and macOS is read so, so `deep/../schema.ts`, `deep` a
+ * link to `lib/x`, is written as `lib/schema.ts` (measured on Linux), where
+ * {@link realSpelling} reads the `..` first and names `schema.ts`; Windows
+ * reads the `..` first, as resolve does (measured, through a junction). And
+ * a link to nothing is followed, since a write opens the file it names and
+ * makes it there (measured on Linux and on GitHub's Windows runner), where
+ * `realSpelling` names the link.
+ * The names are walked one by one from the root, each link replaced by what
+ * it names, so the directory reached holds no link, and `join` reads a `.`,
+ * a `..` and an empty name from it as the system does; what is not there
+ * yet is made as written.
+ */
+export function writtenSpelling(given, cwd) {
+    // On Linux, where the sweep runs, the mutant that reads every path as
+    // Windows does is caught, and the one that reads every path as Linux does
+    // is equivalent; the suite's Windows leg holds it. The root is taken off
+    // the names as it is off a link's, below.
+    const absolute = sep === '/' ? (isAbsolute(given) ? given : `${cwd}/${given}`) : resolve(cwd, given);
+    const root = parse(absolute).root;
+    const names = namesOf(absolute.slice(root.length));
+    let at = root;
+    let links = 0;
+    while (names.length > 0) {
+        const next = join(at, names.shift());
+        let target;
+        try {
+            if (!lstatSync(next).isSymbolicLink()) {
+                at = next;
+                continue;
+            }
+            target = readlinkSync(next);
+        }
+        catch {
+            // Nothing there, or nothing the account may look into: a write makes
+            // what is not there as written, and reaches nothing past a directory
+            // it may not look into.
+            at = join(next, ...names);
+            break;
+        }
+        links += 1;
+        if (links > MOST_LINKS)
+            return null;
+        // A link names a path from the directory it stands in, or from a root,
+        // which is taken off its names: on Linux and macOS the root is `/`,
+        // whose name is empty and read as none, so keeping it there is
+        // equivalent; on Windows it is the drive (a test holds it there).
+        const top = parse(target).root;
+        if (top !== '')
+            at = top;
+        names.unshift(...namesOf(target.slice(top.length)));
+    }
+    // The walk spells what exists as given, links followed; where case is
+    // ignored, the entries' case is the real one. On Linux, where the sweep
+    // runs, the two are one, so the mutant that leaves this out is equivalent
+    // there (a test holds it on Windows and macOS).
+    return realSpelling(at);
+}
+/**
+ * Every file a write of `given` may reach, each by its real spelling: the
+ * one the path reads as ({@link realSpelling}), and the one the system
+ * writes ({@link writtenSpelling}) where that is another. The hook does not
+ * know which of the two a tool writes, so it decides both (ADR-0005). A
+ * path that reaches no file is read as it reads.
+ */
+export function reachedBy(given, cwd) {
+    const read = realSpelling(resolve(cwd, given));
+    const written = writtenSpelling(given, cwd);
+    return written === null || written === read ? [read] : [read, written];
+}
 /**
  * Whether `directory` is the one git names as the top of a work tree: the
  * two spelled alike once the filesystem has spelled the directory, links
@@ -117,6 +267,69 @@ export function repositoryPath(given, root, cwd) {
         return null;
     return rel.split(sep).join('/');
 }
+/**
+ * The top of every work tree of the repository whose common directory is
+ * `common`, `top` among them, read with no process: the main work tree,
+ * whose `.git` the common directory is, and each linked worktree, by the
+ * `gitdir` file git keeps for it under the common directory's `worktrees`,
+ * which names the worktree's `.git` (gitrepository-layout(5)), absolute or
+ * from its own directory. `null` where they cannot all be named: a common
+ * directory of any other name, whose main work tree only its configuration
+ * names, and an entry under `worktrees` that cannot be read.
+ */
+export function workTrees(top, common) {
+    const main = mainWorkTree(common);
+    if (main === null)
+        return null;
+    const kept = join(common, 'worktrees');
+    let names = [];
+    try {
+        names = readdirSync(kept);
+    }
+    catch (error) {
+        // No such directory is no linked worktree, and anything else there is
+        // one that cannot be read.
+        if (error.code !== 'ENOENT')
+            return null;
+    }
+    const linked = names.map((name) => textOf(join(kept, name, 'gitdir')));
+    if (linked.includes(null))
+        return null;
+    // The line's end stands in the last name, the worktree's `.git`, which
+    // dirname takes away with it.
+    return [top, main, ...names.map((name, at) => dirname(resolve(kept, name, linked[at])))];
+}
+/**
+ * Whether every path lies outside every work tree of the repository whose
+ * top and common directory are given, as it reads and as the system writes
+ * it ({@link reachedBy}): such a path is no file of the repository's, so no
+ * brief of its decides it, whatever is wrong with the brief or the
+ * configuration (ADR-0005). Where the work trees cannot all be named, a
+ * path is not known to be outside them, and this is `false`.
+ */
+export function outsideEvery(paths, top, common, cwd) {
+    // A write that names no path is no write outside: no caller asks of
+    // one, and a test holds the answer.
+    if (paths.length === 0)
+        return false;
+    // A path in the work tree that was opened, as nearly every write's is,
+    // is told with nothing of git's directory read; read anyway, `top` is
+    // among the work trees, so the mutant without this test is equivalent.
+    if (paths.some((path) => repositoryPath(path, top, cwd) !== null))
+        return false;
+    // A path with a `..` in it was held here when the hook read a path one
+    // way, its `..` before its links: `/elsewhere/link/../a.ts`, the link to
+    // a directory of the work tree, read as outside and was written inside.
+    // Both readings are read below, and such a path is held as it was all
+    // the same (ADR-0005).
+    if (paths.some((path) => path.split(/[\\/]/).includes('..')))
+        return false;
+    // As a path reads and as the system writes it, a link to nothing among
+    // its links: the file it reaches is outside too, or the path is not.
+    const reached = paths.flatMap((path) => reachedBy(path, cwd));
+    const trees = workTrees(top, common);
+    return trees !== null && reached.every((path) => trees.every((tree) => repositoryPath(path, tree, cwd) === null));
+}
 /**
  * The harness's own directory under the git common directory, created on
  * demand (ADR-0003). Where something that is no directory stands at its path,
@@ -183,10 +396,12 @@ export function gitDirectories(root, env) {
     // No configuration holds no key, as a text without one does: the mutant
     // of the empty text is equivalent.
     const elsewhere = /^\s*worktree\s*=/im.test(textOf(join(common, 'config')) ?? '') || existsSync(join(gitDir, 'config.worktree'));
-    return { top, common, exact: !moved && !elsewhere };
+    return { top, git: gitDir, common, exact: !moved && !elsewhere };
 }
-/** A file's text, or `null` where it cannot be read. */
+/** A file's text, or `null` where it cannot be read or is no file. */
 function textOf(file) {
+    if (!isFile(file))
+        return null;
     try {
         return readFileSync(file, 'utf8');
     }
@@ -229,6 +444,9 @@ export async function keepCall(commonDir, name, text, now = Date.now()) {
 /** What was kept for a call, taken away as it is read; `null` where nothing was. */
 export async function takeCall(commonDir, name) {
     const file = join(commonDir, 'spec-harness', 'calls', name);
+    // What is no file holds nothing kept, and is written over at the next write.
+    if (!isFile(file))
+        return null;
     try {
         const text = await readFile(file, 'utf8');
         // Taken away by another run since it was read, the mutants of `force`
@@ -241,6 +459,157 @@ export async function takeCall(commonDir, name) {
         return null;
     }
 }
+/** SHA-256, loaded where something is hashed: a run that keeps no answer loads no hash (ADR-0002). */
+export async function hasher() {
+    const { createHash } = await import('node:crypto');
+    return (data) => createHash('sha256').update(data).digest('hex');
+}
+/**
+ * How long a session's answer of spec-brief's is kept once it was last
+ * kept (ADR-0003). A day, as a call's: an answer removed costs one start of
+ * spec-brief, and one kept is a few kilobytes.
+ */
+export const ANSWER_LIFE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Keeps a session's answer of spec-brief's under the common directory, with
+ * the key it answers, and removes what was kept over a day ago. Whatever
+ * fails is passed over: the answer is the one given whether or not it is
+ * kept.
+ */
+export async function keepAnswer(commonDir, name, key, answer, now = Date.now()) {
+    try {
+        const directory = await stateDirectory(commonDir, 'answers');
+        await writeAtomic(join(directory, name), `${JSON.stringify({ key, answer })}\n`);
+        // A file another run takes away before it is removed here ends the
+        // pruning in the catch below, where `force` would pass over it, and what
+        // is left is pruned by a later run: the mutants of `force` are
+        // equivalent, and so is the one that also removes a file kept a day ago
+        // to the millisecond.
+        for (const entry of await readdir(directory)) {
+            const file = join(directory, entry);
+            if (now - (await stat(file)).mtimeMs > ANSWER_LIFE_MS)
+                await rm(file, { force: true });
+        }
+    }
+    catch {
+        // A full disk, a directory another run removed: the next run starts spec-brief.
+    }
+}
+/**
+ * The answer kept under `name` for `key`, or `null` where there is none:
+ * nothing there, something that is not a file, a text that is not what
+ * `keepAnswer` writes, or another key's.
+ */
+export async function keptAnswer(commonDir, name, key) {
+    const file = join(commonDir, 'spec-harness', 'answers', name);
+    try {
+        // Only a file is read: a named pipe would be read without end.
+        if (!(await stat(file)).isFile())
+            return null;
+        // A text that holds null throws on the read, and any other that is no
+        // object has no key: the catch answers for both. A Buffer parses as its
+        // text, so the encoding is equivalent to its mutant.
+        const kept = JSON.parse(await readFile(file, 'utf8'));
+        return kept.key === key && typeof kept.answer === 'string' ? kept.answer : null;
+    }
+    catch {
+        // Falling out of the catch answers undefined, which no answer is read
+        // from either: the mutant without the return is equivalent.
+        return null;
+    }
+}
+/** Whether a path that could not be read names nothing: it, or a directory on the way to it, is not there. */
+function nothingThere(error) {
+    const { code } = error;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+/**
+ * Whether a file reads as listed: a file, never a pipe or a directory, whose
+ * bytes have the digest; or, listed as not there, nothing at its path.
+ */
+async function fileReads(file, sha256, hash) {
+    let there;
+    try {
+        there = await stat(file);
+    }
+    catch (error) {
+        return sha256 === null && nothingThere(error);
+    }
+    // Only a file is read: a named pipe would be read without end. A file
+    // listed as not there has no digest a file's bytes have.
+    if (!there.isFile())
+        return false;
+    return hash(await readFile(file)) === sha256;
+}
+/**
+ * Whether a directory is there and holds the files listed, and no other: a
+ * file as spec-brief lists one, an entry that is a file itself, where a
+ * directory or a link is not one. What is no directory, a named pipe among
+ * it, is refused by the listing, which throws. Listed as not there, nothing
+ * may stand at its path in any form, a link that leads nowhere among them.
+ */
+async function entriesRead(directory, entries) {
+    if (entries === null) {
+        try {
+            await lstat(directory);
+            return false;
+        }
+        catch (error) {
+            return nothingThere(error);
+        }
+    }
+    // The entries are names no two of which are one (inputsOf), and so are a
+    // directory's: as many of each, every one of the one among the other, is
+    // the same names, in whatever order the disk lists them.
+    const names = (await readdir(directory, { withFileTypes: true })).flatMap((entry) => (entry.isFile() ? [entry.name] : []));
+    const listed = new Set(entries);
+    return names.length === listed.size && names.every((name) => listed.has(name));
+}
+/**
+ * Whether every input of an answer reads as listed, with no process
+ * started: each file by the digest of its bytes, or as not there; each
+ * directory by its entries; and, where git was asked, the index of the work
+ * tree's git directory and each ignore file. A path is read from the work
+ * tree's top, or as it stands where it is absolute. Anything that cannot be
+ * read, and an index that is not the one git reads for the work tree, is a
+ * doubt, and answers `false` (ADR-0002).
+ */
+export async function readsAsListed(root, inputs, hash, env = process.env) {
+    const at = (path) => (isAbsolute(path) ? path : join(root, ...path.split('/')));
+    const git = inputs.git;
+    let index = null;
+    if (git !== null) {
+        // The index of the work tree's own git directory, as the files git keeps
+        // name it: not where git is sent elsewhere, GIT_DIR, GIT_WORK_TREE or a
+        // worktree key (`exact`), GIT_INDEX_FILE or GIT_COMMON_DIR. A top git
+        // named always holds a `.git`, so the test of none is the compiler's, and
+        // a null read past it throws, which the caller reads as a doubt: that
+        // mutant is equivalent. The top found is the work tree's own but where
+        // git names a top that holds no `.git`, a work tree `core.worktree`
+        // names away from its repository and inside another, whose index the
+        // one found would be.
+        const found = gitDirectories(root, env);
+        if (found === null || !found.exact || env['GIT_INDEX_FILE'] !== undefined || env['GIT_COMMON_DIR'] !== undefined || found.top !== realSpelling(root))
+            return false;
+        index = join(found.git, 'index');
+    }
+    // Made once every check is known to be made, so that none is left to fail
+    // with no one reading it. A text put among them where git was asked
+    // nothing is one `every` reads as true, so that mutant is equivalent.
+    const checks = [
+        ...inputs.files.map((file) => fileReads(at(file.path), file.sha256, hash)),
+        ...inputs.directories.map((directory) => entriesRead(at(directory.path), directory.entries)),
+        ...(git === null ? [] : [fileReads(index, git.index, hash), ...git.ignores.map((file) => fileReads(at(file.path), file.sha256, hash))]),
+    ];
+    try {
+        return (await Promise.all(checks)).every((reads) => reads);
+    }
+    catch {
+        // Falling out of the catch answers undefined, which the caller reads as
+        // false: the mutant without the return is equivalent.
+        return false;
+    }
+}
 /** Writes a file whole or not at all: a temporary file renamed over the target. */
 export async function writeAtomic(file, content) {
     await mkdir(dirname(file), { recursive: true });
@@ -282,7 +651,10 @@ export function isDirectory(path) {
         return false;
     }
 }
+/** A file's text, or `null` where it cannot be read or is no file: a brief, a document one cites, a shim. */
 export async function readText(file) {
+    if (!isFile(file))
+        return null;
     try {
         return await readFile(file, 'utf8');
     }