@yansirplus/cli 0.5.17

package/dist/check/check-coverage.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { listAlgorithmicCheckers } from "./algorithmic-checks.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
+
+const readJson = (relativePath) =>
+  JSON.parse(fs.readFileSync(path.join(repoRoot, relativePath), "utf8"));
+
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+
+const failures = [];
+const fail = (message) => failures.push(message);
+
+const coverage = readJson("packages/cli/src/check/check-coverage.source.json");
+const rulesSource = readJson("docs/agent/boundary-rules.source.json");
+const cliPackage = readJson("packages/cli/package.json");
+
+if (coverage.schemaVersion !== 1) fail("check coverage schemaVersion must be 1");
+if (!Array.isArray(coverage.entries) || coverage.entries.length === 0) {
+  fail("check coverage entries must be non-empty");
+}
+
+const rules = new Map((rulesSource.rules ?? []).map((rule) => [rule.id, rule]));
+const algorithmicCheckers = new Set(listAlgorithmicCheckers());
+const coveredRuleIds = new Set();
+const genericPackageNegativeWitness =
+  "package-owned test fails when the owned contract is violated";
+
+const assertProofWitnesses = (label, assertionIndex, assertion) => {
+  const witnesses = assertion.packageWitnesses;
+  if (witnesses === undefined) return;
+  if (!Array.isArray(witnesses) || witnesses.length === 0)
+    fail(`${label}: assertions[${assertionIndex}] packageWitnesses must be non-empty when present`);
+
+  for (const [witnessIndex, witness] of witnesses.entries()) {
+    const witnessLabel = `${label}: assertions[${assertionIndex}].packageWitnesses[${witnessIndex}]`;
+    if (!isRecord(witness)) {
+      fail(`${witnessLabel} must be an object`);
+      continue;
+    }
+    if (typeof witness.file !== "string" || !witness.file.startsWith("packages/")) {
+      fail(`${witnessLabel}.file must be a package test path`);
+      continue;
+    }
+    if (typeof witness.name !== "string" || witness.name.length === 0) {
+      fail(`${witnessLabel}.name must be non-empty`);
+      continue;
+    }
+
+    const absolutePath = path.join(repoRoot, witness.file);
+    if (!fs.existsSync(absolutePath)) {
+      fail(`${witnessLabel}.file does not exist`);
+      continue;
+    }
+    const source = fs.readFileSync(absolutePath, "utf8");
+    const testNamePattern = new RegExp(
+      `\\b(?:describe|it|test)(?:\\.effect)?\\(\\s*(["'\`])${escapeRegExp(witness.name)}\\1`,
+      "u",
+    );
+    if (!testNamePattern.test(source)) {
+      fail(`${witnessLabel}.name was not found as a test or describe name`);
+    }
+  }
+};
+
+for (const [index, entry] of (coverage.entries ?? []).entries()) {
+  const label =
+    isRecord(entry) && typeof entry.ruleId === "string" ? entry.ruleId : `entry[${index}]`;
+  if (!isRecord(entry)) {
+    fail(`${label}: coverage entry must be an object`);
+    continue;
+  }
+  if (!isRecord(entry.source)) fail(`${label}: missing source`);
+  if (!isRecord(entry.target)) fail(`${label}: missing target`);
+  if (!Array.isArray(entry.assertions) || entry.assertions.length === 0) {
+    fail(`${label}: assertions must be non-empty`);
+  } else {
+    for (const [assertionIndex, assertion] of entry.assertions.entries()) {
+      if (!isRecord(assertion)) {
+        fail(`${label}: assertions[${assertionIndex}] must be an object`);
+        continue;
+      }
+      if (
+        typeof assertion.failureCondition !== "string" ||
+        assertion.failureCondition.length === 0
+      ) {
+        fail(`${label}: assertions[${assertionIndex}] missing failureCondition`);
+      }
+      if (typeof assertion.negativeWitness !== "string" || assertion.negativeWitness.length === 0) {
+        fail(`${label}: assertions[${assertionIndex}] missing negativeWitness`);
+      }
+      if (assertion.negativeWitness === genericPackageNegativeWitness) {
+        fail(`${label}: assertions[${assertionIndex}] has generic package negativeWitness`);
+      }
+    }
+  }
+
+  if (typeof entry.ruleId === "string" && entry.ruleId.includes(",")) {
+    for (const ruleId of entry.ruleId.split(",")) coveredRuleIds.add(ruleId);
+  } else if (typeof entry.ruleId === "string") {
+    coveredRuleIds.add(entry.ruleId);
+  }
+
+  if (entry.target?.kind === "algorithmic") {
+    const rule = rules.get(entry.target.ruleId);
+    if (!isRecord(rule)) {
+      fail(`${label}: algorithmic target references unknown rule ${entry.target.ruleId}`);
+    } else if (rule.acceptance?.engine !== "algorithmic") {
+      fail(`${label}: algorithmic target rule must use algorithmic acceptance`);
+    } else if (rule.acceptance.checker !== entry.target.checker) {
+      fail(`${label}: coverage checker ${entry.target.checker} does not match rule acceptance`);
+    }
+    if (!algorithmicCheckers.has(entry.target.checker)) {
+      fail(`${label}: missing algorithmic checker ${entry.target.checker}`);
+    }
+  }
+
+  if (entry.target?.kind === "proofClass") {
+    const rule = rules.get(entry.target.ruleId);
+    if (!isRecord(rule)) {
+      fail(`${label}: proofClass target references unknown rule ${entry.target.ruleId}`);
+    } else if (rule.acceptance?.engine !== "proofClass") {
+      fail(`${label}: proofClass target rule must use proofClass acceptance`);
+    } else {
+      for (const [assertionIndex, assertion] of (entry.assertions ?? []).entries()) {
+        if (isRecord(assertion)) {
+          assertProofWitnesses(label, assertionIndex, assertion);
+        }
+      }
+    }
+  }
+
+  if (entry.target?.kind === "manifestRule") {
+    const rule = rules.get(entry.target.ruleId);
+    if (!isRecord(rule)) {
+      fail(`${label}: manifestRule target references unknown rule ${entry.target.ruleId}`);
+    } else if (rule.acceptance?.engine !== entry.target.engine) {
+      fail(`${label}: manifestRule target engine must match rule acceptance`);
+    }
+  }
+
+  if (typeof entry.ruleId === "string" && !entry.ruleId.includes(",")) {
+    const rule = rules.get(entry.ruleId);
+    if (isRecord(rule) && entry.owner !== rule.owner) {
+      fail(
+        `${label}: coverage owner ${entry.owner} does not match boundary rule owner ${rule.owner}`,
+      );
+    }
+  }
+
+  if (entry.target?.kind === "algorithmic-helper") {
+    for (const checker of entry.target.checkers ?? []) {
+      if (!algorithmicCheckers.has(checker))
+        fail(`${label}: helper references unknown checker ${checker}`);
+    }
+  }
+}
+
+for (const rule of rulesSource.rules ?? []) {
+  if (!coveredRuleIds.has(rule.id)) fail(`${rule.id}: rule lacks check coverage entry`);
+}
+
+const sourceText = fs.readFileSync(
+  path.join(repoRoot, "docs/agent/boundary-rules.source.json"),
+  "utf8",
+);
+if (sourceText.includes("positiveAcceptance")) {
+  fail("docs/agent/boundary-rules.source.json: positiveAcceptance is no longer allowed");
+}
+if (/\s--fix(?:\s|")/u.test(sourceText)) {
+  fail("docs/agent/boundary-rules.source.json: check commands must not include --fix");
+}
+
+const walk = (relativePath) => {
+  const absolutePath = path.join(repoRoot, relativePath);
+  const files = [];
+  for (const entry of fs.readdirSync(absolutePath, { withFileTypes: true })) {
+    const child = path.join(relativePath, entry.name);
+    if (entry.isDirectory()) files.push(...walk(child));
+    if (entry.isFile()) files.push(child.split(path.sep).join("/"));
+  }
+  return files;
+};
+
+const cliMjsFiles = walk("packages/cli/src").filter((file) => file.endsWith(".mjs"));
+const checkMjsFiles = cliMjsFiles.filter((file) => file.startsWith("packages/cli/src/check/"));
+if (cliMjsFiles.length > 19) {
+  fail(`packages/cli/src: expected at most 19 .mjs files; observed ${cliMjsFiles.length}`);
+}
+if (checkMjsFiles.length > 12) {
+  fail(`packages/cli/src/check: expected at most 12 .mjs files; observed ${checkMjsFiles.length}`);
+}
+for (const file of checkMjsFiles) {
+  const content = fs.readFileSync(path.join(repoRoot, file), "utf8");
+  const selfTestFlag = "--" + "self-test";
+  if (content.includes(selfTestFlag)) fail(`${file}: per-checker self-test flag is not allowed`);
+  const harnessPattern = new RegExp(
+    ["mkd" + "te" + "mp", "tm" + "pdir", "Tem" + "por" + "ary", "te" + "mp"].join("|"),
+    "i",
+  );
+  if (file !== "packages/cli/src/check/algorithmic-checks.mjs" && harnessPattern.test(content)) {
+    fail(`${file}: per-checker ad hoc harness is not allowed`);
+  }
+}
+
+const cliDependencies = Object.keys(cliPackage.dependencies ?? {});
+for (const dependency of cliDependencies) {
+  if (
+    dependency === "@effect/cli" ||
+    dependency === "@effect/platform-node" ||
+    dependency === "@effect/printer" ||
+    dependency === "@effect/printer-ansi" ||
+    dependency === "@effect/typeclass"
+  ) {
+    fail(`packages/cli/package.json: removed Effect CLI dependency returned: ${dependency}`);
+  }
+}
+if (cliPackage.dependencies?.effect === "3.21.2") {
+  fail("packages/cli/package.json: Effect v3 CLI dependency returned");
+}
+
+if (failures.length > 0) {
+  console.error(failures.join("\n"));
+  process.exit(1);
+}
+
+console.log("guard coverage passed");

package/dist/check/command-runner.mjs

@@ -0,0 +1,22 @@
+import { spawnSync } from "node:child_process";
+
+const completedCommands = new Set();
+
+export const runCommand = (command, { cwd, memoize = true } = {}) => {
+  if (/\s--fix(?:\s|$)/u.test(command)) {
+    throw new Error(`${command}: check commands must not run fix mode`);
+  }
+  if (memoize && completedCommands.has(command)) {
+    console.log(`$ ${command} (already checked)`);
+    return;
+  }
+  console.log(`$ ${command}`);
+  const result = spawnSync("sh", ["-c", command], {
+    cwd,
+    env: process.env,
+    stdio: "inherit",
+  });
+  if (result.signal !== null) throw new Error(`${command} terminated by ${result.signal}`);
+  if (result.status !== 0) throw new Error(`${command} exited with ${result.status ?? 1}`);
+  if (memoize) completedCommands.add(command);
+};

package/dist/check/default-gate.mjs

@@ -0,0 +1,51 @@
+import { spawn } from "node:child_process";
+import { repoRoot } from "./gate-selector.mjs";
+import { deriveAffectedGates, printAffectedGates, runAffectedGates } from "./gate-selector.mjs";
+
+const runStage = (label, command, args) =>
+  new Promise((resolve) => {
+    console.log(`$ ${[command, ...args].join(" ")}`);
+    const startedAt = Date.now();
+    const child = spawn(command, args, {
+      cwd: repoRoot,
+      env: process.env,
+      stdio: "inherit",
+    });
+    child.on("error", (error) => {
+      resolve({ label, ok: false, durationMs: Date.now() - startedAt, error });
+    });
+    child.on("exit", (code, signal) => {
+      resolve({
+        label,
+        ok: code === 0 && signal === null,
+        durationMs: Date.now() - startedAt,
+        error:
+          signal === null
+            ? code === 0
+              ? undefined
+              : `${label} exited with ${code ?? 1}`
+            : `${label} terminated by ${signal}`,
+      });
+    });
+  });
+
+export const runDefaultGate = async () => {
+  const startedAt = Date.now();
+  const stages = await Promise.all([
+    runStage("structural", "bun", ["run", "check:structural"]),
+    runStage("typecheck", "bun", ["run", "typecheck"]),
+    runStage("test", "bun", ["run", "test"]),
+  ]);
+  for (const stage of stages) {
+    console.log(`${stage.label} duration: ${stage.durationMs}ms`);
+  }
+  const failed = stages.filter((stage) => !stage.ok);
+  if (failed.length > 0) {
+    throw new Error(failed.map((stage) => stage.error ?? `${stage.label} failed`).join("\n"));
+  }
+  const durationMs = Date.now() - startedAt;
+  console.log(`fast gate duration: ${durationMs}ms`);
+  const result = deriveAffectedGates();
+  printAffectedGates(result);
+  runAffectedGates(result);
+};

package/dist/check/gate-selector.mjs

@@ -0,0 +1,305 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runCommand } from "./command-runner.mjs";
+import {
+  packageManifestDependencyEdges,
+  packageSourceImportEdges,
+  tsconfigReferenceEdges,
+  workspacePackageRecords,
+} from "./package-graph.mjs";
+
+export const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
+const gatesPath = "docs/agent/gates.source.json";
+const compare = (left, right) => left.localeCompare(right);
+const readJson = (relativePath) =>
+  JSON.parse(fs.readFileSync(path.join(repoRoot, relativePath), "utf8"));
+
+const git = (args) => execFileSync("git", args, { cwd: repoRoot, encoding: "utf8" }).trim();
+const gitLines = (args) =>
+  git(args)
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => line.split(path.sep).join("/"));
+
+const escapeRegex = (value) => value.replace(/[.+^${}()|[\]\\]/gu, "\\$&");
+const globToRegex = (pattern) => {
+  let regex = "^";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    const next = pattern[index + 1];
+    if (char === "*" && next === "*") {
+      regex += ".*";
+      index += 1;
+    } else if (char === "*") {
+      regex += "[^/]*";
+    } else {
+      regex += escapeRegex(char);
+    }
+  }
+  return new RegExp(`${regex}$`, "u");
+};
+
+const matchesPattern = (file, pattern) => globToRegex(pattern).test(file);
+const matchesAny = (file, patterns) => patterns.some((pattern) => matchesPattern(file, pattern));
+
+const loadGates = () => readJson(gatesPath);
+
+const edgeKey = (edge) => `${edge.from.name}->${edge.to.name}`;
+
+const extraEdges = (manifest, records) => {
+  const byPath = new Map(records.map((record) => [record.path, record]));
+  const byName = new Map(records.map((record) => [record.name, record]));
+  const edges = [];
+  for (const edge of manifest.extraEdges ?? []) {
+    const from = byPath.get(edge.from) ?? byName.get(edge.from);
+    const to = byPath.get(edge.to) ?? byName.get(edge.to);
+    if (from !== undefined && to !== undefined && from.name !== to.name) {
+      edges.push({ from, to, source: "extra-edge", reason: edge.reason ?? "declared extra edge" });
+    }
+  }
+  return edges;
+};
+
+const affectedGraph = (manifest, records) => {
+  const sourceEdges = packageSourceImportEdges(repoRoot, records);
+  const manifestEdges = packageManifestDependencyEdges(repoRoot, records);
+  const tsconfigEdges = tsconfigReferenceEdges(repoRoot, records);
+  const declaredExtraEdges = extraEdges(manifest, records);
+  const edges = [...sourceEdges, ...manifestEdges, ...tsconfigEdges, ...declaredExtraEdges];
+  const manifestEdgeKeys = new Set(manifestEdges.map(edgeKey));
+  const dependencyDrift = sourceEdges
+    .filter((edge) => !manifestEdgeKeys.has(edgeKey(edge)))
+    .map((edge) => ({
+      from: edge.from.name,
+      to: edge.to.name,
+      file: edge.file,
+      specifier: edge.specifier,
+      reason: "source import edge is not declared in package manifest dependencies",
+    }));
+  const sourceEdgeKeys = new Set(sourceEdges.map(edgeKey));
+  const graphEdgeKeys = new Set(edges.map(edgeKey));
+  const fidelityFailures = [...sourceEdgeKeys]
+    .filter((key) => !graphEdgeKeys.has(key))
+    .map((key) => `affected graph is missing source import edge ${key}`);
+  return { edges, sourceEdges, dependencyDrift, fidelityFailures };
+};
+
+const owningPackage = (records, file) =>
+  records
+    .filter((record) => file === record.path || file.startsWith(`${record.path}/`))
+    .sort((left, right) => right.path.length - left.path.length)[0];
+
+const reverseClosure = (records, edges, startNames) => {
+  const reverse = new Map(records.map((record) => [record.name, []]));
+  for (const edge of edges) reverse.get(edge.to.name)?.push(edge);
+  const affected = new Map();
+  const queue = [...startNames];
+  while (queue.length > 0) {
+    const name = queue.shift();
+    if (name === undefined || affected.has(name)) continue;
+    affected.set(name, true);
+    for (const edge of reverse.get(name) ?? []) queue.push(edge.from.name);
+  }
+  return [...affected.keys()].sort(compare);
+};
+
+const packageProof = (manifest, record) => {
+  const override = (manifest.packageOverrides ?? []).find(
+    (entry) => record.path === entry.path || record.name === entry.name,
+  );
+  return override ?? manifest.defaultPackageProof;
+};
+
+const proofClassCommand = (manifest, proofClass) => {
+  const command = manifest.proofClasses?.[proofClass]?.command;
+  if (typeof command !== "string" || command.length === 0) {
+    throw new Error(`${gatesPath}: proof class ${proofClass} has no command`);
+  }
+  return command;
+};
+
+const fullResult = (manifest, changedPaths, reason) => ({
+  mode: "full",
+  changedPaths,
+  proofClasses: [...(manifest.fullAffectedProofClasses ?? [])].sort(compare),
+  run: [...(manifest.fullAffectedProofClasses ?? [])].sort(compare).map((proofClass) => ({
+    proofClass,
+    command: proofClassCommand(manifest, proofClass),
+    reason,
+  })),
+  skip: [],
+  provenance: [{ kind: "full", reason }],
+  diagnostics: [],
+});
+
+const defaultBase = () => {
+  const detached = (() => {
+    try {
+      git(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+      return false;
+    } catch {
+      return true;
+    }
+  })();
+  if (detached) return { ok: false, reason: "detached HEAD cannot derive a safe default base" };
+  if (git(["rev-parse", "--is-shallow-repository"]) === "true") {
+    return { ok: false, reason: "shallow repository cannot derive a safe default base" };
+  }
+  try {
+    return { ok: true, base: git(["merge-base", "HEAD", "main"]) };
+  } catch {
+    return { ok: false, reason: "git merge-base HEAD main failed" };
+  }
+};
+
+const changedPaths = ({ base, head }) => {
+  const paths = new Set();
+  if (head !== undefined) {
+    for (const file of gitLines(["diff", "--name-only", `${base}..${head}`])) paths.add(file);
+    return [...paths].sort(compare);
+  }
+  for (const file of gitLines(["diff", "--name-only", `${base}...HEAD`])) paths.add(file);
+  for (const file of gitLines(["diff", "--name-only"])) paths.add(file);
+  for (const file of gitLines(["diff", "--name-only", "--cached"])) paths.add(file);
+  return [...paths].sort(compare);
+};
+
+export const deriveAffectedGates = (options = {}) => {
+  const manifest = loadGates();
+  const records = workspacePackageRecords(repoRoot).filter((record) =>
+    record.name?.startsWith("@agent-os/"),
+  );
+  let changed;
+  if (options.changedPaths !== undefined) {
+    changed = [...options.changedPaths].sort(compare);
+  } else {
+    const baseResolution =
+      options.base === undefined ? defaultBase() : { ok: true, base: options.base };
+    if (!baseResolution.ok) return fullResult(manifest, [], baseResolution.reason);
+
+    try {
+      changed = changedPaths({ base: baseResolution.base, head: options.head });
+    } catch (error) {
+      return fullResult(
+        manifest,
+        [],
+        `git diff failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  if (changed.length === 0) {
+    return {
+      mode: "affected",
+      changedPaths: [],
+      proofClasses: [],
+      run: [],
+      skip: (manifest.expensiveProofClasses ?? []).map((proofClass) => ({
+        proofClass,
+        reason: "no changed paths",
+      })),
+      provenance: [],
+      diagnostics: [],
+    };
+  }
+
+  for (const file of changed) {
+    for (const surface of manifest.globalSurfaces ?? []) {
+      if (matchesAny(file, surface.patterns ?? [])) {
+        return fullResult(manifest, changed, `${file}: ${surface.reason ?? "global surface"}`);
+      }
+    }
+  }
+
+  const graph = affectedGraph(manifest, records);
+  if (graph.fidelityFailures.length > 0) {
+    return fullResult(manifest, changed, graph.fidelityFailures.join("; "));
+  }
+
+  const owning = new Map();
+  const directProofClasses = new Map();
+  for (const file of changed) {
+    for (const rule of manifest.changedPathProofRules ?? []) {
+      if (matchesAny(file, rule.patterns ?? [])) {
+        for (const proofClass of rule.proofClasses ?? []) {
+          directProofClasses.set(proofClass, `${file}: ${rule.reason ?? "changed path rule"}`);
+        }
+      }
+    }
+    const owner = owningPackage(records, file);
+    if (owner === undefined) {
+      return fullResult(manifest, changed, `${file}: unknown path owner`);
+    }
+    owning.set(owner.name, owner);
+  }
+
+  const affectedNames = reverseClosure(records, graph.edges, owning.keys());
+  const affectedRecords = affectedNames
+    .map((name) => records.find((record) => record.name === name))
+    .filter(Boolean);
+  const proofReasons = new Map(directProofClasses);
+  for (const record of affectedRecords) {
+    const proof = packageProof(manifest, record);
+    for (const proofClass of proof?.affectedProofClasses ?? []) {
+      proofReasons.set(proofClass, `${record.name}: affected package declares ${proofClass} proof`);
+    }
+  }
+
+  const proofClasses = [...proofReasons.keys()].sort(compare);
+  const run = proofClasses.map((proofClass) => ({
+    proofClass,
+    command: proofClassCommand(manifest, proofClass),
+    reason: proofReasons.get(proofClass),
+  }));
+  const skip = (manifest.expensiveProofClasses ?? [])
+    .filter((proofClass) => !proofReasons.has(proofClass))
+    .sort(compare)
+    .map((proofClass) => ({
+      proofClass,
+      reason: "no affected package or changed-path rule declares this proof",
+    }));
+
+  return {
+    mode: "affected",
+    changedPaths: changed,
+    owningPackages: [...owning.values()].map((record) => record.name).sort(compare),
+    affectedPackages: affectedNames,
+    proofClasses,
+    run,
+    skip,
+    provenance: [
+      ...changed.map((file) => ({
+        kind: "changed-path",
+        file,
+        owner: owningPackage(records, file)?.name,
+      })),
+      ...affectedNames.map((name) => ({ kind: "affected-package", package: name })),
+    ],
+    diagnostics: graph.dependencyDrift,
+  };
+};
+
+export const printAffectedGates = (result, { json = false } = {}) => {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`affected mode: ${result.mode}`);
+  for (const entry of result.run) {
+    console.log(`run   ${entry.proofClass} <- ${entry.reason}`);
+  }
+  for (const entry of result.skip) {
+    console.log(`skip  ${entry.proofClass} <- ${entry.reason}`);
+  }
+  for (const diagnostic of result.diagnostics ?? []) {
+    console.log(
+      `diag  dependency-drift <- ${diagnostic.file}: ${diagnostic.from} imports ${diagnostic.specifier}`,
+    );
+  }
+};
+
+export const runAffectedGates = (result) => {
+  for (const entry of result.run) runCommand(entry.command, { cwd: repoRoot });
+};