@descent-vtt/spec-brief 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -11,6 +11,69 @@ release that can turn a run red. This is the family's policy, recorded in
 releases up to 0.2.7 came before it, and several of their patches changed
 what a run reports.
 
+## 0.10.0
+
+One value written two ways is taken once in three more cases, each of
+which was refused as two values: a drive letter in either case on
+Windows, two revisions git says name one commit, and two lists that name
+the same briefs. Nothing that ran is refused.
+
+`list --format json` names what its answer was read from, so that another
+tool can give the answer again without starting spec-brief. A
+configuration that is not a file is refused, exit 2, where a named pipe
+under its name was read without end.
+
+### Fixed
+
+- **A drive letter names its volume in either case.** On Windows
+  `--root C:\x` beside `--root c:\x`, and two `--config` values the same
+  way, were refused as two directories; each is taken once. The rest of a
+  path is compared as it resolves, so `C:\x` beside `C:\X` is still two
+  ([An option given two values](README.md#an-option-given-two-values);
+  [the family contract](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0005-the-family-contract.md),
+  amended 2026-10-19).
+- **A revision written two ways is asked of git.** `--commit HEAD` beside
+  the hash it names, or `--base main` beside the commit `main` is at, was
+  refused as two values. `archive` now asks git once what commit each
+  names, and takes two that name one as one. Two that name two commits,
+  one git cannot name, and any line with `--no-git`, `--help` or
+  `--version`, none of which asks git, are refused as they were
+  (ADR-0001, amended 2026-10-19).
+- **`--depends-on` is read as the set of ids it names**, each as a brief's
+  id is matched: `7,8` beside `8,7`, `7` beside `007` and `7,8` beside
+  `7,8,7` are taken once, and the brief is written with the later as
+  given. A list that names another brief, or one fewer, is still two
+  values.
+
+### Added
+
+- **`list --format json` names its inputs**, in a field `inputs`: each
+  file the answer was read from, with the SHA-256 of its bytes; each name a
+  configuration was looked for under and was not there, with `null`; each
+  directory the briefs were listed from, with the files in it, or `null`
+  where there was none, as an archive not yet made; and the version that
+  read them. `keep` is `false`, and nothing is listed, wherever that
+  cannot be named whole: a run that starts below its configuration's
+  directory, and one with no configuration file
+  ([`spec-brief list`](README.md#spec-brief-list); ADR-0002, amended
+  2026-10-19). `schemaVersion` stays 2, since a field is added and none
+  changes. `list` asks git nothing where a configuration file names the
+  root, which is a process fewer.
+
+### Changed
+
+- **A configuration that is not a file is refused.** A named pipe at
+  `.spec-brief.json` or `spec-brief.json`, or named by `--config`, was read
+  without end by every command; a socket ended the run on `ENXIO` and a
+  stack, and `--config /dev/zero` on `RangeError`. Each is now exit 2 with
+  one line, `is neither a file nor a directory, not a configuration file`,
+  before it is opened, as a directory was already. A link is read as what
+  it names ([An input that names nothing](README.md#an-input-that-names-nothing);
+  ADR-0003, amended 2026-10-19). Upgrading: nothing to change for a
+  configuration that is a file; `--config <(...)`, which a shell hands as a
+  pipe, ran in `/dev/fd` and found no briefs, and now says what it was
+  handed.
+
 ## 0.9.0
 
 An option that takes one value and is given two is refused, exit 2, where

package/README.md

@@ -126,7 +126,32 @@ Live briefs with their status, in the word the brief writes (`封存` where the
 | --- | --- |
 | `--ready` | Only the ready briefs, which is the question an orchestrator asks. |
 | `--archived` | The archive as well. |
-| `--format json` | The whole table, for an orchestrator, and the sections the configuration asks for, each with its `hint`. |
+| `--format json` | The whole table, for an orchestrator, the sections the configuration asks for, each with its `hint`, and what the answer was read from. |
+
+**What the answer was read from.** `--format json` names, under `inputs`, every input of its answer, so that a tool that asks for the same answer again, as spec-harness does before each write it checks, can give the one it kept while every input reads as listed, without starting spec-brief ([the family contract](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0005-the-family-contract.md), amended 2026-10-19):
+
+```json
+"inputs": {
+  "keep": true,
+  "tool": "0.10.0",
+  "files": [
+    { "path": ".spec-brief.json", "sha256": "ca3d163b..." },
+    { "path": "briefs/001_a.md", "sha256": "5ee9361a..." },
+    { "path": "spec-brief.json", "sha256": null }
+  ],
+  "directories": [
+    { "path": "briefs", "entries": ["001_a.md", "README.md"] },
+    { "path": "briefs/archive", "entries": null }
+  ],
+  "git": null
+}
+```
+
+- **`files`**: each file read, with the SHA-256 of its bytes in hex, and each name a configuration was looked for under and was not there, with `null`: it must still not be there.
+- **`directories`**: each directory the briefs were listed from, with the names of the regular files directly in it, sorted as JavaScript sorts strings. A link and a directory are no file here, and a file that is no brief is named though it is not read, since one renamed would be. A directory looked for and not found, as an archive not yet made, has `null`: there must still be no directory there.
+- **`tool`**: the version that read them. **`git`**: `null`, since `list` reads nothing of git, and asks it nothing where a configuration file names the root.
+- **Paths** are POSIX, from the root, which wherever `keep` is `true` is the directory the run started in.
+- **`keep` is `false`**, and the lists are empty, wherever spec-brief cannot name every input: a run that starts below its configuration's directory, or names a configuration in another, and one with no configuration file, where git or the search above the root finds the root.
 
 ### `spec-brief matrix`
 
@@ -280,7 +305,7 @@ An option, an argument or a path that is given and names nothing is refused: exi
 - **A list that names nothing.** `--depends-on ,` names no brief, and a brief that depends on nothing is one scaffolded without the option. A place in a list that names no brief, the comma too many in `7,8,` or the gap in `7,,8`, is refused as well: it is a brief left out, as `"$A,$B"` is with one of the two unset.
 - **An argument a command does not take.** `init`, `list`, `matrix` and `schedule` take none and refuse one by name, with their usage. `init mydir` set up the current directory; `init --root mydir` is what sets up another.
 - **A `--root` that is no directory.** A file, or a path that does not exist, is refused: the search for a configuration would go on from its parent, and the run would report on, or `new` write into, the tree above. A directory below the configuration's is a place to start from, as the current directory is.
-- **A configuration that is a directory**, named by `--config` or found under the configuration's name, does not load, and is said so in a line, as one that is not JSON is.
+- **A configuration that is not a file**, named by `--config` or found under the configuration's name, does not load, and is said so in a line before it is opened, as one that is not JSON is: a directory, a named pipe, which was read without end, a socket or a device. A link is read as what it names.
 
 ### An option a command does not read
 
@@ -309,8 +334,8 @@ An option that takes one value is given one. Given two that read as two, the run
 spec-brief: --root is given "nowhere" and ".", and takes one value; give one of the two
 ```
 
-- **One value given twice is taken once, however it is written.** Two values are compared as each is read: `--root` and `--config` as the paths they resolve to, so `--root .` beside `--root ./`; `--briefs` and `--archive` as directories of the repository, so `specs` beside `./specs/`; `--wave` and `--pr` by the number their digits write, so `1` beside `01`; `--depends-on` by its ids in their order, so `7,8` beside `7, 8`; `--summary` with the spaces around it taken off. Any other value is read as it is written, in its own case.
-- **A revision written two ways is two values**: `--commit HEAD` beside the hash it names, since only git can say they are one, and the line is checked before git is asked anything.
+- **One value given twice is taken once, however it is written.** Two values are compared as each is read: `--root` and `--config` as the paths they resolve to, so `--root .` beside `--root ./`, and on Windows with the drive letter in either case, so `C:\x` beside `c:\x`, where `C:\x` beside `C:\X` is two; `--briefs` and `--archive` as directories of the repository, so `specs` beside `./specs/`; `--wave` and `--pr` by the number their digits write, so `1` beside `01`; `--depends-on` by the set of ids it names, each as an id is matched to a brief, so `7,8` beside `8,7` or `7, 8`, and `7` beside `007`, and the brief is written with the later; `--summary` with the spaces around it taken off. Any other value is read as it is written, in its own case.
+- **A revision written two ways is asked of git**: `archive` asks git once what commit each value of `--commit`, or of `--base`, names, and takes `HEAD` beside the hash it names as one value. Two that name two commits, or one git cannot name, are two values; so are any two beside `--no-git`, `--help` or `--version`, none of which asks git.
 - **Every option that takes a value takes one.** `--depends-on` is a list written in one value, and no option adds to a list each time it is given. A flag given twice is that flag once.
 - A shell alias or a script that gives an option, and a line that gives it again to override it, is refused: give the option once.
 
@@ -336,7 +361,7 @@ spec-brief: --help is given beside --version, and one of the two answers would g
 
 ## Configuration
 
-`.spec-brief.json` (or `spec-brief.json`) at the root; the nearest one above the working directory is used, and its directory is the root. It is JSON, validated against [`schema.json`](schema.json): an unknown key, a misspelt rule or a value of the wrong type stops the run with exit 2 rather than falling back to defaults and reporting on the wrong rules.
+`.spec-brief.json` (or `spec-brief.json`) at the root; the nearest one above the working directory is used, and its directory is the root. It is a file, and JSON, validated against [`schema.json`](schema.json): an unknown key, a misspelt rule or a value of the wrong type stops the run with exit 2 rather than falling back to defaults and reporting on the wrong rules.
 
 | Key | Default | What it says |
 | --- | --- | --- |

package/dist/cli.d.ts

@@ -24,11 +24,21 @@ export interface CliIO {
     readonly env?: Readonly<Record<string, string | undefined>>;
 }
 type Values = Record<string, string | boolean | undefined>;
+/**
+ * A resolved path as two values of one option compare. On Windows a drive
+ * letter names its volume in either case, and a path resolved there starts
+ * with its drive letter or a backslash, so its first character is folded;
+ * the rest is compared as resolved (spec-core ADR-0005, amended 2026-10-19).
+ * A path written `\\?\c:\x` keeps its letter as written.
+ */
+export declare function onVolume(path: string, platform?: string): string;
 export declare const HELP: string;
 interface Parsed {
     readonly command: string | undefined;
     readonly values: Values;
     readonly positionals: readonly string[];
+    /** Each option's revisions as they were written, where two are written two ways, for git to read. */
+    readonly revisions: ReadonlyMap<string, readonly string[]>;
 }
 /**
  * The line, read and checked. Everything the line alone decides is refused

package/dist/cli.js

@@ -12,6 +12,7 @@ import { parseArgs } from 'node:util';
 import { TransactionError, ConflictError } from './apply.js';
 import { reported } from './collisions.js';
 import { CONFIG_FILES, ConfigError, initialConfig } from './config.js';
+import { idKey } from './corpus.js';
 import { BriefEngine, EngineError, isDate, today } from './engine.js';
 import { NodeFileSystem } from './fs.js';
 import { GitError } from './git.js';
@@ -157,25 +158,38 @@ function unread(command, spec, values) {
     }
     return null;
 }
+/**
+ * A resolved path as two values of one option compare. On Windows a drive
+ * letter names its volume in either case, and a path resolved there starts
+ * with its drive letter or a backslash, so its first character is folded;
+ * the rest is compared as resolved (spec-core ADR-0005, amended 2026-10-19).
+ * A path written `\\?\c:\x` keeps its letter as written.
+ */
+export function onVolume(path, platform = process.platform) {
+    // Folded to either case, two letters compare the same, and the folded path is never shown.
+    return platform === 'win32' ? `${path.charAt(0).toUpperCase()}${path.slice(1)}` : path;
+}
 /**
  * An option's value as the command reads it, so that one thing written two
- * ways is asked for once: a directory as the run resolves it, a number by
- * what its digits count, a list by its ids, a summary as it is trimmed. Any
- * other value is read as it is written, in its own case, which is how each
- * of those options reads it. A revision is read by git, which a line is not
- * checked against, so `HEAD` and the commit it names are two values here.
+ * ways is asked for once: a directory as the run resolves it, its drive
+ * letter in either case, a number by what its digits count, a list by the
+ * set of ids it names, each as a brief's id is matched, a summary as it is
+ * trimmed. Any other value is read as it is written, in its own case, which
+ * is how each of those options reads it. A revision is read by git, which
+ * the run asks once there are two (`sameCommits`).
  */
 function asRead(option, value, root) {
     switch (option) {
         case 'root':
-            return resolve(value);
+            return onVolume(resolve(value));
         case 'config':
-            return resolve(root, value);
+            return onVolume(resolve(root, value));
         case 'wave':
         case 'pr':
             return String(digits(value) ?? value);
         case 'depends-on':
-            return JSON.stringify(idsOf(value));
+            // `7` and `007` name one brief, and `8,7` the briefs `7,8` does.
+            return JSON.stringify([...new Set(idsOf(value).map(idKey))].sort());
         case 'summary':
             return value.trim();
         case 'briefs':
@@ -192,12 +206,18 @@ function asRead(option, value, root) {
     // After the switch, for the reason `untrue` has.
     return value;
 }
+/** The refusal of an option given two values, each shown as JSON, as an empty value is, where what cannot be seen can be. */
+function twoValues(option, first, second) {
+    return `--${option} is given ${JSON.stringify(first)} and ${JSON.stringify(second)}, and takes one value; give one of the two`;
+}
 /**
  * Why a line that gives one option two values is not one to run: the later
  * was read, and the earlier went unread with no word of it, so `--root
  * nowhere --root .` ran in `.` (spec-core ADR-0005, amended 2026-10-18).
+ * Two revisions written two ways are kept in `revisions`, where it is
+ * given, for git to say whether they name one commit.
  */
-function twice(options, values, cwd) {
+function twice(options, values, cwd, revisions) {
     // A configuration is found from the root, as the engine finds it.
     const root = resolve(text(values, 'root') ?? cwd);
     const first = new Map();
@@ -212,8 +232,9 @@ function twice(options, values, cwd) {
         if (earlier === undefined)
             first.set(token.name, { written: token.value, read });
         else if (earlier.read !== read) {
-            // Shown as JSON, as an empty value is, where what cannot be seen can be.
-            return `--${token.name} is given ${JSON.stringify(earlier.written)} and ${JSON.stringify(token.value)}, and takes one value; give one of the two`;
+            if (revisions === null || (token.name !== 'commit' && token.name !== 'base'))
+                return twoValues(token.name, earlier.written, token.value);
+            revisions.set(token.name, [...(revisions.get(token.name) ?? [earlier.written]), token.value]);
         }
     }
     return null;
@@ -421,13 +442,40 @@ export function parse(argv, cwd = process.cwd()) {
         throw new UsageError(`${command} takes no argument, not ${extra}: spec-brief ${command}${spec.noArgument}`);
     }
     const options = parsed.tokens.filter((token) => token.kind === 'option');
-    const refusal = twice(options, parsed.values, cwd) ??
+    // Two revisions written two ways are git's to read, by the run: `--help`
+    // and `--version` start none, and `--no-git` asks git nothing, so with
+    // any of the three they are two values, as the line reads them.
+    const revisions = flag(parsed.values, 'help') || flag(parsed.values, 'version') || flag(parsed.values, 'no-git') ? null : new Map();
+    const refusal = twice(options, parsed.values, cwd, revisions) ??
         answers(options) ??
         (spec === undefined ? null : (unread(command, spec, parsed.values) ?? unwritten(command, spec, parsed.values)));
     if (refusal !== null)
         throw new UsageError(refusal);
     checkValues(command, parsed.values, positionals);
-    return { command, values: parsed.values, positionals };
+    return { command, values: parsed.values, positionals, revisions: revisions ?? new Map() };
+}
+/**
+ * Two revisions of one option are one value where the run's git says both
+ * name one commit, and two where it names two, or cannot say of one: with
+ * no repository, outside one, or for a revision that names none. It is asked
+ * once, for every revision of both options.
+ */
+async function sameCommits(engine, revisions) {
+    // Asked nothing, a git process answers nothing: the mutant that starts one is equivalent.
+    if (revisions.size === 0)
+        return;
+    const asked = [...revisions.values()].flat();
+    // A git a caller of the library hands the engine may have no `commits`;
+    // the command line's is always NodeGit's, which has, so the mutant that
+    // calls it without asking is equivalent here.
+    const named = await engine.git?.commits?.(asked);
+    const commitOf = new Map(asked.map((revision, index) => [revision, named?.[index] ?? null]));
+    for (const [option, [first, ...later]] of revisions) {
+        const commit = commitOf.get(first) ?? null;
+        const other = later.find((revision) => commit === null || commitOf.get(revision) !== commit);
+        if (other !== undefined)
+            throw new UsageError(twoValues(option, first, other));
+    }
 }
 /** A `--format` the command does not write, which the help lists by command. */
 function unwritten(command, spec, values) {
@@ -524,12 +572,14 @@ function useColor(values, io) {
         return false;
     return (io.stdout ?? process.stdout).isTTY === true;
 }
-async function openEngine(run) {
+/** The engine for a run, which asks git nothing where `needsGit` is false and a configuration file names the root. */
+async function openEngine(run, needsGit = true) {
     return BriefEngine.open({
         cwd: text(run.values, 'root') ?? run.cwd,
         config: text(run.values, 'config'),
         ...(flag(run.values, 'no-git') ? { git: null } : {}),
         noConfig: flag(run.values, 'no-config'),
+        needsGit,
     });
 }
 function emitFindings(run, command, findings, checked, extra = {}) {
@@ -607,7 +657,9 @@ async function runLint(run) {
     return emitFindings(run, 'lint', findings, checked, { sections: sectionsJson(engine.config) });
 }
 async function runList(run) {
-    const engine = await openEngine(run);
+    // Nothing `list` answers is read from git, so git is asked nothing where
+    // the root is a configuration file's, and the answer can say so.
+    const engine = await openEngine(run, false);
     engine.requireBriefs();
     const briefs = flag(run.values, 'archived') ? engine.corpus.briefs : engine.corpus.live;
     const ready = new Set(engine.ready());
@@ -615,10 +667,14 @@ async function runList(run) {
         .map((brief) => ({ brief, ready: ready.has(brief), waitingOn: engine.waitingOn(brief) }))
         .filter((row) => !flag(run.values, 'ready') || row.ready);
     if (run.format === 'json') {
+        const { keep, ...read } = engine.inputs();
         run.out(jsonDocument('list', run.version, {
             ok: true,
             briefs: rows.map((r) => briefJson(r.brief, { ready: r.ready, waitingOn: r.waitingOn })),
             sections: sectionsJson(engine.config),
+            // What the answer was read from, for a tool that would give it again
+            // without starting this one, and the version that read it.
+            inputs: { keep, tool: run.version, ...read },
         }));
     }
     else {
@@ -671,6 +727,7 @@ async function runTransition(run, action) {
     if (reference === undefined)
         throw new UsageError(`${action} takes one brief: spec-brief ${action} <brief>`);
     const engine = await openEngine(run);
+    await sameCommits(engine, run.revisions);
     const dryRun = flag(run.values, 'dry-run');
     const plan = action === 'archive'
         ? await engine.planArchive(reference, {
@@ -708,7 +765,7 @@ export async function main(argv = process.argv.slice(2), io = {}) {
         err(error.message);
         return EXIT_ERROR;
     }
-    const { command, values, positionals } = parsed;
+    const { command, values, positionals, revisions } = parsed;
     // From here on, so that what comes before a command is covered as the
     // command is: --version and --help, the package's own manifest, the colour.
     // An error there left main as a rejection, which the launcher ended as
@@ -751,6 +808,7 @@ export async function main(argv = process.argv.slice(2), io = {}) {
             version: await version(),
             values,
             positionals,
+            revisions,
             cwd: io.cwd ?? process.cwd(),
         };
         switch (command) {