simt-dev 0.2.1 → 0.3.0

package/src/monorepo.mjs

@@ -0,0 +1,339 @@
+// Packages inside a repository, from the files that declare them.
+//
+// A monorepo is one repository with several packages in it, and every tool that
+// reads a repository reads only the root: `fingerprint(root)` sees the root's
+// markers, `plan(root)` writes the root's region, and a reader working in
+// `apps/web` inherits whatever the root happened to be. The fix is not "a
+// monorepo is two repositories" — it is one root projection plus a nested one
+// per package, each carrying the profiles that package selects and the root does
+// not (ADR-066).
+//
+// Detection is a table, not code per ecosystem (ADR-013): each row names the
+// files that DECLARE members and how to read the member list out of them. Two
+// rows are deliberately absent and their reason is recorded in ADR-066: `nx.json`
+// declares no member list at all (its projects are computed by running `nx`), and
+// a Gradle `include(...)` is written in the settings file rather than a manifest
+// this table already parses. A row that could only be read by executing the
+// toolchain is not a row: a projection that depended on running the build would
+// be a projection this repository cannot reproduce.
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** Packaged trees are not packages: their directories are dependencies. */
+const SKIP_DIRS = new Set(['node_modules', 'target', 'vendor', 'dist', 'build', '.git', '.venv', 'venv']);
+
+/** What makes a directory a package once a pattern has matched it. */
+const PACKAGE_MARKERS = ['package.json', 'Cargo.toml', 'go.mod', 'build.gradle', 'build.gradle.kts', 'pyproject.toml', 'mix.exs'];
+
+/**
+ * The declarations this tool reads. `patterns` reads a list of repo-relative
+ * directory patterns out of the named file.
+ *
+ * `read` returns patterns in the order the file lists them, because the reader
+ * reviewing the generated files is entitled to see them in the order they wrote
+ * them, and a sort would hide a duplicate that the reader can act on.
+ */
+const DECLARATIONS = [
+  {
+    ecosystem: 'node',
+    file: 'package.json',
+    evidence: 'workspaces field',
+    read: async (text) => {
+      let pkg;
+      try {
+        pkg = JSON.parse(text);
+      } catch {
+        return [];
+      }
+      const w = pkg.workspaces;
+      if (Array.isArray(w)) return w;
+      if (w && Array.isArray(w.packages)) return w.packages;
+      return [];
+    },
+  },
+  {
+    ecosystem: 'node',
+    file: 'pnpm-workspace.yaml',
+    evidence: 'packages list',
+    read: async (text) => {
+      // A YAML list under `packages:`. Only the flat list form is read: a pnpm
+      // workspace that needs a full YAML parser to declare its members is a
+      // workspace whose declaration this tool must not guess at, and
+      // `packages:` with nothing under it declares none.
+      const lines = text.split('\n');
+      const out = [];
+      let inside = false;
+      for (const line of lines) {
+        if (/^packages:\s*$/.test(line)) {
+          inside = true;
+          continue;
+        }
+        if (!inside) continue;
+        const item = /^\s+-\s*(.+?)\s*$/.exec(line);
+        if (item) out.push(stripQuotes(item[1]));
+        else if (/^\S/.test(line)) inside = false;
+      }
+      return out;
+    },
+  },
+  {
+    ecosystem: 'node',
+    file: 'turbo.json',
+    evidence: 'workspaces.packages list',
+    read: async (text) => {
+      let cfg;
+      try {
+        cfg = JSON.parse(text);
+      } catch {
+        return [];
+      }
+      const w = cfg.workspaces;
+      return w && Array.isArray(w.packages) ? w.packages : [];
+    },
+  },
+  {
+    ecosystem: 'rust',
+    file: 'Cargo.toml',
+    evidence: '[workspace] members list',
+    read: async (text) => {
+      const members = tomlList(text, 'workspace', 'members');
+      return members;
+    },
+  },
+  {
+    ecosystem: 'go',
+    file: 'go.work',
+    evidence: 'use list',
+    read: async (text) => {
+      const use = tomlList(text, '', 'use');
+      return use;
+    },
+  },
+  {
+    ecosystem: 'jvm',
+    file: 'settings.gradle',
+    evidence: 'include list',
+    read: async (text) => gradleIncludes(text),
+  },
+  {
+    ecosystem: 'jvm',
+    file: 'settings.gradle.kts',
+    evidence: 'include list',
+    read: async (text) => gradleIncludes(text),
+  },
+];
+
+/**
+ * `include(":apps:web", ":core")` and its multi-line form, as paths.
+ *
+ * Gradle project paths are colon-separated and rooted at a colon, so `:apps:web`
+ * names the directory `apps/web`. That translation is all this reads: the arguments
+ * are literals, and a build that computes its includes from a variable is a build
+ * this tool does not evaluate - a directory with a marker file and no include is
+ * simply not discovered, which is the same honest absence every other unreadable
+ * declaration produces.
+ */
+function gradleIncludes(text) {
+  const out = [];
+  for (const match of text.matchAll(/\binclude\s*\(([^)]*)\)/g)) {
+    for (const quoted of match[1].matchAll(/["']([^"']+)["']/g)) {
+      const path = quoted[1].replace(/^:/, '').split(':').filter(Boolean).join('/');
+      if (path !== '') out.push(path);
+    }
+  }
+  return out;
+}
+
+function stripQuotes(value) {
+  return value.replace(/^["']/, '').replace(/["']$/, '');
+}
+
+/**
+ * One table's key, read as a list of paths.
+ *
+ * Every shape this tool needs is a flat list — `members = ["a", "b"]`,
+ * `members = [\n "a",\n]`, `use (\n ./api\n ./cmd/x\n)` — so the reader is a
+ * line scan with two states rather than a parser. Paths are quoted in TOML and
+ * bare in a `go.work`, so both are accepted; a comment is stripped, because
+ * `use ./api # the api` declares one path and not two.
+ *
+ * `table` is `''` for a file with no tables (go.work), or the table name. A key
+ * this shape does not find returns an empty list: a declaration this tool cannot
+ * read is one it does not guess at.
+ */
+function tomlList(text, table, key) {
+  const out = [];
+  let inTable = table === '';
+  let collecting = false;
+  for (const raw of text.split('\n')) {
+    const line = stripComment(raw);
+    if (/^\s*\[/.test(line)) {
+      inTable = table !== '' && line.trim() === `[${table}]`;
+      collecting = false;
+      continue;
+    }
+    if (!inTable) continue;
+    if (collecting) {
+      out.push(...pathTokens(line));
+      if (line.includes(']') || line.includes(')')) collecting = false;
+      continue;
+    }
+    // Two spellings, because `go.work` uses one and `Cargo.toml` the other:
+    // `members = ["crates/a"]` and a bare `use (` opening a list of paths.
+    const assigned = /^\s*([A-Za-z_.-]+)\s*=\s*(.*)$/.exec(line);
+    const opened = /^\s*([A-Za-z_.-]+)\s*\((.*)$/.exec(line);
+    const kv = assigned ?? opened;
+    if (kv === null || kv[1] !== key) continue;
+    const rest = (assigned !== null ? kv[2] : `(${kv[2]}`).trim();
+    if (rest === '[]' || rest === '') continue;
+    // `use (` and `members = [` both open a list that ends on a later line.
+    if (/[[(]$/.test(rest)) {
+      out.push(...pathTokens(rest));
+      collecting = true;
+      continue;
+    }
+    out.push(...pathTokens(rest));
+  }
+  return out;
+}
+
+function stripComment(line) {
+  const hash = line.indexOf('#');
+  return hash === -1 ? line : line.slice(0, hash);
+}
+
+/** The paths on one line of a list, quoted or bare, comma-separated. */
+function pathTokens(line) {
+  const quoted = [...line.matchAll(/["']([^"']+)["']/g)].map((m) => m[1]);
+  if (quoted.length > 0) return quoted;
+  return line
+    .replace(/[[\]()]/g, ' ')
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s !== '' && !s.startsWith('='));
+}
+
+/**
+ * Expand one declaration pattern into the directories it names.
+ *
+ * `*` matches within a path segment and `**` matches any depth. Both are what
+ * every one of these ecosystems writes, and a pattern syntax narrower than the
+ * declarations it reads is a detector that silently finds fewer packages than
+ * the repository has.
+ */
+async function expand(root, pattern) {
+  const segments = pattern.split('/').filter((s) => s !== '' && s !== '.');
+  if (segments.length === 0) return [];
+  let dirs = [root];
+  for (const seg of segments) {
+    const next = [];
+    for (const dir of dirs) {
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue;
+        if (matches(seg, entry.name)) next.push(join(dir, entry.name));
+        // `**` also admits what is below it, so a member pattern like
+        // `packages/**` finds `packages/a` and `packages/a/inner`.
+        if (seg === '**') {
+          next.push(join(dir, entry.name));
+          next.push(...(await expand(join(dir, entry.name), '**')));
+        }
+      }
+    }
+    dirs = [...new Set(next)];
+  }
+  return dirs;
+}
+
+/** One segment's match: `*` is any run of characters, everything else is literal. */
+function matches(segment, name) {
+  if (segment === '**') return true;
+  if (!segment.includes('*')) return segment === name;
+  const escaped = segment.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*');
+  return new RegExp(`^${escaped}$`).test(name);
+}
+
+/**
+ * Every package this repository declares, in the order the declarations name
+ * them and then in path order, deduplicated.
+ *
+ * A pattern that names a directory with no package marker in it is not a
+ * package, and neither is a pattern that escapes the repository: a declaration
+ * like `../other-repo/packages/*` is a path this tool must refuse to follow,
+ * because everything this tool projects has to resolve inside the repository
+ * that received it.
+ *
+ * @returns {Promise<{packages: {path: string, ecosystem: string, evidence: string}[],
+ *   notes: string[]}>}
+ */
+export async function discoverPackages(root) {
+  const found = new Map();
+  const notes = [];
+
+  const declared = [];
+  for (const decl of DECLARATIONS) {
+    let text;
+    try {
+      text = await readFile(join(root, decl.file), 'utf8');
+    } catch {
+      continue;
+    }
+    const patterns = await decl.read(text);
+    if (patterns.length === 0) continue;
+    declared.push(`${decl.file} (${decl.evidence})`);
+    for (const pattern of patterns) {
+      const negated = stripQuotes(pattern).startsWith('!');
+      const clean = stripQuotes(pattern).replace(/^!/, '').replace(/\/+$/, '');
+      if (clean === '') {
+        notes.push(`${decl.file} names "${pattern}", which is not a path; ignored`);
+        continue;
+      }
+      if (clean.startsWith('..')) {
+        notes.push(`${decl.file} names "${pattern}", which is outside this repository; ignored`);
+        continue;
+      }
+      for (const dir of await expand(root, clean)) {
+        const rel = relativeTo(root, dir);
+        if (rel === '') continue;
+        // `!apps/legacy` excludes what an earlier pattern admitted, which is the
+        // only way pnpm and yarn express "this member is not built any more".
+        if (negated) {
+          found.delete(rel);
+          continue;
+        }
+        if (!(await isPackage(dir))) continue;
+        if (found.has(rel)) continue;
+        found.set(rel, { path: rel, ecosystem: decl.ecosystem, evidence: decl.evidence });
+      }
+    }
+  }
+
+  return {
+    packages: [...found.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+    notes,
+  };
+}
+
+/** A directory is a package when something a build tool would install lives in it. */
+async function isPackage(dir) {
+  for (const marker of PACKAGE_MARKERS) {
+    try {
+      await readFile(join(dir, marker));
+      return true;
+    } catch {
+      // not here
+    }
+  }
+  return false;
+}
+
+function relativeTo(root, dir) {
+  return dir.slice(root.length).replace(/^\//, '');
+}

package/src/output/index.mjs

@@ -28,6 +28,24 @@ const REMEDY = {
   [EXIT.REGISTRY]: `run: ${CLI} graph lint`,
 };
 
+/**
+ * Whether failures are reported as JSON.
+ *
+ * A failure is a result: the caller asked a question and the answer is "no, and
+ * here is why". Written to stderr only, a caller parsing stdout under `--json`
+ * gets an empty document and has to believe the exit code, which tells it that
+ * something went wrong and nothing about what. So under `--json` the failure is
+ * the result and it goes where results go.
+ *
+ * The default answers "plain text" because that is what every run before the flags
+ * were parsed is, and those runs happen before anybody could have asked.
+ */
+let jsonFailure = false;
+
+export function jsonFailMode(on = false) {
+  jsonFailure = on;
+}
+
 /**
  * Report a failure and return its exit code. Callers `return fail(...)` so the
  * code is impossible to forget.
@@ -38,6 +56,10 @@ export function fail(message, code = EXIT.FAIL, remedy) {
   // a reader in a consumer repo got a remedy naming a file that does not exist
   // where they are. Every remedy here is something the reader can run.
   const resolved = remedy ?? REMEDY[code] ?? `run: ${CLI} --help`;
+  if (jsonFailure) {
+    emitJson({ ok: false, error: message, remedy: resolved, exitCode: code });
+    return code;
+  }
   process.stderr.write(`ERROR ${code} ${message}\nREMEDY ${resolved}\n`);
   return code;
 }
@@ -84,8 +106,62 @@ export function emit(text, { maxBytes = 0, stream = process.stdout } = {}) {
   return true;
 }
 
-export function emitJson(value, { stream = process.stdout } = {}) {
-  stream.write(`${JSON.stringify(value, null, 2)}\n`);
+/**
+ * The shape of every JSON payload, in the payload.
+ *
+ * A reader parsing `--json` from an agent has no other way to detect that a field moved
+ * or was renamed between releases: the parse still succeeds, and the reader's next lookup
+ * returns undefined. The number is in every payload rather than in the documentation
+ * because documentation is the thing that goes stale without failing anything, and the
+ * failure this prevents is silent.
+ *
+ * Bumped when a payload changes in a way a reader would notice. Adding a field is not
+ * that; removing, renaming or retyping one is.
+ */
+export const SCHEMA_VERSION = 1;
+
+/**
+ * Whether the next payload is indented.
+ *
+ * Set once per run from the flags, rather than threaded through every call site: the
+ * alternative is twenty-five call sites each remembering to pass a value they do not
+ * otherwise care about, and the one that forgets is the one a reader pipes somewhere
+ * important. The default answers "is a person reading", which is the right answer
+ * before anybody sets it.
+ */
+let prettyDefault = process.stdout.isTTY === true;
+
+export function jsonIndentDefault(pretty = process.stdout.isTTY === true) {
+  prettyDefault = pretty;
+}
+
+/**
+ * Emit JSON, compact unless a human is reading it.
+ *
+ * Indentation is for a person, and an agent pays for it on every call: the same document
+ * is a third again larger, and the reader is `JSON.parse`, not an eye. So the default is
+ * compact, and `--pretty` asks for the readable form. The one exception is a TTY, where
+ * the only consumer is a person: the compact document saves them nothing and costs them
+ * the diff they were about to read.
+ */
+export function emitJson(value, { stream = process.stdout, pretty = prettyDefault, maxBytes = 0 } = {}) {
+  const payload =
+    value !== null && typeof value === 'object' && !Array.isArray(value) && value.schemaVersion === undefined
+      ? { schemaVersion: SCHEMA_VERSION, ...value }
+      : value;
+  const text = `${pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload)}\n`;
+  // The same ceiling and the same announcement `emit` applies: a reader who asked for a
+  // bounded answer gets a bounded answer and is told how much is missing, rather than a
+  // half-parsed document it believes is whole.
+  if (maxBytes > 0 && Buffer.byteLength(text) > maxBytes) {
+    const slice = Buffer.from(text).subarray(0, maxBytes).toString('utf8');
+    const cut = slice.lastIndexOf('\n');
+    stream.write(cut > 0 ? `${slice.slice(0, cut)}\n` : slice);
+    stream.write(`TRUNCATED ${Buffer.byteLength(text) - maxBytes} bytes omitted, raise maxBytes\n`);
+    return false;
+  }
+  stream.write(text);
+  return true;
 }
 
 /**

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 };
+}