simt-dev 0.2.1 → 0.3.0

package/src/projection/rules.mjs

@@ -27,10 +27,15 @@ import { dirname, join, resolve } from 'node:path';
 
 import { fingerprint, KNOWN_TAGS } from '../resolve/fingerprint.mjs';
 import { loadMdcRules, renderMdc } from './mdc.mjs';
-import { foldsRules, frontmatterBlock, resolveSurfaces } from './surfaces.mjs';
+import { foldsRules, frontmatterBlock, resolveSurfaces, rulePath, canScope } from './surfaces.mjs';
 import { ruleTargets } from './targets.mjs';
-import { manifestPath } from './manifest.mjs';
+import { manifestPath, readManifest } from './manifest.mjs';
+import { commandCard, CARD_LIMIT_BYTES } from '../kernel/card.mjs';
+import { filterInferable, inferableDefect, inferableProofs } from '../kernel/inferability.mjs';
 import { BASELINES } from './baselines.mjs';
+import { CLI } from '../name.mjs';
+import { PACK_DIR, resolvePacks } from '../packs.mjs';
+import { discoverPackages } from '../monorepo.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const ROOT = resolve(HERE, '..', '..');
@@ -123,12 +128,37 @@ async function walk(dir, prefix = '') {
 /** Repo-local profile directory, relative to a repo root (ADR-013 section 2). */
 export const LOCAL_PROFILE_DIR = '.simt-dev/profiles';
 
+/**
+ * Which origin outranks which when two profiles claim one `simt-id`.
+ *
+ * A pack is the repository's shared policy and the built-in set is the tool's
+ * opinion, so a repository can replace either and a pack can replace what the
+ * tool ships. Read in one place because the answer to "whose rule is this?" is
+ * asked on every rule of every projection, and a precedence that lives in two
+ * places is a precedence that will disagree with itself.
+ */
+const ORIGIN_RANK = { central: 0, pack: 1, local: 2 };
+
 /** Every key a stack profile or core rule may declare is this tool's own, so every
  *  one carries the `simt-` prefix (ADR-022). A profile carrying a bare key would read
  *  as an editor's instruction — Cursor, Copilot and Antigravity all parse a
  *  frontmatter block the same way — and would be silently inert. */
 /** Frontmatter keys a rule profile declares. See {@link KNOWN_KEYS} on why exported. */
-export const PROFILE_KEYS = new Set(['simt-id', 'simt-title', 'simt-applies', 'simt-fallback']);
+export const PROFILE_KEYS = new Set(['simt-id', 'simt-title', 'simt-applies', 'simt-fallback', 'simt-scope', 'simt-priority']);
+
+/**
+ * Priority classes, packed in this order (plan 0003 R07).
+ *
+ * A class is not a severity, it is a promise about what a reader loses by not having
+ * the line. A hard constraint is one whose absence produces a defect; a command is one
+ * the reader cannot guess; a convention is right to follow and harmless to miss; a style
+ * is a preference. Anything after `command` is the first thing a kernel drops, and that
+ * ordering is the whole content of the mode — everything else about it is bookkeeping.
+ */
+export const PRIORITY_CLASSES = ['hard', 'command', 'convention', 'style'];
+
+/** The classes a kernel keeps. `full` mode keeps all four and is the default. */
+export const KERNEL_CLASSES = new Set(['hard', 'command']);
 
 /** Report the first thing wrong with a profile's frontmatter, in the order a reader
  *  fixes it: no id to select it by, then a key that will not be read, then a tag the
@@ -147,14 +177,33 @@ function describeDefect(meta) {
     const prefixed = `simt-${unknown.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
     return PROFILE_KEYS.has(prefixed)
       ? `key "${unknown}" is this tool's own, not the editor's; it is spelled "${prefixed}"`
-      : `unrecognised frontmatter key "${unknown}"; simt-dev's own keys are simt-id, simt-title, simt-applies, simt-fallback`;
+      : `unrecognised frontmatter key "${unknown}"; simt-dev's own keys are simt-id, simt-title, simt-applies, simt-fallback, simt-scope`;
   }
   const applies = meta['simt-applies'];
   if (!Array.isArray(applies)) return null;
   const undeclared = applies.find((tag) => !KNOWN_TAGS.has(tag));
-  return undeclared === undefined
-    ? null
-    : `simt-applies names "${undeclared}", which fingerprint() never emits, so this profile could never be selected`;
+  if (undeclared !== undefined) {
+    return `simt-applies names "${undeclared}", which fingerprint() never emits, so this profile could never be selected`;
+  }
+  const priority = meta['simt-priority'];
+  if (priority !== undefined && !PRIORITY_CLASSES.includes(priority)) {
+    return `simt-priority is "${priority}"; the classes are ${PRIORITY_CLASSES.join(', ')}, in the order a kernel packs them`;
+  }
+  const scope = meta['simt-scope'];
+  if (scope === undefined) return null;
+  // A scope that matches the whole repository is the eager profile wearing a costume:
+  // the reader is told the rule narrows, and the rule loads on every file. `**` and
+  // `**/*` are the two spellings of that, and both are the default a surface applies
+  // when it is given no pattern at all.
+  const CATCH_ALL = new Set(['**', '**/*', '*']);
+  if (scope.length === 0) {
+    return 'simt-scope is empty; a profile with no pattern would load as eagerly as one with no simt-scope at all';
+  }
+  const bad = scope.find((glob) => typeof glob !== 'string' || glob === '' || CATCH_ALL.has(glob));
+  if (bad !== undefined) {
+    return `simt-scope needs at least one pattern that narrows; "${bad}" matches every file, so the profile would load exactly as eagerly as one with no simt-scope`;
+  }
+  return null;
 }
 
 /**
@@ -361,6 +410,19 @@ async function ruleBodies(root, manifest, flags) {
   return { resolved, bodies, problems, notes, skipped };
 }
 
+/**
+ * The command card for a repository and the evidence its markers may be proved by.
+ *
+ * Both the region and the package regions need the proofs, and they must be the same set:
+ * a rule dropped at the root and kept in a package would be one rule treated as two. The
+ * card comes back alongside because the caller that needs the proofs also needs the card's
+ * bytes, and building it twice would read the manifest twice for no second answer.
+ */
+async function inferableEvidence(root, { stack, facts, manifest }) {
+  const card = await commandCard({ root, manifest, stack, facts });
+  return { card, proofs: inferableProofs({ facts, stack, card, manifest }) };
+}
+
 /**
  * The one place the desired region is computed. `plan` (which writes) and
  * `checkTarget` (which gates) both go through this, so they cannot disagree
@@ -371,21 +433,130 @@ export async function desiredRegion(root, flags) {
   const { stack, facts, manifest } = await fingerprint(root);
   const all = await loadRules(root);
   const { selected, fallback, notes } = select(all, stack, facts);
-
-  let body = render(selected);
-  let sources = selected.map((r) => r.source);
-  const folded = [];
-
-  // When every selected surface carries its rules inside the primary document, the
-  // per-rule bodies belong in the region too — otherwise a repo on the standard
-  // surface receives AGENTS.md and none of the always-on process rules, because
-  // those had nowhere else to live. One file, one region, one place a reader opens.
   const { resolved, bodies, problems, notes: ruleNotes } = await ruleBodies(
     root,
     manifest,
     flags ?? {},
   );
   notes.push(...ruleNotes);
+
+  // A profile that declares a scope leaves the region only when every selected surface
+  // can load it narrowly. The alternative is a profile written only as a scoped file for
+  // a reader whose surface cannot scope — a rule nobody loads, which is worse than one
+  // that loads eagerly (ADR-071). A surface that cannot scope it therefore keeps the
+  // profile in the region and says so, rather than letting the region quietly shrink.
+  const narrowing = resolved.surfaces.every((s) => canScope(s));
+  const scoped = [];
+  const inRegion = [];
+  for (const r of selected) {
+    const declares = Array.isArray(r.scope) && r.scope.length > 0 && r.error === null;
+    if (!declares) {
+      inRegion.push(r);
+      continue;
+    }
+    // A profile only leaves the region when a narrowed file can replace it. When any
+    // selected surface cannot narrow, the file would be the only home for a rule that
+    // reader cannot reach — so it stays, and says why.
+    if (narrowing) {
+      scoped.push(r);
+      continue;
+    }
+    inRegion.push(r);
+    notes.push(
+      `${r.id} declares simt-scope, but ${resolved.source} selects a surface that cannot narrow a rule, so it stays in the region`,
+    );
+  }
+
+// The kernel. In `kernel` mode only the hard and command classes are packed into the
+  // region and every other rule is deferred to `rules show <id>`, which is what makes
+  // R08's accept criterion reachable at all: a budget cannot be met by a projection that
+  // never tries. `full` is the default and stays it until R02 has measured that a
+  // kernel does not lose compliance, because nobody has measured it yet.
+  //
+  // A rule with no stated class is deferred, not packed. The two mistakes are not
+  // symmetric: packing a line that should have been deferred spends the budget the mode
+  // exists to save, while deferring a line that should have been packed costs a reader
+  // one `rules show`. The mode is a promise about bytes, so it is the bytes that win.
+  const mode = await projectionMode(root);
+  const packed = [];
+  const deferred = [];
+  for (const r of inRegion) {
+    if (mode === 'kernel' && (r.error !== null || !KERNEL_CLASSES.has(r.priority))) deferred.push(r);
+    else packed.push(r);
+  }
+  // The command card leads the region. The exact commands for this repository are the
+  // bytes a reader cannot infer from rules that are identical everywhere (plan 0003 R10),
+  // so they go first — above even the core rules. It is derived from committed evidence
+  // only, in one place, so `plan` and `checkTarget` cannot disagree about it and two
+  // machines render it byte-identically.
+  const { card, proofs } = await inferableEvidence(root, { stack, facts, manifest });
+  if (card.dropped.length > 0) {
+    // Reported where every other projection note is reported. A card that lost a command
+    // in silence is a card a reader cannot tell is incomplete.
+    notes.push(
+      `command card: dropped ${card.dropped.join(', ')} to stay within ${CARD_LIMIT_BYTES} bytes`,
+    );
+  }
+  // Inferability (R09). A marked line leaves when the repository proves the evidence it
+  // names. `shipped` is a separate list from `packed` because they are separate decisions:
+  // the kernel is about which classes cost a reader nothing to skip, and this is about
+  // which lines the reader already knows.
+  const inferable = [];
+  const shipped = [];
+  for (const r of packed) {
+    const filtered = filterInferable(r.body, proofs);
+    if (!filtered.changed) {
+      shipped.push(r);
+      continue;
+    }
+    for (const x of filtered.removed) inferable.push({ rule: r.id, text: x.text, expr: x.expr });
+    shipped.push({ ...r, body: filtered.body });
+  }
+  let body = card.text ? `${card.text}\n\n${render(shipped)}` : render(shipped);
+  let sources = shipped.map((r) => r.source);
+  if (inferable.length > 0) {
+    // Never silent, and never a heading. A line that left with no trace repeats the
+    // mistake ADR-073 rejected for deferred rules, and a `## Dropped` section spends region
+    // bytes on lines the reader is being told not to read. A count they can act on, plus —
+    // with `--explain` — the evidence behind each one, is the third option.
+    notes.push(
+      `inferability: dropped ${inferable.length} line(s) this repository already proves; ${CLI} sync --explain names each one and the evidence behind it`,
+    );
+    if (flags?.explain === true) {
+      for (const x of inferable) {
+        notes.push(`inferable: ${x.rule} dropped "${x.text}" — proved by ${x.expr}`);
+      }
+    }
+  }
+  const folded = [];
+
+  // The pointer. A reader who opens AGENTS.md and does not find a profile they know is
+  // there will look for it, and the honest answer is where it moved: the file a scoping
+  // surface loads it from, and the files it now matches. Without the line the region's
+  // source list is quietly short one entry, which reads as a rule that was deleted.
+  if (scoped.length > 0 && narrowing) {
+    const lines = scoped.map(
+      (r) =>
+        `- ${sourceTitle(r, 'profile')} — loads only when a matching file is in play (${r.scope.join(', ')}): ${scopedPaths(r, resolved).join(', ')}`,
+    );
+    body += `\n\n## Scoped rules\n\n${lines.join('\n')}`;
+    for (const r of scoped) sources.push(r.source);
+  }
+
+  if (deferred.length > 0) {
+    // The pointer is the same shape as the scoped one above, and for the same reason:
+    // a reader who opens AGENTS.md and does not find a rule they know is there will
+    // look for it. What it costs to find it has to be one command, named per rule.
+    const lines = [...deferred]
+      .sort(byPriorityThenId)
+      .map(
+        (r) =>
+          `- ${sourceTitle(r, 'profile')} — ${r.priority ?? 'unclassified'}, deferred in kernel mode. Show it with: ${CLI} rules show ${r.id}`,
+      );
+    body += `\n\n## Deferred rules\n\n${lines.join('\n')}`;
+    for (const r of deferred) sources.push(r.source);
+  }
+
   if (foldsRules(resolved)) {
     for (const { rule, body: ruleBody } of bodies) {
       // `## Process:`, not `### id`. The body already uses `##`, and a third-level
@@ -407,6 +578,17 @@ export async function desiredRegion(root, flags) {
     all,
     profiles: selected.map((r) => r.id),
     folded,
+    mode,
+    deferred: deferred.map((r) => r.id),
+    // The marked lines that left, each with the evidence that dropped it. The region is
+    // written without them; `--explain` is what reads this list, so a removal is reportable
+    // without spending region bytes and without a second computation to find it.
+    inferable,
+    // The profiles that left the region, and the surfaces that accepted them as files.
+    // `plan` writes them and `checkTarget` gates them through this list, so a projected
+    // file and a drifted one are decided by the same computation.
+    scoped,
+    narrowing,
     surfaces: resolved.ids,
     surfaceSource: resolved.source,
     problems,
@@ -417,6 +599,27 @@ export async function desiredRegion(root, flags) {
   };
 }
 
+/**
+ * Every per-rule file a scoped profile is written to, as paths a reader can open.
+ *
+ * Only the surfaces that can scope get one: a Cursor `.mdc` with `globs` and
+ * `alwaysApply: false`, an Antigravity file with `trigger: glob`, a Copilot
+ * `.instructions.md` with `applyTo`. A surface that reads the region already (opencode)
+ * has no file channel at all, and Claude's scoping key is the documented-defect one,
+ * so neither appears here.
+ */
+function scopedPaths(rule, resolved) {
+  const out = [];
+  for (const s of resolved.surfaces) {
+    if (!canScope(s) || !s.rule) continue;
+    // A folded surface already carries the whole region; it is the reason this profile
+    // is only a file when folding is off, which is the caller's question to answer.
+    if (s.foldRules === true && s.readsPrimary === true && foldsRules(resolved)) continue;
+    out.push(rulePath(s.id, rule.id));
+  }
+  return out;
+}
+
 /**
  * Read every rule file once, with its frontmatter parsed, plus any repo-local
  * profile under `.simt-dev/profiles/`.
@@ -444,7 +647,42 @@ export async function loadRules(root = null) {
     collected.push({ file, dir: RULES_DIR, origin: 'central', source: `rules/${file}` });
   }
 
+  // Packs go in before the repo's own profiles and after the built-ins, because
+  // that is the order they lose to. The collection order is the tie-break `select`
+  // reads for two profiles of equal rank, so "collected central, then pack, then
+  // local" is the precedence stated once rather than restated in the comparator.
   if (root !== null) {
+    const { packs } = await resolvePacks(root);
+    for (const pack of packs) {
+      // `present`, not `ok`. A pack whose bytes disagree with its pin still projects:
+      // dropping it would let the next `sync` delete the rules it carries, so the
+      // remedy the finding names would cause the damage it exists to report.
+      if (!pack.present) continue;
+      const packRules = join(pack.dir, 'rules');
+      let names = [];
+      try {
+        names = (await readdir(packRules)).filter((n) => n.endsWith('.md')).sort();
+      } catch {
+        names = [];
+      }
+      let stackNames = [];
+      try {
+        stackNames = (await readdir(join(packRules, 'stacks')))
+          .filter((n) => n.endsWith('.md'))
+          .map((n) => `stacks/${n}`);
+      } catch {
+        stackNames.length = 0;
+      }
+      for (const file of [...names, ...stackNames].sort()) {
+        collected.push({
+          file,
+          dir: packRules,
+          origin: 'pack',
+          source: `${PACK_DIR}/${pack.name}/rules/${file}`,
+        });
+      }
+    }
+
     const localDir = join(root, LOCAL_PROFILE_DIR);
     let localNames = [];
     try {
@@ -466,6 +704,7 @@ export async function loadRules(root = null) {
   for (const item of collected) {
     const text = await readFile(join(item.dir, item.file), 'utf8');
     const meta = parseFrontmatter(text);
+    const body = stripFrontmatter(text);
     out.push({
       file: item.file,
       origin: item.origin,
@@ -474,14 +713,81 @@ export async function loadRules(root = null) {
       title: meta['simt-title'] ?? null,
       applies: meta['simt-applies'] ?? [],
       fallback: meta['simt-fallback'] === true,
+      scope: Array.isArray(meta['simt-scope']) ? meta['simt-scope'] : null,
+      priority: meta['simt-priority'] ?? null,
       bytes: Buffer.byteLength(text),
-      body: stripFrontmatter(text),
-      error: describeDefect(meta),
+      body,
+      // A marker naming evidence the tool cannot check is a broken rule like any other, so
+      // it travels the field that already reaches `check` and `rules list`. The
+      // frontmatter defect wins, because a rule that cannot say what it applies to cannot
+      // be reasoned about at all.
+      error: describeDefect(meta) ?? inferableDefect(body),
     });
   }
   return out;
 }
 
+/**
+ * The regions a monorepo's packages each need, as bodies ready to be written.
+ *
+ * A repository with packages in it is projected twice over: the root carries the
+ * rules every package shares, and each package carries the profiles IT selects and
+ * the root does not. A reader working in `apps/web` opens two files by walking up,
+ * and gets the union; a reader who only reads the root still gets everything that
+ * is not package-specific. Nothing is repeated, so nothing goes stale twice
+ * (ADR-066).
+ *
+ * A package whose delta is empty gets no file. Writing an empty region into every
+ * directory of a large monorepo would be noise the reader has to learn to skip,
+ * and a file with nothing in it is not a projection, it is an absence with a
+ * generated header on it.
+ *
+ * The rule set is the ROOT's - local profiles and packs are the repository's, and
+ * a package that re-read them from its own directory would resolve a different
+ * set in a directory that has no manifest.
+ *
+ * @returns {Promise<{regions: {path: string, ecosystem: string, stack: string[],
+ *   facts: string[], profiles: string[], body: string, meta: {sha: string, sources: string[]}}[],
+ *   notes: string[]}>}
+ */
+export async function packageRegions(root, flags, rootProfiles = null) {
+  const shared = rootProfiles ?? (await desiredRegion(root, flags)).profiles;
+  const { packages, notes } = await discoverPackages(root);
+  if (packages.length === 0) return { regions: [], notes };
+
+  const rules = await loadRules(root);
+  const sha = await provenanceDigest();
+  // The ROOT's proofs, not the package's. The rule set is the root's, so which lines it
+  // already proves is a fact about the repository rather than about the directory a file
+  // lands in — filtering a package by the package's own facts would keep a rule here and
+  // drop it one directory up, which is the same rule treated as two.
+  const { proofs } = await inferableEvidence(root, await fingerprint(root));
+  const regions = [];
+  for (const pkg of packages) {
+    const fp = await fingerprint(join(root, pkg.path));
+    const { selected } = select(rules, fp.stack ?? [], fp.facts ?? []);
+    const delta = selected.filter((r) => !shared.includes(r.id));
+    if (delta.length === 0) continue;
+    const shipped = delta.map((r) => {
+      const filtered = filterInferable(r.body, proofs);
+      return filtered.changed ? { ...r, body: filtered.body } : r;
+    });
+    regions.push({
+      path: pkg.path,
+      ecosystem: pkg.ecosystem,
+      stack: fp.stack ?? [],
+      facts: fp.facts ?? [],
+      profiles: delta.map((r) => r.id),
+      // One sentence, because the file's whole purpose is to be found by a reader
+      // who does not know it exists: without it, a nested region reads as a
+      // complete set of rules and the shared half looks forgotten.
+      body: `The rules this package selects on its own. Everything the repository shares with its other packages is in the region at the root.\n\n${render(shipped)}`,
+      meta: { sha, sources: delta.map((r) => r.source) },
+    });
+  }
+  return { regions, notes };
+}
+
 /**
  * Selection is pure set intersection: core always, then every profile whose
  * `simt-applies` intersects the repo's signals. `node` is the fallback, so it is only
@@ -492,7 +798,7 @@ export async function loadRules(root = null) {
  * fact is the more durable choice because it survives the framework being
  * replaced.
  *
- * `shadowed` lists local profiles that replaced a central one, so a caller can
+ * `shadowed` lists profiles that replaced one they outrank, so a caller can
  * report it rather than silently changing what a repo receives.
  */
 export function select(rules, stack, facts = []) {
@@ -506,9 +812,14 @@ export function select(rules, stack, facts = []) {
       ids.set(rule.id, rule);
       continue;
     }
-    // A local profile is allowed to replace a central one; two of the same
-    // origin are a defect the caller must be able to see.
-    const localWins = rule.origin === 'local' && prior.origin !== 'local';
+    // A profile may replace one it outranks; two of the same origin are a defect
+    // the caller must be able to see.
+    //
+    // Ranked rather than `=== 'local'` because there is now a third origin. The
+    // ordering it encodes - the repository's own profile, then a pack it declares,
+    // then what the tool ships - is the whole precedence rule, in one comparison
+    // that cannot drift from the order the files were collected in.
+    const localWins = ORIGIN_RANK[rule.origin] > ORIGIN_RANK[prior.origin];
     if (localWins) {
       ids.set(rule.id, rule);
       shadowed.push({
@@ -580,6 +891,32 @@ export function render(selected) {
     .join('\n\n');
 }
 
+/**
+ * The projection mode this repository declared, or `full`.
+ *
+ * Absent means `full`, and `full` is the default rather than a fallback: no measurement
+ * yet says a kernel does not lose compliance (plan 0003 R02), so the mode that changes
+ * what a reader gets cannot be the one nobody chose.
+ */
+async function projectionMode(root) {
+  const { manifest } = await readManifest(root);
+  return manifest?.mode === 'kernel' ? 'kernel' : 'full';
+}
+
+/**
+ * Deterministic kernel order: the class a rule declares, then its id.
+ *
+ * The tie-break is not decoration. Two rules of the same class packed in file order
+ * would move when a file is added to the directory, and a projection that reorders
+ * itself on an unrelated commit is a projection nobody can diff (ADR-013).
+ */
+function byPriorityThenId(a, b) {
+  const classA = PRIORITY_CLASSES.indexOf(a.priority ?? 'style');
+  const classB = PRIORITY_CLASSES.indexOf(b.priority ?? 'style');
+  if (classA !== classB) return classA - classB;
+  return String(a.id).localeCompare(String(b.id));
+}
+
 /**
  * One source, one `##` heading, then its body with every heading demoted.
  *
@@ -634,6 +971,12 @@ function parseFrontmatter(text) {
         .slice(1, raw.lastIndexOf(']'))
         .split(',')
         .map((s) => s.trim())
+        // A quoted item is a quoted item: the glob inside is the value, not the quotes
+        // around it. A profile author quoting `\"src/**/*.ts\"` because their editor
+        // colouring complains about a bare `*` would otherwise project a pattern the
+        // surface matches nothing against.
+        .map((s) => (s.length >= 2 && s.startsWith('"') && s.endsWith('"') ? s.slice(1, -1) : s))
+        .map((s) => (s.length >= 2 && s.startsWith("'") && s.endsWith("'") ? s.slice(1, -1) : s))
         .filter(Boolean);
     } else out[key] = raw.trim();
   }