simt-dev 0.2.0 → 0.2.2

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

@@ -12,17 +12,40 @@ export const EXIT = {
   OK: 0,
   FAIL: 1, // a gate failed: drift, policy violation, missing evidence
   USAGE: 2, // bad arguments; the remedy is in the message
-  CONFIG: 3, // simt-dev.json missing or invalid
+  CONFIG: 3, // simt.json missing or invalid
   REGISTRY: 4, // skills.graph.json invalid: orphan, dangling edge, cycle
   UNSUPPORTED: 5, // the request cannot be satisfied on this platform or repo
 };
 
 const REMEDY = {
-  [EXIT.USAGE]: 'run: simt-dev --help',
+  // Every default remedy below is `${CLI}` and not the package name, because this
+  // package installs exactly one binary and `package.json`'s `bin` map says which:
+  // `simt`. A remedy naming `simt-dev` is a command the reader types and gets
+  // `unknown command` from, which is the one answer that leaves them with no next
+  // step at all - and it was this default, printed on every bad invocation.
+  [EXIT.USAGE]: `run: ${CLI} --help`,
   [EXIT.CONFIG]: `run: ${CLI} init`,
   [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.
@@ -32,7 +55,11 @@ export function fail(message, code = EXIT.FAIL, remedy) {
   // default and it was only ever resolvable from inside simt-dev's own checkout;
   // 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: simt-dev --help';
+  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;
 }
@@ -60,10 +87,6 @@ export function writeMode(flags) {
   return { dryRun, apply: flags.yes === true && !dryRun };
 }
 
-export function isTty() {
-  return process.stdout.isTTY === true && !process.env.NO_COLOR;
-}
-
 /**
  * Emit a block of text under a heading, respecting --max-bytes.
  * Truncation is always announced with an explicit line, never a silent ellipsis:
@@ -83,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/package-version.mjs

@@ -0,0 +1,74 @@
+// How simt-dev is installed, and the version a repository holds it to.
+//
+// Three distinct things that must not be confused:
+//   - packageVersion() is the version of the binary that is RUNNING. It is read from
+//     the package this code lives in, so it is correct whether the binary was resolved
+//     from node_modules, a global install, or a source checkout.
+//   - hasNpm(root) is the KIND of repository: does it have a package.json? That decides
+//     how it obtains simt-dev at all — pinned as a devDependency where one exists, a
+//     pinned global install where there is no node_modules to pin in.
+//   - the pin is the version a repository recorded when it adopted simt-dev, stored in
+//     the manifest's projection.version. It is what a global install must match: npm
+//     pins the node_modules copy for us, but nothing pins a global binary, so the gate
+//     compares the running version against the pin and refuses on a mismatch.
+
+import { readFileSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { MANIFEST_FILE } from './name.mjs';
+
+/**
+ * The version of the simt-dev package this code is running from.
+ *
+ * Sync, because the render functions it feeds are sync: a rendered artifact bakes in
+ * the version that produced it, and that must be known before the bytes are written.
+ * A missing or unreadable package.json degrades to 'unknown' rather than throwing —
+ * the same call already tolerates it in `--version`, and a render that cannot read its
+ * own version is not a reason to crash the command that calls it.
+ */
+export function packageVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Whether a repository has a package.json, i.e. whether it pins simt-dev as a
+ * devDependency (npm) or must fall back to a global install. Async because the render
+ * call sites that feed it (init, hooks install, the compare stale check) are all async,
+ * and a missing file is an answer (false), not an error.
+ */
+export async function hasNpm(root) {
+  try {
+    await stat(join(root, 'package.json'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether the running binary matches the version a repository pinned when it adopted
+ * simt-dev. Returns null when there is nothing to refuse, otherwise a message that
+ * names both versions and the one command that fixes it.
+ *
+ * This is the gate's fail-closed guard against a stale global binary: for a repository
+ * without npm, simt-dev is a global install and the only thing that knows which version
+ * it should be is the pin. A node_modules copy is pinned by npm itself, so its mismatch
+ * is a stale manifest, which `upgrade` refreshes — the remedy is the same either way.
+ *
+ * A manifest with no recorded pin (adopted before the field existed) is skipped, not
+ * failed: there is nothing to compare against, and failing it would turn every pre-0.2
+ * repository into a red gate the moment this check ships.
+ */
+export function assertVersionPin(manifest) {
+  const pin = manifest?.projection?.version;
+  if (!pin || pin === 'unknown') return null;
+  const running = packageVersion();
+  if (running === pin) return null;
+  return `simt-dev version mismatch: ${MANIFEST_FILE} pins ${pin}, the running binary is ${running}`;
+}