simt-dev 0.3.0 → 0.3.1

package/src/commands/impact.mjs

@@ -0,0 +1,205 @@
+// `simt impact` reports who a file or an export reaches (R23, ADR-096).
+//
+// Importers, the tests that cover them, the decisions and rules that govern
+// the file, the CODEOWNERS line, and — when a workspace is configured —
+// another repository that references a contract this change touches.
+
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { discover } from '../compare/discover.mjs';
+import { extract } from '../index/extract.mjs';
+import { importEdges, readEntries } from '../index/gate.mjs';
+import {
+  contractReferences,
+  dependents,
+  filesExporting,
+  isContractPath,
+  ownersOf,
+  relatedContracts,
+} from '../index/impact.mjs';
+import { decisionHits, scopeHits, sortHits, sourceRoots } from '../index/govern.mjs';
+import { decisionRecords, ruleScopes } from './why.mjs';
+import { resolveWorkspace } from '../workspace.mjs';
+
+const exec = promisify(execFile);
+const TEXT_EXT = new Set(['js', 'mjs', 'cjs', 'jsx', 'ts', 'tsx', 'json', 'yaml', 'yml', 'md', 'toml', 'xml', 'py', 'go', 'kt', 'java', 'rs']);
+const READ_CAP = 256 * 1024;
+const FILE_CAP = 2000;
+
+export async function impactCommand(args, flags, commands = []) {
+  if (args.length > 1) return fail(`unknown impact argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} impact <file|symbol>`);
+  const target = args[0];
+  if (!target) return fail(`a file or a symbol is required`, EXIT.USAGE, `run: ${CLI} impact <file|symbol>`);
+  const root = flags.root ?? process.cwd();
+  const listed = await tracked(root);
+  if (listed.error) return listed.error;
+  const files = new Set(listed.files);
+  const entries = await readEntries(root, files);
+  const imports = importEdges(entries);
+  const symbols = entries.flatMap((entry) => (entry.lang ? extract(entry.path, entry.text, entry.lang).symbols : []));
+  const resolved = resolveTarget(target, files, symbols);
+  if (resolved.error) return resolved.error;
+  const reach = dependents(resolved.file, imports);
+  const governs = await governance(root, resolved.file, files, commands);
+  const owners = await readOwners(root, resolved.file);
+  const contracts = await contractsFor(root, listed.files, resolved, reach.importers);
+  const consumers = await consumersFor(root, flags, basename(root), contracts);
+  const truncated = reach.truncated || consumers.truncated;
+  const payload = {
+    ok: true,
+    command: 'impact',
+    root,
+    file: resolved.file,
+    symbol: resolved.symbol,
+    importers: reach.importers,
+    tests: reach.tests,
+    governs,
+    owners,
+    consumers: consumers.references,
+    truncated,
+  };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  emit(render(payload), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+function resolveTarget(target, files, symbols) {
+  if (files.has(target)) return { file: target, symbol: '' };
+  const exported = filesExporting(target, symbols);
+  if (exported.length === 1) return { file: exported[0], symbol: target };
+  if (exported.length === 0) {
+    return { error: fail(`not a file or an export: ${target}`, EXIT.USAGE, `pass a path git tracks, or the name of one export`) };
+  }
+  return {
+    error: fail(
+      `${target} is exported by ${exported.join(', ')}`,
+      EXIT.USAGE,
+      `pass the path of the export you mean`,
+    ),
+  };
+}
+
+async function governance(root, file, files, commands) {
+  const records = await decisionRecords(root);
+  const rules = await ruleScopes(root);
+  const ctx = { files, commands: new Set(commands), roots: sourceRoots(files) };
+  const { hits } = decisionHits(records, file, ctx);
+  return sortHits([...hits, ...scopeHits(file, { rules })]);
+}
+
+async function readOwners(root, file) {
+  for (const path of ['.github/CODEOWNERS', 'CODEOWNERS', 'docs/CODEOWNERS']) {
+    try {
+      return ownersOf(await readFile(join(root, path), 'utf8'), file);
+    } catch {
+      // The next location may hold the file. GitHub reads the first that exists.
+    }
+  }
+  return [];
+}
+
+async function contractsFor(root, files, resolved, importers) {
+  const contracts = [];
+  for (const path of files) {
+    if (!isContractPath(path) && !mightSniff(path)) continue;
+    let text = '';
+    try {
+      text = await readFile(join(root, path), 'utf8');
+    } catch {
+      continue;
+    }
+    if (!isContractPath(path) && !sniffs(text)) continue;
+    contracts.push({ path, text });
+  }
+  return relatedContracts(contracts, { file: resolved.file, symbol: resolved.symbol, importers });
+}
+
+async function consumersFor(root, flags, repoName, contracts) {
+  if (contracts.length === 0) return { references: [], truncated: false };
+  const workspace = await resolveWorkspace(flags);
+  if (!workspace.root) return { references: [], truncated: false };
+  const found = await discover(workspace.root);
+  if (found.shape !== 'workspace') return { references: [], truncated: false };
+  const here = resolve(root);
+  const files = [];
+  let truncated = false;
+  for (const repo of found.repos) {
+    if (resolve(repo) === here) continue;
+    const listed = await tracked(repo);
+    if (listed.error) continue;
+    const name = basename(repo);
+    let read = 0;
+    for (const path of listed.files) {
+      if (!textExt(path)) continue;
+      if (read >= FILE_CAP) {
+        truncated = true;
+        break;
+      }
+      read += 1;
+      try {
+        const text = await readFile(join(repo, path), 'utf8');
+        if (text.length > READ_CAP) continue;
+        files.push({ repo: name, path, text });
+      } catch {
+        // A file git lists and the worktree no longer has is not a consumer.
+      }
+    }
+  }
+  const refs = contractReferences(contracts, repoName, files);
+  return { references: refs.references, truncated: truncated || refs.truncated };
+}
+
+function render(payload) {
+  const lines = [`file      ${payload.file}`];
+  if (payload.symbol) lines.push(`symbol    ${payload.symbol}`);
+  for (const path of payload.importers) lines.push(`importer  ${path}`);
+  for (const path of payload.tests) lines.push(`test      ${path}`);
+  for (const hit of payload.governs) lines.push(`${hit.kind.padEnd(10)}${hit.id}  ${hit.detail}`);
+  for (const owner of payload.owners) lines.push(`owner     ${owner}`);
+  for (const consumer of payload.consumers) lines.push(`consumer  ${consumer.repo}/${consumer.path}  ${consumer.contract}`);
+  if (payload.truncated) lines.push('truncated  1');
+  return lines.join('\n');
+}
+
+function mightSniff(file) {
+  const base = file.slice(file.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return false;
+  const ext = base.slice(dot + 1).toLowerCase();
+  return ext === 'json' || ext === 'yaml' || ext === 'yml';
+}
+
+function sniffs(text) {
+  const head = text.slice(0, 500);
+  return head.includes('"openapi"') || head.includes('"$schema"');
+}
+
+function textExt(file) {
+  const base = file.slice(file.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return false;
+  return TEXT_EXT.has(base.slice(dot + 1).toLowerCase());
+}
+
+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 the tree (${error.message})`,
+        EXIT.UNSUPPORTED,
+        'run this inside a git repository',
+      ),
+    };
+  }
+}

package/src/commands/index.mjs

@@ -45,6 +45,14 @@ import {
   benchProbesCommand,
 } from './bench.mjs';
 import { planCommand } from './plan.mjs';
+import { sharedPlanCommand, sharedInstallCommand, sharedWarning } from './shared.mjs';
+import { evidenceCommand } from './evidence.mjs';
+import { indexCommand } from './repoindex.mjs';
+import { mapCommand } from './map.mjs';
+import { testsCommand } from './tests.mjs';
+import { whyCommand } from './why.mjs';
+import { gateCommand } from './gate.mjs';
+import { impactCommand } from './impact.mjs';
 import { parse } from '../argv.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { resolveWorkspace } from '../workspace.mjs';
@@ -66,6 +74,11 @@ const GROUPS = new Map([
   ['agent-hooks', 'status'],
   ['harness', 'detect'],
   ['bench', 'mine'],
+  // ADR-084. `shared` is the one group whose default writes nothing, and it is `plan` for
+  // the same reason `skills`'s is `index`: the read answers "what would this do, and
+  // where", and `install` — the subcommand that touches a reader's home directory — is the
+  // one that needs `--yes` before it does anything.
+  ['shared', 'plan'],
 ]);
 
 /**
@@ -99,6 +112,16 @@ export const IMPLEMENTED = {
   'plan status': (args, flags) => planCommand('status', args, flags),
   'plan next': (args, flags) => planCommand('next', args, flags),
   'plan done': (args, flags) => planCommand('done', args, flags),
+  'shared plan': sharedPlanCommand,
+  'shared install': sharedInstallCommand,
+  evidence: evidenceCommand,
+  index: indexCommand,
+  map: mapCommand,
+  tests: testsCommand,
+  why: (args, flags) => whyCommand(args, flags, COMMANDS),
+  gate: gateCommand,
+  impact: (args, flags) => impactCommand(args, flags, COMMANDS),
+  'evidence check': (args, flags) => evidenceCommand(['check', ...args], flags),
   init: initCommand,
   ci: ciCommand,
   'hooks install': (args, flags) => hooksCommand('install', args, flags),
@@ -220,6 +243,13 @@ async function runDoctor(positional, flags) {
   // answer confidently wrong, so the answer is reported rather than inferred
   // (ADR-014).
   const ws = await resolveWorkspace(flags);
+  // The shared file this repository hands rules to (ADR-084). Asked here and nowhere else
+  // because it is the one thing about a repository that is true of the reader's machine
+  // rather than of the tree: `check` must not read `$HOME`, so `doctor` is the only command
+  // that can notice a region that dropped rules into a file nobody has. Reported, never
+  // blocking — a stale copy costs a reader some of their rules, which is worth knowing and
+  // is not this repository's gate failing.
+  const shared = await sharedWarning(root, result.manifest ?? null, flags);
 
   // Under `--json` the document is the whole report, so it has to carry both
   // failures the text path reports AND the workspace answer the text path prints.
@@ -254,6 +284,7 @@ async function runDoctor(positional, flags) {
         detail: ws.detail,
         error: ws.error ?? null,
       },
+      shared,
       ...(failure ?? {}),
     });
     return code;
@@ -276,6 +307,10 @@ async function runDoctor(positional, flags) {
       }`,
       `manifest ${result.manifest ? (result.manifest.error ?? result.manifest.id ?? 'present') : '(absent)'}`,
       `workspace ${ws.root ?? '(none)'}  (${ws.source}: ${ws.detail})`,
+      // Printed only when this repository handed rules to a workspace copy: a line in
+      // every `doctor` is a line in every reader's terminal, and the reader who has
+      // nothing to install is not served by one (ADR-084).
+      ...(shared.declared ? [`shared    ${shared.state}  ${shared.detail}`] : []),
     ].join('\n'),
     { maxBytes: flags.maxBytes ?? 0 },
   );

package/src/commands/map.mjs

@@ -0,0 +1,91 @@
+// `simt map` ranks the files a task is most likely to touch (R22, ADR-091).
+// The cache is read, and rebuilt once when it is empty, because a map of no
+// files is not an answer. The rebuild writes the gitignored index, which is
+// the same cache `simt index` writes.
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { readEdges, readFiles, readSymbols, reindex } from '../index/store.mjs';
+import { DEFAULT_BUDGET, formatRecall, measureRecall, rankFiles, renderMap } from '../index/map.mjs';
+
+const LEVELS = new Set(['outline', 'names', 'signatures']);
+
+export async function mapCommand(args, flags) {
+  if (args.length > 0) return fail(`unknown map argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} map`);
+  const root = flags.root ?? process.cwd();
+  if (flags.recall === true) return recall(root, flags);
+  const level = flags.level ?? 'outline';
+  if (!LEVELS.has(level)) {
+    return fail(`unknown level ${level}`, EXIT.USAGE, 'use outline, names or signatures');
+  }
+  const budget = flags.budget === undefined ? DEFAULT_BUDGET : Number(flags.budget);
+  if (!Number.isInteger(budget) || budget < 0) {
+    return fail(`budget must be a non-negative integer`, EXIT.USAGE, `run: ${CLI} map --budget 2048`);
+  }
+  const loaded = await loadGraph(root);
+  if (loaded.error) return loaded.error;
+  const task = typeof flags.task === 'string' ? flags.task : '';
+  const ranked = rankFiles({ ...loaded, task });
+  const rendered = renderMap(ranked, loaded.symbols, { level, budget });
+  const payload = {
+    ok: true,
+    command: 'map',
+    root,
+    level,
+    budget,
+    shown: rendered.shown,
+    total: rendered.total,
+    truncated: rendered.truncated,
+    files: rendered.files,
+    text: rendered.text,
+  };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = [
+    `level    ${level}`,
+    `shown    ${rendered.shown}`,
+    `total    ${rendered.total}`,
+    `budget   ${budget}`,
+  ];
+  if (rendered.text) lines.push(rendered.text);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function recall(root, flags) {
+  let result;
+  try {
+    result = await measureRecall(root);
+  } catch (error) {
+    return fail(`could not measure recall (${error.message})`, EXIT.UNSUPPORTED, `run ${CLI} index in a git repository`);
+  }
+  const payload = { ok: true, command: 'map', root, recall: result };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  emit(formatRecall(result), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function loadGraph(root) {
+  let files = await readFiles(root);
+  if (files.length === 0) {
+    try {
+      await reindex(root);
+    } catch (error) {
+      return {
+        error: fail(
+          `could not map this repository (${error.message})`,
+          EXIT.UNSUPPORTED,
+          'run this inside a git repository',
+        ),
+      };
+    }
+    files = await readFiles(root);
+  }
+  const [symbols, edges] = await Promise.all([readSymbols(root), readEdges(root)]);
+  return { files, symbols, edges };
+}

package/src/commands/repoindex.mjs

@@ -0,0 +1,52 @@
+// `simt index` rebuilds the local cache from git. The cache is not repository
+// content: it is gitignored, and a second run with the same blobs writes the same
+// rows (ADR-089).
+
+import { execFile } from 'node:child_process';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { JSONL_FILE, SQLITE_FILE, reindex } from '../index/store.mjs';
+
+export async function indexCommand(args, flags) {
+  if (args.length > 0) return fail(`unknown index argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} index`);
+  const root = flags.root ?? process.cwd();
+  let result;
+  try {
+    result = await reindex(root);
+  } catch (error) {
+    return fail(
+      `could not index this repository (${error.message})`,
+      EXIT.UNSUPPORTED,
+      'run this inside a git repository',
+    );
+  }
+  const file = result.backend === 'sqlite' ? SQLITE_FILE : JSONL_FILE;
+  const ignored = await isIgnored(root, file);
+  const payload = { ok: true, command: 'index', root, file, ignored, ...result };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = [
+    `index    ${result.backend}`,
+    `files    ${result.files}`,
+    `updated  ${result.updated}`,
+    `removed  ${result.removed}`,
+    `symbols  ${result.symbols}`,
+    `edges    ${result.edges}`,
+    `ms       ${result.ms}`,
+  ];
+  if (result.parsers === 'missing') lines.push('note     index.parsers did not load, so the built-in extractors ran');
+  if (!ignored) lines.push(`note     ${file} is not gitignored, and the cache is not meant to be committed`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+function isIgnored(root, file) {
+  return new Promise((resolve) => {
+    execFile('git', ['check-ignore', '-q', '--', file], { cwd: root }, (error) => {
+      resolve(!error);
+    });
+  });
+}