simt-dev 0.3.0 → 0.4.0

package/src/commands/sync.mjs

@@ -28,6 +28,10 @@ import { CLI } from '../name.mjs';
 import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
 import { assertVersionPin, packageVersion } from '../package-version.mjs';
 import { resolvePacks } from '../packs.mjs';
+import { computeLock, readLock, LOCK_FILE } from '../projection/lock.mjs';
+import { runDeclaredChecks } from '../kernel/checks.mjs';
+import { DECISIONS_DIR } from '../decisions/index.mjs';
+import { lintDecisions } from '../memory/decide.mjs';
 
 /** Findings `sync` reports and does not fail on.
  *
@@ -49,7 +53,15 @@ import { resolvePacks } from '../packs.mjs';
  *  people learn to ignore. A *foreign* one — a real file or a real directory where the
  *  pointer belongs — is reported loudly with what is in the way, because that one is a
  *  decision somebody has to make. */
-export const SYNC_NON_BLOCKING = new Set(['pointer-unread', 'orphaned', 'pack-unpinned', 'budget']);
+export const SYNC_NON_BLOCKING = new Set([
+  'pointer-unread',
+  'orphaned',
+  'pack-unpinned',
+  'budget',
+  'budget-cut',
+  'file-lines-warn',
+  'check-unbuilt',
+]);
 
 /**
  * Findings `check` reports and does not fail on.
@@ -82,7 +94,11 @@ export const SYNC_NON_BLOCKING = new Set(['pointer-unread', 'orphaned', 'pack-un
 // missing file. Nothing is cut: the projection is still in full mode, so a gate that
 // failed here would be failing a repository for exceeding a ceiling it set itself,
 // with no way to fix it except lowering the number it wrote down.
-export const CHECK_NON_BLOCKING = new Set(['orphaned', 'pack-unpinned', 'budget']);
+// `budget-cut` is here for the same reason and is the second half of the same ruling
+// (ADR-083). It says the projection was cut to fit a ceiling this repository set, so the
+// remedy is a decision about the number — and a cut the repository asked for by declaring
+// a budget is the tool working, not a repository in need of a file.
+export const CHECK_NON_BLOCKING = new Set(['orphaned', 'pack-unpinned', 'budget', 'budget-cut', 'file-lines-warn', 'check-unbuilt']);
 
 export async function syncCommand(positional, flags) {
   const root = flags.root ?? positional[0] ?? process.cwd();
@@ -267,6 +283,18 @@ export async function syncCommand(positional, flags) {
       await writeFile(t.path, t.text);
       note(`wrote    ${t.file}`);
     }
+    const lock = await computeLock(root, flags);
+    const lockText = `${JSON.stringify(lock, null, 2)}\n`;
+    let previousLock = null;
+    try {
+      previousLock = await readFile(join(root, LOCK_FILE), 'utf8');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    if (previousLock !== lockText) {
+      await writeFile(join(root, LOCK_FILE), lockText);
+      note(`wrote    ${LOCK_FILE}`);
+    }
     for (const p of pointerPlan) {
       await mkdir(dirname(p.path), { recursive: true });
       // Only a symlink this tool wrote is replaced, and only because it has no content:
@@ -495,6 +523,25 @@ export async function checkCommand(positional, flags) {  const root = flags.root
     const drift = await manifestDrift(root, stack, await provenanceDigest());
     if (drift) findings.push(drift);
   }
+  if (flags.frozen) findings.push(...(await frozenFindings(root, flags)));
+  // The checkers a selected rule declared (ADR-088). They read the rule source,
+  // not the folded region, so a line that left the prompt is still the line that runs.
+  const fp = await fingerprint(root);
+  const { selected } = select(rules.filter((r) => r.error === null), fp.stack ?? [], fp.facts ?? []);
+  findings.push(...(await runDeclaredChecks(root, selected, manifest ?? null)));
+
+  const decisionsDir = join(root, 'docs', 'decisions');
+  const decisionLint = await lintDecisions(decisionsDir, {
+    allowHistorical: resolve(decisionsDir) === DECISIONS_DIR,
+  });
+  findings.push(
+    ...decisionLint.findings.map((f) => ({
+      file: ['docs', 'decisions', f.file].join('/'),
+      status: f.status,
+      detail: f.detail,
+      remedy: f.remedy,
+    })),
+  );
 
   // `CHECK_NON_BLOCKING`, not the union. This is the gate whose exit code a repository
   // acts on, so a finding it reports and does not fail on is a decision recorded in a
@@ -526,4 +573,41 @@ export async function checkCommand(positional, flags) {  const root = flags.root
   return bad.length === 0 ? EXIT.OK : EXIT.FAIL;
 }
 
-export { plan, checkTargets, checkTarget, select };
+/**
+ * What `--frozen` adds to the gate. Nothing, when the lock matches. One finding
+ * otherwise, and the wording says which of the two failures it was (ADR-086).
+ */
+async function frozenFindings(root, flags) {
+  const { lock, error } = await readLock(root);
+  if (error) {
+    return [{ file: LOCK_FILE, status: 'lock-unreadable', detail: error, remedy: `run: ${CLI} sync --yes` }];
+  }
+  if (lock === null) {
+    return [{
+      file: LOCK_FILE,
+      status: 'lock-absent',
+      detail: 'no lock is recorded',
+      remedy: `run: ${CLI} sync --yes`,
+    }];
+  }
+  const next = await computeLock(root, flags);
+  if (next.inputs !== lock.inputs) {
+    return [{
+      file: LOCK_FILE,
+      status: 'lock-stale',
+      detail: 'the inputs changed and the lock was not rewritten',
+      remedy: `run: ${CLI} sync --yes`,
+    }];
+  }
+  if (next.outputs !== lock.outputs) {
+    return [{
+      file: LOCK_FILE,
+      status: 'lock-unexplained',
+      detail: 'the projection changed and the inputs did not',
+      remedy: `run: ${CLI} sync --yes`,
+    }];
+  }
+  return [];
+}
+
+export { plan, checkTargets, checkTarget, select, frozenFindings };

