simt-dev 0.6.3 → 0.7.1

package/src/projection/manifest.mjs

@@ -24,36 +24,25 @@ import { journaledWriteFile } from '../journal.mjs';
 // answers to "can this repo run that gate", which is precisely the kind of drift this
 // file exists to prevent elsewhere.
 import { getGate } from '../hooks/gates.mjs';
+// Q31: the one Node runner table. This module and the card, capability,
+// dispatcher and CI workflow all spell `<manager> run <script>` from it.
+import { runScript } from '../ecosystem/node-runner.mjs';
 
 // Imported as well as re-exported: a bare `export { X as Y } from` binds nothing here,
 // and the manifest name is used a dozen times below in remedy strings that name this
 // file by name.
 import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+import { GENERATED_KEYS_OF, KEYS, loadManifest, manifestPath } from '../manifest/schema.mjs';
 import { CLI } from '../name.mjs';
 import { packageVersion } from '../package-version.mjs';
 export const MANIFEST = MANIFEST_FILE;
 
+// Still exported from here because this is where the manifest lived: every caller that
+// resolved its path through this module keeps working, and the implementation moved.
+export { manifestPath };
+
 export { MANIFEST_LEGACY };
 
-/**
- * The manifest a repository has, which is not necessarily the one this tool would write.
- *
- * The file was renamed from `simt-dev.json` to `simt.json`. Every read site used to say
- * `join(root, MANIFEST)` and would have reported an adopted repository as unadopted the
- * day the constant moved - and "no manifest" means "never adopted", which is the answer
- * that offers to re-adopt a repo that is already done. Fourteen repositories carry the
- * old name on disk.
- *
- * So the old name is read as a fallback and the new one is written. `writeManifest`
- * renames rather than creating a second file, which is how the window closes: the first
- * `simt init` or `simt sync` in an adopted repo retires the old name by moving it.
- */
-export async function manifestPath(root) {
-  const next = join(root, MANIFEST);
-  if (existsSync(next)) return next;
-  const previous = join(root, MANIFEST_LEGACY);
-  return existsSync(previous) ? previous : next;
-}
 
 
 /**
@@ -201,7 +190,7 @@ export const ECOSYSTEMS = [
  * fail closed — the defect is declaring a gate this repo has no way to run.
  *
  * The check mirrors what the dispatcher actually attempts:
- *   - `script` gates  run `npm run <script>`, so the script must exist
+ *   - `script` gates  run `<manager> run <script>`, so the script must exist
  *   - `staged` gates  look for each named tool in `node_modules/.bin`, so it must be
  *     installed, not merely declared as a dependency
  *   - `command` gates run whatever the manifest's `gates.commands` declares, so a
@@ -237,13 +226,16 @@ export function gateRunnable(gate, capability = {}) {
   }
   if (gate.kind === 'script') {
     const script = gate.script ?? gate.name;
-    if (capability.scripts?.[script]) return { runnable: true, why: `runs: npm run ${script}` };
+    // Q31: the runnable sentence names the repo's own runner, never a bare npm
+    // assumption — the card, the dispatcher and this check read one resolver.
+    const spell = runScript(capability.runner ?? 'npm', script);
+    if (capability.scripts?.[script]) return { runnable: true, why: `runs: ${spell}` };
     // Saying "no script in package.json" about a repo with no package.json states a
     // fact about a file that does not exist and implies a fix that cannot be taken.
     return {
       runnable: false,
       why: foreign
-        ? `this repo runs ${runnerName(capability.runner)}, not npm, so "npm run ${script}" cannot run here`
+        ? `this repo runs ${runnerName(capability.runner)}, not npm, so "${spell}" cannot run here`
         : `no "${script}" script in package.json`,
     };
   }
@@ -277,11 +269,17 @@ function gateRemedy(gate, { existing = false, runner = null } = {}) {
   const name = gate?.name ?? 'the gate';
   const npmShaped = gate?.kind === 'staged' || gate?.kind === 'script';
   const foreign = isForeignRunner(runner);
+  // Q31: a missing tool in a Node repo names the repo's own installer —
+  // `pnpm add -D`, not `npm i -D` — and anything elsewhere keeps the honest
+  // undo: name the program under `gates.commands`.
+  const addDev = { npm: 'npm i -D', pnpm: 'pnpm add -D', yarn: 'yarn add -D', bun: 'bun add -d' }[runner] ?? null;
   const fix =
     npmShaped && foreign
       ? `this repo runs ${runnerName(runner)}, not npm; name the program under "gates.commands" in ${MANIFEST_FILE} instead of the npm equivalent`
       : gate?.kind === 'staged'
-        ? `install ${gate.tools.join(', ')} as a dev dependency`
+        ? addDev
+          ? `install ${gate.tools.join(', ')} as a dev dependency: ${addDev} ${gate.tools.join(' ')}   (the gate runs from the pinned dependency)`
+          : `install ${gate.tools.join(', ')} as a dev dependency`
         : gate?.kind === 'script'
           ? `add a "${gate.script ?? name}" script to package.json`
           : gate?.kind === 'command'
@@ -302,11 +300,14 @@ function gateRemedy(gate, { existing = false, runner = null } = {}) {
 /**
  * Is this runner one where `npm run` is not how a gate is spelled?
  *
- * `undefined` means "the caller did not report a runner", and `npm` means the npm
- * remedy applies. Only a positively identified other ecosystem changes the wording.
+ * `undefined` means "the caller did not report a runner", and every Node manager
+ * (`npm`, `pnpm`, `yarn`, `bun`) spells gates as `<manager> run <script>` with
+ * scripts living in the same `package.json`. Only a positively identified
+ * non-Node runner changes the wording. (Q31: pnpm is Node-shaped, not foreign.)
  */
 function isForeignRunner(runner) {
-  return runner != null && runner !== 'npm';
+  if (runner == null) return false;
+  return !['npm', 'pnpm', 'yarn', 'bun'].includes(runner);
 }
 
 /** How a reader would name the runner in a sentence. */
