simt-dev 0.6.2 → 0.7.0

package/src/completions.mjs

@@ -0,0 +1,196 @@
+// Shell completions, generated from the command registry (plan 0003 R51).
+//
+// The inputs are the two tables that already exist and are already checked:
+// `COMMANDS` — the same list the dispatcher routes and `--help` is asserted
+// against (review 0002 S15) — and the flag tables in argv.mjs. A command added
+// to `IMPLEMENTED` therefore completes in all three shells with no second
+// edit, which is exactly the property S15 demanded of `--help`.
+//
+// Deterministic by construction: every list is sorted and deduplicated before
+// it is rendered, no timestamp, no host name, no environment is read. The same
+// registry produces byte-identical output on any machine, so the generated
+// script can be committed, diffed and reviewed like any other file.
+//
+// Two boundaries, both deliberate:
+//
+//   - Positional VALUES beyond subcommand words are file completion. The
+//     registry knows words, not the skill catalogue or a path's tree, and a
+//     completion that guesses is worse than one that falls back to files.
+//   - bash's script stays 3.2-compatible: macOS ships /bin/bash 3.2, and a
+//     completion script that fails to parse there is a silent no-op.
+
+import { BOOL_FLAGS, VALUE_FLAGS } from './argv.mjs';
+
+/** The shells this command can render, sorted. */
+export const SHELLS = ['bash', 'fish', 'zsh'];
+
+/** Every flag name, sorted: `--budget`, `--root`, ... Flags are global. */
+const FLAGS = [...new Set([...BOOL_FLAGS, ...VALUE_FLAGS])].sort().map((f) => `--${f}`);
+
+/** The value-flag case pattern (`--root|--task|...`), for the prev-word check. */
+const VALUE_CASE = [...VALUE_FLAGS].sort().map((f) => `--${f}`).join('|');
+
+/**
+ * The registry as completions need it: the first words, and for each group the
+ * subcommands under it. Derived from `commands` rather than hand-listed, so a
+ * new command or subcommand arrives here without an edit.
+ *
+ * @param {string[]} commands sorted dispatchable paths, e.g. `['brief', 'skills index']`
+ * @returns {{top: string[], groups: Array<[string, string[]]>}}
+ */
+export function shape(commands) {
+  const top = new Set();
+  const subs = new Map();
+  for (const path of commands) {
+    const [first, second] = path.split(' ');
+    top.add(first);
+    if (second !== undefined) {
+      if (!subs.has(first)) subs.set(first, new Set());
+      subs.get(first).add(second);
+    }
+  }
+  return {
+    top: [...top].sort(),
+    groups: [...subs.entries()]
+      .map(([group, set]) => [group, [...set].sort()])
+      .sort((a, b) => (a[0] < b[0] ? -1 : 1)),
+  };
+}
+
+/**
+ * The completion script for one shell.
+ *
+ * @param {'bash'|'fish'|'zsh'} shell
+ * @param {string[]} commands the dispatchable command paths (`COMMANDS`)
+ * @returns {string} the script, newline-terminated
+ */
+export function renderCompletions(shell, commands) {
+  const s = shape(commands);
+  if (shell === 'bash') return renderBash(s);
+  if (shell === 'zsh') return renderZsh(s);
+  if (shell === 'fish') return renderFish(s);
+  throw new Error(`unknown shell \`${shell}\`; one of: ${SHELLS.join(', ')}`);
+}
+
+function renderBash({ top, groups }) {
+  const cases = groups
+    .map(([group, subs]) => `      ${group}) subs='${subs.join(' ')}' ;;`)
+    .join('\n');
+  return [
+    '# bash completion for simt. Generated by `simt completions bash`; do not edit.',
+    '# Install: source <(simt completions bash), or drop it in /etc/bash_completion.d/.',
+    '# bash 3.2 compatible: macOS ships /bin/bash 3.2.',
+    '_simt() {',
+    '  local cur prev subs flags top',
+    '  cur="${COMP_WORDS[COMP_CWORD]}"',
+    "  prev=\"${COMP_WORDS[COMP_CWORD-1]}\"",
+    "  subs=''",
+    '',
+    '  # A flag that takes a value takes a word only the shell can name: paths.',
+    '  case "$prev" in',
+    '    --) return 0 ;;',
+    `    ${VALUE_CASE}) return 0 ;;`,
+    '  esac',
+    '',
+    `  flags='${FLAGS.join(' ')}'`,
+    `  top='${top.join(' ')}'`,
+    '',
+    '  case "$cur" in',
+    '    -*) COMPREPLY=( $(compgen -W "$flags" -- "$cur") ); return 0 ;;',
+    '  esac',
+    '  if [ "$COMP_CWORD" -eq 1 ]; then',
+    '    COMPREPLY=( $(compgen -W "$top" -- "$cur") )',
+    '  elif [ "$COMP_CWORD" -eq 2 ]; then',
+    '    case "${COMP_WORDS[1]}" in',
+    cases,
+    '    esac',
+    '    if [ -n "$subs" ]; then',
+    '      COMPREPLY=( $(compgen -W "$subs" -- "$cur") )',
+    '    fi',
+    '  fi',
+    '}',
+    'complete -o bashdefault -o default -F _simt simt',
+    '',
+  ].join('\n');
+}
+
+function renderZsh({ top, groups }) {
+  const cases = groups
+    .map(([group, subs]) => `    ${group}) subs=( ${subs.join(' ')} ) ;;`)
+    .join('\n');
+  return [
+    '#compdef simt',
+    '# zsh completion for simt. Generated by `simt completions zsh`; do not edit.',
+    '# Install: save as `_simt` in a directory on $fpath and run `compinit`, or',
+    '# source this after compinit: `source <(simt completions zsh)`.',
+    '_simt() {',
+    '  local cur prev',
+    // compsys sets `words` and `CURRENT` before the function runs; without the
+    // assignment `cur` and `prev` stay empty, so the flag and value-flag cases
+    // below never match and zsh completes only positionals (review 0003 Q51).
+    '  cur=${words[CURRENT]}',
+    '  prev=${words[CURRENT-1]}',
+    '  local -a top flags subs',
+    `  top=( ${top.join(' ')} )`,
+    `  flags=( ${FLAGS.join(' ')} )`,
+    '  subs=()',
+    '',
+    '  # A flag that takes a value takes a word only the shell can name: paths.',
+    '  case "$prev" in',
+    `    --|${VALUE_CASE})`,
+    '      _files',
+    '      return',
+    '      ;;',
+    '  esac',
+    '',
+    '  if [[ "$cur" == -* ]]; then',
+    '    compadd -- ${flags}',
+    '    return',
+    '  fi',
+    '',
+    '  case "${words[2]}" in',
+    cases,
+    '  esac',
+    '',
+    '  if (( CURRENT == 2 )); then',
+    '    compadd -- ${top}',
+    '  elif (( CURRENT == 3 )) && (( ${#subs} )); then',
+    '    compadd -- ${subs}',
+    '  else',
+    '    _files',
+    '  fi',
+    '}',
+    '',
+    'if (( $+functions[compdef] )); then',
+    '  compdef _simt simt',
+    'fi',
+    '',
+  ].join('\n');
+}
+
+function renderFish({ top, groups }) {
+  const level1 = top.map(
+    (word) => `complete -c simt -n '__fish_use_subcommand' -a '${word}'`,
+  );
+  const level2 = groups.flatMap(([group, subs]) =>
+    subs.map(
+      (word) => `complete -c simt -n '__fish_seen_subcommand_from ${group}' -a '${word}'`,
+    ),
+  );
+  const flagLines = FLAGS.map((flag) => {
+    const name = flag.slice(2);
+    return VALUE_FLAGS.has(name)
+      ? `complete -c simt -l ${name} -r`
+      : `complete -c simt -l ${name}`;
+  });
+  return [
+    '# fish completion for simt. Generated by `simt completions fish`; do not edit.',
+    '# Install: simt completions fish > ~/.config/fish/completions/simt.fish',
+    ...level1,
+    '',
+    ...level2,
+    '',
+    ...flagLines,
+    '',
+  ].join('\n');
+}

