simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/src/output/index.mjs

@@ -0,0 +1,96 @@
+// Exit codes and the output layer.
+//
+// Agent tools optimise for tokens; terminal tools optimise for human eyes.
+// Same data, different rendering. Nothing here emits ANSI, prompts, spinners or
+// boxes, because a prompt is a hang for an agent and a spinner is noise in a log.
+//
+// See docs/plans/0002-simt-dev-cli.md section 6.
+
+import { CLI } from '../name.mjs';
+/** Stable machine codes. A non-zero exit always carries one of these. */
+export const EXIT = {
+  OK: 0,
+  FAIL: 1, // a gate failed: drift, policy violation, missing evidence
+  USAGE: 2, // bad arguments; the remedy is in the message
+  CONFIG: 3, // simt-dev.json missing or invalid
+  REGISTRY: 4, // skills.graph.json invalid: orphan, dangling edge, cycle
+  UNSUPPORTED: 5, // the request cannot be satisfied on this platform or repo
+};
+
+const REMEDY = {
+  [EXIT.USAGE]: 'run: simt-dev --help',
+  [EXIT.CONFIG]: `run: ${CLI} init`,
+  [EXIT.REGISTRY]: `run: ${CLI} graph lint`,
+};
+
+/**
+ * Report a failure and return its exit code. Callers `return fail(...)` so the
+ * code is impossible to forget.
+ */
+export function fail(message, code = EXIT.FAIL, remedy) {
+  // The fallback must be a command, never a path. `docs/decisions/` was the old
+  // default and it was only ever resolvable from inside simt-dev's own checkout;
+  // a reader in a consumer repo got a remedy naming a file that does not exist
+  // where they are. Every remedy here is something the reader can run.
+  const resolved = remedy ?? REMEDY[code] ?? 'run: simt-dev --help';
+  process.stderr.write(`ERROR ${code} ${message}\nREMEDY ${resolved}\n`);
+  return code;
+}
+
+/** Whether to emit plain text (default) or structured JSON. */
+export function isJson(flags) {
+  return flags.json === true;
+}
+
+/**
+ * Whether this invocation may change the filesystem, and whether it is a rehearsal.
+ *
+ * This is the only place that decides, because there was a third copy of the same
+ * arithmetic in the commands and they did not agree: `upgrade` consulted `--yes`
+ * and ignored `--dry-run`, so `--yes --dry-run` wrote; `skills install` read
+ * neither. A flag pair that means the same thing to a person must mean the same
+ * thing to every command, or `--dry-run` stops being a promise.
+ *
+ * `dryRun` is reported separately from `apply` because a run that was not
+ * authorised is a dry run in effect even when nobody asked for one, and the report
+ * has to say which happened rather than echoing the flags back.
+ */
+export function writeMode(flags) {
+  const dryRun = flags.dryRun === true;
+  return { dryRun, apply: flags.yes === true && !dryRun };
+}
+
+export function isTty() {
+  return process.stdout.isTTY === true && !process.env.NO_COLOR;
+}
+
+/**
+ * Emit a block of text under a heading, respecting --max-bytes.
+ * Truncation is always announced with an explicit line, never a silent ellipsis:
+ * an agent that cannot tell a truncated answer from a complete one will guess.
+ */
+export function emit(text, { maxBytes = 0, stream = process.stdout } = {}) {
+  const body = text.endsWith('\n') ? text : `${text}\n`;
+  const bytes = Buffer.byteLength(body);
+  if (maxBytes > 0 && bytes > maxBytes) {
+    const slice = Buffer.from(body).subarray(0, maxBytes).toString('utf8');
+    const cut = slice.lastIndexOf('\n');
+    stream.write(cut > 0 ? `${slice.slice(0, cut)}\n` : slice);
+    stream.write(`TRUNCATED ${bytes - maxBytes} bytes omitted, rerun with --max-bytes 0\n`);
+    return false;
+  }
+  stream.write(body);
+  return true;
+}
+
+export function emitJson(value, { stream = process.stdout } = {}) {
+  stream.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+/**
+ * Print to stderr so machine-readable stdout stays parseable. Used for
+ * diagnostics that accompany a real result, never for the result itself.
+ */
+export function note(message, { stream = process.stderr } = {}) {
+  stream.write(`${message}\n`);
+}

simt_dev/vendored/src/projection/baselines.mjs

@@ -0,0 +1,209 @@
+// The tooling baselines: settings that belong to the estate, in files the repo owns.
+//
+// Plan 1 section 2.2 named these as marker-managed before any of them existed —
+// "Same for `.editorconfig`, `.prettierrc`, `.gitattributes`. Local content is never
+// clobbered; shared content can never drift silently" — and this module is that
+// sentence, restricted to the files whose syntax can actually carry a region.
+//
+// The restriction is not caution, it is grammar. A region is delimited by comments,
+// so it can only live in a file that has them and whose comment character the
+// reading tool ignores. `.editorconfig` qualifies: `#` is a comment in INI and every
+// editorconfig parser honours it. `.gitattributes` qualifies for the same reason and
+// for a stronger one: `#` is a comment to git, and gitattributes is last-match-wins,
+// so the shared claim goes first and every repo's own patterns still win beneath it.
+// `tsconfig.base.json` and `.prettierrc.json` do not — JSON has no comment syntax — and
+// `.nvmrc` is a bare version string. Those three are ruled out by ADR-025 and ADR-026,
+// not deferred by accident; a managed region in a JSON file would have to be a string
+// literal that prettier and tsc both choke on.
+//
+// One value is deliberately absent from `.editorconfig`: `end_of_line`. It reads like an
+// editor setting and is not one. It decides whether a save rewrites every line of every
+// file, which is a claim about what belongs in the repository, and that claim is made in
+// `.gitattributes` where git reads it — which is why the second baseline exists. Setting
+// it in the editorconfig would have changed every checkout of every repo on the day it
+// landed, and the repo that wanted CRLF could only have opted out by deleting the
+// indentation baseline with it.
+//
+// Two values are absent for the same class of reason, and the second one is here
+// because it was shipped once and read as settled by two reviews. A formatter's own
+// options are not editorconfig properties: this file shipped `[prettier] singleQuote =
+// true`, and a section header in editorconfig is a glob over paths, so that section
+// matched a file named `prettier` and no key in it is one any reader honours — the
+// specification defines nine and `singleQuote` is not among them, and prettier's own
+// mapping reads six properties, none of them that one. It was decoration describing an
+// artefact that did not exist, and `check` could not see it because the bytes were
+// current.
+//
+// The alternative spelling does exist — prettier reads `quote_type` from a matching
+// glob — and it is deliberately not used. Three of five repositories in this estate
+// already state `singleQuote` and two do not, so a shared `quote_type = single`
+// reformats every source file in those two on the day they adopt the tool. ADR-048
+// carries the survey; the sentence is here because the next person who wants to settle a
+// formatting argument in this file needs to know it was measured, not guessed at.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { inject, parse } from './markers.mjs';
+import { STYLES } from './markers.mjs';
+
+/**
+ * The shared `.editorconfig` block.
+ *
+ * `root = true` is not decoration. An editorconfig search walks parent directories
+ * until it finds a `root = true`, so without it this repo's settings depend on
+ * whether something above it happens to have one — a baseline that changes meaning
+ * depending on where someone cloned it is not a baseline.
+ *
+ * The language sections carry only what a shared file can know: indentation, which is
+ * a property of the language and not of the project. Nothing here is a value any repo
+ * would want to argue with, which is the test it has to pass to belong in a file
+ * every repo has.
+ */
+export const EDITORCONFIG_BODY = `root = true
+
+[*]
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+# Two trailing spaces are a hard line break in Markdown. Stripping them there is not
+# tidiness; it deletes meaning the author wrote.
+trim_trailing_whitespace = false
+
+[*.{js,mjs,cjs,jsx,ts,tsx,json,jsonc,css,scss,html,yml,yaml}]
+indent_style = space
+indent_size = 2
+
+[*.{py,pyi,java,kt,kts}]
+indent_size = 4
+
+[{Makefile,*.mk}]
+indent_style = tab
+
+[{*.go,*.proto}]
+indent_style = tab`;
+
+/**
+ * The shared `.gitattributes` block.
+ *
+ * `text=auto` and not `text`. This is the whole content of the region, so it is worth
+ * saying why it is the cautious half of the choice: `* text eol=lf` forces git to treat
+ * every path as text and is the single most common way to corrupt a binary in a
+ * repository, because nothing tells git it is wrong. `auto` makes git decide per path
+ * from its own content sniffing, so a `.tif`, a `.zip` and a `.mc` file are left exactly
+ * as they are and only files that genuinely are text get normalised. One
+ * already worked this out on its own, which is the strongest evidence available that
+ * the conservative form is the one the estate would have picked.
+ *
+ * `eol=lf` is the claim ADR-025 deliberately refused to make from `.editorconfig`, and
+ * it is made here because this is where git reads it. The effect is on the working tree
+ * rather than on the editor, which is what makes it safe to share: a repo that has
+ * already committed CRLF gets LF on its next checkout, and nothing rewrites a file the
+ * moment the region lands.
+ *
+ * No `-text` on generated or vendored paths, no LFS filters, and no `linguist` or
+ * `diff` driver. Those are per-repo claims about what a file IS; a shared file that
+ * asserted them would be wrong in 13 of 16 repositories, and a wrong attribute is
+ * silently obeyed.
+ */
+export const GITATTRIBUTES_BODY = `* text=auto eol=lf`;
+
+/**
+ * Every baseline, as a row.
+ *
+ * `where` and `style` are the file's properties, not the caller's: both files here are
+ * last-definition-wins and both speak `#`, so the shared block goes first and a reader's
+ * own settings below it keep winning. `check` reports a region that has been moved down,
+ * because after the move it stops being true.
+ *
+ * @typedef {{file: string, style: string, body: () => string, why: string, adr: string}} Baseline
+ * @type {Baseline[]}
+ */
+export const BASELINES = [
+  {
+    file: '.editorconfig',
+    style: 'hash',
+    body: () => EDITORCONFIG_BODY,
+    why: 'ten repos in the estate have no editorconfig at all, so two people opening the same file see two different files',
+    adr: 'ADR-025',
+  },
+  {
+    file: '.gitattributes',
+    style: 'hash',
+    body: () => GITATTRIBUTES_BODY,
+    why: 'line endings are the estate\'s to normalise and only git can normalise them; thirteen repos have no file that says so, and one asks for the forcing form that corrupts binaries',
+    adr: 'ADR-027',
+  },
+];
+
+/**
+ * Build the write targets for every baseline.
+ *
+ * Returns the same shape `targetFor` returns for AGENTS.md, because `sync` writes one
+ * list and `check` compares against the same construction. A second shape here would
+ * be a second place computing the desired bytes, which is the defect that made the
+ * gate report drift on a clean tree before this list existed.
+ */
+export async function baselineTargets(root, sha) {
+  const targets = [];
+  for (const b of BASELINES) {
+    const path = join(root, b.file);
+    let existing = '';
+    let exists = true;
+    try {
+      existing = await readFile(path, 'utf8');
+    } catch {
+      exists = false;
+    }
+    const body = b.body();
+    // No `sources` in the provenance header. It records where the bytes came from,
+    // and for a baseline the file being written IS the source - the module in front
+    // of the reader, not a path in a tree they do not have.
+    const result = inject(existing, body, { sha }, { style: b.style });
+    targets.push({
+      file: b.file,
+      kind: 'baseline',
+      style: b.style,
+      path,
+      exists,
+      action: result.action,
+      // As on the primary target: the state the file was in, for a caller that must
+      // distinguish "no region here" from "this file is small" (ADR-049, S26).
+      region: result.region,
+      previousBody: result.previousBody,
+      reason: result.reason,
+      line: result.line,
+      bytes: Buffer.byteLength(result.text),
+      previousBytes: Buffer.byteLength(existing),
+      sha,
+      body,
+      text: result.text,
+      previous: existing,
+    });
+  }
+  return { targets };
+}
+
+/**
+ * Why a baseline is not where this module would put it.
+ *
+ * A moved region is a silent behaviour change: nothing in the region changed, `check`
+ * would call it current, and the repo's own settings would simply have stopped
+ * applying. The bytes are right and the meaning is wrong, which is the hardest kind
+ * of drift to notice, so it gets its own finding rather than a note.
+ */
+export function misplaced(region, style = 'hash') {
+  if (region.status !== 'ok') return null;
+  if (region.before.trim() === '') return null;
+  const s = STYLES[style] ?? STYLES.hash;
+  return {
+    detail:
+      'the simt-dev region is not at the top of the file, so it overrides the settings ' +
+      'below it; this format takes the last definition that matches, and the repo must win',
+    remedy: `move "${s.begin}" and "${s.end}" above your own settings, or delete the region and set what you need`,
+  };
+}
+
+export { parse };

simt_dev/vendored/src/projection/conflicts.mjs

@@ -0,0 +1,205 @@
+// Detect hand-written rules that contradict a canonical ruling, before writing
+// anything. Pure: it takes text, it never touches the filesystem.
+//
+// The distinction that matters here is conflict vs duplicate. A conflict is a rule
+// that tells an agent to do something the canonical ruling forbids. A duplicate is
+// the same rule restated in prose outside a generated region - prohibited by the
+// anti-duplication doctrine, but not a contradiction.
+//
+// The distinction is not academic. One AGENTS.md says "Do not use `uv run
+// pytest`" - which contains the forbidden string `uv run pytest` verbatim. A naive
+// substring scan reports that file as violating the very rule it is correctly
+// restating. So every match is checked for prohibition context first.
+
+/** Files whose text is a hand-written rule surface. Scanned for conflicts only;
+ *  generated regions are excluded at read time by the caller.
+ *
+ *  `.cursor/rules/*.mdc` was NOT here for the whole life of the tool, and that is
+ *  worth recording: the estate's three always-on `.mdc` families were the single
+ *  worst-drifted content in it, and `simt-dev init` reported `CONFLICTS none detected`
+ *  on the repo holding them. A conflict detector that only looks at the filenames
+ *  it was written for will quietly miss a whole rule surface added later. */
+export const RULE_FILES = ['AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md'];
+
+/** Rule files discovered by glob rather than by name. */
+export const RULE_GLOBS = ['.cursor/rules/*.mdc', '.github/instructions/*.md'];
+
+/** Every hand-written rule path in a repo, named or globbed.
+ *
+ *  The glob is split at its LAST `*`, and the two halves are used for what they
+ *  actually mean: the part before it is the directory, the part after it is either
+ *  a name prefix (`dir/*name.md`) or, when it starts with `.`, a file extension
+ *  (`dir/*.mdc`). Matching a name prefix where an extension was meant finds
+ *  nothing and reports no conflict — a detector that silently matches zero files
+ *  is indistinguishable from a repo with no rules, which is exactly the failure
+ *  this function exists to end. */
+export async function rulePaths(root) {
+  const { readdir } = await import('node:fs/promises');
+  const { join } = await import('node:path');
+  const out = RULE_FILES.map((f) => join(root, f));
+  for (const glob of RULE_GLOBS) {
+    const star = glob.lastIndexOf('*');
+    const dir = join(root, glob.slice(0, star));
+    const tail = glob.slice(star + 1);
+    const suffix = tail.startsWith('.') ? tail : null;
+    const prefix = suffix === null ? tail : '';
+    let names;
+    try {
+      names = await readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names.sort()) {
+      if (suffix !== null ? name.endsWith(suffix) : name.startsWith(prefix) && name.endsWith('.md')) {
+        out.push(join(dir, name));
+      }
+    }
+  }
+  return out;
+}
+
+const PROHIBITION = /\b(do not|do n't|don't|never|must not|mustn't|avoid|forbidden|prohibited|refuse)\b/i;
+
+/** Markdown emphasis and code spans are stripped before the prohibition test, so
+ *  `Do **not** use` reads as `Do not use` rather than as two unrelated words.
+ *  CONTRIBUTING.md writes it the bold way, which is why this is not optional. */
+function deMarkdown(text) {
+  return text.replace(/[*_`~]+/g, ' ').replace(/\s+/g, ' ');
+}
+
+/**
+ * Probes are ordered most-specific first. Each returns a match list; the caller
+ * classifies each hit by its surrounding context.
+ */
+const PROBES = [
+  {
+    id: 'autonomous-push',
+    adr: 'ADR-001',
+    canonical: 'commit locally, report the SHA, push only on explicit approval',
+    detail:
+      'asks for a push the agent performs without approval; the remote may be a production deploy',
+    // The suffix is optional on both words: garmin's DoD says "Committed and
+    // pushed", a different author wrote "Always commit and pushed", and an
+    // anchored pattern that only matched the first form reported a real
+    // autonomous-push rule as clean. `commit` also matches "commits" and
+    // "committed" because `commit?` only absorbs one `t`, not `ted`.
+    re: /\bcommit(?:te[ds]?|ting)?\s+and\s+push(?:e[ds]?|ing)?\b/gi,
+    // `push` with no suffix must match too: the group is optional, because an
+    // earlier version made it required and therefore only ever matched "pushed",
+    // reporting "commit and push without asking" as clean.
+  },
+  {
+    id: 'file-length-hard-split',
+    adr: 'ADR-005',
+    canonical: '400 lines is a review trigger, 1000 is the hard ceiling',
+    detail: 'restates one tier of the two-tier file-length ruling in prose',
+    // Two tiers must both be recognised: "split any file once it exceeds 1000
+    // lines" (the ceiling) and "keep every file under 400 lines" (the trigger).
+    // A repo restating either is not contradicting ADR-005 - the ruling was
+    // written so both positions survive as distinct tiers. It is a duplicate, and
+    // never a conflict, so this probe can only ever downgrade, never block.
+    duplicateOnly: true,
+    re: /\b(?:split (?:any )?file (?:once )?(?:it )?(?:exceeds|past)|file length:|files?\s+(?:under|below|over|max(?:imum)?\s+of))\s*\**(\d{3,4})\s*lines/gi,
+  },
+  {
+    id: 'package-runner',
+    adr: 'ADR-010',
+    canonical: 'invoke through the repository runner (npm run, uv run -m, ./gradlew), never a package runner',
+    detail: 'invokes a binary through a package runner, which resolves outside the project environment',
+    // `npx --no-install <pkg>` is exempt: it cannot fetch, so it cannot drift.
+    re: /\bnpx\s+(?!--no-install)(?:-[\w-]+\s+|[^\s-][\w@/.-]*)/g,
+  },
+  {
+    id: 'bare-console-entrypoint',
+    adr: 'ADR-010',
+    canonical: 'use the module form (uv run -m pytest), not the bare console entrypoint',
+    detail: 'the console entrypoint can miss the import path and silently run against the wrong environment',
+    re: /\buv run pytest\b(?! -m)/g,
+  },
+  {
+    id: 'lint-manually',
+    adr: 'ADR-004',
+    canonical: 'the hook owns format and lint for staged files',
+    detail: 'instructs a manual lint run that duplicates the hook',
+    re: /\brun\s+(?:ruff|eslint|lint|prettier|format)\b[^\n]{0,40}\b(?:by hand|manually)\b/gi,
+  },
+  {
+    id: 'full-suite-mandatory',
+    adr: 'ADR-003',
+    canonical: 'focused tests are the default; a full suite needs a named trigger',
+    detail: 'makes an unconditional full-suite run the gate, which ADR-003 reconciles into named triggers',
+    re: /\b(?:always run|must run|required to run) (?:the )?full (?:suite|gate|test)/gi,
+  },
+];
+
+/**
+ * Scan one document's text.
+ * @param {string} text
+ * @param {string} file display path, used only in findings
+ * @returns {Array<{severity:'conflict'|'duplicate', id, adr, file, line, quote, detail, canonical}>}
+ */
+export function scanDocument(text, file) {
+  const findings = [];
+  if (!text) return findings;
+
+  for (const probe of PROBES) {
+    probe.re.lastIndex = 0;
+    let match;
+    while ((match = probe.re.exec(text)) !== null) {
+      const quote = excerpt(text, match.index, match[0].length);
+      const context = contextBefore(text, match.index);
+      const negative = PROHIBITION.test(deMarkdown(context));
+
+      // No numeric guard: ADR-005 is two-tier and `duplicateOnly` already makes
+      // this probe incapable of producing a conflict. An earlier `n < 1000`
+      // guard looked harmless but silently dropped the entire 400-line tier.
+
+      findings.push({
+        severity: negative || probe.duplicateOnly === true ? 'duplicate' : 'conflict',
+        id: probe.id,
+        adr: probe.adr,
+        file,
+        line: lineOf(text, match.index),
+        quote,
+        detail: probe.detail,
+        canonical: probe.canonical,
+      });
+    }
+  }
+  return findings.sort((a, b) => a.line - b.line || a.id.localeCompare(b.id));
+}
+
+/** Summarise findings into the counts `init` needs to decide whether to proceed. */
+export function summarise(findings) {
+  return {
+    total: findings.length,
+    conflicts: findings.filter((f) => f.severity === 'conflict').length,
+    duplicates: findings.filter((f) => f.severity === 'duplicate').length,
+    byAdr: [...new Set(findings.map((f) => f.adr))].sort(),
+  };
+}
+
+function lineOf(text, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i += 1) {
+    if (text[i] === '\n') line += 1;
+  }
+  return line;
+}
+
+/** The text immediately before a match, used to detect prohibition context.
+ *  160 chars is wide enough to carry "Do not use ..." or "never invoke ...", and
+ *  narrow enough that an unrelated prohibition nearby cannot excuse the match. */
+function contextBefore(text, index) {
+  return text.slice(Math.max(0, index - 160), index);
+}
+
+/** A single-line quote, so a finding can be pasted into a review comment. */
+function excerpt(text, index, length, radius = 48) {
+  const from = Math.max(0, index - radius);
+  const to = Math.min(text.length, index + length + radius);
+  const slice = text.slice(from, to).replace(/\s+/g, ' ').trim();
+  return `${from > 0 ? '...' : ''}${slice}${to < text.length ? '...' : ''}`;
+}
+
+export const __internals = { PROBES, PROHIBITION };