@@ -316,6 +317,9 @@ function runnerName(runner) {
       none: 'no recognised runner',
       gradle: 'Gradle',
       python: 'Python',
+      npm: 'npm',
+      pnpm: 'pnpm',
+      yarn: 'yarn',
       bun: 'bun',
       cargo: 'Cargo',
       go: 'Go',
@@ -383,14 +387,15 @@ export function planGates(stack = [], capability = null, facts = []) {
  */
 function ecosystemCommands(facts = [], capability = null) {
   if (!capability?.tools?.length) return {};
-  // An npm runner already answers "how do I test and format" with its own package.json
-  // scripts, and a seed only wins over those scripts when the repo has not declared a
-  // command of its own — which is exactly the mixed repos (package.json AND Cargo.toml)
-  // where the script is the deliberate answer. Seeding there would replace a choice with
-  // a default; the reader's escape hatch is declaring gates.commands by hand, which a
-  // seed would lose to anyway. Pure ecosystem repos have runner 'cargo'/'go'/... and
-  // seed normally.
-  if (capability.runner === 'npm') return {};
+  // A Node runner (npm/pnpm/yarn/bun) already answers "how do I test and format"
+  // with its own package.json scripts, and a seed only wins over those scripts when
+  // the repo has not declared a command of its own — which is exactly the mixed
+  // repos (package.json AND Cargo.toml) where the script is the deliberate answer.
+  // Seeding there would replace a choice with a default; the reader's escape hatch
+  // is declaring gates.commands by hand, which a seed would lose to anyway. Pure
+  // ecosystem repos have runner 'cargo'/'go'/... and seed normally.
+  // Q31: every Node manager skips seeding — pnpm is not "foreign", it is Node.
+  if (['npm', 'pnpm', 'yarn', 'bun'].includes(capability.runner)) return {};
   const present = new Set(facts);
   const commands = {};
   for (const eco of ECOSYSTEMS) {
@@ -414,7 +419,7 @@ function ecosystemCommands(facts = [], capability = null) {
  */
 export function buildManifest({ root, stack = [], sha, version, existing = null, capability = null, surfaces = undefined, facts = [] }) {
   const gates = defaultGates(stack, facts);
-  const limits = defaultLimits(stack);
+  const limits = defaultLimits();
 
   // A re-init must never silently weaken a repo's own declaration: existing
   // limits and gates win over defaults, and only the projection stamp is refreshed.
@@ -726,7 +731,27 @@ export function declaredShared(manifest) {
   return { level, rules };
 }
 
-export const GENERATED_KEYS = new Set(['$comment', 'projection']);
+// Derived from the table rather than restated: a key this tool writes is a `tool` key
+// marked generated, and a second list here is the drift this module exists to end.
+export const GENERATED_KEYS = GENERATED_KEYS_OF;
+
+
+// The sub-keys of `projection` this tool writes. `projection` is a generated key, but
+// not wholesale: the repository owns sub-keys this writer does not emit (`place` is the
+// one that shipped), and a repair that replaces the object deletes them (review 0003 Q26).
+const PROJECTION_KEYS = new Set(['simtDevSha', 'version']);
+
+/** The `projection` object a manifest carries; anything that is not an object is nothing. */
+function projectionOf(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+/** Only the generated sub-keys of a `projection` object, in the order this writer emits them. */
+function generatedProjection(value) {
+  const out = {};
+  for (const key of PROJECTION_KEYS) if (key in projectionOf(value)) out[key] = value[key];
+  return out;
+}
 
 /**
  * A manifest with this tool's own fields replaced by what this build writes, and
@@ -738,13 +763,22 @@ export const GENERATED_KEYS = new Set(['$comment', 'projection']);
  * repo chose is never compared" is a promise about the repair too, not only about
  * the report, and a repair is exactly where it would be broken.
  *
+ * `projection` merges the same way, one level down: the object the repository has
+ * keeps every sub-key it chose, and the generated sub-keys take this build's values.
+ *
  * @param {object} manifest the repository's manifest, as parsed
  * @param {object} expected `buildManifest`'s output, from the call `manifestDrift` made
  * @returns {object} a new manifest; the argument is not mutated
  */
 export function withGenerated(manifest, expected) {
   const patched = { ...manifest };
-  for (const key of GENERATED_KEYS) if (key in expected) patched[key] = expected[key];
+  for (const key of GENERATED_KEYS) {
+    if (!(key in expected)) continue;
+    patched[key] =
+      key === 'projection'
+        ? { ...projectionOf(manifest?.projection), ...expected.projection }
+        : expected[key];
+  }
   return patched;
 }
 
@@ -787,9 +821,14 @@ export async function manifestDrift(root, stack, sha) {
   // `[...GENERATED_KEYS]`, and not `Object.keys(expected)`: the question is which
   // fields are ours, and the answer is the set above. Iterating the expected object
   // asks the same question of a different list and can only agree by coincidence.
-  const stale = [...GENERATED_KEYS].filter(
-    (key) => key in expected && JSON.stringify(manifest[key]) !== JSON.stringify(expected[key]),
-  );
+  const stale = [...GENERATED_KEYS].filter((key) => {
+    if (!(key in expected)) return false;
+    // `projection` compares on the sub-keys this tool writes: a sub-key the repo
+    // chose (`place`) is not a stale field, and reporting it is what made `sync`
+    // delete the one setting that was not stale (review 0003 Q26).
+    const actual = key === 'projection' ? generatedProjection(manifest[key]) : manifest[key];
+    return JSON.stringify(actual) !== JSON.stringify(expected[key]);
+  });
   if (stale.length > 0) {
     return {
       file: MANIFEST,
@@ -842,20 +881,17 @@ export function manifestText(manifest) {
   return `${JSON.stringify(manifest, null, 2)}\n`;
 }
 
-/** @returns {{manifest: object|null, exists: boolean, error: string|null}} */
+/**
+ * The manifest in the shape the callers already read, now answered by the one loader
+ * (review 0003 Q69). `error` is the unreadable-file case only: a manifest with a value
+ * the schema cannot use is still a manifest, and refusing it here would turn every
+ * reader into a second validator.
+ *
+ * @returns {Promise<{manifest: object|null, exists: boolean, error: string|null}>}
+ */
 export async function readManifest(root) {
-  const path = await manifestPath(root);
-  let text;
-  try {
-    text = await readFile(path, 'utf8');
-  } catch {
-    return { manifest: null, exists: false, error: null };
-  }
-  try {
-    return { manifest: JSON.parse(text), exists: true, error: null };
-  } catch (error) {
-    return { manifest: null, exists: true, error: `unparseable: ${error.message}` };
-  }
+  const { manifest, exists, problems } = await loadManifest(root);
+  return { manifest, exists, error: exists && manifest === null ? (problems[0] ?? 'unparseable') : null };
 }
 
 export async function writeManifest(root, manifest, journal = null) {

package/src/projection/markers.mjs

@@ -165,6 +165,43 @@ export function parse(text, style) {
   };
 }
 
+/**
+ * The line spans of every generated region in `text`, across both marker styles.
+ *
+ * `parse` is the single reader: a malformed region is still a region (an edit
+ * anywhere in the file stays denied), so malformed counts as a span covering the
+ * whole file rather than as absent. Line numbers are 1-based and inclusive.
+ *
+ * @returns {{malformed: boolean, spans: Array<{start: number, end: number}>}}
+ */
+export function regionSpans(text) {
+  const spans = [];
+  let malformed = false;
+  for (const style of ['html', 'hash']) {
+    const state = parse(text, style);
+    if (state.status === 'malformed') {
+      malformed = true;
+      continue;
+    }
+    if (state.status !== 'ok') continue;
+    const start = state.before === '' ? 1 : state.before.split('\n').length + 1;
+    const bodyLines = state.body === '' ? 0 : state.body.split('\n').length;
+    spans.push({ start, end: start + bodyLines + 1 });
+  }
+  if (malformed) {
+    const total = text.split('\n').length;
+    return { malformed: true, spans: [{ start: 1, end: total }] };
+  }
+  return { malformed: false, spans };
+}
+
+/** Line range of `text.slice(index, index + length)`, 1-based and inclusive. */
+export function lineRangeOf(text, index, length) {
+  const start = text.slice(0, index).split('\n').length;
+  const end = text.slice(0, index + length).split('\n').length;
+  return { start, end };
+}
+
 function malformed(lines, from, at, reason) {
   return {
     status: 'malformed',
@@ -359,9 +396,12 @@ export function inject(text, body, meta, opts = {}) {
   // too. A body that matches with a seam that does not is red on `format:check`, and
   // reporting `unchanged` there means `check` finds no drift and `sync` never repairs
   // it - the repository stays red with no remedy the tool offers. Top placement is
-  // excluded because there the splice is a repair that legitimately moves bytes
-  // outside the markers, so the two files differ for a reason unrelated to the seam.
-  const settled = unchanged && (where === 'top' || spliced === text);
+  // excluded from the seam test because there the splice is a repair that
+  // legitimately moves bytes outside the markers, so the two files differ for a
+  // reason unrelated to the seam. Position is the test there instead: a region below
+  // the file's own settings has been moved, and the move is what `where: 'top'`
+  // exists to repair (review 0003 Q26).
+  const settled = unchanged && (where === 'top' ? state.before.trim() === '' : spliced === text);
   if (settled) return { ...seen, text, action: 'unchanged' };
 
   return { ...seen, text: spliced, action: 'updated' };

package/src/projection/mdc.mjs

@@ -28,6 +28,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { parse } from './markers.mjs';
+import { MANIFEST_FILE } from '../name.mjs';
 
 // ROOT is computed here rather than imported: project.mjs is the caller of every
 // function below, so importing it back would create a cycle for the sake of one
@@ -148,9 +149,18 @@ function parseSubstitutions(text) {
     const scope = next ? tail.slice(0, next.index + 1) : tail;
     const def = /^\s*default:\s*(.*)$/m.exec(scope);
     const desc = /^\s*describe:\s*(.*)$/m.exec(scope);
+    // A per-signal default: `default-<signal>:` picks the value when the repository
+    // carries that signal (a stack tag or a detection fact). `default:` is the
+    // fallback. The two cannot collide: `default:` requires the colon immediately
+    // after the word, and a signal line has a `-` there.
+    const perSignal = {};
+    for (const pm of scope.matchAll(/^\s*default-([a-z0-9][a-z0-9-]*):\s*(.*)$/gm)) {
+      perSignal[pm[1]] = unquote(pm[2].trim());
+    }
     out.push({
       key: hit[1],
       default: def ? unquote(def[1].trim()) : '',
+      perSignal,
       describe: desc ? unquote(desc[1].trim()) : '',
     });
   }
@@ -197,6 +207,19 @@ function stripFrontmatter(text) {
     .trim();
 }
 
+/**
+ * The default a signal set selects: the first per-signal default whose signal is
+ * present, else the plain default. Signals carry detection facts as well as stack
+ * tags, because a Go repository is selected on a fact, not a stack (review 0003 Q32).
+ */
+function pickDefault(sub, signals) {
+  const perSignal = sub.perSignal ?? {};
+  for (const s of signals) {
+    if (Object.prototype.hasOwnProperty.call(perSignal, s)) return perSignal[s];
+  }
+  return sub.default;
+}
+
 /**
  * Substitute declared placeholders.
  *
@@ -209,9 +232,11 @@ function stripFrontmatter(text) {
  * rendered rule would ship a literal `{{key}}`, which reads as a finished rule
  * and is not one.
  */
-export function renderMdc(rule, declared = {}) {
+export function renderMdc(rule, declared = {}, signals = []) {
   const problems = [];
-  let body = rule.body;
+  // The rule text names the manifest with a token and the render substitutes it,
+  // so a rename of the file is a change in one place (MANIFEST_FILE).
+  let body = rule.body.replaceAll('{manifest}', MANIFEST_FILE);
 
   for (const sub of rule.substitutions) {
     const has = Object.prototype.hasOwnProperty.call(declared, sub.key);
@@ -226,17 +251,19 @@ export function renderMdc(rule, declared = {}) {
     }
 
     if (provided === undefined || provided === null || provided === '') {
-      // Fall back to the default. An empty DEFAULT is also a drop instruction,
-      // which is how the same file serves a repo that has nothing to add.
-      if (sub.default === '') {
+      // Fall back to the default the signals select. An empty chosen default is
+      // also a drop instruction, which is how the same file serves a repo that
+      // has nothing to add.
+      const chosen = pickDefault(sub, signals);
+      if (chosen === '') {
         body = dropOrReplace(body, sub.key, '');
         continue;
       }
-      if (sub.default === undefined) {
+      if (chosen === undefined) {
         problems.push(`substitution ${sub.key} has no default and none declared`);
         continue;
       }
-      body = dropOrReplace(body, sub.key, sub.default);
+      body = dropOrReplace(body, sub.key, chosen);
       continue;
     }