@descent-vtt/spec-graph 0.13.1 → 0.14.1

package/dist/cli.js

@@ -14,6 +14,7 @@ import { applyBaseline, EMPTY_BASELINE, formatBaseline, parseBaseline, } from '.
 import { discoverConfig, loadConfig } from './config.js';
 import { DiffInputError, diffExports, formatDiffJson, formatDiffMarkdown, formatDiffText, parseGraphExport, } from './diff.js';
 import { isGlob, rebasePattern, underRoot } from './glob.js';
+import { isFamilyName } from './identity.js';
 import { analyse, DEFAULT_PATTERNS, withDiagnostics } from './runner.js';
 import { formatGithub, formatGitlab, formatGraph, formatJson, formatMarkdown, formatReport, formatSarif, shouldUseAscii, shouldUseColor, } from './report.js';
 import { DEFAULT_SEVERITIES, resolveStrict, RULE_DECISIONS, decisionUrl, RULE_DESCRIPTIONS, RULE_IDS, RULE_QUERIES, } from './rules.js';
@@ -60,16 +61,22 @@ OPTIONS
                           and the directory holding it becomes the root - so a
                           run from a subdirectory reports what a run from the
                           top reports. Paths typed on the command line stay
-                          relative to where they were typed.
+                          relative to where they were typed. It has to be a
+                          directory that is there.
   --ignore <glob>         Skip paths. Repeatable.
   --ignore-ref <glob>     Do not report these reference targets when they fail
                           to resolve, for repositories where [[...]] tags a
                           concept rather than naming a file. Repeatable.
                           Suppresses findings only, never edges.
   --family <name>         Families a bare identifier in prose may name. When
-                          given, everything else stays prose. Repeatable.
+                          given, everything else stays prose. Repeatable: one
+                          name each time, the prefix its identifiers are
+                          written with, ADR for ADR-0007. A document here has
+                          to belong to one of them, or the check stops: a list
+                          that names none allows nothing.
   --ignore-family <name>  Families that are never citations - RFC when the repo
-                          cites RFC 2119 and keeps its own RFCs. Repeatable.
+                          cites RFC 2119 and keeps its own RFCs. Repeatable,
+                          one name each time.
   --history <glob>        Files that log what was decided rather than deciding
                           it - journals, changelogs, minutes. Their links are
                           still checked; their obligations are not. Repeatable.
@@ -83,14 +90,15 @@ OPTIONS
   --ratchet               Also fail when a baseline entry no longer occurs, so
                           a paid-off exemption cannot outlive the defect.
   --no-config             Ignore .spec-graph.json and the package.json key.
-  --format <fmt>          human, json, sarif, github, gitlab or markdown. sarif
-                          is the interchange format GitHub code scanning and
-                          editors already read, github the workflow commands a
-                          GitHub Actions log turns into annotations, and gitlab
-                          the Code Quality report a GitLab merge request reads,
-                          all three for check; markdown is a table for a
-                          pull-request comment or $GITHUB_STEP_SUMMARY, for
-                          check or diff (default: human)
+  --format <fmt>          human, json, sarif, github, gitlab or markdown. json
+                          is for check, query or diff. sarif is the interchange
+                          format GitHub code scanning and editors already read,
+                          github the workflow commands a GitHub Actions log
+                          turns into annotations, and gitlab the Code Quality
+                          report a GitLab merge request reads, all three for
+                          check; markdown is a table for a pull-request comment
+                          or $GITHUB_STEP_SUMMARY, for check or diff (default:
+                          human)
   --graph-format <fmt>    dot, mermaid or json (default: dot)
   --documents-only        Leave items out of the exported graph
   --rule <id>=<severity>  Override one rule: error, warn, info or off. A project
@@ -101,12 +109,32 @@ OPTIONS
   --strict                Raise every warning to an error. An explicit --rule
                           still wins, so --strict --rule x=warn exempts x.
   --color / --no-color    Force colour on or off
-  --ascii                 Use ASCII glyphs only
+  --ascii                 Use ASCII glyphs only. SPEC_GRAPH_ASCII asks for the
+                          same, unless it is empty, 0 or false
   --verbose               Include parse problems, per-file detail, and every
                           reference --ignore-ref or --ignore-family silenced
+  --explain               With rules: add each rule's selector and the ADR
+                          that decided it
   -h, --help              Show this help
   -v, --version           Show the version
 