package/src/commands/tests.mjs

@@ -0,0 +1,145 @@
+// `simt tests [path]` lists the tests that exercise a file (R24, ADR-092).
+//
+// The index already stores imports, but a test import that spans lines is not
+// one of them. Test files are read back from their blobs, once, in a single
+// batch. Coverage is read only from a fixed list of paths. History is the last
+// 200 non-merge commits, which is a map and not the whole changelog.
+
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { isTestPath } from '../bench/mine.mjs';
+import { blobTexts, langOf, readEdges, readFiles, reindex } from '../index/store.mjs';
+import { HISTORY, importsOf, parseCoverage, testEdges, testsFor } from '../index/tests.mjs';
+
+const exec = promisify(execFile);
+
+const COVERAGE_PATHS = [
+  'coverage/lcov.info',
+  'lcov.info',
+  'coverage/coverage-final.json',
+  'coverage.json',
+  'jacoco.xml',
+  'build/reports/jacoco/test/jacocoTestReport.xml',
+  'coverage.out',
+  'cover.out',
+];
+
+export async function testsCommand(args, flags) {
+  if (args.length > 1) return fail(`unknown tests argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} tests [path]`);
+  const root = flags.root ?? process.cwd();
+  const loaded = await loadFiles(root);
+  if (loaded.error) return loaded.error;
+  const { files } = loaded;
+  const [stored, texts, coverage, commits] = await Promise.all([
+    readEdges(root),
+    testBlobs(root, files),
+    coverageTexts(root),
+    history(root),
+  ]);
+  const paths = new Set(files.map((file) => file.path));
+  const imports = stored.filter((edge) => edge.kind === 'import');
+  for (const file of files) {
+    if (!isTestPath(file.path)) continue;
+    const text = texts.get(file.blob);
+    if (!text) continue;
+    imports.push(...importsOf(file.path, text, langOf(file.path), paths));
+  }
+  const edges = testEdges({ files, imports, coverage, commits });
+  const target = args[0];
+  if (!target) return summarise(root, flags, edges);
+  if (!paths.has(target)) {
+    return fail(`not in the index: ${target}`, EXIT.USAGE, `pass a path ${CLI} index knows`);
+  }
+  const tests = testsFor(target, edges, { cochange: flags.cochange === true });
+  const payload = { ok: true, command: 'tests', root, path: target, tests };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = [`tests    ${tests.length}`, ...tests];
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+function summarise(root, flags, edges) {
+  let test = 0;
+  let cochange = 0;
+  for (const edge of edges) {
+    if (edge.kind === 'test') test += 1;
+    else if (edge.kind === 'cochange') cochange += 1;
+  }
+  const payload = { ok: true, command: 'tests', root, test, cochange };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  emit(`test      ${test}\ncochange  ${cochange}`, { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function loadFiles(root) {
+  let files = await readFiles(root);
+  if (files.length === 0) {
+    try {
+      await reindex(root);
+    } catch (error) {
+      return {
+        error: fail(
+          `could not map tests in this repository (${error.message})`,
+          EXIT.UNSUPPORTED,
+          'run this inside a git repository',
+        ),
+      };
+    }
+    files = await readFiles(root);
+  }
+  return { files };
+}
+
+async function testBlobs(root, files) {
+  const blobs = [];
+  for (const file of files) {
+    if (isTestPath(file.path) && file.blob) blobs.push(file.blob);
+  }
+  return blobTexts(root, blobs).catch(() => new Map());
+}
+
+async function coverageTexts(root) {
+  const texts = [];
+  for (const path of COVERAGE_PATHS) {
+    try {
+      const text = await readFile(join(root, path), 'utf8');
+      if (parseCoverage(text).length > 0 || text.trim() !== '') texts.push(text);
+    } catch {
+      // Absent coverage is the usual case. It is not a failed map.
+    }
+  }
+  return texts;
+}
+
+async function history(root) {
+  let stdout = '';
+  try {
+    ({ stdout } = await exec('git', ['log', '-n', String(HISTORY), '--no-merges', '--name-only', '--pretty=format:%x1e'], {
+      cwd: root,
+      maxBuffer: 16 << 20,
+    }));
+  } catch {
+    return [];
+  }
+  const commits = [];
+  for (const block of stdout.split('\x1e')) {
+    const paths = [];
+    for (const line of block.split('\n')) {
+      const path = line.trim();
+      if (path) paths.push(path);
+    }
+    if (paths.length > 0) commits.push(paths);
+  }
+  return commits;
+}

package/src/commands/tokens.mjs

@@ -34,6 +34,7 @@ import {
   totals,
 } from '../measure/context.mjs';
 import { measureSession } from '../measure/session.mjs';
+import { sharedTotals } from '../projection/shared.mjs';
 
 /** `1234567`, never `1,234,567`. `toLocaleString` output depends on the locale, and
  *  this command exists so two machines produce two numbers a pull request can diff. */
@@ -109,7 +110,17 @@ export async function tokensCommand(positional, flags) {
   for (const path of roots) rows.push(await measureRoot(path));
   annotate(rows);
 
-  const summary = totals(rows);
+  const measured = totals(rows);
+  // The workspace copy, counted once (ADR-084). A figure that measured the regions and
+  // ignored the file the rules moved into would show a saving the reader's context never
+  // saw, so it is in the total from the first run rather than as an afterthought.
+  const shared = await sharedTotals(rows);
+  const summary = {
+    ...measured,
+    sharedBytes: shared.bytes,
+    estateBytes: measured.generatedBytes + shared.bytes,
+    sharedFiles: shared.files,
+  };
   const mcp = mcpTools();
 
   if (isJson(flags)) {
@@ -142,6 +153,15 @@ export async function tokensCommand(positional, flags) {
     lines.push(
       `totals   generated ${plain(summary.generatedBytes)} B  duplicate ${plain(summary.duplicateBytes)} B (${plain(share)}% of generated)  unique ${plain(summary.uniqueBytes)} B  repeat ${plain(summary.repeatBytes)} B  ~${plain(summary.tokens)} tokens`,
     );
+    // Only when there is a copy to count. The line a reader sees most is the one that
+    // says what their whole estate loads, and adding a second number to it that is
+    // usually zero is how a report stops being read.
+    if (summary.sharedBytes > 0) {
+      lines.push(
+        `shared   ${plain(summary.sharedBytes)} B carried once in ${plain(summary.sharedFiles.length)} user-level file(s)  estate total ${plain(summary.estateBytes)} B`,
+      );
+      for (const f of summary.sharedFiles) lines.push(`  ${f.path}  ${plain(f.bytes)} B  ${plain(f.rules)} rule(s)`);
+    }
   } else {
     const row = rows[0];
     lines.push(`tokens   ${row.path}`);
@@ -155,6 +175,15 @@ export async function tokensCommand(positional, flags) {
     lines.push(
       `always-on ${plain(row.generatedBytes)} B generated  ~${plain(row.generatedTokens)} tokens  budget ${plain(row.budget.bytes)} B  ${verdict}`,
     );
+    // The same reason as the `--repos` line, and it matters more here: measuring one
+    // repository is the default, so a reader who owns the workspace copy and never saw it
+    // counted would read a saving their own session does not get.
+    if (summary.sharedBytes > 0) {
+      lines.push(
+        `shared   ${plain(summary.sharedBytes)} B carried once in ${plain(summary.sharedFiles.length)} user-level file(s)  always-on for you: ${plain(summary.estateBytes)} B`,
+      );
+      for (const f of summary.sharedFiles) lines.push(`  ${f.path}  ${plain(f.bytes)} B  ${plain(f.rules)} rule(s)`);
+    }
     lines.push(
       `redundant ${plain(row.redundancy.duplicateBytes)} B repeats an earlier repository  ${plain(row.redundancy.repeatBytes)} B repeats an earlier document here  ${plain(row.redundancy.uniqueBytes)} B unique of ${plain(row.redundancy.blockBytes)} B counted in blocks`,
     );

package/src/commands/why.mjs

@@ -0,0 +1,172 @@
+// `simt why [path]` lists what governs a file (R25, ADR-093).
+//
+// With a path, one line per decision, rule, skill, gate and lesson. With no
+// path, the Affects tokens that name nothing this tree contains. The file list
+// is `git ls-files`. The index is not rebuilt: governance is the records, and
+// writing the cache to answer a question would change the tree.
+
+import { execFile } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { FORMATTABLE, GATES } from '../hooks/gates.mjs';
+import {
+  decisionHits,
+  scopeHits,
+  scopePaths,
+  sortHits,
+  sourceRoots,
+  unresolvedAffects,
+} from '../index/govern.mjs';
+import { splitFrontmatter } from '../memory/decide.mjs';
+import { listPromotedLessons } from '../memory/lessons.mjs';
+
+const exec = promisify(execFile);
+
+const RULE_DIRS = ['rules', 'rules/stacks', 'rules/mdc', '.simt-dev/profiles'];
+
+export async function whyCommand(args, flags, commands = []) {
+  if (args.length > 1) return fail(`unknown why argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} why [path]`);
+  const root = flags.root ?? process.cwd();
+  const listed = await tracked(root);
+  if (listed.error) return listed.error;
+  const files = new Set(listed.files);
+  const ctx = { files, commands: new Set(commands), roots: sourceRoots(files) };
+  const records = await decisionRecords(root);
+  const target = args[0];
+  if (!target) return reportUnresolved(root, flags, unresolvedAffects(records, ctx));
+  if (!files.has(target)) return fail(`not in the tree: ${target}`, EXIT.USAGE, `pass a path git tracks`);
+  const corpus = await loadCorpus(root);
+  const { hits } = decisionHits(records, target, ctx);
+  const items = sortHits([...hits, ...scopeHits(target, corpus)]);
+  const payload = { ok: true, command: 'why', root, path: target, items };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = items.map((item) => `${item.kind.padEnd(10)}${item.id}  ${item.detail}`);
+  emit(lines.length > 0 ? lines.join('\n') : 'none', { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+function reportUnresolved(root, flags, unresolved) {
+  const payload = { ok: true, command: 'why', root, unresolved };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = unresolved.map((item) => `UNRESOLVED-AFFECTS  ${item.token}  ${item.id}`);
+  emit([`unresolved  ${unresolved.length}`, ...lines].join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function tracked(root) {
+  try {
+    const { stdout } = await exec('git', ['ls-files'], { cwd: root, maxBuffer: 16 << 20 });
+    return { files: stdout.split('\n').filter(Boolean) };
+  } catch (error) {
+    return {
+      error: fail(
+        `could not read what governs files here (${error.message})`,
+        EXIT.UNSUPPORTED,
+        'run this inside a git repository',
+      ),
+    };
+  }
+}
+
+export async function decisionRecords(root) {
+  const dir = join(root, 'docs', 'decisions');
+  let names = [];
+  try {
+    names = (await readdir(dir)).filter((name) => /^ADR-\d{3,}-.*\.md$/i.test(name)).sort();
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const name of names) {
+    const text = await readFile(join(dir, name), 'utf8');
+    const { body } = splitFrontmatter(text);
+    const id = /^ADR-\d{3,}/i.exec(name)[0].toUpperCase();
+    const heading = /^#\s+(.*)$/m.exec(body)?.[1] ?? id;
+    const title = heading.replace(/^ADR-\d{3,}\s*[—–-]\s*/i, '').trim();
+    records.push({ id, title, text });
+  }
+  return records;
+}
+
+async function loadCorpus(root) {
+  const [rules, skills, lessons, commands] = await Promise.all([
+    ruleScopes(root),
+    skillScopes(root),
+    lessonScopes(root),
+    gateCommands(root),
+  ]);
+  const gates = Object.values(GATES).map((gate) => ({
+    id: gate.name,
+    detail: gate.why,
+    extensions: gate.kind === 'staged' ? FORMATTABLE : null,
+  }));
+  return { rules, skills, gates, lessons, commands };
+}
+
+export async function ruleScopes(root) {
+  const rules = [];
+  for (const dir of RULE_DIRS) {
+    let names = [];
+    try {
+      names = await readdir(join(root, dir));
+    } catch {
+      continue;
+    }
+    for (const name of names.sort()) {
+      if (!name.endsWith('.md') && !name.endsWith('.mdc')) continue;
+      const text = await readFile(join(root, dir, name), 'utf8');
+      const paths = scopePaths(text);
+      if (paths.length === 0) continue;
+      const id = /^simt-id:\s*(\S+)/m.exec(text)?.[1] ?? name;
+      const detail = /^simt-title:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? id;
+      rules.push({ id, detail, paths });
+    }
+  }
+  return rules;
+}
+
+async function skillScopes(root) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(join(root, 'graph', 'skills.graph.json'), 'utf8'));
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed?.skills)) return [];
+  return parsed.skills
+    .filter((skill) => Array.isArray(skill.paths) && skill.paths.length > 0)
+    .map((skill) => ({ id: String(skill.name ?? ''), detail: String(skill.summary ?? ''), paths: skill.paths }));
+}
+
+export async function lessonScopes(root) {
+  return (await listPromotedLessons(root))
+    .filter((lesson) => lesson.paths.length > 0)
+    .map((lesson) => ({
+      id: lesson.id,
+      detail: lesson.title,
+      paragraph: lesson.paragraph,
+      paths: lesson.paths,
+      signature: lesson.signature,
+      keywords: lesson.keywords,
+    }));
+}
+
+async function gateCommands(root) {
+  try {
+    const parsed = JSON.parse(await readFile(join(root, MANIFEST_FILE), 'utf8'));
+    const commands = parsed?.gates?.commands;
+    return commands && typeof commands === 'object' ? commands : {};
+  } catch {
+    return {};
+  }
+}