simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/src/hooks/dispatcher.mjs

@@ -0,0 +1,268 @@
+// Run the gates a repo declares for a hook event.
+//
+// Design commitments, all of them load-bearing:
+//
+//   Fail closed, never fail open. A gate that cannot run is a failure, not a
+//   skip. A repository removed tests from pre-commit because they were slow, and
+//   the documented consequence was that authors reached for --no-verify. A
+//   dispatcher that skips what it cannot do reproduces exactly that.
+//
+//   Never weaken a control to make a hook pass. If a gate fails, the gate
+//   fails. There is no "warn and continue" mode, and no gate can be downgraded
+//   from inside the hook - only from the manifest, where a reviewer sees it.
+//
+//   Format and lint are staged-only. (ADR-004) Formatting the whole working
+//   tree from a pre-commit hook would rewrite files the author did not stage and
+//   did not ask to change.
+//
+//   Report what did not run. The summary names every gate, its disposition and
+//   its reason, so "passed" can never be mistaken for "only some of it passed".
+
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { GATES } from './gates.mjs';
+import { resolveGate } from './resolve.mjs';
+import { CLI } from '../name.mjs';
+import { MANIFEST_FILE } from '../name.mjs';
+
+const exec = promisify(execFile);
+
+/** Gates that are known but not required for the event to pass. */
+export const DEFAULT_EVENTS = { 'pre-commit': 'preCommit', 'pre-push': 'prePush' };
+
+/**
+ * @param {string} event 'pre-commit' | 'pre-push'
+ * @param {object} ctx
+ * @param {string} ctx.root
+ * @param {object} ctx.manifest parsed simt-dev.json, or null
+ * @returns {Promise<{event: string, gates: object[], failed: boolean}>}
+ */
+export async function runGates(event, { root, manifest }) {
+  const key = DEFAULT_EVENTS[event];
+  if (key === undefined) {
+    return { event, gates: [], failed: true, error: `unknown hook event ${event}` };
+  }
+
+  const declared = manifest?.gates?.[key];
+  if (!Array.isArray(declared) || declared.length === 0) {
+    // An array, not a string. This field sat next to `gates` as a bare string while
+    // the caller iterated it, so an empty gate list printed one note line per
+    // character — 180 lines of noise in a hook whose only job is to be readable.
+    // Only reachable on a repo that has no formatter and no linter, so the one path
+    // where an author's patience is already spent.
+    return {
+      event,
+      gates: [],
+      failed: false,
+      notes: [
+        `nothing runs on ${event}: ${MANIFEST_FILE} declares no gates.${key}. That is a valid ` +
+          `answer when the repo has no tool for any of them - \`${CLI} check\` reports each ` +
+          `gate it could not run and why - but it is also what an unfiltered default looks like.`,
+      ],
+    };
+  }
+
+  const pkg = await readPkg(root);
+  const staged = event === 'pre-commit' ? await stagedFiles(root) : [];
+  const unstaged = event === 'pre-commit' ? await unstagedFiles(root) : new Set();
+  const commands = manifest?.gates?.commands;
+  const results = [];
+  // What the format gate rewrote, so restage touches those files and nothing else.
+  let formatted = [];
+
+  for (const name of declared) {
+    const gate = GATES[name];
+    if (gate === undefined) {
+      results.push({
+        name,
+        status: 'failed',
+        detail: `unknown gate; the shared dispatcher knows: ${Object.keys(GATES).sort().join(', ')}`,
+        remedy: `remove "${name}" from ${MANIFEST_FILE} gates.${key}`,
+        adr: null,
+      });
+      continue;
+    }
+
+    const resolution = await resolveGate(gate, { root, pkg, staged, commands });
+    if (!resolution.ok) {
+      results.push({
+        name,
+        status: 'failed',
+        detail: resolution.reason,
+        remedy: resolution.remedy,
+        adr: gate.adr,
+      });
+      continue;
+    }
+    if (resolution.argv === null) {
+      results.push({ name, status: 'skipped', detail: resolution.detail, adr: gate.adr, exitCode: null });
+      continue;
+    }
+
+    // A formatter rewrites the WORKING TREE copy of the files it is given, so
+    // handing it a file that also has unstaged changes destroys work the author
+    // staged around deliberately. `git add -p` exists so a commit can carry part
+    // of a file; formatting first and re-adding the whole thing silently throws
+    // the rest away, which is ADR-004's exact prohibition on the one path that
+    // runs on every commit. Refuse rather than stash: a hook that guesses what the
+    // author meant is worse than a hook that says so.
+    if (gate.kind === 'staged') {
+      // The resolved staged tool is handed an explicit file list, so the targets are
+      // known. A `gates.commands` declaration is an arbitrary command line - it may
+      // take a directory or a glob rather than paths - so every staged file with
+      // unstaged changes is treated as at risk, because nothing here can tell.
+      const targets = resolution.declared === true ? staged : resolution.argv.slice(2);
+      const conflicts = targets.filter((f) => unstaged.has(f));
+      if (conflicts.length > 0) {
+        results.push({
+          name,
+          status: 'failed',
+          detail: `${conflicts.length} staged file(s) also have unstaged changes: ${conflicts.join(', ')}`,
+          remedy:
+            `stage the whole file (git add ${conflicts[0]}) so the formatter sees all of it, ` +
+            `or run the formatter yourself and stage the result`,
+          adr: gate.adr,
+        });
+        continue;
+      }
+      formatted = targets;
+    }
+
+    const outcome = await run(resolution.argv, root);
+    results.push({
+      name,
+      status: outcome.code === 0 ? 'passed' : 'failed',
+      detail: `${resolution.detail}${outcome.code === 0 ? '' : `: exit ${outcome.code}`}`,
+      output: outcome.code === 0 ? '' : tail(outcome.stderr || outcome.stdout),
+      adr: gate.adr,
+      exitCode: outcome.code,
+    });
+  }
+
+  // A formatter that rewrote staged files must re-stage them, or the commit
+  // records the unformatted bytes while the working tree holds the formatted
+  // ones. This is the one case where the hook mutates the index on purpose.
+  //
+  // Only the files the formatter was actually given, and only when their staged
+  // bytes really moved. This used to `git add` every staged path from
+  // `--name-only` with no `--diff-filter`, so a commit containing a deletion made
+  // the add fail, the catch swallowed it, and the hook reported success while the
+  // commit recorded unformatted bytes. It also claimed to have re-staged files
+  // whenever anything was staged, formatted or not.
+  if (results.some((r) => r.name === 'format' && r.status === 'passed')) {
+    const outcome = await restage(root, formatted);
+    if (outcome.error) {
+      results.push({
+        name: 'restage',
+        status: 'failed',
+        detail: `the formatter passed but its output could not be staged: ${outcome.error}`,
+        remedy: 'stage the formatted files yourself and commit again',
+        adr: null,
+        exitCode: null,
+      });
+    } else if (outcome.restaged.length > 0) {
+      results.push({
+        name: 'restage',
+        status: 'passed',
+        detail: `re-staged ${outcome.restaged.length} file(s) the formatter rewrote: ${outcome.restaged.join(', ')}`,
+        adr: null,
+        exitCode: 0,
+      });
+    }
+  }
+
+  return { event, gates: results, failed: results.some((r) => r.status === 'failed') };
+}
+
+async function run(argv, cwd) {
+  try {
+    const { stdout, stderr } = await exec(argv[0], argv.slice(1), { cwd, maxBuffer: 8 * 1024 * 1024 });
+    return { code: 0, stdout, stderr };
+  } catch (error) {
+    return { code: typeof error.code === 'number' ? error.code : 1, stdout: error.stdout ?? '', stderr: error.stderr ?? String(error.message ?? error) };
+  }
+}
+
+async function readPkg(root) {
+  try {
+    return JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Staged paths, or [] when git cannot answer (an unborn branch, for instance). */
+export async function stagedFiles(root) {
+  try {
+    const { stdout } = await exec('git', ['diff', '--cached', '--name-only', '--diff-filter=ACMR'], { cwd: root });
+    return stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Paths whose working-tree copy differs from the index - the ones a partial stage
+ * leaves behind. Read as a Set because every stage check is a membership test over
+ * the same staged list, and this is asked once per run.
+ *
+ * A path staged as DELETED is not here: the index and the working tree agree that
+ * it is gone, so there is no unstaged work to protect and no reason to refuse.
+ */
+export async function unstagedFiles(root) {
+  try {
+    const { stdout } = await exec('git', ['diff', '--name-only'], { cwd: root });
+    return new Set(stdout.split('\n').map((s) => s.trim()).filter(Boolean));
+  } catch {
+    return new Set();
+  }
+}
+
+/** The staged blob hash for each path, or an empty map if git cannot answer. */
+async function stagedBlobs(root, files) {
+  if (files.length === 0) return new Map();
+  try {
+    const { stdout } = await exec('git', ['ls-files', '-s', '--', ...files], { cwd: root });
+    const blobs = new Map();
+    for (const line of stdout.split('\n')) {
+      const [meta, ...rest] = line.split('\t');
+      if (rest.length === 0) continue;
+      const [, sha] = meta.trim().split(/\s+/);
+      blobs.set(rest.join('\t'), sha ?? null);
+    }
+    return blobs;
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * Stage the formatter's output, and report which paths actually moved.
+ *
+ * The before/after blob comparison is the whole point: a formatter that rewrote
+ * nothing is a pass with nothing to report, and a hook that claims otherwise has
+ * trained its readers to distrust the lines that matter.
+ */
+async function restage(root, files) {
+  if (files.length === 0) return { restaged: [], error: null };
+  const before = await stagedBlobs(root, files);
+  try {
+    await exec('git', ['add', '--', ...files], { cwd: root });
+  } catch (error) {
+    return { restaged: [], error: String(error.stderr ?? error.message ?? error).trim() };
+  }
+  const after = await stagedBlobs(root, files);
+  const restaged = files.filter((f) => before.get(f) !== after.get(f));
+  return { restaged, error: null };
+}
+
+/** Last few lines of output, for a failure a human or agent has to act on. */
+function tail(text, lines = 12) {
+  const parts = String(text).trimEnd().split('\n');
+  return parts.slice(-lines).join('\n');
+}
+
+export const __internals = { tail, basename };

simt_dev/vendored/src/hooks/gates.mjs

@@ -0,0 +1,144 @@
+import { MANIFEST_FILE } from '../name.mjs';
+// Gate definitions for the shared hook dispatcher.
+//
+// A gate has one of three kinds, and the choice is not cosmetic:
+//
+//   staged   run a formatter over the STAGED FILES ONLY, then re-stage them.
+//            Whole-repo formatting from a pre-commit hook would rewrite
+//            unstaged work the author did not ask to touch.
+//   script   run a script the repo already declares. Correct for anything
+//            global: tests, typecheck, coverage.
+//   command  run a command the MANIFEST declares. Correct for gates that are
+//            genuinely repo-specific - ConnectIQ memory budgets, codegen
+//            drift, i18n completeness - because the central dispatcher cannot
+//            know what monkeyc or a Kotlin script path looks like in one repo
+//            and something else in another. Plan 0001 section 3.2 keeps repo
+//            commands and paths local; this is that ruling in code.
+//
+// ADR-010 note: no gate invokes `npx` or `npm exec`. Script gates go through
+// `npm run`, and staged gates resolve the formatter from the project's own
+// `node_modules/.bin`, which is the declared dependency's binary rather than
+// one fetched at hook time.
+
+export const GATE_KINDS = new Set(['staged', 'script', 'command']);
+
+/** Extensions a `staged` formatter gate will hand to the tool. */
+export const FORMATTABLE = new Set([
+  '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.json', '.jsonc',
+  '.css', '.less', '.scss', '.html', '.md', '.yml', '.yaml', '.graphql',
+]);
+
+/**
+ * @typedef {{name: string, kind: 'staged'|'script'|'command', adr: string,
+ *            script?: string, tools?: string[], why: string}} Gate
+ */
+
+/** @type {Record<string, Gate>} */
+export const GATES = {
+  format: {
+    name: 'format',
+    kind: 'staged',
+    adr: 'ADR-004',
+    tools: ['prettier'],
+    why: 'the hook owns format for staged files, so an author never commits unformatted work',
+  },
+  lint: {
+    name: 'lint',
+    kind: 'script',
+    adr: 'ADR-004',
+    script: 'lint',
+    why: 'the hook owns lint; re-running it by hand is what ADR-004 tells agents not to do',
+  },
+  typecheck: {
+    name: 'typecheck',
+    kind: 'script',
+    adr: 'ADR-010',
+    script: 'typecheck',
+    why: 'not hook-covered evidence: a type error is not a style error',
+  },
+  test: {
+    name: 'test',
+    kind: 'script',
+    adr: 'ADR-003',
+    script: 'test',
+    why: 'the focused gate every commit must pass before review',
+  },
+  coverage: {
+    name: 'coverage',
+    kind: 'script',
+    adr: 'ADR-006',
+    script: 'test:coverage',
+    why: 'the numeric bar is declared per repo, so this gate is opt-in rather than assumed',
+  },
+  'i18n-completeness': {
+    name: 'i18n-completeness',
+    kind: 'command',
+    adr: 'ADR-010',
+    why: 'repo-specific: every repo spells this check differently, so the manifest declares the command',
+  },
+  memory: {
+    name: 'memory',
+    kind: 'command',
+    adr: 'ADR-003',
+    why: 'ConnectIQ memory budgets are a hard platform limit; the repo declares the script that proves it',
+  },
+  'codegen-drift': {
+    name: 'codegen-drift',
+    kind: 'command',
+    adr: 'ADR-002',
+    why: 'a protocol change is a two-repo change; the drift check is what makes half of it fail loudly',
+  },
+};
+
+export function getGate(name) {
+  return GATES[name] ?? null;
+}
+
+/**
+ * A gate a repo cannot run is a FAILURE, never a skip.
+ *
+ * This is the load-bearing decision of the whole dispatcher. A gate that
+ * silently does nothing is indistinguishable from a gate that passed, and the
+ * documented consequence in this estate is an agent reaching for
+ * `--no-verify` - a repository removed its tests from pre-commit precisely
+ * because they were slow, and slow-plus-silent is what teaches everyone that
+ * hooks are advisory.
+ */
+export function unresolved(name, { hasScript, binary, command, stack }) {
+  const gate = getGate(name);
+  if (gate === null) {
+    return {
+      gate: name,
+      reason: `unknown gate; the shared dispatcher knows: ${Object.keys(GATES).sort().join(', ')}`,
+      remedy: `remove "${name}" from ${MANIFEST_FILE} gates`,
+    };
+  }
+  if (gate.kind === 'script' && !hasScript(gate.script)) {
+    return {
+      gate: name,
+      reason: `no "${gate.script}" script in package.json`,
+      remedy: `add the script, or remove "${name}" from ${MANIFEST_FILE} gates`,
+    };
+  }
+  if (gate.kind === 'command' && !command) {
+    return {
+      gate: name,
+      reason: `no command declared for this gate in ${MANIFEST_FILE}`,
+      remedy: `set gates.commands["${name}"] to the command that proves it, or remove "${name}" from ${MANIFEST_FILE} gates`,
+    };
+  }
+  if (gate.kind === 'staged' && !binary) {
+    return {
+      gate: name,
+      reason: `${gate.tools.join('/')} is not installed in node_modules/.bin`,
+      remedy: `run the repo install command, or remove "format" from ${MANIFEST_FILE} gates`,
+    };
+  }
+  return null;
+}
+
+export function gateNames() {
+  return Object.keys(GATES).sort();
+}
+
+export const __internals = { FORMATTABLE, GATES };

simt_dev/vendored/src/hooks/resolve.mjs

@@ -0,0 +1,194 @@
+// Resolve a gate to something executable, or explain precisely why it cannot be.
+//
+// Every failure mode returns a remedy the author can act on without reading
+// this source. That is the difference between a hook people keep and a hook
+// people disable: a hook that fails vaguely gets `--no-verify`, and once
+// `--no-verify` is normal, no hook in the estate means anything.
+//
+// ADR-010: nothing here invokes `npx` or `npm exec`. Script gates go through
+// `npm run`, and staged gates resolve the formatter from the project's own
+// `node_modules/.bin` - the declared dependency's binary, not one fetched at
+// hook time.
+
+import { access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+
+import { FORMATTABLE, GATES, GATES as _G } from './gates.mjs';
+import { MANIFEST_FILE } from '../name.mjs';
+
+/** Gate names the shared dispatcher knows, sorted. */
+export function knownGates() {
+  return Object.keys(GATES).sort();
+}
+
+export function gateKind(name) {
+  return GATES[name]?.kind ?? null;
+}
+
+export function gateWhy(name) {
+  return GATES[name]?.why ?? null;
+}
+
+export function gateAdr(name) {
+  return GATES[name]?.adr ?? null;
+}
+
+/**
+ * Is this path an executable file?
+ * @param {string} path
+ */
+export async function isExecutable(path) {
+  try {
+    await access(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the formatter binary a `staged` gate should invoke.
+ *
+ * Prettier is required because ADR-004 makes format a staged-files obligation
+ * and the estate's single agreed formatter is prettier. A repo without it gets a
+ * failure with a remedy, never a silent pass.
+ */
+export async function resolveStagedTool(root, gate) {
+  const tools = gate.tools ?? [];
+  const tried = [];
+  for (const tool of tools) {
+    const path = join(root, 'node_modules', '.bin', tool);
+    if (await isExecutable(path)) return { tool, path, tried };
+    tried.push(path);
+  }
+  return { tool: null, path: null, tried };
+}
+
+/** Does package.json declare this script? */
+export function hasScript(pkg, script) {
+  if (!pkg || typeof pkg.scripts !== 'object' || pkg.scripts === null) return false;
+  return typeof pkg.scripts[script] === 'string' && pkg.scripts[script].length > 0;
+}
+
+/**
+ * Build the argv for a gate, or return a structured refusal.
+ *
+ * @param {object} gate
+ * @param {object} ctx
+ * @param {string} ctx.root
+ * @param {object|null} ctx.pkg parsed package.json, or null when absent
+ * @param {string[]} ctx.staged staged paths (empty for pre-push)
+ * @param {Record<string,string>|undefined} ctx.commands manifest gates.commands
+ * @returns {Promise<{ok: true, argv: string[], kind: string, detail: string}
+ *                  | {ok: false, gate: string, kind: string, reason: string, remedy: string}>}
+ */
+export async function resolveGate(gate, { root, pkg, staged, commands }) {
+  const name = gate.name;
+  const declared = commands?.[name];
+
+  // A declared command wins for EVERY kind, not just `command` gates.
+  //
+  // This is what makes `gates.commands` the ecosystem escape hatch it is advertised as.
+  // A Gradle repo has no `test` npm script and never will, so `test` is declared as
+  // `command` kind instead — but the repo also has no `npm run lint` for a gate named
+  // `lint`, or a prettier for `format`. In each case the reader is told, by this tool's
+  // own remedy, to "name the program under gates.commands"; a dispatcher that then
+  // ignored that declaration would contradict the remedy, and so would `check`.
+  if (declared) {
+    const argv = declared.trim().split(/\s+/).filter(Boolean);
+    if (argv.length === 0) {
+      return {
+        ok: false,
+        gate: name,
+        kind: gate.kind,
+        reason: `gates.commands["${name}"] is empty`,
+        remedy: `set gates.commands["${name}"] to the command that proves it, or remove "${name}" from ${MANIFEST_FILE} gates`,
+      };
+    }
+    return {
+      ok: true,
+      kind: gate.kind,
+      argv,
+      // The dispatcher has to know whether these argv entries are paths it chose or
+      // words it was handed. Sniffing the detail string meant the safety guard on
+      // partial stages would quietly stop working the day that wording changed.
+      declared: true,
+      detail: `declared command: ${declared}`,
+    };
+  }
+
+  if (gate.kind === 'staged') {
+    const tool = await resolveStagedTool(root, gate);
+    if (tool.path === null) {
+      return {
+        ok: false,
+        gate: name,
+        kind: gate.kind,
+        reason: `no formatter binary in node_modules/.bin (looked for ${(gate.tools ?? []).join(', ')})`,
+        remedy: `run the repo install command, or remove "format" from ${MANIFEST_FILE} gates`,
+      };
+    }
+    const files = staged.filter((f) => FORMATTABLE.has(extname(f)));
+    if (files.length === 0) {
+      return {
+        ok: true,
+        kind: gate.kind,
+        argv: null, // nothing to do; the dispatcher reports this as a pass with a count
+        detail: `no staged files this gate handles (looked for ${[...FORMATTABLE].join(', ')})`,
+      };
+    }
+    return {
+      ok: true,
+      kind: gate.kind,
+      argv: [tool.path, '--write', ...files],
+      detail: `${files.length} staged file(s) via node_modules/.bin/${tool.tool}`,
+    };
+  }
+
+  if (gate.kind === 'script') {
+    const script = gate.script;
+    if (!hasScript(pkg, script)) {
+      return {
+        ok: false,
+        gate: name,
+        kind: gate.kind,
+        reason: `package.json declares no "${script}" script`,
+        remedy: `add "${script}" to scripts, or remove "${name}" from ${MANIFEST_FILE} gates`,
+      };
+    }
+    return {
+      ok: true,
+      kind: gate.kind,
+      argv: ['npm', 'run', '--silent', script],
+      detail: `npm run ${script}`,
+    };
+  }
+
+  if (gate.kind === 'command') {
+    if (!declared) {
+      return {
+        ok: false,
+        gate: name,
+        kind: gate.kind,
+        reason: `no command declared for this gate in ${MANIFEST_FILE}`,
+        remedy: `set gates.commands["${name}"] to the command that proves it, or remove "${name}" from ${MANIFEST_FILE} gates`,
+      };
+    }
+  }
+
+  return {
+    ok: false,
+    gate: name,
+    kind: 'unknown',
+    reason: `unknown gate kind "${gate.kind}"`,
+    remedy: `this is a bug in simt-dev; known gates: ${knownGates().join(', ')}`,
+  };
+}
+
+function extname(path) {
+  const dot = path.lastIndexOf('.');
+  return dot > 0 ? path.slice(dot).toLowerCase() : '';
+}
+
+export const __internals = { extname, FORMATTABLE };