simt-dev 0.2.0 → 0.2.2

package/src/projection/rules.mjs

@@ -27,10 +27,13 @@ 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 { 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, '..', '..');
@@ -57,13 +60,15 @@ const RULES_DIR = join(ROOT, 'rules');
  * unrecoverably. That is the failure this replaces (ADR-032).
  *
  * The digest covers every byte string that leaves the package, and nothing else. That
- * set is `rules/` and `graph/` on disk plus the RENDERED baseline bodies: the shared
+ * set is `rules/` on disk plus the RENDERED baseline bodies: the shared
  * `.editorconfig` and `.gitattributes` blocks are strings a repository receives, so by
  * ADR-015's rule a source is identified by its content rather than by the file it
- * happens to live in, and a body defined in `src/` is a source like any other.
+ * happens to live in, and a body defined in `src/` is a source like any other. The
+ * registry (`graph/`) is workspace data the package no longer ships (ADR-061), so it is
+ * not part of this set even where it exists on disk.
  *
- * It deliberately excludes `src/` as a directory. A refactor that changes no rule, no
- * registry entry and no baseline body produces byte-identical output, and stamping those
+ * It deliberately excludes `src/` as a directory. A refactor that changes no rule and
+ * no baseline body produces byte-identical output, and stamping those
  * consumers would report drift where there is none - which is the estate's own rule that
  * a report must be a fact.
  *
@@ -93,7 +98,7 @@ export async function provenanceDigest() {
  */
 export async function provenanceInputs() {
   const inputs = [];
-  for (const dir of ['rules', 'graph']) {
+  for (const dir of ['rules']) {
     for (const rel of await walk(join(ROOT, dir))) {
       inputs.push({ path: `${dir}/${rel}`, bytes: await readFile(join(ROOT, dir, rel)) });
     }
@@ -121,11 +126,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. */
-const PROFILE_KEYS = new Set(['simt-id', 'simt-title', 'simt-applies', 'simt-fallback']);
+/** 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', '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
@@ -144,14 +175,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;
 }
 
 /**
@@ -293,8 +343,18 @@ async function ruleBodies(root, manifest, flags) {
 
   const declared = await readDeclared(root);
 
+  // Deliberately NOT folded in. This array becomes `mdc.problems`, and `sync` reports it
+  // as "canonical .mdc rule(s) cannot be projected" with the remedy "fix the reported
+  // substitution keys in simt.json". A surface typo is not a rule problem and has no
+  // substitution keys — `surfaces: ["curosr"]` was reported to a reader as though they
+  // had misspelled a key in a block they had never heard of, and the only way to find the
+  // real cause was to run `check`, which already said it plainly. Two surfaces report the
+  // same problem; only one of them names it correctly, and the one that mislabels it is
+  // the one the writer uses.
+  //
+  // Nothing is lost by dropping it here: `plan` returns `surfaceProblems` from this same
+  // `resolveSurfaces` call, and `checkTargets` reads it independently at project.mjs.
   const resolved = resolveSurfaces(manifest, flags ?? {});
-  for (const p of resolved.problems) problems.push(p);
 
   // A manifest key that no shipped rule declares is a typo, or a leftover from a rule
   // that was renamed. Both read as "configured" in the one file a reviewer opens to
@@ -358,21 +418,88 @@ 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);
+  }
+  let body = render(packed);
+  let sources = packed.map((r) => r.source);
+  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
@@ -394,6 +521,13 @@ export async function desiredRegion(root, flags) {
     all,
     profiles: selected.map((r) => r.id),
     folded,
+    mode,
+    deferred: deferred.map((r) => r.id),
+    // 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,
@@ -404,6 +538,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/`.
@@ -431,7 +586,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 {
@@ -461,6 +651,8 @@ 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),
@@ -469,6 +661,58 @@ export async function loadRules(root = null) {
   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();
+  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;
+    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(delta)}`,
+      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
@@ -479,7 +723,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 = []) {
@@ -493,9 +737,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({
@@ -567,6 +816,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.
  *
@@ -574,7 +849,7 @@ export function render(selected) {
  * so it lands directly under `## Stack: …` instead of under whatever section the
  * previous source ended on.
  */
-export function frameSource(rule, body, kind) {
+function frameSource(rule, body, kind) {
   const text = demoteHeadings(body).trim();
   if (!text) return '';
   const title = sourceTitle(rule, kind);
@@ -621,6 +896,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();
   }