simt-dev 0.2.0 → 0.2.2

package/src/projection/manifest.mjs

@@ -29,6 +29,7 @@ import { getGate } from '../hooks/gates.mjs';
 // file by name.
 import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
 import { CLI } from '../name.mjs';
+import { packageVersion } from '../package-version.mjs';
 export const MANIFEST = MANIFEST_FILE;
 
 export { MANIFEST_LEGACY };
@@ -98,6 +99,93 @@ const TAG_GATES = [
   { tag: 'hono', preCommit: ['i18n-completeness'] },
 ];
 
+/**
+ * The ecosystems that produce a fact rather than a stack tag, and what a fresh
+ * adoption of one should declare.
+ *
+ * A row proposes gates the way `GATES_BY_STACK` does, and the fact it keys on is
+ * the same signal a profile's `simt-applies` names, so one marker file reaches
+ * both: the region this repo reads and the gates its commits run.
+ *
+ * `commands` is what a FRESH manifest declares for each proposed gate, and it is
+ * written only when the probe in `readCapability` found `tool` where this row says
+ * it lives. A declared gate that cannot run blocks every commit, so a command is
+ * never declared on the faith of a marker file: the marker says the ecosystem is
+ * here, the probe says its program can run (ADR-017). A command the repo already
+ * declared wins over the seed, because a seed is a default and a declaration is a
+ * choice.
+ *
+ * `file` marks a tool that is a file in the repository rather than a binary on
+ * PATH: the Maven wrapper, probed the way this tool already probes `gradlew`.
+ */
+export const ECOSYSTEMS = [
+  {
+    fact: 'has-cargo-toml',
+    tool: 'cargo',
+    preCommit: ['format', 'lint'],
+    prePush: ['test'],
+    commands: { format: 'cargo fmt --check', lint: 'cargo clippy -- -D warnings', test: 'cargo test' },
+  },
+  {
+    fact: 'has-go-mod',
+    tool: 'go',
+    preCommit: ['format', 'lint'],
+    prePush: ['test'],
+    commands: { format: 'test -z "$(gofmt -l .)"', lint: 'go vet ./...', test: 'go test ./...' },
+  },
+  {
+    fact: 'has-nuget',
+    tool: 'dotnet',
+    preCommit: ['format'],
+    prePush: ['test', 'typecheck'],
+    commands: { format: 'dotnet format --verify-no-changes', test: 'dotnet test', typecheck: 'dotnet build -warnaserror' },
+  },
+  {
+    fact: 'has-swift-package',
+    tool: 'swift',
+    preCommit: ['format'],
+    prePush: ['test', 'typecheck'],
+    commands: { format: 'swift format lint -r .', test: 'swift test', typecheck: 'swift build' },
+  },
+  {
+    fact: 'has-deno-config',
+    tool: 'deno',
+    preCommit: ['format', 'lint'],
+    prePush: ['test', 'typecheck'],
+    commands: { format: 'deno fmt --check', lint: 'deno lint', test: 'deno test', typecheck: 'deno check .' },
+  },
+  {
+    fact: 'has-gemfile',
+    tool: 'bundle',
+    preCommit: ['format'],
+    prePush: ['test'],
+    commands: { format: 'bundle exec rubocop', test: 'bundle exec rspec' },
+  },
+  {
+    fact: 'has-pubspec',
+    tool: 'dart',
+    preCommit: ['format', 'lint'],
+    prePush: ['test'],
+    commands: { format: 'dart format --output=none --set-exit-if-changed .', lint: 'dart analyze', test: 'dart test' },
+  },
+  {
+    fact: 'has-mix',
+    tool: 'mix',
+    preCommit: ['format'],
+    prePush: ['test'],
+    commands: { format: 'mix format --check-formatted', test: 'mix test' },
+  },
+  // The wrapper is a file the repository commits, not a program on PATH. A repo with
+  // a pom.xml and no wrapper cannot run `./mvnw -q verify`, so the probe is the file.
+  {
+    fact: 'has-maven-pom',
+    tool: 'mvnw',
+    file: true,
+    prePush: ['test'],
+    commands: { test: './mvnw -q verify' },
+  },
+];
+
 /**
  * Can this repo actually run the gate?
  *
@@ -240,22 +328,68 @@ function runnerName(runner) {
  *   - `command` gates run whatever `gates.commands` declares, so a command gate with
  *     no declared command is unrunnable by definition
  *
- * @returns {{gates: {preCommit: string[], prePush: string[]}, dropped: {gate: string, why: string}[]}}
+ * The seeds are returned alongside the plan because a fresh adoption writes them
+ * into `gates.commands` and the reader is owed the line that says so: a command
+ * that lands in the manifest without appearing in the plan is a silent write.
+ *
+ * @returns {{gates: {preCommit: string[], prePush: string[]}, dropped: {gate: string, why: string}[], commands: Record<string,string>}}
  */
