@descent-vtt/spec-brief 0.7.0 → 0.9.0

package/dist/cli.js

@@ -7,11 +7,12 @@
  * 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 { BriefEngine, EngineError, isDate, today } from './engine.js';
 import { NodeFileSystem } from './fs.js';
 import { GitError } from './git.js';
 import { failing, sortFindings, summarise } from './lint.js';
@@ -72,6 +73,194 @@ const TABLE = {
     },
     unarchive: { options: { 'dry-run': { type: 'boolean' } }, formats: ['pretty', 'json'] },
 };
+/**
+ * Whether taking the option would tell someone what is not so. `init
+ * --strict` says the briefs were set up strictly, where nothing was strict;
+ * `init --config team.json` that the configuration was written there, where
+ * `.spec-brief.json` was; `init --color` and `new --color` that colour was
+ * printed, where neither prints any; `new --strict` and `list --strict` that
+ * a warning would have failed the run, where neither has one. Each ran as
+ * the line without the option does, exit 0.
+ *
+ * A function, not a table beside the commands': a table built when the
+ * module loads is static to Stryker, and each of its mutants then runs the
+ * whole suite (ADR-0009).
+ */
+function untrue(command, option) {
+    switch (option) {
+        case 'config':
+            return command === 'init';
+        case 'strict':
+            return command === 'init' || command === 'new' || command === 'list';
+        case 'color':
+            return command === 'init' || command === 'new';
+    }
+    // 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
+ * so asks for what is already so: `init` opens no configuration file and
+ * asks git nothing, and neither it nor `new` prints colour. Such an option
+ * is taken. A script that runs every command in a tree without git, or into
+ * a log, passes it to each of them, as spec-harness passes `--no-color`.
+ * The command reads nothing of it, so a refusal's line lists it apart from
+ * what the command reads, as taken.
+ */
+function alreadySo(command, option) {
+    switch (option) {
+        case 'no-config':
+        case 'no-git':
+            return command === 'init';
+        case 'no-color':
+            return command === 'init' || command === 'new';
+    }
+    // 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) {
+    const options = names.map((name) => `--${name}`);
+    return options.length === 1 ? options[0] : `${options.slice(0, -1).join(', ')} and ${options.at(-1)}`;
+}
+/**
+ * Why a command line that parsed is still not one to run.
+ *
+ * An option is refused where taking it would tell someone what is not so,
+ * and so are two options of which one would go unread: `--config team.json
+ * --no-config` says the file was read, where the defaults ran, and `--color
+ * --no-color` that colour was forced on, where it was off. An option that
+ * asks a command to leave out what it never does asks for what is already
+ * so, and is taken.
+ */
+function unread(command, spec, values) {
+    // The first such option as the line was typed, which is the order the
+    // parser keeps.
+    const stray = Object.keys(values).find((option) => untrue(command, option));
+    if (stray !== undefined) {
+        const shared = Object.keys(GLOBAL).filter((option) => option !== 'help' && option !== 'version' && !untrue(command, option));
+        const reads = [...shared.filter((option) => !alreadySo(command, option)), ...Object.keys(spec.options)];
+        const takes = shared.filter((option) => alreadySo(command, option));
+        return `${command} does not read --${stray}; it reads ${listed(reads)}${takes.length > 0 ? `, and takes ${listed(takes)}` : ''}`;
+    }
+    if (text(values, 'config') !== undefined && flag(values, 'no-config')) {
+        return '--config is given beside --no-config, which has the run read no configuration file; give one of the two';
+    }
+    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;
+}
+/**
+ * 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.
+ */
+function asRead(option, value, root) {
+    switch (option) {
+        case 'root':
+            return resolve(value);
+        case 'config':
+            return resolve(root, value);
+        case 'wave':
+        case 'pr':
+            return String(digits(value) ?? value);
+        case 'depends-on':
+            return JSON.stringify(idsOf(value));
+        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;
+}
+/**
+ * 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).
+ */
+function twice(options, values, cwd) {
+    // 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) {
+            // 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`;
+        }
+    }
+    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
@@ -108,14 +297,14 @@ Commands:
   archive <brief>       close a round: check it, stamp it, freeze it, move it
   unarchive <brief>     reopen an archived brief
 
-Options for every command:
+Options for every command, except where a line says otherwise:
   --root <dir>          run from this directory instead of the current one; it must exist, unless init makes it
-  --config <file>       use this configuration file
+  --config <file>       use this configuration file; not for init, which writes .spec-brief.json
   --no-config           use the defaults, ignoring any configuration file
   --format <format>     the output format, pretty by default; each command's are below
-  --strict              treat warnings as errors
+  --strict              treat warnings as errors; not for init, new or list, which have none
   --no-git              leave git out; read the files on disk instead
-  --color, --no-color   force colour on or off
+  --color, --no-color   force colour on or off; --color not for init or new, which print none
   -h, --help            show this help
   -v, --version         show the version
 
@@ -156,7 +345,17 @@ unarchive:
   --dry-run             print the plan and change nothing
 
 An option given an empty value, a list that names nothing and an argument a
-command does not take are refused, not read as if they were not there.
+command does not take are refused, not read as if they were not there. So is
+an option where taking it would say what is not so, as init --strict, and so
+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.
 `;
@@ -176,7 +375,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) {
@@ -184,12 +390,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);
@@ -209,8 +420,22 @@ 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}`);
     }
+    const options = parsed.tokens.filter((token) => token.kind === 'option');
+    const refusal = twice(options, parsed.values, cwd) ??
+        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 };
 }
+/** 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) {
     return values[key];
@@ -218,15 +443,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;
 }
@@ -238,9 +511,13 @@ function useColor(values, io) {
     const env = io.env ?? process.env;
     if ((env['NO_COLOR'] ?? '') !== '')
         return false;
+    // Off for exactly "0" and exactly "false": Node itself and supports-color
+    // read "false" as off, and here it forced colour on. Any other value that
+    // is not empty is on, "FALSE" too, which is the one reading the family's
+    // tools share (spec-core ADR-0005).
     const force = env['FORCE_COLOR'];
     if (force !== undefined && force !== '')
-        return force !== '0';
+        return force !== '0' && force !== 'false';
     // A terminal that says it is dumb has asked for no escape sequence, and
     // Node itself counts one colour for it: the family's tools read it alike.
     if (env['TERM'] === 'dumb')
@@ -285,20 +562,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'];
@@ -319,18 +583,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,
@@ -414,7 +667,8 @@ 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);
     const dryRun = flag(run.values, 'dry-run');
@@ -427,7 +681,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;
@@ -447,7 +702,7 @@ 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);
@@ -468,12 +723,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 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