package/src/decisions/dir.mjs

@@ -0,0 +1,84 @@
+// The one answer to "where are this repository's decision records" (review 0003 Q55).
+//
+// Before this, every reader hard-coded `docs/decisions` while detection already
+// knew four spellings (`docs/decisions`, `docs/adr`, `docs/adrs`, `adr`), so a
+// repository that kept its records under `docs/adr/` was fingerprinted correctly
+// and then unread by every command. One resolution, every reader.
+//
+// Precedence is declaration first. A manifest `decisions.dir` names the directory
+// relative to the repository root; without one, the first existing candidate
+// wins; without any, the default is `docs/decisions`. The cutoff below answers
+// the companion question — which records predate structured frontmatter — and it
+// lives in the same config (`decisions.historicalCutoff`), never in code.
+
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { readManifest } from '../projection/manifest.mjs';
+
+/** Directory spellings a repository's decision records live under, in priority order. */
+const DECISION_DIR_CANDIDATES = ['docs/decisions', 'docs/adr', 'docs/adrs', 'adr'];
+
+/** The default when nothing is declared and nothing exists yet. */
+const DEFAULT_DECISIONS_DIR = 'docs/decisions';
+
+/**
+ * The repository's own `decisions` manifest key, or null.
+ *
+ * Read with the manifest loader (so the legacy name resolves the same way for
+ * this as for every other reader) and returned as-is: validation belongs to
+ * the caller that knows what it needs.
+ */
+async function manifestDecisions(root) {
+  try {
+    const { manifest } = await readManifest(root);
+    const decisions = manifest?.decisions;
+    return decisions !== null && typeof decisions === 'object' && !Array.isArray(decisions) ? decisions : null;
+  } catch {
+    // An unreadable manifest is not evidence either way; detection decides.
+    return null;
+  }
+}
+
+async function isDir(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The relative decisions directory for this repository.
+ *
+ * @param {string} root repository root
+ * @returns {Promise<string>} e.g. `docs/decisions`
+ */
+export async function decisionsDir(root) {
+  const declared = await manifestDecisions(root);
+  if (typeof declared?.dir === 'string' && declared.dir.trim() !== '') {
+    return declared.dir.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+  }
+  for (const candidate of DECISION_DIR_CANDIDATES) {
+    if (await isDir(join(root, candidate))) return candidate;
+  }
+  return DEFAULT_DECISIONS_DIR;
+}
+
+/**
+ * How many leading records predate structured frontmatter and are exempt from it.
+ *
+ * The package's own history is the only corpus with such records, and even it
+ * declares the number in its own manifest rather than in code: a number in code
+ * is a second answer the next record silently moves. Any other repository gets
+ * zero unless it declares otherwise.
+ *
+ * @param {string} root repository root
+ * @returns {Promise<number>}
+ */
+export async function decisionsCutoff(root) {
+  const declared = await manifestDecisions(root);
+  const value = declared?.historicalCutoff;
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return Math.floor(value);
+  return 0;
+}

package/src/decisions/index.mjs

@@ -14,13 +14,20 @@
 // such, because "no decision behind this" is exactly what a reviewer needs to
 // see and exactly what an empty output would hide.
 
-import { readFile, readdir } from 'node:fs/promises';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { readdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MANIFEST_FILE } from '../name.mjs';
 import { CLI } from '../name.mjs';
 import { PREFIX_ARGUING, TOOL_WORDS } from '../toolwords.mjs';
+import { LOCAL_DIR } from '../state.mjs';
+import { packageVersion } from '../package-version.mjs';
+// Q55: read lazily (see commandVerbs). The registry imports the `decide`
+// command, which imports this module, so touching COMMANDS during module
+// evaluation would read an initialising binding on one of the two load
+// orders. Every use below happens at runtime, when both sides are loaded.
+import { COMMANDS } from '../commands/index.mjs';
 import { PARTIAL_CLAUSE, parseDecisionFrontmatter, splitFrontmatter } from '../memory/decide.mjs';
 import { affectsTokens } from '../index/govern.mjs';
 
@@ -82,7 +89,16 @@ export function redactInternalPaths(text) {
   return String(text ?? '').replace(internalPathPattern(), 'a file in this tool');
 }
 
-const ADR_IN_TEXT = /\bADR-(\d{3})\b/g;
+// Q55: four digits and more are real record numbers, not a typo. The old `\d{3}`
+// silently dropped every citation past ADR-999, and lexical sorting put ADR-1000
+// before ADR-999 in every listing that trusted string order.
+const ADR_IN_TEXT = /\bADR-(\d{3,})\b/g;
+
+/** Numeric sort for record ids: ADR-1000 follows ADR-999, not ADR-100. */
+function compareAdrIds(a, b) {
+  const num = (id) => Number(id.replace(/^ADR-/i, ''));
+  return num(a) - num(b) || (a < b ? -1 : a > b ? 1 : 0);
+}
 
 /**
  * A line that begins one of the record's other front-matter fields.
@@ -159,7 +175,7 @@ export function citations(text) {
   for (const match of String(text ?? '').matchAll(ADR_IN_TEXT)) {
     found.add(`ADR-${match[1]}`);
   }
-  return [...found].sort();
+  return [...found].sort(compareAdrIds);
 }
 
 /**
@@ -252,7 +268,11 @@ export function parseDecision(file, text, { all = false } = {}) {
 export async function loadDecisions({ all = false, dir = DECISIONS_DIR } = {}) {
   let names;
   try {
-    names = (await readdir(dir)).filter((n) => /^ADR-\d{3,}-.*\.md$/.test(n)).sort();
+    // Numeric, so the first record `byId` keeps under a duplicate is deterministic
+    // (lint flags the collision; the load does not guess between two files).
+    names = (await readdir(dir))
+      .filter((n) => /^ADR-\d{3,}-.*\.md$/i.test(n))
+      .sort((a, b) => compareAdrIds(adrIdOf(a) ?? a, adrIdOf(b) ?? b));
   } catch (error) {
     return { ok: false, decisions: [], errors: [`${dir}: unreadable (${error.message})`] };
   }
@@ -300,11 +320,72 @@ export async function loadDecisions({ all = false, dir = DECISIONS_DIR } = {}) {
   return { ok: errors.length === 0, decisions, errors };
 }
 
+/** The record id a filename claims, or null when it claims none. */
+function adrIdOf(file) {
+  return /^ADR-(\d{3,})/i.exec(file)?.[0]?.toUpperCase() ?? null;
+}
+
 /** Index by id, for a lookup per cited ADR. */
 export function byId(decisions) {
   return new Map(decisions.map((d) => [d.id, d]));
 }
 
+/** The command verbs a record may quote, derived from the dispatch registry. */
+export function decisionVerbs() {
+  return commandVerbs();
+}
+
+/** One file's cache identity: name, size and mtime. Any write changes one of them. */
+async function fileSignature(dir, name) {
+  const st = await stat(join(dir, name));
+  return { name, size: st.size, mtimeMs: st.mtimeMs };
+}
+
+/**
+ * Load the records, reusing a machine-local cache when the tree is unchanged.
+ *
+ * Every call used to re-parse every record (`rules why` 44 ms; part of
+ * `resources/list` 771 ms). The cache lives under `.simt/local/` — machine
+ * state, never committed — and is keyed on the directory, the `all` flag, the
+ * running version and one signature per file, so an edit, an add or an upgrade
+ * all miss honestly. Best-effort throughout: any cache failure loads fresh.
+ *
+ * @param {{root: string, dir: string, all?: boolean}} input `dir` is absolute;
+ *   callers resolve it with `decisionsDir(root)` (or the package directory for
+ *   shipped records) so this loader never guesses whose records these are.
+ */
+export async function loadDecisionsCached({ root, dir, all = false } = {}) {
+  const cachePath = root ? join(root, LOCAL_DIR, 'decisions.index.json') : null;
+  let files = null;
+  try {
+    const names = (await readdir(dir)).filter((n) => /^ADR-\d{3,}-.*\.md$/i.test(n));
+    files = [];
+    for (const name of names) files.push(await fileSignature(dir, name));
+    files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  } catch {
+    return loadDecisions({ all, dir });
+  }
+  const key = { v: 1, tool: packageVersion(), dir, all, files };
+  if (cachePath) {
+    try {
+      const cached = JSON.parse(await readFile(cachePath, 'utf8'));
+      if (JSON.stringify(cached.key) === JSON.stringify(key)) return cached.result;
+    } catch {
+      // A missing or corrupt cache is a miss, never an error.
+    }
+  }
+  const fresh = await loadDecisions({ all, dir });
+  if (cachePath) {
+    try {
+      await mkdir(join(root, LOCAL_DIR), { recursive: true });
+      await writeFile(cachePath, JSON.stringify({ key, result: fresh }), 'utf8');
+    } catch {
+      // A read-only checkout keeps working uncached.
+    }
+  }
+  return fresh;
+}
+
 /**
  * What the decision actually says, in the reader's terms.
  *
@@ -506,7 +587,7 @@ const section = (name) => {
     // A record whose subject is the prefix is arguing rather than citing, so it names none.
     writtenAgainst: PREFIX_ARGUING.has(file)
       ? []
-      : [...new Set((text.match(ESTATE) ?? []).filter((name) => !TOOL_WORDS.has(name)))].sort(),
+      : [...new Set((text.match(ESTATE) ?? []).filter((name) => !TOOL_WORDS.has(name.toLowerCase())))].sort(),
   };
 }
 
@@ -545,8 +626,11 @@ const section = (name) => {
  * them - which is what this file used to do. Detection of those now depends on a name
  * never being written into shipped text, rather than on a check.
  */
-export const ESTATE_NAME =
-  /\b(?:simt-(?!dev\b)[\w-]+|repo-\d{2})\b/;
+// Q55: one shape, two flags. The estate-name pattern used to be written out twice
+// (`ESTATE_NAME` and `ESTATE`), so a shape fixed in one kept matching in the other.
+const ESTATE_SOURCE = '\\b(?:simt-(?!dev\\b)[\\w-]+|repo-\\d{2})\\b';
+
+export const ESTATE_NAME = new RegExp(ESTATE_SOURCE);
 
 /** Replace estate repository names with a phrase a reader who does not have them can use. */
 export function redactEstate(text) {
@@ -554,7 +638,7 @@ export function redactEstate(text) {
     // The tool's own names are left where they are. Redacting them turned a ruling about
     // `simt-priority` into a sentence about `a repository`, which is how a reader learned
     // that the record had surveyed something and not what it said (ADR-080).
-    TOOL_WORDS.has(name) ? name : 'a repository',
+    TOOL_WORDS.has(name.toLowerCase()) ? name : 'a repository',
   );
 }
 
@@ -575,10 +659,24 @@ export function redactEstate(text) {
  * Only a real verb follows, which is what keeps `simt-dev.json`, `simt-dev-check.yml` and
  * `simt-dev's` untouched - those are the project's artefacts and the project keeps its name.
  */
-const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|agent-hook|agent-hooks|mcp|rules|skills|graph|tokens|harness|bench|shared|evidence|index|map|tests|why|gate|impact|lessons|decide|brief|plan|--[a-z-]+)';
+// Q55: the verbs a record may quote are the commands this binary dispatches,
+// not a hand list. The list used to miss `pack`, `plugin` and `lease`, so a record
+// quoting one read as prose instead of a runnable command.
+let verbAlternation = null;
+function commandVerbs() {
+  if (verbAlternation === null) {
+    const words = new Set();
+    for (const path of COMMANDS) {
+      const first = path.split(' ')[0];
+      if (first) words.add(first.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    }
+    verbAlternation = `(?:${[...words].sort().join('|')}|--[a-z-]+)`;
+  }
+  return verbAlternation;
+}
 
 function redactCommand(text) {
-  return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${VERB})\\b`, 'g'), `${CLI} `);
+  return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${commandVerbs()})\\b`, 'g'), `${CLI} `);
 }
 
 /**
@@ -590,7 +688,7 @@ function redactCommand(text) {
  * enumerating the names here put the portfolio in every adopting repository. The records
  * themselves now carry `repo-NN` labels, so that is what this matches in practice.
  */
-const ESTATE = /\b(?:simt-(?!dev\b)[\w-]+|repo-\d{2})\b/gi;
+const ESTATE = new RegExp(ESTATE_SOURCE, 'gi');
 
 /** Trim to whole sentences within a budget, never leaving a stub fragment. */
 function sentence(text, limit = 260) {