simt-dev 0.2.0 → 0.2.1

package/src/projection/targets.mjs

@@ -64,14 +64,45 @@ export async function ruleTargets(root, rule, body, sha, resolved, notes) {
     }
 
     const mine = s.ruleFrontmatter(rule);
-    const frontmatter = extractFrontmatter(existing) ?? frontmatterBlock(mine);
+    // The frontmatter is re-derived, never inherited (S16).
+    //
+    // Two things were wrong and only the second was visible. The first was
+    // `extractFrontmatter(existing) ?? frontmatterBlock(mine)`, where the file's own
+    // block won whenever the file already had one. The second was this line's
+    // neighbour: when the existing region parsed cleanly, `composed` was the whole
+    // existing file, so `inject` replaced the region between the markers and left the
+    // frontmatter above them exactly as it found it — whatever this tool emitted the
+    // first time it saw this surface, forever. A surface that adds a key, or whose
+    // `alwaysApply` flips, could never reach a repository that had already adopted it,
+    // and no gate could report it: the file agrees with itself, so nothing is stale by
+    // any comparison the tool makes.
+    //
+    // One asymmetry, deliberately: a surface that emits NO frontmatter leaves whatever
+    // is there alone. This tool owns the block it writes and will replace it; deleting a
+    // block it did not write is a different operation, and a surface with no frontmatter
+    // of its own has no opinion about it.
+    const frontmatter = mine.length > 0 ? frontmatterBlock(mine) : extractFrontmatter(existing) ?? '';
     const state = exists ? parse(existing) : { status: 'absent' };
     // A surface that wants no frontmatter must not get a blank line where the
     // frontmatter would have been: Claude's rule files opened with two empty lines
     // before the marker, which is untidy in a file the reader will open, and a
     // difference between surfaces that no check reported.
+    //
+    // Swapped in place rather than stripped and rejoined. My first attempt here was
+    // `${frontmatter}\n${bodyAfterFrontmatter(existing)}`, which looked equivalent and
+    // was not: that helper's trailing `\n*` swallows the blank line between `---` and
+    // the region, so the reconstruction was one newline short of the file and `inject`
+    // reported `updated` on every run forever while writing identical bytes. The file
+    // was right; the verdict never settled, so `check` reported drift no reader could
+    // see and `sync` rewrote a correct file on every invocation. Anything that rebuilds
+    // a file has to reproduce the bytes it did not mean to touch, and the cheapest way
+    // to guarantee that is not to rebuild them.
     const composed =
-      state.status === 'ok' ? existing : frontmatter === '' ? '' : `${frontmatter}\n`;
+      state.status === 'ok'
+        ? swapFrontmatter(existing, frontmatter)
+        : frontmatter === ''
+          ? ''
+          : `${frontmatter}\n`;
     const result = inject(composed, body, { sha, sources: [rule.source] });
 
     // Report the prose being retired rather than letting it vanish into a diff the
@@ -201,11 +232,6 @@ export async function pointerState(root, pointer) {
   return { file: pointer.file, state: 'mispointed', link, detail: `points at ${link}` };
 }
 
-export function surfaceFrontmatter(surfaceId, rule) {
-  const s = SURFACES.find((x) => x.id === surfaceId);
-  return s && s.ruleFrontmatter ? s.ruleFrontmatter(rule) : [];
-}
-
 // The per-surface path lives in surfaces.mjs next to the row that justifies it;
 // re-exported so a caller building a target never has to know which module owns
 // path construction as opposed to frontmatter construction.
@@ -216,6 +242,26 @@ export function extractFrontmatter(text) {
   return m ? m[0].trimEnd() : null;
 }
 
+/**
+ * Put `frontmatter` where a frontmatter block already is, and leave every other byte
+ * exactly where it was.
+ *
+ * The block match deliberately stops at the closing `---` and not past it, so the
+ * replacement starts at the newline that follows — the blank line a formatter requires
+ * before an HTML comment survives belongs to the file, not to the block, and consuming
+ * it here is what made `inject` report `updated` forever on files whose bytes never
+ * changed.
+ *
+ * A file with no block gets one above its content. The separator below it is left to
+ * `inject`'s `seam`, which is the one place that knows what the surrounding document
+ * format requires.
+ */
+function swapFrontmatter(text, frontmatter) {
+  if (frontmatter === '') return text;
+  const m = /^---\n[\s\S]*?\n---/.exec(text);
+  return m === null ? `${frontmatter}\n${text}` : `${frontmatter}${text.slice(m[0].length)}`;
+}
+
 function bodyAfterFrontmatter(text) {
   return text.replace(/^---\n[\s\S]*?\n---\n*/, '');
 }

