simt-dev 0.2.0 → 0.2.2

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,6 +597,10 @@ 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.
  */
+// 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 [];
@@ -489,6 +612,14 @@ export 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`,
       });