@descent-vtt/spec-brief 0.8.0 → 0.10.0

package/dist/cli.js

@@ -7,11 +7,13 @@
  * must never exit as though it found nothing.
  */
 import { readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
 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 { BriefEngine, EngineError, today } from './engine.js';
+import { idKey } from './corpus.js';
+import { BriefEngine, EngineError, isDate, today } from './engine.js';
 import { NodeFileSystem } from './fs.js';
 import { GitError } from './git.js';
 import { failing, sortFindings, summarise } from './lint.js';
@@ -93,11 +95,11 @@ function untrue(command, option) {
             return command === 'init' || command === 'new' || command === 'list';
         case 'color':
             return command === 'init' || command === 'new';
-        // Each caller asks only whether the answer is true, so the mutant that
-        // leaves this case out, and answers nothing, is equivalent.
-        default:
-            return false;
     }
+    // After the switch and not as its `default`: a `default` with its return
+    // taken out answers nothing, which each caller reads as false, and no test
+    // can tell that mutant from the code (ADR-0009).
+    return false;
 }
 /**
  * Whether the option asks the command to leave out what it never does, and
@@ -115,11 +117,9 @@ function alreadySo(command, option) {
             return command === 'init';
         case 'no-color':
             return command === 'init' || command === 'new';
-        // Each caller asks only whether the answer is true, so the mutant that
-        // leaves this case out, and answers nothing, is equivalent.
-        default:
-            return false;
     }
+    // After the switch, for the reason `untrue` has.
+    return false;
 }
 /** Options by their names on the command line, as a sentence lists them. */
 function listed(names) {
@@ -151,8 +151,137 @@ function unread(command, spec, values) {
     }
     if (flag(values, 'color') && flag(values, 'no-color'))
         return '--color is given beside --no-color, which turns colour off; give one of the two';
+    // The engine refuses the pair as well, for a caller of the library; here it
+    // is refused with the line, where --help and --version are no way past it.
+    if (flag(values, 'no-git') && (text(values, 'commit') !== undefined || text(values, 'base') !== undefined)) {
+        return 'a commit or a base needs git; drop --no-git, or drop --commit and --base';
+    }
+    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, 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 onVolume(resolve(value));
+        case 'config':
+            return onVolume(resolve(root, value));
+        case 'wave':
+        case 'pr':
+            return String(digits(value) ?? value);
+        case 'depends-on':
+            // `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':
+        case 'archive':
+            // Last: one outside the repository leaves the switch and is read as it
+            // was written, for `directories` to refuse by what it was given. A catch
+            // that returned it would have a mutant, its return taken out, that fell
+            // into the next case and read it the same, which no test can tell apart.
+            try {
+                return normalisePath(value);
+            }
+            catch { }
+    }
+    // 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, revisions) {
+    // A configuration is found from the root, as the engine finds it.
+    const root = resolve(text(values, 'root') ?? cwd);
+    const first = new Map();
+    for (const token of options) {
+        // A flag has no value to compare, and one given twice is that flag once.
+        // Taken in here it would be read as nothing each time, which decides
+        // nothing either: the mutant that takes it in is equivalent.
+        if (token.value === undefined)
+            continue;
+        const read = asRead(token.name, token.value, root);
+        const earlier = first.get(token.name);
+        if (earlier === undefined)
+            first.set(token.name, { written: token.value, read });
+        else if (earlier.read !== read) {
+            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;
+}
+/**
+ * `--help` beside `--version` asks for two answers, and printed one of
+ * them; the other went unread. Named as each was written, `-h` or `--help`.
+ */
+function answers(options) {
+    let asked;
+    for (const token of options) {
+        if (token.name !== 'help' && token.name !== 'version')
+            continue;
+        if (asked === undefined)
+            asked = token;
+        else if (asked.name !== token.name)
+            return `${asked.rawName} is given beside ${token.rawName}, and one of the two answers would go unread; give one of the two`;
+    }
     return null;
 }
+/**
+ * What a command's own options hold, refused where the line is read, by what
+ * each holds: a number, a list of ids, a date, a revision, a directory, and a
+ * second brief where a command takes one. What only the tree can answer - a
+ * root that is not there, an id that is taken, a type the configuration does
+ * not have - is asked by the run, which `--help` and `--version` do not start.
+ */
+function checkValues(command, values, positionals) {
+    integer(values, 'wave', 0);
+    integer(values, 'pr', 1);
+    dependencies(values);
+    const date = text(values, 'date');
+    if (date !== undefined && !isDate(date))
+        throw new UsageError(`"${date}" is not a date written YYYY-MM-DD`);
+    for (const option of ['commit', 'base']) {
+        // Handed to git, it would be read as one of git's options.
+        const revision = text(values, option);
+        if (revision?.startsWith('-') === true)
+            throw new UsageError(`"${revision}" is not a revision`);
+    }
+    // Only init takes --briefs and --archive; for any other command they are
+    // the defaults, which are two directories inside the root.
+    directories(values);
+    if ((command === 'archive' || command === 'unarchive') && positionals.length > 1) {
+        throw new UsageError(`${command} takes one brief: spec-brief ${command} <brief>`);
+    }
+}
 /**
  * The commands by name, and nothing for a command line that names none. A map,
  * because an object answers to more names than it was given: `constructor` and
@@ -243,6 +372,12 @@ are --config beside --no-config and --color beside --no-color, of which one
 would go unread. An option that asks a command to leave out what it never
 does is taken, as init --no-git: it asks for what is already so.
 
+An option that takes one value and is given two is refused, as --root a
+--root b, since the earlier would go unread; one value given twice, however
+it is written, is taken once, as --root . --root ./. A line refused for any
+of these is refused with --help or --version on it too, and so is --help
+beside --version.
+
 Exit codes: 0 clean, 1 findings or refused, 2 the run could not be trusted.
 `;
 /** Global options that take a value, so the value is not mistaken for the command. */
@@ -261,7 +396,14 @@ function commandOf(argv) {
     }
     return undefined;
 }
