simt-dev 0.2.0 → 0.2.2

package/src/packs.mjs

@@ -0,0 +1,182 @@
+// Shared rule sets, vendored into the repository that uses them.
+//
+// A pack is one answer to a question fourteen repositories kept asking separately:
+// "several repositories share one set of rules, and it must change in one place."
+// What a pack is NOT is a remote fetch. The content lives in the adopting
+// repository at `.simt-dev/packs/<name>/`, and the manifest records a digest of
+// it. Reading it from anywhere else would make the rendered region depend on a
+// path that does not resolve in the receiving repository - which is the single
+// failure this whole tool exists to prevent, and it would be introduced by the
+// feature meant to remove duplication.
+//
+// `graph/skills.graph.json` is deliberately not part of a pack. ADR-061 ruled
+// the registry to be workspace data; a second source for it would need its own
+// resolution ruling, and inventing one here would be how that gets settled by
+// accident.
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+
+import { readManifest } from './projection/manifest.mjs';
+import { CLI, MANIFEST_FILE } from './name.mjs';
+
+/** Where a pack's files live, relative to a repository root. */
+export const PACK_DIR = '.simt-dev/packs';
+
+// A pack name is a directory name under `PACK_DIR`, and it ends up in a path the
+// tool builds from manifest content. Restricted to the characters a directory
+// name can hold without escaping, so a hand-edited manifest cannot point the
+// reader's renderer at something outside the repository.
+const NAME = /^[a-z0-9][a-z0-9._-]*$/;
+
+/**
+ * @returns {string|null} the name if it is usable, else why it is not.
+ */
+function packNameProblem(name) {
+  if (typeof name !== 'string' || name.length === 0) return 'a pack name must be a non-empty string';
+  if (!NAME.test(name)) return `\`${name}\` is not a usable pack name: lowercase letters, digits, dot, dash and underscore`;
+  if (name === '.' || name === '..') return `\`${name}\` is not a usable pack name`;
+  return null;
+}
+
+/**
+ * The digest of one pack directory: every file, relative path and bytes, in
+ * sorted path order. Same shape as the rule provenance digest on purpose - a
+ * reader who has seen one digest in a manifest has seen the other.
+ *
+ * The paths are pack-relative, so a pack moved to another repository hashes the
+ * same. That is the property that makes the digest a statement about CONTENT
+ * rather than about where the reader happens to keep it.
+ *
+ * @returns {Promise<string>} 40 hex chars, or `''` for a directory that is not there.
+ */
+export async function packDigest(dir) {
+  const files = [];
+  const walk = async (d, prefix = '') => {
+    let entries;
+    try {
+      entries = await readdir(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) await walk(join(d, entry.name), rel);
+      else if (entry.isFile()) files.push(rel);
+    }
+  };
+  await walk(dir);
+  files.sort();
+
+  const hash = createHash('sha256');
+  for (const rel of files) {
+    const bytes = await readFile(join(dir, rel));
+    hash.update(`${rel}:${bytes.length}:`);
+    hash.update(bytes);
+  }
+  return hash.digest('hex').slice(0, 40);
+}
+
+/**
+ * Resolve the packs a repository declares, and report the ones it cannot use.
+ *
+ * A declared pack with no directory, or whose bytes no longer match the digest,
+ * is a finding rather than a silent omission: a repo whose region renders
+ * without half its rules is a repo whose reader was told something false, and the
+ * next `sync` would overwrite the truth on disk with the shorter region.
+ *
+ * `present` and `ok` are separate questions on purpose. A pack whose bytes do not
+ * match its pin is still PROJECTED - otherwise the remedy the finding names,
+ * `sync --yes`, would delete every rule the pack carries, which is the opposite of
+ * what a reader who ran the remedy meant. What is questioned is the pin, and the
+ * gate stays red until it is re-recorded; what is missing is the directory, and
+ * there is nothing to project.
+ *
+ * The remedy is `git checkout -- <dir>`, because the pack is vendored: git has
+ * the bytes this manifest's digest names. `sync` cannot help - it would render
+ * the region without the pack and call it current - so the remedy does not name
+ * it as the repair and does name it as the thing to run afterwards.
+ *
+ * @returns {Promise<{packs: {name: string, dir: string, source: string, version: string, digest: string, declared: string, ok: boolean}[], findings: {file: string, status: string, detail: string, remedy: string}[]}>}
+ */
+export async function resolvePacks(root) {
+  const findings = [];
+  const packs = [];
+  const { manifest, exists, error } = await readManifest(root);
+  if (!exists || error !== null || manifest === null) return { packs, findings };
+
+  const declared = Array.isArray(manifest.packs) ? manifest.packs : [];
+  const seen = new Set();
+
+  for (const entry of declared) {
+    const name = entry?.name;
+    const problem = packNameProblem(name);
+    if (problem !== null) {
+      findings.push({
+        file: MANIFEST_FILE,
+        status: 'pack-name-invalid',
+        detail: problem,
+        remedy: `correct or remove the entry, then: ${CLI} sync --yes`,
+      });
+      continue;
+    }
+    if (seen.has(name)) {
+      findings.push({
+        file: MANIFEST_FILE,
+        status: 'pack-declared-twice',
+        detail: `pack \`${name}\` is declared twice; the second declaration is read as the first`,
+        remedy: `remove the duplicate entry, then: ${CLI} sync --yes`,
+      });
+      continue;
+    }
+    seen.add(name);
+
+    const dir = join(root, PACK_DIR, name);
+    const source = typeof entry.source === 'string' ? entry.source : null;
+    const version = typeof entry.version === 'string' ? entry.version : null;
+    let present = false;
+    try {
+      present = (await stat(dir)).isDirectory();
+    } catch {
+      present = false;
+    }
+    if (!present) {
+      findings.push({
+        file: `${PACK_DIR}/${name}`,
+        status: 'pack-missing',
+        detail: `the manifest declares pack \`${name}\`, and there is no directory for it; every rule it carries is missing from this repository's projection`,
+        remedy: `restore it with: git checkout -- ${PACK_DIR}/${name}  (or remove the declaration, then: ${CLI} sync --yes)`,
+      });
+      packs.push({ name, dir, source, version, digest: '', declared: '', present: false, ok: false });
+      continue;
+    }
+
+    const digest = await packDigest(dir);
+    const declaredDigest = typeof entry.digest === 'string' ? entry.digest : null;
+    // An absent digest is not a mismatch. A pack someone vendored and has not
+    // pinned yet still carries its rules, and refusing to project them would make
+    // the tool refuse a repository for a field it has always treated as optional.
+    // It is reported, because "pinned to nothing" is not a fact about the content.
+    let ok = true;
+    if (declaredDigest === null) {
+      findings.push({
+        file: MANIFEST_FILE,
+        status: 'pack-unpinned',
+        detail: `pack \`${name}\` has no digest, so nothing records which bytes it was declared at`,
+        remedy: `record \`${digest}\` as its digest, then: ${CLI} sync --yes`,
+      });
+    } else if (declaredDigest !== digest) {
+      ok = false;
+      findings.push({
+        file: `${PACK_DIR}/${name}`,
+        status: 'pack-digest-mismatch',
+        detail: `pack \`${name}\` is pinned to ${declaredDigest} and its bytes digest to ${digest}`,
+        remedy: `restore the pinned bytes with: git checkout -- ${PACK_DIR}/${name}  (or update the digest to ${digest}, then: ${CLI} sync --yes)`,
+      });
+    }
+    packs.push({ name, dir, source, version, digest, declared: declaredDigest ?? digest, present: true, ok });
+  }
+
+  return { packs, findings };
+}

