simt-dev 0.2.2 → 0.3.1

package/src/projection/lock.mjs

@@ -0,0 +1,93 @@
+// The lock records the two digests a frozen check compares (ADR-086).
+//
+// Input is everything the projection reads that a repository can change, plus the
+// digest of what this package ships. Output is the region body. An output that moves
+// while the input does not is a renderer that is not a function of its inputs, and
+// that is the failure `--frozen` exists to catch. An input that moves is a stale
+// lock: the projection changed because the repository did, and the lock was not
+// rewritten.
+
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { fingerprint } from '../resolve/fingerprint.mjs';
+import { desiredRegion, provenanceDigest, LOCAL_PROFILE_DIR } from './rules.mjs';
+import { readManifest } from './manifest.mjs';
+
+export const LOCK_FILE = 'simt-dev.lock.json';
+
+/** Manifest keys that change what the region contains. Anything else in the file is
+ *  the repository's own notes, and hashing it would make a comment fail the lock. */
+const MANIFEST_KEYS = ['mode', 'budget', 'shared', 'surfaces', 'gates'];
+
+/**
+ * The lock this repository's projection should have.
+ *
+ * @param {string} root
+ * @param {object} [flags] the same flags `sync` rendered with, so the output is the
+ *   body that was written and not a body for a different set of surfaces
+ */
+export async function computeLock(root, flags = {}) {
+  const desired = await desiredRegion(root, flags);
+  return {
+    inputs: await inputDigest(root),
+    outputs: createHash('sha256').update(desired.body).digest('hex'),
+  };
+}
+
+/** Read a lock, or null when the file is not there. A file that does not parse is an
+ *  error the caller reports, not a missing lock: absence and damage are different
+ *  repairs. */
+export async function readLock(root) {
+  let text;
+  try {
+    text = await readFile(join(root, LOCK_FILE), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { lock: null, error: null };
+    throw error;
+  }
+  try {
+    const lock = JSON.parse(text);
+    if (typeof lock?.inputs !== 'string' || typeof lock?.outputs !== 'string') {
+      return { lock: null, error: 'must be an object with inputs and outputs' };
+    }
+    return { lock, error: null };
+  } catch (error) {
+    return { lock: null, error: error.message };
+  }
+}
+
+async function inputDigest(root) {
+  const hash = createHash('sha256');
+  hash.update(`provenance:${await provenanceDigest()}\n`);
+  const { stack, facts } = await fingerprint(root);
+  hash.update(`signals:${JSON.stringify({ stack, facts })}\n`);
+  const { manifest } = await readManifest(root);
+  const owned = {};
+  if (manifest && typeof manifest === 'object') {
+    for (const key of MANIFEST_KEYS) {
+      if (manifest[key] !== undefined) owned[key] = manifest[key];
+    }
+  }
+  hash.update(`manifest:${JSON.stringify(owned)}\n`);
+  let names = [];
+  try {
+    names = (await readdir(join(root, LOCAL_PROFILE_DIR))).filter((n) => n.endsWith('.md')).sort();
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  for (const name of names) {
+    const bytes = await readFile(join(root, LOCAL_PROFILE_DIR, name));
+    hash.update(`profile:${name}:${bytes.length}:`);
+    hash.update(bytes);
+  }
+  try {
+    const raw = await readFile(join(root, 'package.json'), 'utf8');
+    const scripts = JSON.parse(raw).scripts ?? {};
+    hash.update(`scripts:${JSON.stringify(scripts)}\n`);
+  } catch (error) {
+    if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
+  }
+  return hash.digest('hex');
+}

package/src/projection/manifest.mjs

@@ -67,8 +67,12 @@ export async function manifestPath(root) {
  * real is the recorded SHA under `projection`.
  */
 export const MANIFEST_COMMENT = {
-  $comment:
-    `Written and maintained by simt-dev. Edit by hand only if you intend to take ownership of this file: \`${CLI} sync --yes\` regenerates the projected rules, and re-running \`${CLI} init\` refreshes the SHA without weakening a value you set here.`,
+  $comment: [
+    `Written and maintained by simt-dev. \`${CLI} sync --yes\` regenerates the projected rules.`,
+    `\`${CLI} init\` refreshes the SHA and keeps every key it does not write, so a value you add here survives a re-init.`,
+    `\`plans\` is such a key: it selects the tracker template and the directories \`${CLI} plan\` reads.`,
+    'Omit it and the tracker template applies, which reads docs/plans and docs/reviews.',
+  ].join(' '),
 };
 
 /**
@@ -418,7 +422,7 @@ export function buildManifest({ root, stack = [], sha, version, existing = null,
       ? { ...planned.gates, commands: planned.commands }
       : planned.gates;
 
-  return {
+  const owned = {
     ...MANIFEST_COMMENT,
     id: existing?.id ?? defaultId(root),
     stack: existing?.stack?.length ? existing.stack : stack,
@@ -459,6 +463,15 @@ export function buildManifest({ root, stack = [], sha, version, existing = null,
     // 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-084: the rules this repository hands to the workspace's user-level copy, and
+    // the level that copy lives at. Declared, not generated, for the same reason as
+    // `budget` and `mode`: `shared install` writes the list once, but the bytes that land
+    // in a repository's region depend on it on every `sync` — so if `upgrade` rewrote it
+    // from its own opinion of what a workspace shares, a repository's region would change
+    // without anybody asking, which is the failure `budget` moving by itself was.
+    // Absent means "no repository in this workspace shares anything", which is the state
+    // every repository is in until somebody runs `shared install`.
+    ...(existing?.shared === undefined ? {} : { shared: existing.shared }),
     // 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
@@ -473,6 +486,25 @@ export function buildManifest({ root, stack = [], sha, version, existing = null,
     // adopted. See src/package-version.mjs.
     projection: { simtDevSha: sha ?? null, version: version ?? null },
   };
+  return withRepoKeys(existing, owned);
+}
+
+/**
+ * Keys this writer does not recognise belong to the repository.
+ *
+ * A re-init used to return only the object above, so anything else in the file
+ * disappeared. `plans` is the tracker overlay, and it is not the only key a
+ * repository might have added. Owned keys stay in the order the writer emits
+ * them; an unknown key is copied after them, in the order the file had it.
+ */
+function withRepoKeys(existing, owned) {
+  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) return owned;
+  const kept = {};
+  for (const key of Object.keys(existing)) {
+    if (Object.hasOwn(owned, key)) continue;
+    kept[key] = existing[key];
+  }
+  return { ...owned, ...kept };
 }
 
 /**
@@ -608,6 +640,24 @@ function defaultId(root) {
  */
 export const DEFAULT_BUDGET_BYTES = 30000;
 
+/**
+ * The budget a repository declared, or the default it gets for declaring nothing.
+ *
+ * One reader for one number, and it exists because two callers need it and a third
+ * already had its own: the packer that cuts a kernel to fit (ADR-083) and the meter that
+ * reports what it carries, against a ceiling each would otherwise spell differently. The
+ * byte they disagree about is the byte the repository wrote down.
+ *
+ * `0` is honoured — "this repository wants an empty projection" is a decision somebody can
+ * make. `null`, a string and `NaN` are not budgets at all, and a hand-edited manifest is
+ * exactly where one turns up; the default stands in rather than the ceiling becoming a
+ * string that every comparison against it silently passes.
+ */
+export function declaredBudget(manifest) {
+  const declared = manifest?.budget?.bytes;
+  return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_BUDGET_BYTES;
+}
+
 /**
  * Report a projection that carries more than the repository agreed to carry.
  *
@@ -644,6 +694,31 @@ export function budgetFinding(bytes, budget, mode = 'full') {
   };
 }
 
+/**
+ * The workspace-shared rules this repository declared, as a set of ids.
+ *
+ * One reader, because the region, `doctor` and `shared` all need the same answer and a
+ * projection that renders a delta the meter cannot see is the one-question-two-answers
+ * defect this repository exists to end.
+ *
+ * `level` is read and validated rather than assumed, because `user` is the only level any
+ * reader loads from outside a repository and a hand-edited manifest is exactly where a
+ * second value turns up. A list that is not a list of strings yields an empty set: the
+ * repository then projects everything it selects, which is the state it was in before
+ * anybody ran `shared install`, and is never a state that loses a rule.
+ */
+export function declaredShared(manifest) {
+  const shared = manifest?.shared;
+  if (shared === undefined || shared === null) return { level: null, rules: new Set() };
+  const level = shared.level === 'user' ? 'user' : null;
+  const rules = new Set(Array.isArray(shared.rules) ? shared.rules.filter((id) => typeof id === 'string') : []);
+  // A level of `user` with nothing in it is a declaration that changes nothing, and a
+  // level that is not `user` names a place this tool cannot write — so neither is a
+  // reason to drop rules out of a region.
+  if (level === null || rules.size === 0) return { level: null, rules: new Set() };
+  return { level, rules };
+}
+
 export const GENERATED_KEYS = new Set(['$comment', 'projection']);
 
 /**

package/src/projection/markers.mjs

@@ -189,6 +189,57 @@ function readSha(body, style) {
  * never drift independently of it.
  */
 export function compose(body, { sha, sources = [] } = {}, style) {
+  return render(body, { sha, sources }, style, (s, sha, sources) =>
+    [
+      s.line(`${MARKER_PREFIX}:generated`),
+      s.line(`${MARKER_PREFIX}:sha=${sha}`),
+      ...(sources.length > 0 ? [s.line(`${MARKER_PREFIX}:sources=${sources.join(',')}`)] : []),
+      // Addressed to whoever reads this repo, not to whoever owns the rules upstream.
+      // "Edit the source in simt-dev" was the wrong instruction twice over: a consumer
+      // of the published package has no such tree, and an agent reading this repo has
+      // no business editing the region it was told not to edit. The only two actions
+      // available to a reader are: don't edit it, or regenerate it.
+      s.note(
+        'Generated content. Do not edit by hand - your changes are overwritten.',
+        `Run \`${CLI} sync --yes\` to regenerate, or \`${CLI} check\` to see what is stale.`,
+      ),
+    ],
+  );
+}
+
+/**
+ * The user-level shared region (ADR-084).
+ *
+ * A different note from `compose`, and the difference is the whole point of having two
+ * functions. `compose`'s remedy is `simt sync --yes`, and that remedy is wrong for a file
+ * in the reader's home directory: `sync` acts on a repository, so a reader who follows
+ * the instruction inside `~/.config/opencode/AGENTS.md` runs a command that will not
+ * repair it and concludes the projection is broken. The stamp and the marker grammar are
+ * shared, so `parse`, `inject` and `diff` read this region exactly as they read a
+ * repository's own — only the two sentences a reader acts on differ.
+ */
+export function composeShared(body, { sha, sources = [] } = {}, style) {
+  return render(body, { sha, sources }, style, (s, sha, sources) =>
+    [
+      s.line(`${MARKER_PREFIX}:generated`),
+      s.line(`${MARKER_PREFIX}:sha=${sha}`),
+      ...(sources.length > 0 ? [s.line(`${MARKER_PREFIX}:sources=${sources.join(',')}`)] : []),
+      s.note(
+        'Generated content shared by every repository in this workspace. Do not edit it by hand - your changes are overwritten.',
+        `Run \`${CLI} shared install --yes\` to regenerate it, or \`${CLI} doctor\` to see whether this copy is stale.`,
+      ),
+    ],
+  );
+}
+
+/**
+ * A region, markers and provenance header included, with a header this module chose.
+ *
+ * Split out because two headers now exist and the trailing-newline and empty-body cases
+ * below are load-bearing twice over — the formatter fight the header shape prevents does
+ * not care which of the two files it is happening in.
+ */
+function render(body, { sha, sources = [] }, style, headerLines) {
   const s = styleOf(style);
   // A stamp this tool cannot read back is worse than no stamp: `parse` matches
   // `[0-9a-f]{7,40}`, so the old `unknown` fallback produced a region that reported
@@ -200,21 +251,7 @@ export function compose(body, { sha, sources = [] } = {}, style) {
   }
   // Write-new, like the markers: the legacy spelling is read but never emitted, so a
   // migrated region is stable and a legacy one drifts exactly once.
-  const header = [s.line(`${MARKER_PREFIX}:generated`), s.line(`${MARKER_PREFIX}:sha=${sha}`)];
-  if (sources.length > 0) {
-    header.push(s.line(`${MARKER_PREFIX}:sources=${sources.join(',')}`));
-  }
-  // Addressed to whoever reads this repo, not to whoever owns the rules upstream.
-  // "Edit the source in simt-dev" was the wrong instruction twice over: a consumer
-  // of the published package has no such tree, and an agent reading this repo has
-  // no business editing the region it was told not to edit. The only two actions
-  // available to a reader are: don't edit it, or regenerate it.
-  header.push(
-    s.note(
-      'Generated content. Do not edit by hand - your changes are overwritten.',
-      `Run \`${CLI} sync --yes\` to regenerate, or \`${CLI} check\` to see what is stale.`,
-    ),
-  );
+  const header = headerLines(s, sha, sources);
   const trimmed = body.replace(/\n+$/, '');
   // Two lines here exist only because a real repo proved they are needed. A
   // formatter that runs on commit - several repositories have one, and three of the
@@ -269,7 +306,9 @@ function splice(state, region, where) {
  * adopted?" — `region: 'absent'` is that answer, and reading it off `previousBytes` gets a
  * repository with hand-written prose and no region wrong.
  *
- * @param {object} [opts] `style` overrides the syntax; `where` overrides placement.
+ * @param {object} [opts] `style` overrides the syntax; `where` overrides placement;
+ *   `compose` overrides which header the region carries (`composeShared` for the
+ *   user-level file, whose remedy is not `sync`).
  * @returns {{text: string, action: 'added'|'updated'|'unchanged'|'malformed', reason?: string,
  *   region: 'absent'|'ok'|'malformed', previousBody: string}}
  */
@@ -281,7 +320,7 @@ export function inject(text, body, meta, opts = {}) {
   if (state.status === 'malformed') {
     return { ...seen, text, action: 'malformed', reason: state.reason, line: state.line };
   }
-  const region = compose(body, meta, s);
+  const region = (opts.compose ?? compose)(body, meta, s);
 
   if (state.status === 'absent') {
     if (where === 'top') {

package/src/projection/project.mjs

@@ -26,6 +26,7 @@ import { checkTsconfig } from '../tsconfig.mjs';
 import { checkToolchain } from '../toolchain.mjs';
 import { diff, parse, inject, BEGIN, END } from './markers.mjs';
 import { budgetFinding, readManifest } from './manifest.mjs';
+import { budgetCutFinding } from '../kernel/budget.mjs';
 import { measureRoot } from '../measure/context.mjs';
 import { loadMdcRules, renderMdc } from './mdc.mjs';
 import { foldsRules, resolveSurfaces, SURFACES, SURFACE_IDS } from './surfaces.mjs';
@@ -165,23 +166,6 @@ export async function checkTargets(root, flags = {}) {
     findings.push(...readLimitFindings(text, PRIMARY_TARGET));
   }
 
-  // The budget: what this repository agreed to carry, against what it carries.
-  //
-  // Measured from the same `desiredRegion` the region above was compared against, plus
-  // the rule files this function went on to compare, because a gate and a meter that
-  // each counted their own set would report two different totals for one repository and
-  // the reader would have no way to tell which was the budget. Both numbers are the
-  // DESIRED ones, so a drifted repo is reported against what it would carry after a
-  // sync rather than what it carries today.
-  //
-  // Non-blocking by design: nothing is cut, because there is nothing to cut yet (ADR-072).
-  const budgetTotal = await alwaysOnBytes(root);
-  if (budgetTotal !== null) {
-    const { manifest } = await readManifest(root);
-    const over = budgetFinding(budgetTotal.bytes, manifest?.budget, manifest?.mode);
-    if (over) findings.push({ ...over, file: MANIFEST_FILE, detail: over.detail });
-  }
-
   // Every package of a monorepo is a projection root in its own right, so the gate
   // covers it the way it covers the root. A nested region that drifts is as stale as
   // the root's region, and the reader working in that package reads only that file.
@@ -246,6 +230,29 @@ export async function checkTargets(root, flags = {}) {
   const all = await loadMdcRules();
   const desired = await desiredRegion(root, flags);
   const { stack, facts, manifest } = desired;
+
+  // The budget, both halves of it, and in that order: what this repository agreed to
+  // carry against what it carries, then what was cut to get there.
+  //
+  // The total comes from the meter rather than from a sum this file could do itself,
+  // because a gate and a meter that each counted their own set would report two different
+  // numbers for one repository and the reader would have no way to tell which was the
+  // budget (ADR-072). The cut comes from the projection itself for the same reason — the
+  // packer wrote it, so the packer's own record of it is the one that cannot disagree with
+  // what `sync` would write.
+  //
+  // Both are non-blocking, for the reason ADR-072 gave for the first and ADR-083 for the
+  // second: the remedy is a decision about the number, not a missing file.
+  const budgetTotal = await alwaysOnBytes(root);
+  if (budgetTotal !== null) {
+    const over = budgetFinding(budgetTotal.bytes, manifest?.budget, manifest?.mode);
+    if (over) findings.push({ ...over, file: MANIFEST_FILE, detail: over.detail });
+  }
+  const packed = desired.budget;
+  if (packed !== null && packed.cuts.length > 0) {
+    findings.push(budgetCutFinding({ file: PRIMARY_TARGET, ...packed }));
+  }
+
   const declared = await readDeclared(root);
   const resolved = resolveSurfaces(manifest, flags);
   for (const p of resolved.problems) {