-export function parse(argv) {
+/**
+ * The line, read and checked. Everything the line alone decides is refused
+ * here, before `--help` and `--version` are answered, as an option the
+ * parser does not know always was: a wrong line is wrong with either of them
+ * on it (spec-core ADR-0005, amended 2026-10-18). `cwd` is the directory a
+ * run without `--root` starts in, from which a `--config` is found.
+ */
+export function parse(argv, cwd = process.cwd()) {
     const command = commandOf(argv);
     const spec = COMMANDS.get(command);
     if (command !== undefined && spec === undefined) {
@@ -269,12 +411,17 @@ export function parse(argv) {
     }
     let parsed;
     try {
-        parsed = parseArgs({
+        const read = parseArgs({
             args: [...argv],
             options: { ...GLOBAL, ...(spec?.options ?? {}) },
             allowPositionals: true,
             strict: true,
+            tokens: true,
         });
+        // The cast stands on the name, with nothing under it: Stryker makes no
+        // mutant of what an `as` holds, and the call above is what the parser
+        // is asked (ADR-0009).
+        parsed = read;
     }
     catch (error) {
         throw new UsageError(error.message);
@@ -294,7 +441,48 @@ export function parse(argv) {
         const extra = positionals.map((argument) => `"${argument}"`).join(', ');
         throw new UsageError(`${command} takes no argument, not ${extra}: spec-brief ${command}${spec.noArgument}`);
     }
-    return { command, values: parsed.values, positionals };
+    const options = parsed.tokens.filter((token) => token.kind === 'option');
+    // 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, 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) {
+    const asked = text(values, 'format') ?? 'pretty';
+    // Cast on the name, as above. The check below is what makes it true.
+    const format = asked;
+    return spec.formats.includes(format) ? null : `--format for ${command} is one of ${spec.formats.join(', ')}, not "${format}"`;
 }
 /** The value of an option declared a string, which is all `parseArgs` gives one. */
 function text(values, key) {
@@ -303,15 +491,63 @@ function text(values, key) {
 function flag(values, key) {
     return values[key] === true;
 }
+/** The number a value's digits count, or nothing for a value that is not digits alone. */
+function digits(raw) {
+    return /^\d+$/.test(raw) ? Number(raw) : undefined;
+}
 function integer(values, key, minimum) {
     const raw = text(values, key);
     if (raw === undefined)
         return undefined;
-    if (!/^\d+$/.test(raw) || Number(raw) < minimum)
+    const number = digits(raw);
+    if (number === undefined || number < minimum)
         throw new UsageError(`--${key} must be a whole number of at least ${minimum}, not "${raw}"`);
-    return Number(raw);
+    return number;
+}
+/** The ids of a list written with commas between them, spaces beside each taken off. */
+function idsOf(listed) {
+    return listed.split(',').map((id) => id.trim());
+}
+/** `--depends-on` as the ids it names, or nothing where it is not given. */
+function dependencies(values) {
+    const listed = text(values, 'depends-on');
+    const dependsOn = listed === undefined ? undefined : idsOf(listed);
+    // A list that names no brief is not a brief that depends on none: written
+    // as given, "," scaffolded a brief with no dependency and said nothing.
+    if (dependsOn?.every((d) => d === '')) {
+        throw new UsageError(`--depends-on is ${JSON.stringify(listed)}, which names no brief; give it ids with commas between them, as in 7,8, or leave the option out`);
+    }
+    // And a place in it that names none is a brief left out: "$A,$B" with one
+    // of the two unset scaffolded a brief that depends on the other alone.
+    if (dependsOn?.includes('')) {
+        throw new UsageError(`--depends-on is ${JSON.stringify(listed)}, which names no brief in one of its places; give it ids with one comma between each two, as in 7,8, and none before or after`);
+    }
+    return dependsOn;
+}
+/**
+ * The directories `init` sets up. One above the root is refused as the
+ * configuration refuses one (config.ts), in the same words, before anything
+ * is written.
+ */
+function directories(values) {
+    const inside = (option, given) => {
+        try {
+            return normalisePath(given);
+        }
+        catch {
+            throw new UsageError(`--${option} must be a directory inside the repository, not "${given}"`);
+        }
+    };
+    const briefs = inside('briefs', text(values, 'briefs') ?? 'briefs');
+    const archive = inside('archive', text(values, 'archive') ?? `${briefs}/archive`);
+    if (briefs === '' || archive === '' || briefs === archive)
+        throw new UsageError('--briefs and --archive must be two directories');
+    return { briefs, archive };
 }
 async function version() {
+    // `JSON.parse` reads a file's bytes as it reads their text in UTF-8, so the
+    // encoding says what the manifest is and decides nothing: with none named,
+    // the version read is the same, and no test can tell the two apart.
     const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
     return pkg.version;
 }
@@ -336,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 = {}) {
@@ -374,20 +612,7 @@ async function runInit(run) {
         if (await fs.exists(name))
             throw new UsageError(`${name} already exists here; edit it instead`);
     }
-    // A directory above the root is refused as the configuration refuses one
-    // (config.ts), in the same words, before anything is written.
-    const inside = (option, given) => {
-        try {
-            return normalisePath(given);
-        }
-        catch {
-            throw new UsageError(`--${option} must be a directory inside the repository, not "${given}"`);
-        }
-    };
-    const briefs = inside('briefs', text(run.values, 'briefs') ?? 'briefs');
-    const archive = inside('archive', text(run.values, 'archive') ?? `${briefs}/archive`);
-    if (briefs === '' || archive === '' || briefs === archive)
-        throw new UsageError('--briefs and --archive must be two directories');
+    const { briefs, archive } = directories(run.values);
     const config = `${JSON.stringify(initialConfig(briefs, archive), null, 2)}\n`;
     await fs.write('.spec-brief.json', config);
     const written = ['.spec-brief.json'];
@@ -408,18 +633,7 @@ async function runNew(run) {
     const title = run.positionals.join(' ').trim();
     if (title === '')
         throw new UsageError('new needs a title: spec-brief new "<title>"');
-    const listed = text(run.values, 'depends-on');
-    const dependsOn = listed?.split(',').map((d) => d.trim());
-    // A list that names no brief is not a brief that depends on none: written
-    // as given, "," scaffolded a brief with no dependency and said nothing.
-    if (dependsOn?.every((d) => d === '')) {
-        throw new UsageError(`--depends-on is ${JSON.stringify(listed)}, which names no brief; give it ids with commas between them, as in 7,8, or leave the option out`);
-    }
-    // And a place in it that names none is a brief left out: "$A,$B" with one
-    // of the two unset scaffolded a brief that depends on the other alone.
-    if (dependsOn?.includes('')) {
-        throw new UsageError(`--depends-on is ${JSON.stringify(listed)}, which names no brief in one of its places; give it ids with one comma between each two, as in 7,8, and none before or after`);
-    }
+    const dependsOn = dependencies(run.values);
     const engine = await openEngine(run);
     const created = await engine.create({
         title,
@@ -443,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());
@@ -451,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 {
@@ -503,9 +723,11 @@ async function runSchedule(run) {
 }
 async function runTransition(run, action) {
     const reference = run.positionals[0];
-    if (reference === undefined || run.positionals.length > 1)
+    // A second brief is refused with the line; none at all is what --help is asked for.
+    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, {
@@ -516,7 +738,8 @@ async function runTransition(run, action) {
             date: text(run.values, 'date') ?? run.today(),
             allowDirty: flag(run.values, 'allow-dirty'),
             strict: run.strict,
-            noGit: flag(run.values, 'no-git'),
+            // No noGit: under --no-git the engine is opened without git, and a
+            // commit or a base beside it is refused with the line.
         })
         : engine.planUnarchive(reference, { strict: run.strict });
     const refused = plan.blocking.length > 0;
@@ -536,13 +759,13 @@ export async function main(argv = process.argv.slice(2), io = {}) {
     };
     let parsed;
     try {
-        parsed = parse(argv);
+        parsed = parse(argv, io.cwd ?? process.cwd());
     }
     catch (error) {
         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
@@ -557,15 +780,9 @@ export async function main(argv = process.argv.slice(2), io = {}) {
             // Asked for, the help is the answer; printed because no command was named, it is the error.
             return flag(values, 'help') ? EXIT_OK : EXIT_ERROR;
         }
-        const spec = COMMANDS.get(command);
-        const refusal = unread(command, spec, values);
-        if (refusal !== null)
-            throw new UsageError(refusal);
-        const format = (text(values, 'format') ?? 'pretty');
-        if (!spec.formats.includes(format)) {
-            err(`--format for ${command} is one of ${spec.formats.join(', ')}, not "${format}"`);
-            return EXIT_ERROR;
-        }
+        const asked = text(values, 'format') ?? 'pretty';
+        // Cast on the name, as in `parse`, which refused a format the command does not write.
+        const format = asked;
         // A file, or a name with nothing behind it, had the search for a
         // configuration go on from its parent: the run reported on a tree nobody
         // had named, and `new` wrote into it. A path that cannot be reached is
@@ -591,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) {