@antelopejs/dms 0.15.1 → 0.16.1

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

@@ -0,0 +1,245 @@
+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 { join } from "node:path";
+import test from "node:test";
+import { decodeCommitStatuses, readFeatureResults } from "./decode.mjs";
+import { readFormalResult } from "./formal.mjs";
+import { readJudgement } from "./judgement.mjs";
+import { loadSkill } from "./skill.mjs";
+
+/**
+ * @param {import("node:test").TestContext} t The test
+ * @returns {string} A scratch folder removed when the test ends
+ */
+function scratch(t) {
+  const dir = mkdtempSync(join(tmpdir(), "dms-control-decode-test-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+/**
+ * @param {string} file The file
+ * @param {unknown} value What it holds as JSON
+ */
+function writeJson(file, value) {
+  mkdirSync(join(file, ".."), { recursive: true });
+  writeFileSync(file, JSON.stringify(value));
+}
+
+const FORMAL = {
+  name: "formal-add",
+  exitCode: 0,
+  violated: [],
+  passing: ["AddWorks"],
+  folder: "formal/formal-add",
+};
+
+await test("a formal result is read as recorded", (t) => {
+  const evidence = scratch(t);
+  writeJson(join(evidence, "formal", "formal-add", "result.json"), {
+    ...FORMAL,
+    base: null,
+    fixed: [],
+  });
+  assert.deepEqual(readFormalResult({ evidence }, "formal-add"), {
+    ...FORMAL,
+    base: null,
+    fixed: [],
+  });
+  assert.equal(readFormalResult({ evidence }, "formal-other"), undefined);
+});
+
+await test("a formal result whose rules are no list is refused", (t) => {
+  const evidence = scratch(t);
+  writeJson(join(evidence, "formal", "formal-add", "result.json"), {
+    ...FORMAL,
+    violated: "AddWorks",
+  });
+  assert.throws(
+    () => readFormalResult({ evidence }, "formal-add"),
+    /result\.json is malformed: expected a formal check result/,
+  );
+});
+
+const RESULT = {
+  feature: "smoke",
+  journey: "onboard",
+  title: "Onboard",
+  entryPoint: "/",
+  status: "PASS",
+  database: "dms_run",
+  steps: [
+    { name: "open", checks: [{ name: "loads", pass: true, detail: "" }] },
+  ],
+  error: null,
+  folder: "smoke/onboard",
+};
+
+await test("journey results are read as recorded and none when absent", (t) => {
+  const dir = scratch(t);
+  assert.deepEqual(readFeatureResults(join(dir, "feature.json")), []);
+  writeJson(join(dir, "feature.json"), [RESULT]);
+  assert.deepEqual(readFeatureResults(join(dir, "feature.json")), [RESULT]);
+});
+
+await test("a journey result with a status that is neither PASS nor FAIL is refused", (t) => {
+  const dir = scratch(t);
+  writeJson(join(dir, "feature.json"), [{ ...RESULT, status: "PASSED" }]);
+  assert.throws(
+    () => readFeatureResults(join(dir, "feature.json")),
+    /feature\.json is malformed: expected a list of journey results/,
+  );
+});
+
+await test("a journey result whose check does not say pass or fail is refused", (t) => {
+  const dir = scratch(t);
+  const steps = [
+    { name: "open", checks: [{ name: "loads", pass: "yes", detail: "" }] },
+  ];
+  writeJson(join(dir, "feature.json"), [{ ...RESULT, steps }]);
+  assert.throws(
+    () => readFeatureResults(join(dir, "feature.json")),
+    /malformed: expected a list of journey results/,
+  );
+});
+
+await test("a status list without a context and state is refused", () => {
+  const statuses = [{ context: "verify", state: "success", id: 1 }];
+  assert.deepEqual(decodeCommitStatuses(statuses, "gh"), statuses);
+  assert.throws(
+    () => decodeCommitStatuses({ message: "Not Found" }, "gh api statuses"),
+    /gh api statuses is malformed/,
+  );
+  assert.throws(
+    () => decodeCommitStatuses([{ context: "verify" }], "gh"),
+    /malformed: expected a list of commit statuses/,
+  );
+});
+
+const CONFIG = `export default {
+  playground: "playground",
+  prepare: [["pnpm", "install"]],
+  userFacing: ["src/**"],
+  smoke: "smoke",
+  smokeJourney: "onboard",
+  doors: { data: { globs: ["src/**"], funnels: [], containments: [], why: "rows" }, format: null },
+  formal: [],
+};
+`;
+
+/**
+ * @param {import("node:test").TestContext} t The test
+ * @param {string} config What `verify.config.ts` holds
+ * @returns {string} The skill folder, inside a git checkout
+ */
+function skillFolder(t, config) {
+  const repo = scratch(t);
+  execFileSync("git", ["init", "-q"], { cwd: repo });
+  execFileSync(
+    "git",
+    [
+      "-c",
+      "user.name=t",
+      "-c",
+      "user.email=t@example.com",
+      "-c",
+      "commit.gpgsign=false",
+      "commit",
+      "-q",
+      "--allow-empty",
+      "-m",
+      "init",
+    ],
+    { cwd: repo },
+  );
+  const dir = join(repo, ".agents", "skills", "verify-demo");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "verify.config.ts"), config);
+  return dir;
+}
+
+await test("a config without the optional list of non-user-facing paths loads with none", async (t) => {
+  const skill = await loadSkill(skillFolder(t, CONFIG), tmpdir());
+  assert.deepEqual(skill.config.notUserFacing, []);
+  assert.equal(skill.config.doors.format, null);
+});
+
+await test("a config missing a field is refused where the skill loads", async (t) => {
+  const dir = skillFolder(t, CONFIG.replace('smoke: "smoke",\n', ""));
+  await assert.rejects(
+    loadSkill(dir, tmpdir()),
+    /verify\.config\.ts is malformed: expected a verification skill config/,
+  );
+});
+
+await test("a config whose formal check pattern is a string is refused", async (t) => {
+  const dir = skillFolder(
+    t,
+    CONFIG.replace(
+      "formal: []",
+      'formal: [{ name: "f", covers: [], command: ["node"], violation: "^x", passing: null }]',
+    ),
+  );
+  await assert.rejects(
+    loadSkill(dir, tmpdir()),
+    /malformed: expected a verification skill config/,
+  );
+});
+
+await test("a config module without a default export is refused", async (t) => {
+  const dir = skillFolder(t, "export const config = {};\n");
+  await assert.rejects(
+    loadSkill(dir, tmpdir()),
+    /verify\.config\.ts is malformed/,
+  );
+});
+
+const JUDGEMENT = {
+  verifier: "thread",
+  notVerified: ["ui"],
+  attention: [],
+  docs: [{ page: "docs/a.md", matches: true, note: "ok" }],
+  doors: { none: "no door" },
+};
+
+await test("a judgement is read into the verdict's shape", async (t) => {
+  const skill = await loadSkill(skillFolder(t, CONFIG), tmpdir());
+  const file = join(scratch(t), "judgement.json");
+  writeJson(file, JUDGEMENT);
+  assert.deepEqual(readJudgement(skill, file), {
+    notVerified: ["ui"],
+    attention: [],
+    docs: [{ page: "docs/a.md", matches: true, note: "ok" }],
+    doorsNone: "no door",
+    doors: [],
+    falsePositives: [],
+    verifier: "thread",
+  });
+});
+
+await test("a judgement whose lists hold other than strings is refused", async (t) => {
+  const skill = await loadSkill(skillFolder(t, CONFIG), tmpdir());
+  const file = join(scratch(t), "judgement.json");
+  writeJson(file, { ...JUDGEMENT, notVerified: "ui" });
+  assert.throws(
+    () => readJudgement(skill, file),
+    /judgement\.json is malformed: expected a verifier's judgement/,
+  );
+  writeJson(file, {
+    ...JUDGEMENT,
+    docs: [{ page: "docs/a.md", matches: "yes" }],
+  });
+  assert.throws(
+    () => readJudgement(skill, file),
+    /malformed: expected a verifier/,
+  );
+});
+
+await test("a judgement that is no object is refused", async (t) => {
+  const skill = await loadSkill(skillFolder(t, CONFIG), tmpdir());
+  const file = join(scratch(t), "judgement.json");
+  writeJson(file, ["verifier"]);
+  assert.throws(() => readJudgement(skill, file), /is malformed/);
+});

package/bin/control/verify/doors.mjs

@@ -5,7 +5,7 @@ import { matchesGlob } from "node:path";
  * The one-way door kinds whose path rules a set of changed files hits, with
  * the files per kind. A declared funnel module is a path rule of its kind.
  *
- * @param {Record<string, any>} skill The skill
+ * @param {import("./skill.mjs").Skill} skill The skill
  * @param {string[]} files Repository paths
  * @returns {{ kind: string, files: string[] }[]} The flagged kinds
  */

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

@@ -0,0 +1,40 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import { flaggedDoors, patchFiles } from "./doors.mjs";
+import { loadSkill } from "./skill.mjs";
+
+const skill = await loadSkill(undefined, import.meta.dirname);
+const kinds = Object.entries(skill.config.doors)
+  .filter(
+    ([kind, rule]) =>
+      rule && existsSync(join(skill.seededDoorsDir, `${kind}.patch`)),
+  )
+  .map(([kind]) => kind);
+
+for (const kind of kinds) {
+  const patch = join(skill.seededDoorsDir, `${kind}.patch`);
+
+  await test(`the ${kind} seeded door applies to the current tree`, () => {
+    assert.doesNotThrow(
+      () =>
+        execFileSync("git", ["apply", "--check", patch], {
+          cwd: skill.repo,
+          stdio: "pipe",
+        }),
+      `${kind}.patch no longer applies; refresh it against the current source`,
+    );
+  });
+
+  await test(`the ${kind} seeded door flags the ${kind} door`, () => {
+    const flagged = flaggedDoors(skill, patchFiles(patch)).map(
+      (door) => door.kind,
+    );
+    assert.ok(
+      flagged.includes(kind),
+      `${kind}.patch flags ${flagged.join(", ") || "nothing"}`,
+    );
+  });
+}

package/bin/control/verify/emit.mjs

@@ -3,6 +3,12 @@ import { createRequire } from "node:module";
 import { dirname, extname, join, posix } from "node:path";
 import { PACKAGE_ROOT } from "../stack.mjs";
 
+/** @typedef {typeof import("typescript")} TypeScript */
+/** @typedef {import("typescript").Node} Node */
+/** @typedef {{ modules: Set<string>, functions: Set<string> }} Covered The covered modules and function names */
+/** @typedef {{ structure: string, text: string, hoisted: boolean }} Item */
+/** @typedef {{ path: string, file: import("typescript").SourceFile }} Script */
+
 const CODE_EXTENSIONS = new Set([
   ".ts",
   ".mts",
@@ -16,9 +22,14 @@ const CODE_EXTENSIONS = new Set([
 const OUTPUT_LIMIT = 64 * 1024 * 1024;
 const TEXT_LENGTH = 160;
 
+/**
+ * @param {string} repo
+ * @returns {TypeScript}
+ */
 function loadTypeScript(repo) {
   for (const folder of [repo, join(repo, "packages", "dms"), PACKAGE_ROOT]) {
     try {
+      // oxlint-disable-next-line typescript/no-unsafe-return -- createRequire loads TypeScript by a path known only at run time, from the checkout under test first and the dms package last, and Node types what require answers as any.
       return createRequire(join(folder, "package.json"))("typescript");
     } catch {
       continue;
@@ -29,6 +40,12 @@ function loadTypeScript(repo) {
   );
 }
 
+/**
+ * @param {string} repo
+ * @param {string} sha
+ * @param {string} path
+ * @returns {string | null}
+ */
 function fileAt(repo, sha, path) {
   const shown = spawnSync("git", ["show", `${sha}:${path}`], {
     cwd: repo,
@@ -38,6 +55,12 @@ function fileAt(repo, sha, path) {
   return shown.status === 0 ? shown.stdout : null;
 }
 
+/**
+ * @param {TypeScript} ts
+ * @param {Node} node
+ * @param {Map<string, string>} bindings
+ * @returns {string}
+ */
 function leafOf(ts, node, bindings) {
   if (ts.isIdentifier(node))
     return propertyName(ts, node)
@@ -59,15 +82,46 @@ function leafOf(ts, node, bindings) {
 
 const MODULE_EXTENSION = /\.(?:[cm]?[jt]s|[jt]sx)$/;
 
+/**
+ * The text of a module specifier: a string, template without substitutions,
+ * number or identifier, which is all the parser leaves a `text` on.
+ *
+ * @param {TypeScript} ts
+ * @param {import("typescript").Expression} specifier
+ * @returns {string}
+ * @throws {TypeError} For any other expression, such as a call
+ */
+function specifierText(ts, specifier) {
+  if (ts.isLiteralExpression(specifier) || ts.isIdentifier(specifier))
+    return specifier.text;
+  throw new TypeError(
+    `a module specifier must be a name, found ${ts.SyntaxKind[specifier.kind]}`,
+  );
+}
+
+/**
+ * @param {string} path
+ * @param {string} specifier The text of the module specifier
+ * @returns {string}
+ */
 function moduleKey(path, specifier) {
   if (!specifier.startsWith(".")) return specifier;
   return posix.join(dirname(path), specifier).replace(MODULE_EXTENSION, "");
 }
 
+/**
+ * @param {string} path
+ * @returns {string}
+ */
 function stripExtension(path) {
   return path.replace(MODULE_EXTENSION, "");
 }
 
+/**
+ * @param {TypeScript} ts
+ * @param {Node} node
+ * @returns {boolean}
+ */
 function propertyName(ts, node) {
   const parent = node.parent;
   return (
@@ -89,7 +143,7 @@ function propertyName(ts, node) {
  * otherwise, so a variable or class of one file never reads as one of the same
  * name in another.
  *
- * @param {{ modules: Set<string>, functions: Set<string> }} covered The covered modules and function names
+ * @param {Covered} covered The covered modules and function names
  * @param {string} module The resolved module
  * @param {string} name The imported name
  * @returns {string} The origin
@@ -100,8 +154,16 @@ function bindingOrigin(covered, module, name) {
     : `${module}#${name}`;
 }
 
+/**
+ * @param {TypeScript} ts
+ * @param {import("typescript").ImportClause} clause
+ * @param {string} module
+ * @param {Covered} covered
+ * @returns {[string, string][]}
+ */
 function importedBindings(ts, clause, module, covered) {
   const named = clause.namedBindings;
+  /** @type {[string, string][]} */
   const bindings = [];
   if (clause.name)
     bindings.push([
@@ -123,6 +185,13 @@ function importedBindings(ts, clause, module, covered) {
   return bindings;
 }
 
+/**
+ * @param {TypeScript} ts
+ * @param {import("typescript").ExportDeclaration} statement
+ * @param {string} module
+ * @param {Covered} covered
+ * @returns {string[]}
+ */
 function reexportTexts(ts, statement, module, covered) {
   const exported = statement.exportClause;
   const inside = covered.modules.has(module);
@@ -146,6 +215,11 @@ function reexportTexts(ts, statement, module, covered) {
  * origin of what they export. An export under its own name of a local needs no
  * entry, the same as an `export` keyword, so only a renamed local and any
  * imported binding does.
+ * @param {TypeScript} ts
+ * @param {import("typescript").ExportDeclaration} statement
+ * @param {Map<string, string>} bindings
+ * @param {Map<string, string>} locals
+ * @returns {string[]}
  */
 function localExportTexts(ts, statement, bindings, locals) {
   const exported = statement.exportClause;
@@ -170,17 +244,21 @@ function localExportTexts(ts, statement, bindings, locals) {
  * module. Side-effect imports keep their order in the file. Re-exports and
  * renamed or imported exports become entries keyed by the origin they export.
  *
- * @param {any} ts The TypeScript module
+ * @param {TypeScript} ts The TypeScript module
  * @param {string} path The file
- * @param {{ modules: Set<string>, functions: Set<string> }} covered The covered modules and function names
- * @param {any} file The emitted source file
+ * @param {Covered} covered The covered modules and function names
+ * @param {import("typescript").SourceFile} file The emitted source file
  * @param {Map<string, string>} locals The top-level variables and classes of the file, keyed by file and name
  * @returns {{ bindings: Map<string, string>, entries: { structure: string, text: string, hoisted: boolean }[], ordered: { structure: string, text: string, hoisted: boolean }[] }} The origins; `entries` may move freely, `ordered` keep their order in the file
  */
 function originsOf(ts, path, covered, file, locals) {
+  /** @type {Map<string, string>} */
   const bindings = new Map();
+  /** @type {string[]} */
   const texts = [];
+  /** @type {string[]} */
   const ordered = [];
+  /** @type {import("typescript").ExportDeclaration[]} */
   const exports = [];
   for (const statement of file.statements) {
     if (
@@ -191,7 +269,7 @@ function originsOf(ts, path, covered, file, locals) {
     if (specifier === undefined && ts.isExportDeclaration(statement))
       exports.push(statement);
     if (specifier === undefined) continue;
-    const module = moduleKey(path, specifier.text);
+    const module = moduleKey(path, specifierText(ts, specifier));
     if (ts.isImportDeclaration(statement)) {
       if (statement.importClause === undefined) {
         ordered.push(`import ${module}`);
@@ -208,6 +286,11 @@ function originsOf(ts, path, covered, file, locals) {
   }
   for (const statement of exports)
     texts.push(...localExportTexts(ts, statement, bindings, locals));
+  /**
+   * @param {string} text
+   * @param {boolean} hoisted
+   * @returns {Item}
+   */
   const item = (text, hoisted) => ({ structure: text, text, hoisted });
   return {
     bindings,
@@ -216,6 +299,11 @@ function originsOf(ts, path, covered, file, locals) {
   };
 }
 
+/**
+ * @param {TypeScript} ts
+ * @param {Node} node
+ * @returns {boolean}
+ */
 function dropped(ts, node) {
   return (
     node.kind === ts.SyntaxKind.ExportKeyword ||
@@ -228,14 +316,15 @@ function dropped(ts, node) {
  * and its children's structure, with parentheses, positions, trivia, quote
  * style and line breaks left out, so formatting never changes it.
  *
- * @param {any} ts The TypeScript module
- * @param {any} node A node of the emitted JavaScript
+ * @param {TypeScript} ts The TypeScript module
+ * @param {Node} node A node of the emitted JavaScript
  * @param {Map<string, string>} bindings The origin of each imported binding
  * @returns {string} The structure
  */
 function structureOf(ts, node, bindings) {
   if (ts.isParenthesizedExpression(node))
     return structureOf(ts, node.expression, bindings);
+  /** @type {string[]} */
   const children = [];
   ts.forEachChild(node, (child) => {
     if (!dropped(ts, child)) children.push(structureOf(ts, child, bindings));
@@ -243,6 +332,12 @@ function structureOf(ts, node, bindings) {
   return `${ts.SyntaxKind[node.kind]}(${leafOf(ts, node, bindings)}|${children.join(",")})`;
 }
 
+/**
+ * @param {TypeScript} ts
+ * @param {string} path
+ * @param {string} source
+ * @returns {Script}
+ */
 function parseScript(ts, path, source) {
   const { outputText } = ts.transpileModule(source, {
     fileName: path,
@@ -265,11 +360,20 @@ function parseScript(ts, path, source) {
   };
 }
 
+/**
+ * @param {string} text
+ * @returns {string}
+ */
 function readable(text) {
   const flat = text.replace(/\s+/g, " ").trim();
   return flat.length > TEXT_LENGTH ? `${flat.slice(0, TEXT_LENGTH)}…` : flat;
 }
 
+/**
+ * @param {TypeScript} ts
+ * @param {import("typescript").BindingName} name
+ * @returns {string[]}
+ */
 function declaredNames(ts, name) {
   return ts.isIdentifier(name)
     ? [name.text]
@@ -278,6 +382,11 @@ function declaredNames(ts, name) {
       );
 }
 
+/**
+ * @param {TypeScript} ts
+ * @param {import("typescript").Statement} statement
+ * @returns {statement is import("typescript").FunctionDeclaration & { name: import("typescript").Identifier }}
+ */
 function isFunctionDeclaration(ts, statement) {
   return (
     ts.isFunctionDeclaration(statement) &&
@@ -286,7 +395,12 @@ function isFunctionDeclaration(ts, statement) {
   );
 }
 
-/** The top-level variables, classes and enums of a script, each keyed by its file and name: what a function moved into another file must not pick up by name. */
+/**
+ * The top-level variables, classes and enums of a script, each keyed by its file and name: what a function moved into another file must not pick up by name.
+ * @param {TypeScript} ts
+ * @param {Script} script
+ * @returns {Map<string, string>}
+ */
 function localsOf(ts, script) {
   const file = stripExtension(script.path);
   const names = script.file.statements.flatMap((statement) => {
@@ -303,6 +417,12 @@ function localsOf(ts, script) {
   return new Map(names.map((name) => [name, `${file}#${name}`]));
 }
 
+/**
+ * @param {TypeScript} ts
+ * @param {Script} script
+ * @param {Covered} covered
+ * @returns {Item[]}
+ */
 function scriptItems(ts, script, covered) {
   const locals = localsOf(ts, script);
   const origins = originsOf(ts, script.path, covered, script.file, locals);
@@ -329,7 +449,12 @@ function scriptItems(ts, script, covered) {
   return [...origins.entries, ...origins.ordered, ...statements];
 }
 
-/** A covered file as its scripts and the items that are not scripts: a Vue template, or the whole text of any other file. */
+/**
+ * A covered file as its scripts and the items that are not scripts: a Vue template, or the whole text of any other file.
+ * @param {TypeScript} ts
+ * @param {string} path
+ * @param {string} source
+ */
 function parsedFile(ts, path, source) {
   if (path.endsWith(".vue")) {
     const template = /<template\b[^>]*>([\s\S]*)<\/template>/.exec(source);
@@ -384,6 +509,7 @@ function parsedFile(ts, path, source) {
  */
 export function emitFingerprint(repo, sha, files) {
   const ts = loadTypeScript(repo);
+  /** @type {{ functions: Item[], files: Record<string, Item[]> }} */
   const fingerprint = { functions: [], files: {} };
   const parsed = files.flatMap((path) => {
     const source = fileAt(repo, sha, path);