-export function planGates(stack = [], capability = null) {
-  const proposed = defaultGates(stack);
-  if (!capability) return { gates: proposed, dropped: [] };
+export function planGates(stack = [], capability = null, facts = []) {
+  const proposed = defaultGates(stack, facts);
+  if (!capability) return { gates: proposed, dropped: [], commands: {} };
+  const seeds = ecosystemCommands(facts, capability);
+  // A command the repo already declared wins over a seed: the seed is a default,
+  // the declaration is a choice, and a default overwriting a choice is a re-init
+  // that edits the repo's mind.
+  const effective = { ...capability, commands: { ...seeds, ...capability.commands } };
   const dropped = [];
   const runnable = (list) =>
     list.filter((name) => {
       const gate = getGate(name);
-      const verdict = gateRunnable(gate, capability);
+      const verdict = gateRunnable(gate, effective);
       if (!verdict.runnable) {
         dropped.push({ gate: name, why: verdict.why, remedy: gateRemedy(gate, { runner: capability.runner }) });
       }
       return verdict.runnable;
     });
-  return { gates: { preCommit: runnable(proposed.preCommit), prePush: runnable(proposed.prePush) }, dropped };
+  return {
+    gates: { preCommit: runnable(proposed.preCommit), prePush: runnable(proposed.prePush) },
+    dropped,
+    commands: seeds,
+  };
+}
+
+/**
+ * The canonical `gates.commands` a fresh manifest of this repository should carry.
+ *
+ * Two probes, and both must pass before a command is declared: the fact says the
+ * ecosystem is in the repository, and `capability.tools` says its program can run
+ * on this machine. A marker file without a toolchain would otherwise declare a
+ * gate that fails closed on every commit — the defect ADR-017 exists to prevent,
+ * reached from the ecosystem table rather than the stack table.
+ *
+ * Pure, so `planGates` and `buildManifest` answer with one implementation.
+ */
+function ecosystemCommands(facts = [], capability = null) {
+  if (!capability?.tools?.length) return {};
+  // An npm runner already answers "how do I test and format" with its own package.json
+  // scripts, and a seed only wins over those scripts when the repo has not declared a
+  // command of its own — which is exactly the mixed repos (package.json AND Cargo.toml)
+  // where the script is the deliberate answer. Seeding there would replace a choice with
+  // a default; the reader's escape hatch is declaring gates.commands by hand, which a
+  // seed would lose to anyway. Pure ecosystem repos have runner 'cargo'/'go'/... and
+  // seed normally.
+  if (capability.runner === 'npm') return {};
+  const present = new Set(facts);
+  const commands = {};
+  for (const eco of ECOSYSTEMS) {
+    if (!present.has(eco.fact)) continue;
+    if (!capability.tools.includes(eco.tool)) continue;
+    for (const [gate, command] of Object.entries(eco.commands)) {
+      if (!capability.commands?.[gate]) commands[gate] = command;
+    }
+  }
+  return commands;
 }
 
 /**
@@ -267,16 +401,22 @@ export function planGates(stack = [], capability = null) {
  * make, and quietly disarming a gate somebody declared on purpose is a worse surprise
  * than a visible one.
  */
-export function buildManifest({ root, stack = [], sha, existing = null, capability = null, surfaces = undefined }) {
-  const gates = defaultGates(stack);
+export function buildManifest({ root, stack = [], sha, version, existing = null, capability = null, surfaces = undefined, facts = [] }) {
+  const gates = defaultGates(stack, facts);
   const limits = defaultLimits(stack);
 
   // A re-init must never silently weaken a repo's own declaration: existing
   // limits and gates win over defaults, and only the projection stamp is refreshed.
   const limitsFinal = existing?.limits ? { ...limits, ...existing.limits } : limits;
+  const planned = planGates(stack, capability, facts);
+  // The seeds land only on a FRESH manifest. On an existing one the repo's
+  // declaration is the answer, and adding commands under it would be a re-init
+  // writing into a field the reader owns — the same rule as the gates above.
   const gatesFinal = existing?.gates
     ? { ...gates, ...existing.gates }
-    : planGates(stack, capability).gates;
+    : Object.keys(planned.commands).length > 0
+      ? { ...planned.gates, commands: planned.commands }
+      : planned.gates;
 
   return {
     ...MANIFEST_COMMENT,
@@ -296,6 +436,29 @@ export function buildManifest({ root, stack = [], sha, existing = null, capabili
     // substitution value: it lists the rules this repo declares it has a problem
     // with, which is something detection cannot infer.
     substitutions: existing?.substitutions ?? {},
+    // ADR-065: rule sets this repository shares with its siblings, and the digest
+    // of the bytes it has for each. Not a generated field - which packs a repo uses
+    // is the repo's decision, and `check` reports a digest that does not match the
+    // directory rather than a value here that differs from what the tool would pick.
+    packs: existing?.packs ?? [],
+    // ADR-072: how many bytes of always-on projection this repository has agreed to
+    // carry. A declaration, not a generated field, for the same reason `packs` is not:
+    // the number is the repository's own line in the sand, and `upgrade` must not
+    // rewrite it to whatever the tool happens to project today — a budget that moved by
+    // itself would be a budget nobody is held to.
+    //
+    // Absent when the repository declared nothing, which is the point. Writing the
+    // default here would make every adopted repo look like it had chosen it, and a
+    // reader told "declared: true" about a line nobody wrote is being lied to about the
+    // only thing the number is for. The default belongs to whoever measures, and
+    // `budgetFinding` and `simt tokens` both read it from one place.
+    ...(existing?.budget === undefined ? {} : { budget: existing.budget }),
+    // ADR-073: `full` projects every selected rule; `kernel` projects only the hard
+    // constraints and defers the rest to `rules show`. Absent means `full`, and the
+    // default stays `full` because nobody has yet measured whether a kernel loses
+    // compliance (plan 0003 R02) — a mode chosen by default would be a bet the
+    // repository never made. Declared, not generated, for the same reason as `budget`.
+    ...(existing?.mode === undefined ? {} : { mode: existing.mode }),
     // ADR-020: which editors this repo's rules are projected into. Absent means the
     // global standard applies; an explicit empty list is a real choice meaning
     // AGENTS.md only. Recorded rather than inferred, because "which IDE does this repo
@@ -303,7 +466,12 @@ export function buildManifest({ root, stack = [], sha, existing = null, capabili
     // because a typo here silently reduces the estate to AGENTS.md, which looks
     // exactly like a working setup.
     surfaces: surfaces ?? existing?.surfaces ?? null,
-    projection: { simtDevSha: sha ?? null },
+    // simtDevSha is the digest of the rule bytes this projection was rendered from;
+    // version is the simt-dev release that produced it. The gate compares the running
+    // binary to version and refuses on a mismatch, which is how a repository without
+    // npm (a global install, pinned only by this field) is held to the release it
+    // adopted. See src/package-version.mjs.
+    projection: { simtDevSha: sha ?? null, version: version ?? null },
   };
 }
 
@@ -325,6 +493,24 @@ export function unrunnableGates(manifest, capability) {
   ];
   const findings = [];
   const seen = new Set();
+  // `gates.cwd` names a directory a gate runs in, and a name that is not a declared
+  // gate is as much a landmine as one that cannot run: the entry is inert, the reader
+  // believes the gate runs in the package it names, and nothing anywhere says so. Same
+  // shape as the unknown-gate finding in the dispatcher, so both are repaired the same
+  // way.
+  const cwds = manifest?.gates?.cwd;
+  if (cwds && typeof cwds === 'object' && !Array.isArray(cwds)) {
+    for (const name of Object.keys(cwds).sort()) {
+      if (declared.includes(name)) continue;
+      findings.push({
+        file: MANIFEST,
+        status: 'unknown-gate-cwd',
+        gate: name,
+        detail: `gates.cwd names "${name}", which is not declared in gates.preCommit or gates.prePush, so it is never read`,
+        remedy: `declare "${name}" in gates.preCommit or gates.prePush, or remove gates.cwd["${name}"]`,
+      });
+    }
+  }
   for (const name of declared) {
     if (seen.has(name)) continue;
     seen.add(name);
@@ -348,18 +534,30 @@ function defaultLimits() {
 }
 
 /** ADR-006: coverage stays null. Set it only if the repo has a real numeric gate. */
-function defaultGates(stack) {
-  const tags = new Set(stack);
+function defaultGates(stack, facts = []) {
+  // Tags and facts are one signal set for gate purposes: a row in `GATES_BY_STACK`
+  // keys on a tag, a row in `ECOSYSTEMS` on a fact, and the two never name each
+  // other's vocabulary (facts are `has-*`, tags are not), so one union cannot
+  // cross-match.
+  const signals = new Set([...stack, ...facts]);
   const gates = { preCommit: [], prePush: [] };
 
   for (const row of GATES_BY_STACK) {
-    if (row.when.some((tag) => tags.has(tag))) {
+    if (row.when.some((tag) => signals.has(tag))) {
       gates.preCommit.push(...row.preCommit);
       gates.prePush.push(...row.prePush);
     }
   }
+  for (const row of ECOSYSTEMS) {
+    if (signals.has(row.fact)) {
+      // A row proposes what it has: the Maven row has no preCommit gates, so a
+      // missing key is "none", not a defect. Spreading undefined throws.
+      gates.preCommit.push(...(row.preCommit ?? []));
+      gates.prePush.push(...(row.prePush ?? []));
+    }
+  }
   for (const row of TAG_GATES) {
-    if (tags.has(row.tag)) gates.preCommit.push(...row.preCommit);
+    if (signals.has(row.tag)) gates.preCommit.push(...row.preCommit);
   }
 
   // A repo with no recognised stack still gets a gate list, because a gate that
@@ -388,6 +586,86 @@ function defaultId(root) {
   return name === '' || name === '.' ? 'unnamed-repo' : name;
 }
 
+/**
+ * The fields this tool writes. Everything else in a manifest belongs to the
+ * repository that adopted the tool.
+ *
+ * It is a value rather than an expression inside `manifestDrift` because the question
+ * "is this field ours?" now has two callers that must answer it identically: the gate
+ * that reports one stale, and `sync`, which repairs exactly the fields the gate names.
+ * A second implementation of this set is a repair that fixes a field nothing reports,
+ * or a report about a field nothing repairs - and each half passes its own test,
+ * which is ADR-045's shape reached from the other direction.
+ */
+/**
+ * The bytes of always-on projection a repository carries per root before the number is
+ * worth an argument.
+ *
+ * Thirty thousand is S38's figure and not a measurement this tool took: it is the line
+ * the review drew, the one the whole row exists to check. A default nobody would accept
+ * is a default that reports nothing, and a budget only works as a budget when exceeding
+ * it is something a reader can see.
+ */
+export const DEFAULT_BUDGET_BYTES = 30000;
+
+/**
+ * Report a projection that carries more than the repository agreed to carry.
+ *
+ * Non-blocking by design, and that is the honest answer rather than a convenient one:
+ * the plan's own wording is that `check` reports `BUDGET-CUT` and nothing is cut, because
+ * cutting requires a kernel to pack lines into and the kernel does not exist yet
+ * (R07, blocked on the R02 evaluation). A gate that failed here would fail every
+ * repository in the estate on a number this tool has not yet earned the right to enforce.
+ *
+ * The finding names what is over and what is NOT cut, because a reader who is told only
+ * that a budget was exceeded will assume something was removed and stop looking.
+ *
+ * @returns {{file: string, status: string, detail: string, remedy: string}|null}
+ */
+export function budgetFinding(bytes, budget, mode = 'full') {
+  const allowed = budget?.bytes ?? DEFAULT_BUDGET_BYTES;
+  if (!Number.isFinite(bytes) || bytes <= allowed) return null;
+  // The two modes answer different questions, and conflating them is the one way this
+  // finding could be actively wrong. In `full` nothing is cut, so a reader told only
+  // "over budget" would look for a removed rule and find none. In `kernel` the packing
+  // already ran and the projection the reader will see is the packed one — so a number
+  // over the line here means the KERNEL is over the line, which is a different remedy
+  // entirely: no amount of raising the number fixes a kernel that is too large on its own.
+  const kernel = mode === 'kernel';
+  return {
+    file: MANIFEST,
+    status: 'budget',
+    detail: kernel
+      ? `${bytes} bytes of always-on projection in kernel mode; this repository declared ${allowed}. The kernel itself is over the line: only hard and command rules were packed, so this is not a projection waiting to be trimmed`
+      : `${bytes} bytes of always-on projection; this repository declared ${allowed}. Nothing was cut: the projection is still in full mode, so every rule is loaded as written`,
+    remedy: kernel
+      ? `raise budget.bytes to ${bytes}, or move rules out of the hard and command classes into convention or style, which is the only way a kernel shrinks`
+      : `raise budget.bytes to ${bytes} if the projection is meant to be this size, switch mode to kernel to defer the convention and style rules, or narrow the rules that carry it`,
+  };
+}
+
+export const GENERATED_KEYS = new Set(['$comment', 'projection']);
+
+/**
+ * A manifest with this tool's own fields replaced by what this build writes, and
+ * nothing else touched.
+ *
+ * Spread from the repository's manifest rather than from `buildManifest`'s output:
+ * the builder fills a default for every key, so writing its result wholesale would
+ * overwrite `gates` and `limits` in any repository that chose its own. "Content the
+ * repo chose is never compared" is a promise about the repair too, not only about
+ * the report, and a repair is exactly where it would be broken.
+ *
+ * @param {object} manifest the repository's manifest, as parsed
+ * @param {object} expected `buildManifest`'s output, from the call `manifestDrift` made
+ * @returns {object} a new manifest; the argument is not mutated
+ */
+export function withGenerated(manifest, expected) {
+  const patched = { ...manifest };
+  for (const key of GENERATED_KEYS) if (key in expected) patched[key] = expected[key];
+  return patched;
+}
+
 /**
  * Is a generated field of this manifest wrong, or has a formatter taken its bytes?
  *
@@ -408,6 +686,12 @@ function defaultId(root) {
  *    again. `upgrade` reported `current` the whole time, which is correct: the pin
  *    was current. The bytes were not.
  *
+ *    This one is a consequence of routing, not of adoption. Nothing reformatted the
+ *    manifest until the pre-commit gate started running, so every repository that
+ *    adopts the tool and runs a formatter arrives here on its first commit. The
+ *    remedy is therefore "stop the formatter taking it, then `sync`" — and it was
+ *    `init --yes`, which re-runs adoption to change one file's formatting (ADR-050).
+ *
  * Content the repo chose is never compared. A repo that edited `limits.coverage` on
  * purpose is not being told to revert it.
  *
@@ -417,20 +701,34 @@ export async function manifestDrift(root, stack, sha) {
   const { manifest, exists, error } = await readManifest(root);
   if (!exists || error !== null || manifest === null) return null;
 
-  const expected = buildManifest({ root, stack, sha, existing: manifest });
-  const stale = [];
-  for (const key of Object.keys(expected)) {
-    const generated =
-      key === '$comment' ||
-      (key === 'projection' && JSON.stringify(expected.projection) !== JSON.stringify(manifest.projection ?? null));
-    if (generated && JSON.stringify(manifest[key]) !== JSON.stringify(expected[key])) stale.push(key);
-  }
+  const expected = buildManifest({ root, stack, sha, version: packageVersion(), existing: manifest });
+  // `[...GENERATED_KEYS]`, and not `Object.keys(expected)`: the question is which
+  // fields are ours, and the answer is the set above. Iterating the expected object
+  // asks the same question of a different list and can only agree by coincidence.
+  const stale = [...GENERATED_KEYS].filter(
+    (key) => key in expected && JSON.stringify(manifest[key]) !== JSON.stringify(expected[key]),
+  );
   if (stale.length > 0) {
     return {
       file: MANIFEST,
       status: 'stale-generated-field',
       detail: `generated field(s) ${stale.join(', ')} do not match what this simt-dev writes`,
-      remedy: `run: ${CLI} init --yes   (it refreshes the stamp without touching values this repo set)`,
+      // `sync`, and not `init`. `sync` repairs exactly this field set and nothing
+      // else; `init` re-runs adoption - it tags, it branches, it asks every question
+      // again - and two commands must not answer one question with different
+      // instructions (ADR-050).
+      //
+      // The remedy said `init` because for two releases nothing could repair a stale
+      // field, so the only command that could was the only one named. `sync` having
+      // nothing to repair while `check` refused anyway is the one-question-two-answers
+      // defect this repository exists to end, and it was true in all fourteen adopted
+      // repositories at the same moment: measured, not inferred. `check` exited 1 in
+      // every one of them while `sync` printed "already current; nothing written".
+      //
+      // No trailing parenthetical, because `compare` prints this string verbatim as
+      // the remedy on its own row. A remedy that reads well in one command's output
+      // and badly in another's is two answers wearing one string.
+      remedy: `run: ${CLI} sync --yes`,
     };
   }
 
@@ -446,10 +744,22 @@ export async function manifestDrift(root, stack, sha) {
     file: MANIFEST,
     status: 'reformatted',
     detail: 'content is what simt-dev would write, but the bytes differ - another formatter owns this file',
-    remedy: `add ${MANIFEST_FILE} to .prettierignore (a generated file is not prose), then: ${CLI} init --yes`,
+    remedy: `add ${MANIFEST_FILE} to .prettierignore (a generated file is not prose), then: ${CLI} sync --yes`,
   };
 }
 
+/**
+ * The bytes a manifest is written as.
+ *
+ * Exported because two callers now need them and one of them is a preview: a plan
+ * that reports a byte count it computed with a different serialiser than the writer
+ * used reports a number nothing will ever observe. `writeManifest` is the only place
+ * this format is spelled.
+ */
+export function manifestText(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
 /** @returns {{manifest: object|null, exists: boolean, error: string|null}} */
 export async function readManifest(root) {
   const path = await manifestPath(root);
@@ -473,6 +783,6 @@ export async function writeManifest(root, manifest) {
   const previous = join(root, MANIFEST_LEGACY);
   const fresh = join(root, MANIFEST);
   if (existsSync(previous) && !existsSync(fresh)) await rename(previous, fresh);
-  await writeFile(fresh, `${JSON.stringify(manifest, null, 2)}\n`);
+  await writeFile(fresh, manifestText(manifest));
   return fresh;
 }

package/src/projection/mdc.mjs

@@ -24,7 +24,6 @@
 
 import { readFile, readdir } from 'node:fs/promises';
 
-import { frontmatterBlock } from './surfaces.mjs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -45,7 +44,9 @@ const MDC_DIR = join(ROOT, 'rules', 'mdc');
  * defect — which is the failure ADR-016 shipped once, a rule that reached no repo
  * because `applies` was absent, silently and with a test green.
  */
-const KNOWN_KEYS = new Set([
+/** Frontmatter keys this tool reads, ADR-022. Exported so the one authority on the
+ *  tool's own vocabulary is also the one a guard subtracts, rather than a second copy. */
+export const KNOWN_KEYS = new Set([
   'simt-id',
   'simt-target',
   'simt-title',
@@ -300,14 +301,6 @@ function dropOrReplace(text, key, value) {
   return kept.join('\n').replace(/\n{3,}/g, '\n\n');
 }
 
-/** The frontmatter a projected `.mdc` keeps. `alwaysApply` and `description` are
- *  read by the editor before any rule text, so they belong outside the region. */
-export function mdcFrontmatter(rule) {
-  return frontmatterBlock([
-    `description: ${rule.description ?? `Canonical ${rule.id} rule managed by simt-dev`}`,
-    `alwaysApply: ${rule.alwaysApply ? 'true' : 'false'}`,
-  ]);
-}
 
 
 /**
@@ -322,6 +315,4 @@ export function ruleName(rule) {
   if (typeof rule.target !== 'string' || rule.target === '') return null;
   const base = rule.target.slice(rule.target.lastIndexOf('/') + 1);
   return base.replace(/\.mdc$/, '');
-}
-
-export { MDC_DIR, parse as parseRegion };
+}