package/src/resolve/eval.mjs

@@ -0,0 +1,64 @@
+// Gold-corpus evaluation: run each case through the resolver and score it.
+//
+// Plan 0002 section 9: "A resolver that is not measured is a resolver that is merely
+// felt." The corpus (test/fixtures/eval-corpus.json) states, for real repository signals
+// and tasks, which skills must come back and which must not. Two callers must never
+// disagree about the score - `simt skills eval` reports it to a reader, and
+// test/eval.test.mjs asserts it in CI - so the arithmetic lives here once (ADR-002).
+
+import { rankSkills, tokenize } from './resolve.mjs';
+
+/** The skill names the resolver selects for one case's declared signals and task. */
+function selectForCase(registry, c) {
+  const context = {
+    repoStack: c.repo?.stack ?? [],
+    paths: c.repo?.paths ?? [],
+    taskTokens: tokenize(c.task ?? ''),
+  };
+  const { selected } = rankSkills(registry.skills, context);
+  return selected.map((e) => e.skill.name);
+}
+
+/** Skill names the corpus cites that the registry does not declare. */
+export function unknownSkills(registry, corpus) {
+  const names = new Set(registry.skills.map((s) => s.name));
+  return [
+    ...new Set(
+      corpus.cases.flatMap((c) => [...(c.select ?? []), ...(c.reject ?? [])]).filter((n) => !names.has(n)),
+    ),
+  ];
+}
+
+/**
+ * Score the whole corpus: per-case detail plus precision and recall.
+ *
+ * `unexpected` is the half of precision that named negatives cannot see: a case whose
+ * truth is "nothing" names only a sample of what must not come back, so for those the
+ * whole selected set is the miss. `clean` is what the exit code rests on; the two
+ * ratios are measurements, and a case can break `clean` while both still read 1.0 -
+ * the first version of this arithmetic scored that case a perfect precision (S19).
+ */
+export function scoreCorpus(registry, corpus) {
+  let expected = 0;
+  let negatives = 0;
+  const cases = corpus.cases.map((c) => {
+    expected += c.select?.length ?? 0;
+    negatives += c.reject?.length ?? 0;
+    const got = new Set(selectForCase(registry, c));
+    const missing = (c.select ?? []).filter((n) => !got.has(n));
+    const wronglySelected = (c.reject ?? []).filter((n) => got.has(n));
+    return {
+      name: c.name,
+      selected: [...got],
+      missing,
+      wronglySelected,
+      unexpected: c.select?.length === 0 ? [...got] : wronglySelected,
+    };
+  });
+  const missed = cases.reduce((n, c) => n + c.missing.length, 0);
+  const wrong = cases.reduce((n, c) => n + c.wronglySelected.length, 0);
+  const recall = expected === 0 ? 1 : (expected - missed) / expected;
+  const precision = negatives === 0 ? 1 : (negatives - wrong) / negatives;
+  const clean = missed === 0 && cases.every((c) => c.unexpected.length === 0);
+  return { cases, expected, missed, negatives, wrong, recall, precision, clean };
+}

package/src/resolve/fingerprint.mjs

