simt-dev 0.2.1 → 0.3.0

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,
@@ -436,6 +440,29 @@ export function buildManifest({ root, stack = [], sha, version, existing = null,
     // 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
@@ -450,6 +477,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 };
 }
 
 /**
@@ -470,6 +516,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);
@@ -556,6 +620,53 @@ function defaultId(root) {
  * 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']);
 
 /**

package/src/projection/project.mjs

@@ -25,10 +25,11 @@ import { planDependabot } from '../ci/dependabot.mjs';
 import { checkTsconfig } from '../tsconfig.mjs';
 import { checkToolchain } from '../toolchain.mjs';
 import { diff, parse, inject, BEGIN, END } from './markers.mjs';
-import { readManifest } from './manifest.mjs';
+import { budgetFinding, readManifest } from './manifest.mjs';
+import { measureRoot } from '../measure/context.mjs';
 import { loadMdcRules, renderMdc } from './mdc.mjs';
 import { foldsRules, resolveSurfaces, SURFACES, SURFACE_IDS } from './surfaces.mjs';
-import { pointerState, pointerTargets, ruleTargets } from './targets.mjs';
+import { pointerState, pointerTargets, ruleTargets, scopedTargets } from './targets.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import {
@@ -36,6 +37,7 @@ import {
   provenanceDigest,
   isEligible,
   loadRules,
+  packageRegions,
   LOCAL_PROFILE_DIR,
   mdcTargets,
   readDeclared,
@@ -69,12 +71,31 @@ export async function plan(root, flags = {}) {
 
   const surfaces = resolveSurfaces(manifest, flags);
 
+  // Profiles that narrowed out of the region, written as files for the surfaces whose
+  // scoping key was read in the vendor's own documentation. Only when EVERY selected
+  // surface can scope: a profile that left the region while a reader could not narrow
+  // would be a rule that reader never loads, and `desiredRegion` already kept it in the
+  // region in that case, which is why `narrowing` is the gate here too.
+  const scoped =
+    desired.narrowing === true
+      ? await scopedTargets(root, desired.scoped ?? [], meta.sha, surfaces, notes)
+      : { targets: [] };
+
   // The baselines are the same list shape as every other target, so `sync` writes
   // them and reports them in the same plan it prints for AGENTS.md and the rule
   // files. A file the reader was not shown is a file they approve by reading the diff
   // afterwards, which is the one review step this tool exists to make unnecessary.
   const baselines = await baselineTargets(root, meta.sha);
 
+  // A monorepo projects once per package as well as once at the root. The nested
+  // regions come after the root's and before the rule files, because the root is
+  // what a reader meets first and a plan that listed a package's region before the
+  // root's would read as though the packages were the repository.
+  const packages = await packageRegions(root, flags, profiles);
+  const nested = await Promise.all(
+    packages.regions.map((r) => targetFor(join(root, r.path), r.body, r.meta, `${r.path}/${PRIMARY_TARGET}`)),
+  );
+
   return {
     root,
     stack,
@@ -85,13 +106,14 @@ export async function plan(root, flags = {}) {
     surfaceSource: surfaces.source,
     surfaceProblems: surfaces.problems,
     rules: all,
-    targets: [target, ...mdc.targets, ...baselines.targets],
+    targets: [target, ...nested, ...mdc.targets, ...scoped.targets, ...baselines.targets],
+    packages: packages.regions.map((r) => ({ path: r.path, profiles: r.profiles })),
     mdcProblems: mdc.problems,
-    notes: [...notes, ...mdc.notes],
+    notes: [...notes, ...mdc.notes, ...packages.notes],
   };
 }
 
-async function targetFor(root, body, meta) {
+async function targetFor(root, body, meta, label = PRIMARY_TARGET) {
   const path = join(root, PRIMARY_TARGET);
   let existing = '';
   let exists = true;
@@ -103,7 +125,10 @@ async function targetFor(root, body, meta) {
 
   const result = inject(existing, body, meta, await regionOpts(root));
   return {
-    file: PRIMARY_TARGET,
+    // The repo-relative path, and not the basename: a monorepo writes the same
+    // document once per package, and a plan that printed `AGENTS.md` twice with no
+    // directory on either line would leave the reader unable to tell which is which.
+    file: label,
     path,
     exists,
     action: result.action,
@@ -140,6 +165,36 @@ 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.
+  //
+  // Gated on the root having a region at all: a monorepo that has not adopted has no
+  // nested regions either, and reporting one as absent would describe a half-adoption
+  // that nobody performed.
+  const { regions: packageBodies } = await packageRegions(root, flags);
+  for (const region of packageBodies) {
+    const file = `${region.path}/${PRIMARY_TARGET}`;
+    findings.push({ ...(await checkRegion(root, join(root, region.path), region.body, region.meta)), file, profiles: region.profiles });
+  }
+
   // The gate has to run where the merge happens, not only on the machine of whoever
   // remembers to run it. A repo that already runs GitHub Actions and has no simt-dev
   // job is ungated at its front door, and that is the one finding here that no amount
@@ -189,7 +244,8 @@ export async function checkTargets(root, flags = {}) {
   // Selection must match `plan` exactly, or the gate reports a rule absent that
   // `sync` was never going to write — a permanently red check nothing can fix.
   const all = await loadMdcRules();
-  const { stack, facts, manifest } = await desiredRegion(root, flags);
+  const desired = await desiredRegion(root, flags);
+  const { stack, facts, manifest } = desired;
   const declared = await readDeclared(root);
   const resolved = resolveSurfaces(manifest, flags);
   for (const p of resolved.problems) {
@@ -200,6 +256,36 @@ export async function checkTargets(root, flags = {}) {
   const sha = await provenanceDigest();
   const notes = [];
 
+  // The profiles that left the region, gated through the same construction that wrote
+  // them. Without this loop a scoped file is planned and written but never checked, so a
+  // repository that edits or deletes one shows a clean `check` and a stale reader — the
+  // exact asymmetry the region-versus-file gate exists to prevent.
+  const scopedRules = desired.scoped ?? [];
+  if (desired.narrowing === true) {
+    for (const target of (await scopedTargets(root, scopedRules, sha, resolved, notes)).targets) {
+      if (!target.exists) {
+        findings.push({
+          file: target.file,
+          surface: target.surface,
+          status: 'absent',
+          detail: `no ${target.surface} rule here; run: ${CLI} sync --yes`,
+        });
+        continue;
+      }
+      // The writer's own verdict, from the same inject call `plan` will make. A second
+      // construction here would be a third place computing the same file, which is the
+      // defect this whole function exists to avoid.
+      const action = target.action;
+      findings.push({
+        file: target.file,
+        surface: target.surface,
+        status: action === 'unchanged' ? 'current' : 'drift',
+        detail: action === 'unchanged' ? undefined : `region is ${action}; run: ${CLI} sync --yes`,
+        recordedSha: parse(target.previous).sha ?? null,
+      });
+    }
+  }
+
   for (const rule of rules) {
     if (rule.error !== null) {
       findings.push({
@@ -433,7 +519,18 @@ export async function checkTarget(root, flags = {}) {
 
 async function checkPrimary(root, flags = {}) {
   const { body, meta } = await desiredRegion(root, flags);
-  const path = join(root, PRIMARY_TARGET);
+  return checkRegion(root, root, body, meta);
+}
+
+/**
+ * One region, compared against what this simt-dev would write for it.
+ *
+ * `dir` is the projection root that owns the document: the repository for the root
+ * region, a package for a nested one. `regionOpts` is read from the repository
+ * either way, because placement is a repository-level decision.
+ */
+async function checkRegion(root, dir, body, meta) {
+  const path = join(dir, PRIMARY_TARGET);
   let existing = '';
   try {
     existing = await readFile(path, 'utf8');
@@ -468,6 +565,28 @@ async function checkPrimary(root, flags = {}) {
     expectedSha: meta.sha,
   };
 }
+/**
+ * The bytes of always-on projection this repository carries, or null if it has not
+ * adopted at all.
+ *
+ * Delegates to the meter rather than counting here, and that is the whole of the
+ * design. A first version summed the region plus the rule files this function already
+ * compares, which sounds cheaper and is wrong: the meter also counts the managed skills
+ * and the `.mdc` files a reader loads, so the gate and the report came to different
+ * totals for one repository. Two definitions of one budget is the defect ADR-034 was
+ * filed about, rebuilt one layer up. The meter is the definition; the gate quotes it.
+ *
+ * The cost is that `check` now reads the documents the meter reads, which it did not
+ * do before. That is a real cost, paid knowingly: the alternative is a gate that fails
+ * on a number the report does not print, which is worse than a slower gate.
+ */
+async function alwaysOnBytes(root) {
+  const { exists } = await readManifest(root);
+  if (!exists) return null;
+  const measured = await measureRoot(root);
+  return { bytes: measured.generatedBytes };
+}
+
 /** `projection.place: "top"` puts the AGENTS.md region above the hand-written prefix. */
 async function regionOpts(root) {
   const { manifest } = await readManifest(root);
@@ -478,7 +597,11 @@ async function regionOpts(root) {
  * A reader that stops at a byte offset never sees a region that ends past it.
  * The finding names the reader, because "the file is long" does not say who stops.
  */
-function readLimitFindings(text, file) {
+// Exported for the context meter (`simt-dev tokens`), which answers the same question
+// about a region rather than about a diff. It reads the structured fields instead of
+// re-deriving the limit, because a second implementation of "which reader stops, and
+// where" is a second thing to keep right - and a second thing to quote in a message.
+export function readLimitFindings(text, file) {
   const state = parse(text);
   if (state.status !== 'ok' || typeof state.endByte !== 'number') return [];
   const findings = [];
@@ -489,6 +612,14 @@ function readLimitFindings(text, file) {
       findings.push({
         file,
         status: 'beyond-read-limit',
+        // The numbers, not only the sentence. `check` prints the detail and the context
+        // meter puts the reader, the limit and the offset in its JSON, and a consumer
+        // that has to regex prose to get them is a consumer that breaks when the prose
+        // is edited.
+        reader: limit.reader,
+        limitBytes: limit.bytes,
+        endByte: state.endByte,
+        overBy: state.endByte - limit.bytes,
         detail: `BEYOND-READ-LIMIT: the region ends at byte ${state.endByte}, past ${limit.reader}'s ${limit.bytes}-byte read of ${file}`,
         remedy: `set projection.place to "top" in ${MANIFEST_FILE} and run: ${CLI} sync --yes, or raise ${limit.reader}'s project_doc_max_bytes`,
       });