@antelopejs/dms 0.11.0 → 0.12.0

package/bin/control/verify/formal.test.mjs

@@ -0,0 +1,120 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { formalGate, runFormalCheck, touchedFormalChecks } from "./formal.mjs";
+
+const ADD = "export function add(a, b) {\n  return a + b;\n}\n";
+const CHECK = `import { readFileSync } from "node:fs";
+const source = readFileSync("src/math.js", "utf8");
+console.log(source.includes("a + b") ? "holds AddWorks" : "BROKEN AddWorks");
+console.log("finding NegativeZero");
+`;
+const CHECK_WITHOUT_RULE = CHECK.replace(/console\.log\("finding[^\n]*\n/, "");
+const CHECK_FIXED = CHECK.replace(
+  '"finding NegativeZero"',
+  '"holds NegativeZero"',
+);
+
+const CHECK_CONFIG = {
+  name: "formal-add",
+  covers: ["src/math.js"],
+  files: [".agents/skills/formal-add/**"],
+  command: ["node", ".agents/skills/formal-add/check.mjs"],
+  violation: /^(?:finding|BROKEN) (\w+)/gm,
+  passing: /^holds (\w+)/gm,
+  behaviour: { kind: "emit" },
+};
+
+function git(repo, ...args) {
+  return execFileSync("git", args, { cwd: repo, encoding: "utf8" }).trim();
+}
+
+function commit(repo, files, message) {
+  for (const [path, content] of Object.entries(files)) {
+    mkdirSync(dirname(join(repo, path)), { recursive: true });
+    writeFileSync(join(repo, path), content);
+  }
+  git(repo, "add", "-A");
+  git(
+    repo,
+    "-c",
+    "user.name=t",
+    "-c",
+    "user.email=t@example.com",
+    "-c",
+    "commit.gpgsign=false",
+    "commit",
+    "-q",
+    "-m",
+    message,
+  );
+  return git(repo, "rev-parse", "HEAD");
+}
+
+function formalRepo(t, head) {
+  const root = mkdtempSync(join(tmpdir(), "dms-control-formal-test-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  git(root, "init", "-q");
+  const baseSha = commit(
+    root,
+    {
+      "src/math.js": ADD,
+      ".agents/skills/formal-add/check.mjs": CHECK,
+    },
+    "base",
+  );
+  const headSha = commit(root, head, "head");
+  const changed = git(root, "diff", "--name-only", baseSha, headSha)
+    .split("\n")
+    .filter(Boolean);
+  const evidence = join(root, "..", `${root.split("/").pop()}-evidence`);
+  mkdirSync(evidence);
+  t.after(() => rmSync(evidence, { recursive: true, force: true }));
+  const skill = { repo: root, config: { formal: [CHECK_CONFIG] } };
+  return { skill, state: { evidence }, diff: { baseSha, headSha, changed } };
+}
+
+function gated({ skill, state, diff }) {
+  const [check] = touchedFormalChecks(skill, diff.changed);
+  return check ? runFormalCheck(skill, state, check, diff) : null;
+}
+
+test("a rule counts as fixed only when HEAD reports it passing, never when HEAD drops it", (t) => {
+  const fixed = gated(
+    formalRepo(t, {
+      "src/math.js": ADD.replace("a + b", "a + b + 0"),
+      ".agents/skills/formal-add/check.mjs": CHECK_FIXED,
+    }),
+  );
+  assert.deepEqual(fixed.fixed, ["NegativeZero"]);
+  assert.deepEqual(fixed.missing, []);
+  const dropped = gated(
+    formalRepo(t, {
+      "src/math.js": ADD.replace("a + b", "a + b + 0"),
+      ".agents/skills/formal-add/check.mjs": CHECK_WITHOUT_RULE,
+    }),
+  );
+  assert.deepEqual(dropped.fixed, []);
+  assert.deepEqual(dropped.missing, ["NegativeZero"]);
+});
+
+test("a diff that touches only a check's own files runs the check and gates it against the base", (t) => {
+  const result = gated(
+    formalRepo(t, {
+      ".agents/skills/formal-add/check.mjs": CHECK_WITHOUT_RULE,
+    }),
+  );
+  assert.deepEqual(result.missing, ["NegativeZero"]);
+  assert.deepEqual(formalGate(result), {
+    fails: true,
+    outcome: "rules the base broke are absent at HEAD: NegativeZero",
+  });
+});
+
+test("a diff that touches neither the covered files nor the check's files does not touch the check", (t) => {
+  const { skill, diff } = formalRepo(t, { "README.md": "# Demo\n" });
+  assert.deepEqual(touchedFormalChecks(skill, diff.changed), []);
+});

package/bin/control/verify/judgement.mjs

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from "node:fs";
+
+function doorKind(skill, value, label) {
+  if (!Object.hasOwn(skill.config.doors, value)) {
+    throw new Error(
+      `judgement.json: ${label} is "${value}", not one of ${Object.keys(skill.config.doors).join(", ")}`,
+    );
+  }
+  return value;
+}
+
+function parseRows(skill, raw) {
+  return (raw.doors?.rows ?? []).map((row, index) => {
+    if (!row.kind || !row.location || !row.irreversible || !row.containment) {
+      throw new Error(
+        `judgement.json: doors.rows[${index}] needs kind, location, irreversible and containment`,
+      );
+    }
+    return {
+      ...row,
+      kind: doorKind(skill, row.kind, `doors.rows[${index}].kind`),
+      containmentJourney: row.containmentJourney ?? "",
+    };
+  });
+}
+
+function parseFalsePositives(skill, raw) {
+  return (raw.doors?.falsePositives ?? []).map((entry, index) => {
+    if (!entry.location || !entry.reason?.trim()) {
+      throw new Error(
+        `judgement.json: doors.falsePositives[${index}] needs location and reason`,
+      );
+    }
+    return {
+      ...entry,
+      kind: doorKind(skill, entry.kind, `doors.falsePositives[${index}].kind`),
+    };
+  });
+}
+
+/**
+ * Parses `evidence/judgement.json`, what only the verifier can judge. A
+ * verdict without a One-way doors section is void, and one that does not
+ * name its verifier is refused, so both throw.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {string} file The judgement file
+ * @returns {{ notVerified: string[], attention: string[], docs: { page: string, matches: boolean, note: string }[], doorsNone: string | null, doors: Record<string, string>[], falsePositives: Record<string, string>[], verifier: string }} The judgement
+ */
+export function readJudgement(skill, file) {
+  if (!existsSync(file)) {
+    throw new Error(
+      `${file} is missing: write the verifier's judgement before rendering the verdict`,
+    );
+  }
+  const raw = JSON.parse(readFileSync(file, "utf8"));
+  const rows = parseRows(skill, raw);
+  const none = raw.doors?.none?.trim() || null;
+  if (!none && rows.length === 0) {
+    throw new Error(
+      "judgement.json: doors needs `none` with a reason or at least one row; a verdict without it is void",
+    );
+  }
+  const verifier = raw.verifier?.trim();
+  if (!verifier) {
+    throw new Error(
+      "judgement.json: verifier must say who judged this run, for example the verifier thread's URL",
+    );
+  }
+  return {
+    notVerified: raw.notVerified ?? [],
+    attention: raw.attention ?? [],
+    docs: (raw.docs ?? []).map((entry) => ({
+      page: entry.page,
+      matches: entry.matches === true,
+      note: entry.note ?? "",
+    })),
+    doorsNone: none,
+    doors: rows,
+    falsePositives: parseFalsePositives(skill, raw),
+    verifier,
+  };
+}

package/bin/control/verify/map.mjs

@@ -0,0 +1,211 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join, matchesGlob } from "node:path";
+import { git } from "../git.mjs";
+import { flaggedDoors, patchFiles } from "./doors.mjs";
+import { loadJourneys } from "../journey.mjs";
+import { journeysFile, readFeatures } from "./skill.mjs";
+
+function matches(file, globs) {
+  return globs.some((glob) => matchesGlob(file, glob));
+}
+
+/**
+ * Whether a repository path is user-facing: matched by the config's
+ * `userFacing` globs and by none of its `notUserFacing` globs.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {string} file A repository path
+ * @returns {boolean} True when a feature must cover it
+ */
+export function isUserFacing(skill, file) {
+  return (
+    matches(file, skill.config.userFacing) &&
+    !matches(file, skill.config.notUserFacing ?? [])
+  );
+}
+
+/**
+ * The features whose `covers:` globs match a file.
+ *
+ * @param {string} file A repository path
+ * @param {{ name: string, covers: string[] }[]} features The features
+ * @returns {string[]} Their names
+ */
+export function featuresOf(file, features) {
+  return features
+    .filter((feature) => matches(file, feature.covers))
+    .map((feature) => feature.name);
+}
+
+function trackedFiles(skill) {
+  return git(["ls-files"], skill.repo).split("\n").filter(Boolean);
+}
+
+async function featureProblems(skill, feature, tracked) {
+  const problems = [];
+  const file = journeysFile(skill, feature.name);
+  const journeys = existsSync(file) ? await loadJourneys(file) : null;
+  if (!journeys)
+    problems.push(`${feature.file}: no journeys/${feature.name}.mjs`);
+  for (const journey of journeys ?? []) {
+    if (!feature.body.includes(`\`${journey.id}\``)) {
+      problems.push(
+        `${feature.file}: journey \`${journey.id}\` is not described`,
+      );
+    }
+  }
+  if (feature.name !== skill.config.smoke && feature.covers.length === 0) {
+    problems.push(`${feature.file}: lists no covers globs`);
+  }
+  for (const glob of feature.covers) {
+    if (!tracked.some((path) => matchesGlob(path, glob))) {
+      problems.push(`${feature.file}: glob ${glob} matches no tracked file`);
+    }
+  }
+  for (const doc of feature.docs) {
+    if (!existsSync(join(skill.repo, doc))) {
+      problems.push(`${feature.file}: docs path ${doc} does not exist`);
+    }
+  }
+  const patch = join(skill.seededBreaksDir, `${feature.name}.patch`);
+  if (!existsSync(patch)) {
+    problems.push(
+      `${feature.file}: seeded-breaks/${feature.name}.patch is missing`,
+    );
+  }
+  const always = feature.name === skill.config.smoke;
+  for (const file of existsSync(patch) && !always ? patchFiles(patch) : []) {
+    if (!matches(file, feature.covers)) {
+      problems.push(
+        `${feature.file}: its seeded break edits ${file}, which its covers globs miss, so plan would not run it`,
+      );
+    }
+  }
+  return problems;
+}
+
+function doorProblems(skill, tracked) {
+  const problems = [];
+  for (const [kind, rule] of Object.entries(skill.config.doors)) {
+    if (!rule) continue;
+    if (!existsSync(join(skill.seededDoorsDir, `${kind}.patch`))) {
+      problems.push(
+        `seeded-doors/${kind}.patch is missing for the ${kind} door rule`,
+      );
+    }
+    for (const glob of [...rule.globs, ...rule.funnels]) {
+      if (!tracked.some((path) => matchesGlob(path, glob))) {
+        problems.push(
+          `verify.config.ts: ${kind} door glob ${glob} matches no tracked file`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * Checks the map against the repository: every user-facing file is
+ * covered, every feature has journeys, each described in its file, a
+ * seeded break that edits only files its own globs cover (the smoke
+ * feature runs on every verdict and is exempt), existing docs
+ * pages, every feature and door glob
+ * matches a tracked file, and every door rule has a seeded door.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @returns {Promise<string[]>} One line per problem
+ */
+export async function checkMap(skill) {
+  const features = readFeatures(skill);
+  const tracked = trackedFiles(skill);
+  const problems = tracked
+    .filter(
+      (file) =>
+        isUserFacing(skill, file) && featuresOf(file, features).length === 0,
+    )
+    .map((file) => `unmapped: ${file} matches no feature glob`);
+  for (const feature of features)
+    problems.push(...(await featureProblems(skill, feature, tracked)));
+  if (existsSync(skill.journeysDir)) {
+    for (const file of readdirSync(skill.journeysDir).filter((name) =>
+      name.endsWith(".mjs"),
+    )) {
+      const name = file.replace(/\.mjs$/, "");
+      if (!features.some((feature) => feature.name === name)) {
+        problems.push(`journeys/${file} has no features/${name}.md`);
+      }
+    }
+  }
+  return [...problems, ...doorProblems(skill, tracked)];
+}
+
+const CONTAINED_KINDS = ["data", "format"];
+
+/**
+ * The containment journeys, as `feature/journey`, of the Data and Format
+ * doors a set of changed files opens: a door row must name one of them,
+ * passing in the run.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {string[]} changed Repository paths
+ * @returns {string[]} The journeys, each once
+ */
+function containmentJourneys(skill, changed) {
+  const kinds = flaggedDoors(skill, changed)
+    .map((door) => door.kind)
+    .filter((kind) => CONTAINED_KINDS.includes(kind));
+  return [
+    ...new Set(
+      kinds.flatMap((kind) => skill.config.doors[kind]?.containments ?? []),
+    ),
+  ];
+}
+
+/**
+ * Maps the diff from the merge base of `baseRef` to HEAD onto features:
+ * every touched feature plus the smoke feature runs, a user-facing file
+ * outside every glob is an unmapped surface, and `containments` lists the
+ * journeys that can contain each Data or Format door the diff opens.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {string} baseRef The base, such as `origin/main`
+ * @returns {{ baseRef: string, baseSha: string, headSha: string, changed: string[], touched: { feature: string, files: string[] }[], unmapped: string[], docs: string[], containments: string[], run: string[] }} The plan
+ */
+export function planFor(skill, baseRef) {
+  const features = readFeatures(skill);
+  const baseSha = git(["merge-base", baseRef, "HEAD"], skill.repo);
+  const changed = git(["diff", "--name-only", `${baseSha}...HEAD`], skill.repo)
+    .split("\n")
+    .filter(Boolean);
+  const touched = features
+    .map((feature) => ({
+      feature: feature.name,
+      files: changed.filter((file) => matches(file, feature.covers)),
+    }))
+    .filter((entry) => entry.files.length > 0);
+  const unmapped = changed.filter(
+    (file) =>
+      isUserFacing(skill, file) && featuresOf(file, features).length === 0,
+  );
+  const touchedNames = new Set(touched.map((entry) => entry.feature));
+  const docs = [
+    ...new Set(
+      features
+        .filter((feature) => touchedNames.has(feature.name))
+        .flatMap((feature) => feature.docs),
+    ),
+  ];
+  const smoke = skill.config.smoke;
+  const containments = containmentJourneys(skill, changed);
+  return {
+    baseRef,
+    baseSha,
+    headSha: git(["rev-parse", "HEAD"], skill.repo),
+    changed,
+    touched,
+    unmapped,
+    docs,
+    containments,
+    run: [smoke, ...[...touchedNames].filter((name) => name !== smoke)],
+  };
+}

package/bin/control/verify/publish.mjs

@@ -0,0 +1,180 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { git } from "../git.mjs";
+import { originRepository } from "./verdict.mjs";
+
+const EVIDENCE_BRANCH = "verify-evidence";
+const SCRATCH_BRANCH = "verify-evidence-scratch";
+
+function remoteBranchExists(repo) {
+  return git(["ls-remote", "--heads", "origin", EVIDENCE_BRANCH], repo) !== "";
+}
+
+/**
+ * Commits the run's evidence under `pr-<n>/<sha>/` of the orphan
+ * `verify-evidence` branch and pushes it, from a temporary worktree so the
+ * checkout under review is never touched.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {Record<string, any>} state The run
+ * @param {{ pr: number, headSha: string, result: string }} verdict The verdict
+ * @returns {string} The pushed evidence commit
+ */
+export function pushEvidence(skill, state, verdict) {
+  const repo = skill.repo;
+  const worktree = mkdtempSync(join(tmpdir(), "verify-evidence-"));
+  try {
+    if (remoteBranchExists(repo)) {
+      git(
+        [
+          "fetch",
+          "--quiet",
+          "origin",
+          `${EVIDENCE_BRANCH}:refs/remotes/origin/${EVIDENCE_BRANCH}`,
+        ],
+        repo,
+      );
+      git(
+        [
+          "worktree",
+          "add",
+          "--quiet",
+          "--detach",
+          worktree,
+          `origin/${EVIDENCE_BRANCH}`,
+        ],
+        repo,
+      );
+    } else {
+      git(
+        [
+          "worktree",
+          "add",
+          "--quiet",
+          "--orphan",
+          "-B",
+          SCRATCH_BRANCH,
+          worktree,
+        ],
+        repo,
+      );
+    }
+    const target = join(worktree, `pr-${verdict.pr}`, verdict.headSha);
+    rmSync(target, { recursive: true, force: true });
+    mkdirSync(target, { recursive: true });
+    cpSync(state.evidence, target, { recursive: true });
+    git(["add", "--all", "."], worktree);
+    const message = `verify: evidence for #${verdict.pr} at ${verdict.headSha.slice(0, 7)} (${verdict.result})`;
+    git(
+      [
+        "-c",
+        "commit.gpgsign=false",
+        "commit",
+        "--quiet",
+        "--allow-empty",
+        "--no-verify",
+        "-m",
+        message,
+      ],
+      worktree,
+    );
+    git(
+      [
+        "push",
+        "--quiet",
+        "--no-verify",
+        "origin",
+        `HEAD:refs/heads/${EVIDENCE_BRANCH}`,
+      ],
+      worktree,
+    );
+    return git(["rev-parse", "HEAD"], worktree);
+  } finally {
+    git(["worktree", "remove", "--force", worktree], repo);
+    if (git(["branch", "--list", SCRATCH_BRANCH], repo) !== "") {
+      git(["branch", "--quiet", "-D", SCRATCH_BRANCH], repo);
+    }
+  }
+}
+
+/**
+ * Posts the verdict as a PR comment.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {{ pr: number, markdown: string }} verdict The verdict
+ * @returns {string} The comment URL gh prints
+ */
+export function postComment(skill, verdict) {
+  return execFileSync(
+    "gh",
+    [
+      "pr",
+      "comment",
+      String(verdict.pr),
+      "--repo",
+      originRepository(skill.repo),
+      "--body",
+      verdict.markdown,
+    ],
+    { cwd: skill.repo, encoding: "utf8" },
+  ).trim();
+}
+
+/**
+ * Sets the `verify` commit status on the head SHA the verdict judged:
+ * `success` for PASS and PASS+NOTES, `failure` for FAIL.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {{ headSha: string, result: string }} verdict The verdict
+ * @param {string} targetUrl The comment URL
+ * @returns {string | null} GitHub's error when the status could not be set
+ */
+export function setStatus(skill, verdict, targetUrl) {
+  const state = verdict.result === "FAIL" ? "failure" : "success";
+  const result = spawnSync(
+    "gh",
+    [
+      "api",
+      "--silent",
+      `repos/${originRepository(skill.repo)}/statuses/${verdict.headSha}`,
+      "-f",
+      `state=${state}`,
+      "-f",
+      "context=verify",
+      "-f",
+      `description=${skill.name}: ${verdict.result}`,
+      "-f",
+      `target_url=${targetUrl}`,
+    ],
+    { cwd: skill.repo, encoding: "utf8" },
+  );
+  return result.status === 0
+    ? null
+    : `${result.stderr}${result.stdout}`.trim() || `gh exited ${result.status}`;
+}
+
+/**
+ * Reads back the `verify` status GitHub holds for a SHA, so the write is
+ * checked through a second command.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {string} sha The commit
+ * @returns {string} The status state, or `absent`
+ */
+export function readStatus(skill, sha) {
+  const statuses = JSON.parse(
+    execFileSync(
+      "gh",
+      ["api", `repos/${originRepository(skill.repo)}/commits/${sha}/statuses`],
+      {
+        cwd: skill.repo,
+        encoding: "utf8",
+      },
+    ),
+  );
+  return (
+    statuses.find((status) => status.context === "verify")?.state ?? "absent"
+  );
+}