@@ -178,6 +178,7 @@ const FACTS = [
   { name: 'has-pubspec', kind: 'file', paths: ['pubspec.yaml'] },
   { name: 'has-swift-package', kind: 'file', paths: ['Package.swift'] },
   { name: 'has-mix', kind: 'file', paths: ['mix.exs'] },
+  { name: 'has-deno-config', kind: 'file', paths: ['deno.json', 'deno.jsonc'] },
   { name: 'has-bun-lock', kind: 'file', paths: ['bun.lock', 'bun.lockb'] },
   // A glob walk skips dot directories, and `.devcontainer` is one. Stat the path.
   { name: 'has-devcontainer', kind: 'path', paths: ['.devcontainer/devcontainer.json'] },

package/src/resolve/near.mjs

@@ -10,7 +10,7 @@
 // suggestion that far away is noise: an agent will install the wrong skill.
 
 /** Levenshtein distance, two-row, with an early exit once the bound is passed. */
-export function editDistance(a, b, max = Infinity) {
+function editDistance(a, b, max = Infinity) {
   if (a === b) return 0;
   if (Math.abs(a.length - b.length) > max) return max + 1;
 
@@ -38,22 +38,41 @@ export function editDistance(a, b, max = Infinity) {
 /**
  * Candidates worth suggesting, nearest first.
  *
- * A substring hit is always included: `skill` is a real answer for a query of
- * `slice-commit`, and the distance test alone would rank it below noise.
+ * Two directions of substring, and they are not the same claim about what was typed.
+ *
+ * **The candidate contains the query** — `slice-commit` for `slice-commmit` — is a
+ * hit: the agent typed a prefix. It scores 1, not 0, because zero edits is what an
+ * exact match means and a prefix is not one. Scoring both 0 sorted `graph` ahead of
+ * `graphs` for the query `graphs`, and an agent that installs the first name in a
+ * "did you mean" list installs the wrong one.
+ *
+ * **The candidate sits inside the query** — `coverage` for `coverage-hunt` — is a hit
+ * only when it is at least half the query. Without that, the rule degenerates: `e` is
+ * a substring of `test`, so `nearMatches('test', ['e'])` returned `e` at distance 0
+ * and the message read `did you mean e?`.
+ *
+ * The bound also shrinks with the query, which is the same failure from the other side.
+ * Three edits is a typo in a name; three edits to a four-character query is a
+ * different string, and offering it violates the rule in the header of this file — "a
+ * suggestion that far away is noise: an agent will install the wrong skill". Under
+ * three characters nothing is a typo, so nothing is offered.
  */
 export function nearMatches(needle, candidates, { max = 3, limit = 3 } = {}) {
   if (!needle) return [];
   const lower = needle.toLowerCase();
+  const bound = Math.max(1, Math.min(max, Math.floor(lower.length / 3)));
 
   const scored = [];
   for (const candidate of candidates) {
     const cl = candidate.toLowerCase();
-    if (cl.includes(lower) || lower.includes(cl)) {
+    if (cl === lower) {
       scored.push({ candidate, distance: 0 });
-      continue;
+    } else if (cl.includes(lower) || (lower.includes(cl) && cl.length * 2 >= lower.length)) {
+      scored.push({ candidate, distance: 1 });
+    } else {
+      const distance = editDistance(lower, cl, bound);
+      if (distance <= bound) scored.push({ candidate, distance });
     }
-    const distance = editDistance(lower, cl, max);
-    if (distance <= max) scored.push({ candidate, distance });
   }
 
   scored.sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate));

package/src/resolve/resolve.mjs

@@ -210,7 +210,7 @@ export function stackCompatible(skill, repoSignals) {
  * agent knows it is standing in that repo, so name the overlapping tag when there
  * is one and say plainly when there is not.
  */
-export function stackReason(skill, repoSignals) {
+function stackReason(skill, repoSignals) {
   if (repoSignals.length === 0) return 'repo signals undetected, not excluded';
   const repo = new Set(repoSignals);
   const overlap = (skill.stack ?? []).filter((tag) => repo.has(tag));

package/src/resolve/source.mjs

@@ -35,7 +35,7 @@ import { measureSkill } from '../graph/load.mjs';
  *
  * @returns {{path: string, how: 'workspace'|'repo'}[]}
  */
-export function candidateLocations(source, { workspaceRoot = null, root = null } = {}) {
+function candidateLocations(source, { workspaceRoot = null, root = null } = {}) {
   const out = [];
   if (workspaceRoot) out.push({ path: join(workspaceRoot, source.repo, source.path), how: 'workspace' });
   if (root) out.push({ path: join(root, source.path), how: 'repo' });

package/src/workspace.mjs

@@ -252,15 +252,6 @@ function absolute(p) {
   return isAbsolute(expanded) ? expanded : resolve(expanded);
 }
 
-/**
- * The workspace, or null. Callers that can degrade use this and report `source: 'none'`;
- * callers that genuinely cannot proceed should use `resolveWorkspace` and fail with its detail.
- */
-export async function workspaceOrNull(flags = {}, options = {}) {
-  const { root, error } = await resolveWorkspace(flags, options);
-  return error ? null : root;
-}
-
 /**
  * The path a multi-repo command should work on: `--root` or the first positional if
  * given, else the resolved workspace, else the current directory.