simt-dev 0.7.1 → 0.8.0

package/src/compare/hooksstate.mjs

@@ -6,16 +6,15 @@
 // duplicated-source-of-truth problem the tool exists to remove. `compare` reads it
 // for N repos, so it must not shell out per repo per event.
 
-import { execFile } from 'node:child_process';
 import { readFile, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
-import { promisify } from 'node:util';
 
 import { CHAIN_MARKER, EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderChainedShim, renderShim } from '../hooks/shim.mjs';
 import { foreignHooks, resolveHooksDir } from '../hooks/where.mjs';
 import { packageVersion, hasNpm } from '../package-version.mjs';
 import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
+import { gitText } from '../sys/git.mjs';
 
 /**
  * The Node manager id for this repository, or null without a package.json.
@@ -34,8 +33,6 @@ async function nodeManagerFor(root) {
   return resolveNodeRunner({ facts: detected.facts, packageManager }).id;
 }
 
-const exec = promisify(execFile);
-
 /**
  * The chained shim at `path`, read back out of the file itself.
  *
@@ -120,8 +117,7 @@ export function wantsShim(manifest, exists, event) {
 /** `core.hooksPath`, or null when unset or the repo is not a git repo. */
 export async function readHooksPath(root) {
   try {
-    const { stdout } = await exec('git', ['config', '--get', HOOKS_PATH_KEY], { cwd: root });
-    const value = stdout.trim();
+    const value = await gitText(root, ['config', '--get', HOOKS_PATH_KEY]);
     return value === '' ? null : value;
   } catch {
     return null;

package/src/compare/learn.mjs

@@ -19,7 +19,9 @@ import { mapCapped, DEFAULT_CONCURRENCY } from './parallel.mjs';
 
 import { policiesFor } from '../agenthooks/policy.mjs';
 import { DEL_R_TOLERANCE, parseAblationArmName } from '../bench/ablate.mjs';
-import { compareArms, evaluateRunRecord, loadPrices, loadRunRecords } from '../bench/report.mjs';
+import { evaluateRunRecord, loadPrices } from '../measure/metrics.mjs';
+import { loadRunRecords } from '../measure/records.mjs';
+import { compareArms } from '../measure/stats.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { readLedger } from '../ledger/index.mjs';
 import { readLessonCandidates } from '../memory/lessons.mjs';

package/src/decisions/index.mjs

@@ -28,7 +28,8 @@ import { packageVersion } from '../package-version.mjs';
 // 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 { PARTIAL_CLAUSE, parseDecisionFrontmatter } from '../memory/decide.mjs';
+import { parseFrontmatter } from '../text/frontmatter.mjs';
 import { affectsTokens } from '../index/govern.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -189,7 +190,7 @@ export function citations(text) {
  */
 export function parseDecision(file, text, { all = false } = {}) {
   const fm = parseDecisionFrontmatter(text);
-  const { body } = splitFrontmatter(text);
+  const { body } = parseFrontmatter(text);
   const fileId = /^ADR-(\d{3,})/i.exec(file)?.[0]?.toUpperCase();
   const heading = /^#\s+(.*)$/m.exec(body)?.[1] ?? null;
   const headId = heading ? /^(ADR-\d{3,})/i.exec(heading)?.[1]?.toUpperCase() : null;

package/src/docs/commands.mjs

@@ -0,0 +1,65 @@
+// The README's command list, rendered from the spec (review 0003 Q60).
+//
+// The README carried the fifth copy of the command list this review found. The other
+// four now come from `spec.mjs`; this one could not, because a README line is a sentence
+// for a reader rather than a table row for a parser. It does not need to be: a row's
+// `path` is the command and its `summary` is already one phrase, written for help. So the
+// list is rendered from those two fields, and `test/docs.test.mjs` fails when the README
+// and the spec stop agreeing.
+//
+// The group comment is the first word of the path, which is what a reader scans for. The
+// order is the order the spec lists groups in, so a new group lands where its author put
+// it rather than wherever it sorts.
+import { SPEC } from '../commands/spec.mjs';
+import { CLI } from '../name.mjs';
+
+export const README_FILE = 'README.md';
+export const BEGIN = '<!-- simt:commands:begin -->';
+export const END = '<!-- simt:commands:end -->';
+
+/** The fenced command list, markers included, exactly as the README must carry it. */
+export function renderCommandBlock() {
+  const groups = new Map();
+  for (const row of SPEC) {
+    const group = row.path.split(' ')[0];
+    if (!groups.has(group)) groups.set(group, []);
+    groups.get(group).push(row);
+  }
+  // The invocation, not the path: `brief` without `"<task>"` is a command a reader has
+  // to go and look up, which is what the hand-written list it replaced was for.
+  const command = (row) => `${row.path}${row.usage === undefined ? '' : ` ${row.usage}`}`;
+  const width = Math.max(...SPEC.map((row) => command(row).length));
+  const lines = [];
+  for (const [group, rows] of groups) {
+    lines.push('', `# ${group}`);
+    for (const row of [...rows].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) {
+      lines.push(`${CLI} ${command(row).padEnd(width)}  # ${row.summary}`);
+    }
+  }
+  // The first group's leading blank line would sit directly under the fence, which reads
+  // as a stray newline in the block rather than a separation.
+  if (lines[0] === '') lines.shift();
+  return [
+    BEGIN,
+    '<!-- Rendered from the spec by `simt docs readme --yes`; do not edit by hand. -->',
+    '',
+    '```sh',
+    ...lines,
+    '```',
+    END,
+  ].join('\n');
+}
+
+/**
+ * Replace the region between the markers, or return null when the file carries none.
+ *
+ * Null rather than an appended block: a README without the markers has the list somewhere
+ * else, and writing a second one beside it is the duplicated list this rendering exists
+ * to remove.
+ */
+export function replaceBlock(text, block) {
+  const start = text.indexOf(BEGIN);
+  const end = text.indexOf(END);
+  if (start === -1 || end === -1 || end < start) return null;
+  return `${text.slice(0, start)}${block}${text.slice(end + END.length)}`;
+}

package/src/ecosystem/records.mjs

@@ -0,0 +1,219 @@
+// Ecosystem and language data records.
+//
+// ADR-013: content is data, the engine is code. An ecosystem is a record under
+// `ecosystems/`, not a row in a table the engine edits. A new ecosystem arrives as a
+// new file; the engine — this loader and the views over it — never changes shape to
+// make a product work. The Dependabot entry, the card's build/focused/fallback lines,
+// the language tables and the manifest's gate rows are all READ from the same records,
+// so a product and its facets land together in one file and cannot drift apart.
+//
+// The shipped records live in `ecosystems/` at the package root. A repository may
+// override them under `.simt/ecosystems/`: a same-id record is a shallow merge over the
+// shipped one (arrays replaced whole), a new id is appended, and a record that does not
+// parse is skipped, never a crash — the shipped default wins and the reader fixes the
+// file on the next run.
+//
+// The package root is computed here rather than imported from workspace.mjs because
+// workspace.mjs imports projection/manifest.mjs, which imports this module: an import
+// cycle that would leave the binding in the temporal dead zone when manifest.mjs builds
+// its table at evaluation time. This file is two levels below the root (src/ecosystem/),
+// so two levels up is the root — a fixed path, not a heuristic.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const SHIPPED_DIR = join(PACKAGE_ROOT, 'ecosystems');
+
+/**
+ * The records in force for a repository: the shipped set, with a repo-local
+ * `.simt/ecosystems/` merged over it. `null` is the shipped set alone, which is what the
+ * const-iterating tests and every call without a root read.
+ */
+export function loadEcosystems(root = null) {
+  const base = shipped();
+  if (!root) return base;
+  const localDir = join(root, '.simt', 'ecosystems');
+  if (!existsSync(localDir)) return base;
+  const byId = new Map(base.map((r) => [r.id, r]));
+  for (const file of readdirSync(localDir)) {
+    if (!file.endsWith('.json')) continue;
+    const id = file.slice(0, -5);
+    const rec = parse(join(localDir, file));
+    if (!rec) continue;
+    // Same id: a shallow merge over the shipped record, so a local override that omits
+    // a field keeps the shipped one. New id: the record as-is.
+    byId.set(id, byId.has(id) ? { ...byId.get(id), ...rec } : rec);
+  }
+  return [...byId.values()];
+}
+
+/** The shipped records, read once per process and cached. */
+function shipped() {
+  if (shippedCache) return shippedCache;
+  const map = new Map();
+  if (existsSync(SHIPPED_DIR)) readRecords(SHIPPED_DIR, map);
+  shippedCache = [...map.values()];
+  return shippedCache;
+}
+
+let shippedCache = null;
+
+/** Read one directory of records into `into`, keyed by the file stem. */
+function readRecords(dir, into) {
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.json')) continue;
+    const id = file.slice(0, -5);
+    const rec = parse(join(dir, file));
+    // The id must match the file stem: a mismatch is a record pointing at the wrong
+    // ecosystem, and shipping it would make two names mean one record.
+    if (rec && rec.id === id) into.set(id, rec);
+  }
+}
+
+/** One record, or null when the file is absent, unreadable or does not parse. */
+function parse(path) {
+  try {
+    const rec = JSON.parse(readFileSync(path, 'utf8'));
+    return rec && typeof rec === 'object' ? rec : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The gate rows, in manifest order: one per record that declares a `manifestOrder`, the
+ * nine tool ecosystems a fresh adoption seeds gates from. `preCommit` is emitted only
+ * when present (the Maven row has none) and `file` only when set, so the rows keep the
+ * exact shape the const-iterating tests pin.
+ */
+export function ecosystemGateRows(root = null) {
+  return loadEcosystems(root)
+    .filter((r) => r.manifestOrder != null)
+    .sort((a, b) => a.manifestOrder - b.manifestOrder)
+    .map((r) => {
+      const row = { fact: r.facts[0], tool: r.tool };
+      if (r.file === true) row.file = true;
+      if (Array.isArray(r.gates?.preCommit)) row.preCommit = r.gates.preCommit;
+      if (Array.isArray(r.gates?.prePush)) row.prePush = r.gates.prePush;
+      row.commands = r.gates?.commands ?? {};
+      return row;
+    });
+}
+
+/**
+ * The Dependabot entries in the table's order. Each record contributes zero or more
+ * `{fact?|stack?, value, manifest}` rows; the order is the records' `order`, not
+ * detection's, so a config whose entry order followed readdir could not be diffed.
+ * `ecosystems()` downstream deduplicates by `value`; this view only orders and flattens.
+ */
+export function dependabotEntries(root = null) {
+  const entries = [];
+  for (const r of loadEcosystems(root)) {
+    for (const e of r.dependabot ?? []) entries.push({ ...e });
+  }
+  entries.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  return entries.map(({ order, ...rest }) => rest);
+}
+
+/** The card's build lines, in their first-match-wins order. */
+export function cardBuilds(root = null) {
+  const builds = [];
+  for (const r of loadEcosystems(root)) if (r.card?.build) builds.push({ ...r.card.build });
+  builds.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  return builds.map(({ order, ...rest }) => rest);
+}
+
+/** The card's focused-test lines, in their first-match-wins order. */
+export function cardFocused(root = null) {
+  const focused = [];
+  for (const r of loadEcosystems(root)) for (const e of r.card?.focused ?? []) focused.push({ ...e });
+  focused.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  return focused.map(({ order, ...rest }) => rest);
+}
+
+/** The card's fallback lines — verbs the gate table does not seed, used by the card alone. */
+export function cardFallbacks(root = null) {
+  const fallbacks = [];
+  for (const r of loadEcosystems(root)) for (const e of r.card?.fallback ?? []) fallbacks.push({ ...e });
+  fallbacks.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  return fallbacks.map(({ order, ...rest }) => rest);
+}
+
+/**
+ * The extension table, keyed by language. The records' `exts` are the single source; a
+ * language named by more than one record unions, so the same table the indexer extracts
+ * from and the resolver maps from cannot desynchronize.
+ */
+export function languageExts(root = null) {
+  const exts = {};
+  for (const r of loadEcosystems(root)) {
+    for (const l of r.languages ?? []) {
+      if (!Array.isArray(l.exts)) continue;
+      exts[l.lang] = exts[l.lang] ? [...new Set([...exts[l.lang], ...l.exts])] : [...l.exts];
+    }
+  }
+  return exts;
+}
+
+/**
+ * The extension-to-language map: an extension without its dot, to the language that owns
+ * it. `canonical` names the extensions that resolve to the language (the JavaScript
+ * record claims `.ts` for extraction but not for resolution); absent it, `exts` does.
+ */
+export function languageResolver(root = null) {
+  const map = {};
+  for (const r of loadEcosystems(root)) {
+    for (const l of r.languages ?? []) {
+      for (const ext of l.canonical ?? l.exts ?? []) {
+        map[ext.startsWith('.') ? ext.slice(1) : ext] = l.lang;
+      }
+    }
+  }
+  return map;
+}
+
+/**
+ * The per-language test-path conventions: one entry per language that declares
+ * `testConventions`. The miner compiles the `base` sources to regexes; a language may
+ * contribute a pattern that also matches a sibling's files (the JVM pattern matches both
+ * `.java` and `.kt`), which the caller de-duplicates.
+ */
+export function testConventions(root = null) {
+  const out = [];
+  for (const r of loadEcosystems(root)) {
+    for (const l of r.languages ?? []) {
+      if (l.testConventions) out.push({ lang: l.lang, ...l.testConventions });
+    }
+  }
+  return out;
+}
+
+/**
+ * Does a data condition match a repository's signals? A condition is one of:
+ *   {fact: 'has-x'}    one named fact
+ *   {facts: ['a','b']} any of the listed facts
+ *   {stack: 'gradle'}  one named stack tag
+ */
+export function matches(condition, { stack = new Set(), facts = new Set() } = {}) {
+  if (!condition) return false;
+  if (condition.fact) return facts.has(condition.fact);
+  if (Array.isArray(condition.facts)) return condition.facts.some((f) => facts.has(f));
+  if (condition.stack) return stack.has(condition.stack);
+  return false;
+}
+
+/**
+ * Resolve a card template. A string is the whole template, its `{placeholder}`s left for
+ * the reader. An object is the Node shape: a static default, and a dynamic form when the
+ * repository's own test script matches — the manager is the repo's committed runner, so
+ * `<manager> test -- <file>` is the ADR-010 shape (never `npx`).
+ */
+export function evalTemplate(template, { scripts = {}, runner = null } = {}) {
+  if (typeof template === 'string') return template;
+  const test = scripts?.test ?? '';
+  if (!new RegExp(template.ifScriptMatches).test(test)) return template.static;
+  const run = runner?.run ?? 'npm';
+  return template.dynamic.replaceAll('{runner}', run);
+}

package/src/explain.mjs

@@ -15,6 +15,7 @@
  * @type {Record<string, CodeRow>}
  */
 export const EXPLAIN_CODES = {
+
   absent: {
     what: 'The file the gate reads does not exist: no AGENTS.md at the repository root, so there is no region to compare.',
     why: 'ADR-025: the region is the baseline in a file the repository owns. Absence is the pre-adoption state — there is nothing to verify against yet, which is why the gate reports it instead of passing a repository it never inspected.',
@@ -93,6 +94,18 @@ export const EXPLAIN_CODES = {
     fix: 'Point gates.cwd at a directory inside this repository, or remove it.',
     example: 'gates.cwd.test set to "../shared" in a monorepo member.',
   },
+  generated: {
+    what: 'The path carries bytes this tool generates, so a write there is discarded by the next sync instead of applied.',
+    why: 'ADR-036: the region is generated text and the repository owns the prose around it. An edit inside the markers is an edit the next writer overwrites, which is why the hook refuses the write and names the source rather than letting the work disappear quietly.',
+    fix: 'Edit the source the region comes from - the rule body, or this repository manifest - then run: simt sync --yes.',
+    example: 'A hand edit inside the simt region of AGENTS.md: the write is refused with this code.',
+  },
+  'hooks-disable': {
+    what: 'The command removes or reroutes the git hooks the gates run in: core.hooksPath is unset or repointed, or the hooks directory is deleted.',
+    why: 'ADR-104: the gates run from the hooks, so a quiet reroute turns every declared gate into a suggestion while check still reports the repository as adopted. The policy reports it before the command runs, not after the gates have stopped.',
+    fix: 'If the reroute is deliberate, run: simt hooks install --yes afterwards, so the gates keep running.',
+    example: 'git config core.hooksPath .git/hooks: refused, naming the config key that matched.',
+  },
   inconsistent: {
     what: 'The project\u2019s tsconfig spells `moduleResolution` in a form the TypeScript parser accepts but the documentation does not, so it compiles and quietly disagrees with every repository that spells it the documented way.',
     why: 'The parser is case-insensitive, which is the whole reason a workspace drifts on this key: both spellings work, so nothing ever said the other one did not. Consistency with the documentation is the only spelling checkable in one repository at a time \u2014 consistency with the other repositories would need a workspace, and `check` runs in a repository on its own.',
@@ -123,6 +136,12 @@ export const EXPLAIN_CODES = {
     fix: 'Renumber the newer record to a free number, then rerun the check.',
     example: 'ADR-002-first.md and ADR-002-second.md: DUPLICATE-DECISION-ID names both.',
   },
+  lease: {
+    what: 'The path is leased by another session, so a write here collides with work happening right now.',
+    why: 'ADR-101: two sessions editing one file is the conflict no merge repairs. The lease makes the collision visible before the edit, and the report names the holder and the expiry so a wait is a number rather than a guess.',
+    fix: 'Wait for the lease TTL, edit a different file, or ask the holder to release the claim.',
+    example: 'A write to a file another session holds until 12:04: the message names the holder and the time.',
+  },
   'lock-absent': {
     what: 'No lock is recorded: the projection was never locked, so there is nothing `--frozen` can compare against.',
     why: 'ADR-086: the lock is the byte-identical contract across machines, and `--frozen` without one would compare the projection against nothing and call it current. Reported only under --frozen, because a repository that never locked is not drift.',
@@ -213,6 +232,12 @@ export const EXPLAIN_CODES = {
     fix: 'Declare simt-supersedes: [{ adr: "ADR-MMM", ruling: N }] in the record\u2019s frontmatter.',
     example: 'A status line "ruling 2 narrowed by ADR-024" with empty frontmatter: the lint names the raw clause.',
   },
+  push: {
+    what: 'The command pushes: a remote mutation, which needs explicit approval before it runs.',
+    why: 'ADR-001: a push can deploy, migrate, or rewrite a branch the remote treats as production, and the agent that ran the tests is not the one who decides to publish them.',
+    fix: 'Ask for approval first; commit locally and report the SHA in the meantime.',
+    example: 'git push origin main: refused before it runs, with the approval line to ask for.',
+  },
   reformatted: {
     what: 'The manifest\u2019s content is what simt-dev would write, but the bytes differ: another formatter owns this file\u2019s shape.',
     why: 'ADR-050: a formatter that rewrites the file on every run and a tool that rewrites it back would fight forever, with init as the only repair — which re-runs adoption to change one file\u2019s formatting. Comparing content-to-content isolates the real question: does another tool own this file.',
@@ -225,6 +250,12 @@ export const EXPLAIN_CODES = {
     fix: 'Add the file, or amend the rule if the requirement moved on.',
     example: 'A rule requiring SECURITY.md in a repo without one.',
   },
+  rewrite: {
+    what: 'The command amends, rebases, resets --hard, force-pushes or passes --no-verify: each one rewrites history or skips a declared gate.',
+    why: 'ADR-017: the gates are the contract, and every one of these forms is the escape that turns them into a suggestion. A skipped gate leaves no trace for the next reader, which is why the policy refuses rather than warns.',
+    fix: 'Commit a new commit instead, or ask for approval before rewriting history.',
+    example: 'git commit --amend, git reset --hard, git push --force: each reports this code and the flag that matched.',
+  },
   'stale-generated-field': {
     what: 'Generated manifest fields do not match what simt-dev writes: the projection SHA, the stack, or the version pin drifted without a re-run.',
     why: 'ADR-050: sync repairs exactly this field set and nothing else, so init\u2019s re-adoption is never the repair for a stale field. check names the fields; sync rewrites them.',