package/src/projection/conflicts.mjs

@@ -11,6 +11,8 @@
 // substring scan reports that file as violating the very rule it is correctly
 // restating. So every match is checked for prohibition context first.
 
+import { POINTERS, SURFACES } from './surfaces.mjs';
+
 /** Files whose text is a hand-written rule surface. Scanned for conflicts only;
  *  generated regions are excluded at read time by the caller.
  *
@@ -18,11 +20,60 @@
  *  worth recording: the estate's three always-on `.mdc` families were the single
  *  worst-drifted content in it, and `simt-dev init` reported `CONFLICTS none detected`
  *  on the repo holding them. A conflict detector that only looks at the filenames
- *  it was written for will quietly miss a whole rule surface added later. */
+ *  it was written for will quietly miss a whole rule surface added later.
+ *
+ *  And then it did. The comment above was written as a lesson and the lesson was not
+ *  taken: the list stayed hand-written, two surfaces were added to `SURFACES`
+ *  afterwards, and `.claude/rules/` and `.agents/rules/` were silently unscanned —
+ *  two of the five surfaces, and both of them read a rule that this tool writes. A
+ *  comment saying "derive this" is not deriving it. So the per-rule directories come
+ *  from `SURFACES` now (see `ruleGlobs`), and this list holds only the files no
+ *  surface declares. */
 export const RULE_FILES = ['AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md'];
 