+  An option belongs to the commands that read it, and any other command
+  refuses it by name:
+
+    --root, --verbose                   check, query, graph, rules
+    --ignore, --history                 check, query, graph
+    --format                            check, query, diff
+    --graph-format, --documents-only    graph
+    --explain                           rules
+    every other option                  check
+
+  --no-config, --no-color and --ascii are taken by every command: each is
+  true already of a command with nothing to read it for.
+
+  A value that begins with -- reads as an option, so the option before it is
+  refused as missing its value. A name that does begin so is written ./--name
+  for a file, [-]-name in a pattern and \\--name for a reference target.
+
 SELECTORS
   A selector is a path through the graph.
 
@@ -132,6 +160,11 @@ EXIT CODES
   1  findings at error severity (or over --max-warnings)
   2  the tool could not run
 
+  An input that is set and names nothing is a 2, named on stderr, and never
+  read as if it had not been given: an empty value, a family name no family
+  has, a list of families no document here belongs to, a --root that is no
+  directory, a second word after rules, an option of another command.
+
 CONFIGURATION
   Anything repeated on every run belongs in the repository rather than in the
   command. spec-graph reads the first of these that exists:
@@ -153,9 +186,10 @@ CONFIGURATION
   finding lists, 8 unless set, and 0 lists none.
 
   A problem in that file stops the run with exit 2, named on stderr: invalid
-  JSON, an unknown key, a rule that does not compile. A configuration that did
-  not load checks a different repository than the one configured, and would
-  report that one as consistent. --no-config runs on defaults instead.
+  JSON, an unknown key, a rule that does not compile, a file that is there and
+  cannot be read. A configuration that did not load checks a different
+  repository than the one configured, and would report that one as consistent.
+  --no-config runs on defaults instead.
 
 PROJECT RULES
   A convention spec-graph never anticipated is a selector plus a sentence, and
