@descent-vtt/spec-harness 0.18.0 → 0.20.0

package/dist/fs.d.ts

@@ -2,12 +2,49 @@
  * 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';
-/** Reads `.spec-harness.json` at the root, or the defaults when there is none. */
+/**
+ * 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. 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
+ * for a defect (spec-core ADR-0005).
+ */
+export declare class StateError extends Error {
+    constructor(message: string);
+}
 /**
  * The real spelling of a path: links resolved and, on a filesystem that
  * ignores case, the case the directory entries have. A path that does not
@@ -25,6 +62,15 @@ export declare function realSpelling(path: string): string;
  * for what it would say from the other.
  */
 export declare function isTop(directory: string, top: string): boolean;
+/**
+ * The repository's main work tree, where git keeps the repository as that
+ * work tree's `.git`, as `git init` and `git clone` do and every linked
+ * worktree's common directory then is: `null` for a common directory of any
+ * other name, a bare repository's, a submodule's under its superproject's
+ * `modules`, or one kept apart with `--separate-git-dir`. Read from the
+ * name, with no process: it says only where an install is looked for.
+ */
+export declare function mainWorkTree(commonDir: string): string | null;
 /** Whether a `.git` stands in `directory`, a repository's or the file that names one, as at the top of a work tree. */
 export declare function holdsGit(directory: string): boolean;
 /**
@@ -32,12 +78,113 @@ 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 harness's own directory under the git common directory, created on demand (ADR-0003). */
+/**
+ * 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: 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,
+ * or at one between it and git's, Node refuses to make it, with ENOTDIR or
+ * EEXIST, and the harness says which path holds what.
+ */
 export declare function stateDirectory(commonDir: string, ...parts: string[]): Promise<string>;
+/**
+ * A work tree and its git directories as the files git keeps name them, read
+ * with no process: the nearest directory at or above `root` that holds a
+ * `.git`; the git directory, that `.git` or the one a `.git` file names
+ * (`gitdir: <path>`, relative to the file's directory); and the common
+ * directory, the one that git directory's `commondir` file names, relative
+ * to it, or the git directory itself (gitrepository-layout(5)). `exact` is
+ * whether git, asked, would name the same work tree: not where
+ * `GIT_DIR` or `GIT_WORK_TREE` sends it elsewhere, and not where the
+ * repository's configuration names a `worktree`, which `core.worktree`
+ * moves it to (git-config(1)), or keeps one of its own for a worktree.
+ * `null` where no directory up to the top of the filesystem holds one, or
+ * a `.git` file names none.
+ */
+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;
+/**
+ * How long a call's decisions are kept for a run after the write that does
+ * not come: a call refused by the person, one that failed, one stopped
+ * (ADR-0002). A day, since a call waits on a person's prompt for as long as
+ * the person is away, and an entry removed too soon costs only that call's
+ * answer being decided again.
+ */
+export declare const CALL_LIFE_MS: number;
+/**
+ * Keeps what a run before a write decided, under the common directory, for
+ * the run after it, and removes what no run after a write read in a day.
+ * Nothing here may change the answer before the write: whatever fails is
+ * passed over, and the run after the write then decides as it did.
+ */
+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>;
-/** A JSON object from a file: `null` when there is no file, `'unreadable'` when it holds anything else. */
+/**
+ * A JSON object from a file: `null` when there is no file, `'unreadable'`
+ * when it holds anything else. Only a file is read: a named pipe where a
+ * settings file is expected was read without end, and neither doctor nor
+ * init came back. What is neither a file nor a directory holds no JSON
+ * object, as a directory holds none.
+ */
 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>;