-/** Rule files discovered by glob rather than by name. */
-export const RULE_GLOBS = ['.cursor/rules/*.mdc', '.github/instructions/*.md'];
+/** Pointer targets, scanned because this tool writes them and they are rule files.
+ *
+ *  `CLAUDE.md` was named by hand in `RULE_FILES` for the whole life of the tool, and
+ *  `GEMINI.md` — which `POINTERS` creates for a repo on the Antigravity surface — was
+ *  not. So one file this tool writes was scanned and the other was not, with nothing
+ *  in the source saying which was which: the difference was an accident of the order
+ *  the two were added. Derived from `POINTERS` now, so it cannot recur. */
+function pointerFiles() {
+  return POINTERS.map((p) => p.path);
+}
+
+/**
+ * The per-rule directories, read out of `SURFACES` rather than written out here.
+ *
+ * One list of surfaces, read by everything that has to know where a surface keeps its
+ * rules. A surface added to `SURFACES` is now scanned for conflicts the moment it
+ * exists, which is the property the hand-written list kept failing to have — and it
+ * could only fail quietly, because a detector that matches nothing reports the same
+ * answer as a repository with no rules.
+ *
+ * `CLAUDE.md` and `GEMINI.md` are here through `RULE_FILES`/`POINTERS` rather than
+ * through this: they are symlinks to the primary region, so they are scanned as
+ * *files*, and `CONTRIBUTING.md` belongs to no surface at all.
+ *
+ * Takes the list as an argument rather than closing over it so the derivation can be
+ * shown on a surface that does not exist. The default is `SURFACES`, so every caller
+ * still reads the one authority; there is no way to pass anything else in production.
+ *
+ * @param {{rule?: string}[]} [surfaces]
+ */
+export function ruleGlobs(surfaces = SURFACES) {
+  return surfaces.filter((s) => typeof s.rule === 'string').map((s) => {
+    const slash = s.rule.lastIndexOf('/');
+    const extension = s.rule.slice(s.rule.lastIndexOf('.'));
+    // The FINAL extension, not the whole tail after `{name}`. Copilot's template is
+    // `{name}.instructions.md`, and matching that whole suffix would be narrower than
+    // the `.md` this file used to list by hand — which is the difference between seeing
+    // a hand-written `reviewer.md` in that directory and reporting the directory as
+    // empty. A file this tool writes always carries its own suffix; a file a person
+    // wrote in the same directory need not, and the person is who this scanner is for.
+    return `${s.rule.slice(0, slash)}/*${extension}`;
+  });
+}
 
 /** Every hand-written rule path in a repo, named or globbed.
  *
@@ -36,8 +87,8 @@ export const RULE_GLOBS = ['.cursor/rules/*.mdc', '.github/instructions/*.md'];
 export async function rulePaths(root) {
   const { readdir } = await import('node:fs/promises');
   const { join } = await import('node:path');
-  const out = RULE_FILES.map((f) => join(root, f));
-  for (const glob of RULE_GLOBS) {
+  const out = [...new Set([...RULE_FILES, ...pointerFiles()])].map((f) => join(root, f));
+  for (const glob of ruleGlobs()) {
     const star = glob.lastIndexOf('*');
     const dir = join(root, glob.slice(0, star));
     const tail = glob.slice(star + 1);