@@ -213,6 +247,61 @@ EXAMPLES
   spec-graph diff base.json head.json --format markdown >> "$GITHUB_STEP_SUMMARY"
 `;
 const SEVERITIES = ['error', 'warn', 'info', 'off'];
+/**
+ * The commands that read an option, or nothing for one every command takes.
+ *
+ * Any other command refuses the option, rather than run as if it were not
+ * there: `query --strict` taking the flag and doing nothing with it would
+ * tell someone their query was strict, `graph --record-baseline` wrote no
+ * file and said so nowhere, and `spec-graph --graph-format mermaid`, the
+ * command forgotten, wrote the check's report into what was meant to hold a
+ * graph. The three options about citations are a check's alone: they pass
+ * over findings and never an edge, so a graph or a query is the same with
+ * them as without.
+ *
+ * `--no-color`, `--ascii` and `--no-config` are taken by every command.
+ * Each is true already of what the commands that do not read it write - none
+ * of them colours or draws a glyph, and `diff` reads no configuration - and
+ * a script passes them to every command it runs. `--color` is not one of
+ * them: it would promise colour that only a check prints.
+ *
+ * A function and not a table, so that none of it runs when the module loads:
+ * a mutant of a table built at import pays for the whole suite (ADR-0007).
+ */
+function readersOf(option) {
+    switch (option) {
+        case '--root':
+        case '--verbose':
+            return ['check', 'query', 'graph', 'rules'];
+        case '--ignore':
+        case '--history':
+            return ['check', 'query', 'graph'];
+        case '--format':
+            return ['check', 'query', 'diff'];
+        case '--graph-format':
+        case '--documents-only':
+            return ['graph'];
+        case '--explain':
+            return ['rules'];
+        case '--ignore-ref':
+        case '--family':
+        case '--ignore-family':
+        case '--baseline':
+        case '--record-baseline':
+        case '--ratchet':
+        case '--rule':
+        case '--strict':
+        case '--max':
+        case '--max-warnings':
+        case '--color':
+            return ['check'];
+    }
+    return undefined;
+}
+/** `a`, `a or b`, `a, b or c`: one name or more in a sentence, with the word that joins the last. */
+function listed(names, joint) {
+    return names.length < 2 ? names[0] : `${names.slice(0, -1).join(', ')} ${joint} ${names[names.length - 1]}`;
+}
 /** Parses argv into options. Throws {@link UsageError} on anything malformed. */
 export function parseArgs(argv, cwd) {
     const args = [...argv];
@@ -247,10 +336,42 @@ export function parseArgs(argv, cwd) {
     let selector = null;
     let help = false;
     let version = false;
+    // In the order they were given, so the first that does not belong is the
+    // one named. A set keeps that order, and starts from no literal: a list
+    // seeded with a word no option is called would refuse nothing more, which
+    // is a mutant no test can tell from the code.
+    const given = new Set();
     const next = (flag, index) => {
         const value = args[index + 1];
         if (value === undefined)
             throw new UsageError(`${flag} needs a value`);
+        // The option after one whose value was forgotten. Taken as the value,
+        // `--ignore --strict` ignored a directory called `--strict` and the check
+        // was not strict, and `--record-baseline --verbose` wrote a file of that
+        // name. A name that does begin with two dashes has another spelling
+        // wherever one can be meant: `./--x` for a file, `[-]-x` in a pattern,
+        // `\--x` for a reference target.
+        if (value.startsWith('--') || value === '-h' || value === '-v') {
+            throw new UsageError(`${flag} needs a value, and ${value} reads as an option`);
+        }
+        return value;
+    };
+    // A blank value is what an unset variable leaves in `--root "$DIR"`. A path
+    // made of it names the directory beside it or a file called " ", and the run
+    // then answered for a place nobody named.
+    const filled = (flag, index, what) => {
+        const value = next(flag, index);
+        if (value.trim() === '')
+            throw new UsageError(`${flag} expects ${what}, got "${value}"`);
+        return value;
+    };
+    // A family is taken once per option. A blank, `ADR,RFC` or the option typed
+    // after it is a name no family has: alone on the allowlist it left every
+    // citation as prose, and the check passed over the ones that dangle.
+    const family = (flag, index) => {
+        const value = next(flag, index);
+        if (!isFamilyName(value))
+            throw new UsageError(`${flag} expects one family's name, such as ADR, got "${value}"`);
         return value;
     };
     for (let i = 0; i < args.length; i += 1) {
@@ -266,6 +387,7 @@ export function parseArgs(argv, cwd) {
                 patterns.push(arg);
             continue;
         }
+        given.add(arg);
         switch (arg) {
             case '-h':
             case '--help':
@@ -300,7 +422,7 @@ export function parseArgs(argv, cwd) {
                 verbose = true;
                 break;
             case '--root':
-                root = next(arg, i);
+                root = filled(arg, i, 'a directory');
                 rootExplicit = true;
                 i += 1;
                 break;
@@ -313,11 +435,11 @@ export function parseArgs(argv, cwd) {
                 i += 1;
                 break;
             case '--family':
-                families.push(next(arg, i));
+                families.push(family(arg, i));
                 i += 1;
                 break;
             case '--ignore-family':
-                ignoreFamilies.push(next(arg, i));
+                ignoreFamilies.push(family(arg, i));
                 i += 1;
                 break;
             case '--history':
@@ -325,11 +447,11 @@ export function parseArgs(argv, cwd) {
                 i += 1;
                 break;
             case '--baseline':
-                baseline = next(arg, i);
+                baseline = filled(arg, i, 'a file');
                 i += 1;
                 break;
             case '--record-baseline':
-                recordBaseline = next(arg, i);
+                recordBaseline = filled(arg, i, 'a file');
                 i += 1;
                 break;
             case '--no-config':
@@ -404,9 +526,35 @@ export function parseArgs(argv, cwd) {
     if (format === 'markdown' && command !== 'check' && command !== 'diff' && !help && !version) {
         throw new UsageError(`--format markdown is a report for a pull request, so it belongs to check or diff, not to ${command}`);
     }
+    // JSON is refused where the other reports are, and for the reason above:
+    // `graph --format json` wrote DOT and `rules --format json` a list, each
+    // with exit 0, to whatever was waiting for JSON.
+    if (format === 'json' && (command === 'graph' || command === 'rules') && !help && !version) {
+        const instead = command === 'graph' ? 'graph writes JSON with --graph-format json' : 'rules lists the rules as text';
+        throw new UsageError(`--format json belongs to check, query or diff, not to ${command}: ${instead}`);
+    }
+    if (!help && !version) {
+        for (const option of given) {
+            const readers = readersOf(option);
+            if (readers !== undefined && !readers.includes(command)) {
+                throw new UsageError(`${option} belongs to ${listed(readers, 'or')}, not to ${command}`);
+            }
+        }
+    }
+    // The second word given to `rules` was dropped, so `rules a b` listed `a`
+    // and said nothing of `b`.
+    if (command === 'rules' && patterns.length > 1 && !help && !version) {
+        throw new UsageError(`rules takes one rule id, got ${patterns.length}: ${patterns.join(', ')}`);
+    }
     if (command === 'diff' && patterns.length !== 2 && !help && !version) {
         throw new UsageError('diff compares two graph exports, for example:\n  spec-graph diff base.json head.json\n  (make each with spec-graph graph --graph-format json)');
     }
+    // An empty name resolved to the directory the run was started in, and the
+    // refusal was the read's: `cannot read : EISDIR`.
+    const blank = patterns.findIndex((path) => path.trim() === '');
+    if (command === 'diff' && blank !== -1 && !help && !version) {
+        throw new UsageError(`diff expects a graph export on each side, got "${patterns[blank]}" for the ${blank === 0 ? 'first' : 'second'}`);
+    }
     if (command === 'query' && selector === null && !help && !version) {
         throw new UsageError('query needs a selector, for example:\n  spec-graph query \'item[openness=open]\'');
     }
@@ -540,6 +688,20 @@ async function run(io, err) {
     // it can compare exports from a checkout it is not running in.
     if (options.command === 'diff')
         return runDiff(options.patterns, cwd, options.format, out, err);
+    // A root that was named is a directory, for every command that reads one.
+    // `rules --root` with a path that is not there listed the built-in rules and
+    // exited 0, as if the repository declared none, and the others said only
+    // that no specification matched under it.
+    if (options.rootExplicit) {
+        const { stat } = await import('node:fs/promises');
+        // A path that cannot be reached reads as one that is not there: either
+        // way there is nothing under it to read.
+        const found = await stat(options.root).catch(() => null);
+        if (found === null || !found.isDirectory()) {
+            err(`spec-graph: --root "${options.root}" is not ${found === null ? 'there' : 'a directory'}\n`);
+            return EXIT_ERROR;
+        }
+    }
     const color = options.color ?? shouldUseColor({ isTTY: io.isTTY, env });
     const ascii = options.ascii ?? shouldUseAscii({ env });
     // Configuration is what is true of the repository; a flag is somebody
@@ -625,16 +787,19 @@ async function run(io, err) {
     const patterns = typed.patterns.length > 0 ? typed.patterns : (file.patterns ?? DEFAULT_PATTERNS);
     const severityOverrides = { ...(file.severities ?? {}), ...options.severities };
     const { severities, escalated } = resolveStrict(severityOverrides, options.strict || (file.strict ?? false), projectRules);
+    // The list the check is held against, once it has read the documents.
+    const families = [...(file.families ?? []), ...options.families];
     const analyseOptions = {
         root,
         patterns,
-        // A stray entry in one of the empty fallbacks below changes a run only if
-        // it matches a path, a target or a family some corpus has, so the mutants
-        // that plant one survive every corpus but one built for them - except in
-        // `families`, where any entry is an allowlist.
+        // A stray entry in one of the empty fallbacks here changes a run only if
+        // it matches a path or a target some corpus has, so the mutants that plant
+        // one survive every corpus but one built for them - except in the two
+        // lists of families, where what they plant is no family's name and is
+        // refused.
         ignore: [...(file.ignore ?? []), ...typed.ignore],
         ignoreReferences: [...(file.ignoreReferences ?? []), ...options.ignoreReferences],
-        families: [...(file.families ?? []), ...options.families],
+        families,
         ignoreFamilies: [...(file.ignoreFamilies ?? []), ...options.ignoreFamilies],
         historyPatterns: [...(file.historyPatterns ?? []), ...typed.history],
         severities,
@@ -701,6 +866,30 @@ async function run(io, err) {
             return matches.length > 0 ? EXIT_OK : EXIT_FAILED;
         }
         default: {
+            // An allowlist is held against the corpus it was written for. One that
+            // names no family a document here belongs to allows nothing the corpus
+            // has: every citation is then prose, and the run that failed on a
+            // dangling one reported a consistent graph - for `--family ADRS` as it
+            // did for `--family ""`. Nothing was measured, which is not clean
+            // (spec-core's ADR-0005), so the run stops before it says anything. A
+            // list that names such a family beside one the corpus has is a family
+            // the repository means to start, or a typo in half of it: said, and
+            // nothing fails.
+            const allowed = [...new Set(families.map((family) => family.trim().toUpperCase()))];
+            const absent = allowed.filter((family) => !result.corpus.families.includes(family));
+            if (absent.length > 0) {
+                const lists = [];
+                if (options.families.length > 0)
+                    lists.push('--family');
+                if (file.families !== undefined && file.families.length > 0)
+                    lists.push(`"families" in ${loaded.source}`);
+                const here = `the documents here belong to ${result.corpus.families.length > 0 ? listed(result.corpus.families, 'and') : 'no family'}`;
+                if (absent.length === allowed.length) {
+                    err(`spec-graph: no document here belongs to a family named by ${lists.join(' and ')} (${allowed.join(', ')}); ${here}\n  name a family the documents belong to, or leave the list out\n`);
+                    return EXIT_ERROR;
+                }
+                err(`spec-graph: no document here belongs to ${listed(absent, 'or')}, named by ${lists.join(' and ')}; ${here}\n`);
+            }
             // Recording is not checking. It writes down what is wrong today so that
             // tomorrow can be compared against it, and says nothing about whether
             // today is acceptable - so it reports what it wrote and exits clean.