simt-dev 0.3.0 → 0.3.1

package/src/kernel/checks.mjs

@@ -0,0 +1,378 @@
+// A marked line is enforced by a checker, so the projection keeps its name and not
+// its prose (plan 0003 R19, ADR-088).
+//
+// The unit is one list item, including the wrapped lines under it. A blank-line
+// block would be the whole section: the core rules are consecutive bullets, and
+// marking one of them must not take its neighbours with it.
+//
+// `import-direction` records nothing about which way an import may point. The
+// index has the edges (R21). A direction still has to be named before the prose
+// can leave, or the line would say Enforced and nothing would be enforcing it.
+
+import { execFile } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+export const CHECK_MARKER = 'simt-check';
+
+/** Checkers this tool can run. `import-direction` is recognised and waits on a named direction. */
+const RUNNABLE = new Set(['max-file-lines', 'forbid-regex', 'forbidden-path-edit', 'required-file']);
+
+const MARKER = /<!--\s*simt-check:\s*([^>]*?)\s*-->/g;
+const MARKER_AT = /\s*<!--\s*simt-check:\s*[^>]*?-->/g;
+const HAS_MARKER = /<!--\s*simt-check:/;
+const ITEM_START = /^(\s*)(?:[-*]|\d+\.)\s+/;
+
+/** ADR-005's two tiers, used when a repository has not named its own. */
+const DEFAULT_WARN = 400;
+const DEFAULT_ERROR = 1000;
+
+/**
+ * What is wrong with the markers in a body, or null. The same field as a
+ * frontmatter defect, so `check` needs no second way to see a broken rule.
+ */
+export function checkDefect(body) {
+  for (const unit of units(body)) {
+    if (fenced(unit)) continue;
+    const found = markersIn(unit);
+    if (found.length === 0) continue;
+    if (found.length > 1) {
+      return `carries more than one ${CHECK_MARKER} marker on one line; one line is one checker`;
+    }
+    const parsed = parseCheck(found[0]);
+    if (parsed.error) return parsed.error;
+  }
+  return null;
+}
+
+/**
+ * Replace each runnable check with one `Enforced:` line. A body with no marker
+ * is returned unchanged, so a rule nobody marked does not move a byte.
+ *
+ * @returns {{body: string, enforced: {name: string}[], changed: boolean}}
+ */
+export function foldChecks(body) {
+  if (checkDefect(body) !== null || !HAS_MARKER.test(body)) {
+    return { body, enforced: [], changed: false };
+  }
+  const enforced = [];
+  const kept = [];
+  for (const unit of units(body)) {
+    const found = fenced(unit) ? [] : markersIn(unit);
+    if (found.length === 0) {
+      kept.push(unit);
+      continue;
+    }
+    const parsed = parseCheck(found[0]);
+    if (!parsed.runnable) {
+      kept.push(stripMarkers(unit));
+      continue;
+    }
+    const indent = ITEM_START.exec(unit)?.[1] ?? '';
+    const bullet = ITEM_START.test(unit) ? '- ' : '';
+    kept.push(`${indent}${bullet}Enforced: ${parsed.name}`);
+    enforced.push({ name: parsed.name });
+  }
+  const next = kept.join('\n');
+  return { body: next, enforced, changed: next !== body };
+}
+
+/**
+ * Run the checkers the selected rules declare. A directory that is not a git
+ * repository has no tracked tree and no diff, so the checkers that need one
+ * report nothing rather than failing a repository they cannot see.
+ *
+ * @param {string} root
+ * @param {{id: string, source: string, body: string}[]} rules
+ * @param {object|null} manifest
+ */
+export async function runDeclaredChecks(root, rules, manifest) {
+  const declared = [];
+  const seen = new Set();
+  for (const rule of rules) {
+    if (checkDefect(rule.body) !== null) continue;
+    for (const unit of units(rule.body)) {
+      if (fenced(unit)) continue;
+      for (const expr of markersIn(unit)) {
+        const parsed = parseCheck(expr);
+        if (parsed.error) continue;
+        const key = `${parsed.name}\0${parsed.arg}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        declared.push({ ...parsed, source: rule.source });
+      }
+    }
+  }
+  const findings = [];
+  for (const check of declared) {
+    findings.push(...(await runOne(root, check, manifest)));
+  }
+  return findings;
+}
+
+async function runOne(root, check, manifest) {
+  if (check.name === 'import-direction') {
+    return [{
+      file: check.source,
+      status: 'check-unbuilt',
+      detail: 'import-direction has no direction to enforce; the index records imports and no rule names which way they may point',
+      remedy: 'leave the instruction in the rule until a direction is named',
+    }];
+  }
+  if (check.name === 'max-file-lines') return fileLines(root, check, manifest);
+  if (check.name === 'required-file') return requiredFile(root, check);
+  const diff = await workDiff(root);
+  if (diff === null) return [];
+  if (check.name === 'forbid-regex') return forbidRegex(check, diff);
+  return forbiddenPath(check, diff);
+}
+
+async function fileLines(root, check, manifest) {
+  const limits = manifest?.limits?.fileLines ?? {};
+  const generated = limits.generated;
+  if (generated !== undefined && !Array.isArray(generated)) {
+    return [{
+      file: 'simt.json',
+      status: 'invalid',
+      detail: 'limits.fileLines.generated must be a list of paths',
+      remedy: 'name each generated path, or remove the key',
+    }];
+  }
+  const warnAt = Number.isInteger(limits.warn) ? limits.warn : DEFAULT_WARN;
+  const errorAt = Number.isInteger(limits.error) ? limits.error : DEFAULT_ERROR;
+  const files = await tracked(root);
+  if (files === null) return [];
+  const findings = [];
+  const prefixes = Array.isArray(generated) ? generated.filter((g) => typeof g === 'string' && g !== '') : [];
+  for (const rel of files) {
+    // A committed dependency is not a file this repository wrote. Counting it
+    // fails every install of this package, because the package's own sources
+    // are longer than the ceiling the consumer declared.
+    if (rel.split('/').includes('node_modules')) continue;
+    if (exempt(rel, prefixes)) continue;
+    let text;
+    try {
+      text = await readFile(resolve(root, rel));
+    } catch {
+      continue;
+    }
+    if (text.includes(0)) continue;
+    const source = text.toString('utf8');
+    // The region marker is this tool naming itself as the generator. A path the
+    // repository names is the other exemption; a filename that looks generated is not.
+    if (source.includes('simt:generated')) continue;
+    const lines = lineCount(source);
+    if (lines > errorAt) {
+      findings.push({
+        file: rel,
+        status: 'file-lines',
+        detail: `${lines} lines, over the ceiling of ${errorAt}`,
+        remedy: 'split the file, or name its generator in limits.fileLines.generated',
+      });
+    } else if (lines > warnAt) {
+      findings.push({
+        file: rel,
+        status: 'file-lines-warn',
+        detail: `${lines} lines, over the review trigger of ${warnAt}`,
+        remedy: 'say why the file stays whole, or split it',
+      });
+    }
+  }
+  return findings;
+}
+
+async function requiredFile(root, check) {
+  const full = resolve(root, check.arg);
+  const rel = relative(root, full);
+  if (rel.startsWith('..') || rel.includes(`..${sep}`)) {
+    return [{
+      file: check.source,
+      status: 'required-file',
+      detail: `${check.arg} is outside the repository`,
+      remedy: 'name a path inside the repository',
+    }];
+  }
+  const info = await stat(full).catch(() => null);
+  if (info?.isFile()) return [];
+  return [{
+    file: check.arg,
+    status: 'required-file',
+    detail: 'a rule requires this file and it is absent',
+    remedy: `add ${check.arg}`,
+  }];
+}
+
+function forbidRegex(check, diff) {
+  let pattern;
+  try {
+    pattern = new RegExp(check.arg);
+  } catch {
+    return [];
+  }
+  const findings = [];
+  for (const file of diff.files) {
+    if (file.added.some((line) => pattern.test(line))) {
+      findings.push({
+        file: file.path,
+        status: 'forbid-regex',
+        detail: `an added line matches ${check.arg}`,
+        remedy: 'take the match out of the change',
+      });
+    }
+  }
+  return findings;
+}
+
+function forbiddenPath(check, diff) {
+  const hit = diff.files.find((file) => file.path === check.arg || file.path.startsWith(`${check.arg}/`));
+  if (!hit) return [];
+  return [{
+    file: hit.path,
+    status: 'forbidden-path',
+    detail: `${check.arg} is a path a rule says not to edit`,
+    remedy: 'edit the source the rule names, and leave this path unchanged',
+  }];
+}
+
+function parseCheck(expr) {
+  const parts = String(expr).trim().split(/\s+/);
+  const name = parts[0] ?? '';
+  const arg = parts.slice(1).join(' ');
+  if (name === 'import-direction') {
+    if (arg !== '') return { error: `${CHECK_MARKER} import-direction takes no argument` };
+    return { name, arg: '', runnable: false };
+  }
+  if (!RUNNABLE.has(name)) {
+    return { error: `${CHECK_MARKER} names "${name}", which is not a checker; the checkers are ${[...RUNNABLE, 'import-direction'].sort().join(', ')}` };
+  }
+  if (name !== 'max-file-lines' && arg === '') {
+    return { error: `${CHECK_MARKER} ${name} needs its argument` };
+  }
+  if (name === 'max-file-lines' && arg !== '') {
+    return { error: `${CHECK_MARKER} max-file-lines takes the repository's limits.fileLines, not an argument` };
+  }
+  if (name === 'forbid-regex') {
+    try {
+      RegExp(arg);
+    } catch (error) {
+      return { error: `${CHECK_MARKER} forbid-regex is not a regular expression (${error.message})` };
+    }
+  }
+  if ((name === 'forbidden-path-edit' || name === 'required-file') && (arg.startsWith('/') || arg.split('/').includes('..'))) {
+    return { error: `${CHECK_MARKER} ${name} needs a path inside the repository` };
+  }
+  return { name, arg, runnable: true };
+}
+
+function fenced(unit) {
+  return /^\s*(```|~~~)/.test(unit);
+}
+
+function markersIn(unit) {
+  return [...unit.matchAll(MARKER)].map((m) => m[1]);
+}
+
+function stripMarkers(unit) {
+  return unit.replace(MARKER_AT, '').replace(/[ \t]+$/gm, '');
+}
+
+/** Lines of a body, fences kept whole, list items split from their neighbours. */
+function units(body) {
+  const lines = String(body ?? '').split('\n');
+  const out = [];
+  let fenced = false;
+  let current = [];
+  const flush = () => {
+    if (current.length > 0) out.push(current.join('\n'));
+    current = [];
+  };
+  for (const line of lines) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      if (!fenced) flush();
+      current.push(line);
+      fenced = !fenced;
+      if (!fenced) flush();
+      continue;
+    }
+    if (fenced) {
+      current.push(line);
+      continue;
+    }
+    if (line.trim() === '') {
+      flush();
+      out.push(line);
+      continue;
+    }
+    if (ITEM_START.test(line) && current.length > 0) flush();
+    current.push(line);
+  }
+  flush();
+  return out;
+}
+
+function lineCount(text) {
+  if (text.length === 0) return 0;
+  const n = text.split('\n').length;
+  return text.endsWith('\n') ? n - 1 : n;
+}
+
+function exempt(rel, prefixes) {
+  return prefixes.some((prefix) => rel === prefix || rel.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`));
+}
+
+async function tracked(root) {
+  try {
+    const { stdout } = await exec('git', ['ls-files', '-z'], { cwd: root });
+    return stdout.split('\0').filter((p) => p !== '');
+  } catch {
+    return null;
+  }
+}
+
+async function workDiff(root) {
+  let text = '';
+  try {
+    const { stdout } = await exec('git', ['diff', '--no-ext-diff', '--unified=0', 'HEAD'], { cwd: root, maxBuffer: 8 * 1024 * 1024 });
+    text = stdout;
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    text = typeof error.stdout === 'string' ? error.stdout : '';
+  }
+  const files = parseDiff(text);
+  let untracked = [];
+  try {
+    const { stdout } = await exec('git', ['ls-files', '--others', '--exclude-standard', '-z'], { cwd: root });
+    untracked = stdout.split('\0').filter((p) => p !== '');
+  } catch {
+    return { files };
+  }
+  for (const path of untracked) {
+    let raw;
+    try {
+      raw = await readFile(resolve(root, path));
+    } catch {
+      continue;
+    }
+    if (raw.includes(0)) continue;
+    files.push({ path, added: raw.toString('utf8').split('\n') });
+  }
+  return { files };
+}
+
+function parseDiff(text) {
+  const files = [];
+  let current = null;
+  for (const line of text.split('\n')) {
+    const header = /^diff --git a\/(.+) b\/(.+)$/.exec(line);
+    if (header) {
+      current = { path: header[2], added: [] };
+      files.push(current);
+      continue;
+    }
+    if (current && line.startsWith('+') && !line.startsWith('+++')) current.added.push(line.slice(1));
+  }
+  return files;
+}

package/src/ledger/index.mjs

@@ -0,0 +1,112 @@
+// The evidence ledger (ADR-087).
+//
+// A passing command is evidence about one tree and no other. The tree is taken with a
+// private index, because `git add -A` on the real index would stage work the author had
+// left unstaged. Editing any file afterwards produces a different tree, so the old line
+// no longer proves anything about what is on disk now.
+
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { appendFile, mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+const LEDGER_FILE = '.simt-dev/ledger.jsonl';
+
+/** Phrases that claim a run happened. `unverified` and `not verified` are removed
+ *  first, because both contain the word and neither is a claim. */
+const CLAIM = /\btests?\s+pass(?:ed)?\b|\bverified\b/i;
+
+/**
+ * The tree of everything in the worktree, without staging any of it.
+ *
+ * @param {string} root
+ * @returns {Promise<string>} the write-tree id
+ */
+export async function treeId(root) {
+  const dir = await mkdtemp(join(tmpdir(), 'tree-index-'));
+  const index = join(dir, 'index');
+  const env = { ...process.env, GIT_INDEX_FILE: index };
+  try {
+    // The ledger is a record of the tree, so it cannot be part of the tree it names.
+    // `git add -A` would take it once the file exists, and the line would prove a
+    // tree that stopped existing when the line was written.
+    await exec('git', ['add', '-A', '--', '.', ':(exclude).simt-dev/ledger.jsonl'], { cwd: root, env });
+    const { stdout } = await exec('git', ['write-tree'], { cwd: root, env });
+    return stdout.trim();
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Append one run. The output itself is not stored: the digest is enough to notice a
+ * change, and a ledger that kept logs would keep whatever the command printed.
+ */
+export async function recordRun(root, { cmd, exit, ms, output }) {
+  const line = {
+    v: 1,
+    ts: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    tree: await treeId(root),
+    cmd,
+    exit,
+    ms,
+    outputDigest: `sha256-${createHash('sha256').update(output).digest('hex')}`,
+    summary: summarise(output, exit),
+  };
+  await mkdir(join(root, '.simt-dev'), { recursive: true });
+  await appendFile(join(root, LEDGER_FILE), `${JSON.stringify(line)}\n`);
+  return line;
+}
+
+/** Every well-formed line. A line that does not parse is returned as an error so a
+ *  damaged ledger cannot look empty. */
+export async function readLedger(root) {
+  let text;
+  try {
+    text = await readFile(join(root, LEDGER_FILE), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { entries: [], errors: [] };
+    throw error;
+  }
+  const entries = [];
+  const errors = [];
+  for (const [i, raw] of text.split('\n').entries()) {
+    if (raw.trim() === '') continue;
+    try {
+      const line = JSON.parse(raw);
+      if (typeof line.tree !== 'string' || typeof line.exit !== 'number') {
+        errors.push(`line ${i + 1} has no tree or exit`);
+        continue;
+      }
+      entries.push(line);
+    } catch (error) {
+      errors.push(`line ${i + 1} does not parse (${error.message})`);
+    }
+  }
+  return { entries, errors };
+}
+
+export function claimsVerification(message) {
+  const text = String(message).replace(/\bunverified\b/gi, ' ').replace(/\bnot\s+verified\b/gi, ' ');
+  return CLAIM.test(text);
+}
+
+/** `block` fails the commit. Anything unset is a warning. A third spelling is an
+ *  error, because a typo for `block` must not quietly warn. */
+export function evidenceMode(manifest) {
+  const value = manifest?.gates?.evidence;
+  if (value === undefined || value === 'warn') return 'warn';
+  if (value === 'block') return 'block';
+  return null;
+}
+
+function summarise(output, exit) {
+  const pass = /(\d+)\s+pass\b/.exec(output) ?? /\bpass\s+(\d+)/.exec(output);
+  const fail = /(\d+)\s+fail\b/.exec(output) ?? /\bfail\s+(\d+)/.exec(output);
+  if (pass || fail) return `${pass?.[1] ?? 0} pass, ${fail?.[1] ?? 0} fail`;
+  return `exit ${exit}`;
+}

package/src/measure/context.mjs

@@ -26,7 +26,12 @@ import { basename, join } from 'node:path';
 
 import { resolveSurfaces } from '../projection/surfaces.mjs';
 import { parse } from '../projection/markers.mjs';
-import { budgetFinding, DEFAULT_BUDGET_BYTES, readManifest } from '../projection/manifest.mjs';
+import {
+  budgetFinding,
+  declaredBudget,
+  DEFAULT_BUDGET_BYTES,
+  readManifest,
+} from '../projection/manifest.mjs';
 import { extractFrontmatter } from '../projection/targets.mjs';
 import { readLimitFindings } from '../projection/project.mjs';
 import { loader } from '../projection/loaders.mjs';
@@ -328,10 +333,7 @@ export async function measureRoot(root) {
 
   const generatedBytes = documents.reduce((sum, d) => sum + d.generatedBytes, 0);
   const readerBytes = documents.reduce((sum, d) => sum + d.readerBytes, 0);
-  const budgetBytes =
-    manifest?.budget?.bytes !== undefined && Number.isFinite(manifest.budget.bytes)
-      ? manifest.budget.bytes
-      : ALWAYS_ON_BUDGET_BYTES;
+  const budgetBytes = declaredBudget(manifest);
 
   const byChannel = new Map();
   for (const doc of documents) {

package/src/projection/disclosure.mjs

@@ -0,0 +1,92 @@
+// The names a reader needs before it can open anything that was kept out of the region.
+//
+// A scoped profile and an installed skill are the same situation: the body is not in the
+// file the reader loads at session start, and a reader that is not told the name will
+// never ask for it. This module reads only what the index line needs — a skill's name and
+// its description — and never the body. The body is the cost the index exists to avoid.
+
+import { readdir, readFile, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { readFrontmatter } from '../graph/spec.mjs';
+
+/**
+ * Where an installed skill can live. These are the directories `skills install` writes
+ * and the directories the loader table records, which are the same four. A fifth would
+ * be a place this tool can write a skill and then fail to tell the reader it is there.
+ */
+const SKILL_DIRS = ['.agents/skills', '.cursor/skills', '.claude/skills', '.opencode/skills'];
+
+/**
+ * The skills installed in a repository, one entry per file.
+ *
+ * A symlink fan-out is one skill: the file is counted by its real path, so the same
+ * body linked from two of these directories produces one line. Two different files that
+ * share a name both stay, because dropping one would hide a trigger.
+ *
+ * @param {string} root
+ * @returns {Promise<{name: string, trigger: string, dir: string}[]>}
+ */
+export async function installedSkills(root) {
+  const seen = new Set();
+  const skills = [];
+  for (const dir of SKILL_DIRS) {
+    let entries;
+    try {
+      entries = await readdir(join(root, dir), { withFileTypes: true });
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') continue;
+      throw error;
+    }
+    for (const entry of entries) {
+      const file = await skillFile(root, dir, entry);
+      if (file === null) continue;
+      let key;
+      try {
+        key = await realpath(file);
+      } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        throw error;
+      }
+      if (seen.has(key)) continue;
+      seen.add(key);
+      let text;
+      try {
+        text = await readFile(key, 'utf8');
+      } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        throw error;
+      }
+      const { meta } = readFrontmatter(text);
+      const fallback = entry.isDirectory() ? entry.name : entry.name.replace(/\.md$/, '');
+      const name = typeof meta.name === 'string' && meta.name !== '' ? meta.name : fallback;
+      const trigger = typeof meta.description === 'string' ? meta.description.replace(/\s+/g, ' ').trim() : '';
+      skills.push({ name, trigger, dir });
+    }
+  }
+  skills.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));
+  return skills;
+}
+
+/**
+ * The file that holds one skill, or null when the entry is not a skill.
+ *
+ * A symlink is the fan-out case: the directory a reader opens is a link, and
+ * `Dirent.isDirectory` is false for it, so treating "not a directory" as "not a
+ * skill" would index the canonical copy and then miss a repository whose only
+ * copy is the link.
+ */
+async function skillFile(root, dir, entry) {
+  const base = join(root, dir, entry.name);
+  if (entry.isDirectory() || entry.isSymbolicLink()) {
+    const nested = join(base, 'SKILL.md');
+    try {
+      await realpath(nested);
+      return nested;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  if ((entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith('.md')) return base;
+  return null;
+}