@outerlayer/cli 0.12.0 → 0.13.0

package/skill-pack/template/build/scripts/record-criteria.mjs

@@ -1,13 +1,19 @@
 #!/usr/bin/env node
-// Reads an issue body, finds the acceptance criteria, writes them as the
-// list `outerlayer emit criteria` takes, records the list, and notes the
-// outcome in the build's state file. Needs only Node.
+// Records the criteria the build read from the issue, or drafted for an issue
+// that has none, and notes the outcome in the build's state file. The agent
+// reads the issue and writes the criteria file; this script checks it, gives
+// the criteria ids, runs `outerlayer emit criteria`, and handles its answer.
+// Needs only Node.
 //
-//   node record-criteria.mjs --item <number> --issue-file <path>
+//   node record-criteria.mjs --item <number> --criteria-file <path> [--drafted]
 //
-// It never edits the issue, never replaces a list a person recorded (the
-// gateway answers 409 and the item's list stands), and records nothing when
-// the issue holds neither shape.
+// The criteria file is `{ "criteria": [{ "id"?, "text", "proof"? }] }`, in
+// the order the issue lists them. The ids are kept only when every criterion
+// carries one that fits the id grammar; otherwise every criterion is numbered
+// `AC-<item>-NN` in order. A drafted list is always numbered and is recorded
+// with `drafted: true`. An empty list records nothing. The script never edits
+// the issue, and never replaces a list the item already has (the gateway
+// answers 409 and the item's list stands).
 import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -15,118 +21,64 @@ import { pathToFileURL } from "node:url";
 
 /** Mirrors ARTIFACT_KINDS in @outerlayer/session-schema (a test pins them equal); this script imports no packages. */
 export const PROOF_KINDS = ["video", "screenshot", "report", "log", "test", "file"];
-const BULLET = /^\s*(?:[-*+]|\d+[.)])\s+(.*)$/;
-const HEADING = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
-const ID_ITEM = /^`([A-Za-z0-9_.:-]{1,64})`\s*(.*)$/;
-const LABEL = /^\s{0,3}(?:#{1,6}\s+)?(?:\*\*|__)?(acceptance(?: criteria)?|done when)\s*:?\s*(?:\*\*|__)?\s*:?\s*$/i;
+/** Mirrors ArtifactCriterionIdSchema in @outerlayer/session-schema (a test pins them equal). */
+export const CRITERION_ID = /^[A-Za-z0-9_.:-]{1,64}$/;
+/** Mirrors CHECK_BOUND_ARTIFACT_IDS in @outerlayer/session-schema (a test pins them equal): ids that name a check, not a criterion. */
+export const RESERVED_IDS = ["code-review-ran", "acceptance-criteria"];
+const PROOF_IN_TEXT = /\(proof:\s*([a-z]+)\s*\)/i;
 
-/** The lines with the contents of fenced code blocks, and the fences, blanked: a quoted example is not a section. */
-function blankFencedLines(lines) {
-  let fence = null;
-  return lines.map((line) => {
-    const opener = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
-    if (fence === null) {
-      if (opener === null) return line;
-      fence = opener[1];
-      return "";
-    }
-    if (opener !== null && opener[1][0] === fence[0] && opener[1].length >= fence.length) fence = null;
-    return "";
-  });
-}
-
-/** A bullet and the indented lines continuing it, as one string. */
-function collectItems(lines, start) {
-  const items = [];
-  let i = start;
-  for (; i < lines.length; i++) {
-    const line = lines[i];
-    const bullet = BULLET.exec(line);
-    if (bullet) {
-      items.push(bullet[1].trim());
-    } else if (line.trim() === "") {
-      // a blank line ends the list unless another bullet follows
-      const next = lines.slice(i + 1).find((l) => l.trim() !== "");
-      if (next === undefined || !BULLET.test(next)) break;
-    } else if (/^\s+\S/.test(line) && items.length > 0) {
-      items[items.length - 1] += ` ${line.trim()}`;
-    } else {
-      break;
-    }
-  }
-  return items;
-}
+/** A criteria file the agent must fix before anything is recorded. */
+export class CriteriaFileError extends Error {}
 
-function stripCheckbox(text) {
-  return text.replace(/^\[[ xX]\]\s+/, "");
+/** The proof a criterion declares: the file's `proof` when it is an artifact
+ * kind, else a `(proof: <kind>)` written in its text, else `null`. */
+function proofOf(entry) {
+  if (PROOF_KINDS.includes(entry.proof)) return entry.proof;
+  const written = PROOF_IN_TEXT.exec(entry.text)?.[1]?.toLowerCase();
+  return PROOF_KINDS.includes(written) ? written : null;
 }
 
-/** The id-bearing shape: an `## Acceptance criteria` section whose every item starts with a backticked id. */
-function readIdSection(lines) {
-  const at = lines.findIndex((l) => {
-    const h = HEADING.exec(l);
-    return h !== null && h[1].length === 2 && /^acceptance criteria$/i.test(h[2]);
-  });
-  if (at === -1) return null;
-  const items = [];
-  for (let i = at + 1; i < lines.length; i++) {
-    const h = HEADING.exec(lines[i]);
-    if (h !== null && h[1].length <= 2) break;
-    const bullet = BULLET.exec(lines[i]);
-    if (bullet) items.push(bullet[1].trim());
-    else if (/^\s+\S/.test(lines[i]) && items.length > 0) items[items.length - 1] += ` ${lines[i].trim()}`;
-  }
-  if (items.length === 0) return null;
-  const parsed = items.map((item) => ID_ITEM.exec(item));
-  const withId = parsed.filter((m) => m !== null && m[2].trim() !== "").length;
-  if (withId === 0) return null;
-  if (withId < parsed.length) return { mixed: true };
-  return {
-    criteria: parsed.map((m) => {
-      const kind = /\(proof:\s*([a-z]+)\s*\)/i.exec(m[2])?.[1]?.toLowerCase();
-      return { id: m[1], text: m[2].trim(), proof: PROOF_KINDS.includes(kind) ? kind : null };
-    }),
-  };
-}
-
-/** The plain shape: an Acceptance / Acceptance criteria / Done when label, then a bullet list. */
-function readLabelledBullets(lines) {
-  for (let i = 0; i < lines.length; i++) {
-    if (!LABEL.test(lines[i])) continue;
-    let start = i + 1;
-    while (start < lines.length && lines[start].trim() === "") start++;
-    const items = collectItems(lines, start).map(stripCheckbox).filter((t) => t !== "");
-    if (items.length > 0) return items;
-  }
+/** Why the written ids cannot be kept, or `null` when they can. */
+function idProblem(entries) {
+  const ids = entries.map((entry) => entry.id);
+  const missing = ids.filter((id) => typeof id !== "string" || id.trim() === "").length;
+  if (missing === ids.length) return "no criterion carried an id";
+  if (missing > 0) return "only some criteria carried an id";
+  const bad = ids.find((id) => !CRITERION_ID.test(id));
+  if (bad !== undefined) return `the id ${JSON.stringify(bad)} does not fit the id grammar`;
+  const reserved = ids.find((id) => RESERVED_IDS.includes(id));
+  if (reserved !== undefined) return `the id ${JSON.stringify(reserved)} names a check, not a criterion`;
+  const repeated = ids.find((id, n) => ids.indexOf(id) !== n);
+  if (repeated !== undefined) return `the id ${JSON.stringify(repeated)} appears twice`;
   return null;
 }
 
 /**
- * Finds the criteria in an issue body.
- * @returns {{shape: "ids"|"bullets"|"none", criteria: Array<{id:string,text:string,proof:string|null}>, note?: string}}
+ * Turns the agent's criteria file into the list `outerlayer emit criteria`
+ * takes. Throws {@link CriteriaFileError} for a file the agent must fix.
+ * @returns {{criteria: Array<{id:string,text:string,proof:string|null}>, numbered: boolean, numberedBecause?: string}}
  */
-export function parseCriteria(body, item) {
-  const lines = blankFencedLines(String(body).split(/\r?\n/));
-  const ids = readIdSection(lines);
-  if (ids?.criteria) return { shape: "ids", criteria: ids.criteria };
-  const bullets = readLabelledBullets(lines);
-  if (ids?.mixed && bullets) {
-    return {
-      shape: "none",
-      criteria: [],
-      note: "some criteria carry an id and some do not; recording nothing rather than renumbering the written ids",
-    };
+export function readCriteria(input, item, { drafted = false } = {}) {
+  if (typeof input !== "object" || input === null || !Array.isArray(input.criteria)) {
+    throw new CriteriaFileError('the criteria file must be { "criteria": [ ... ] }');
   }
-  if (bullets) {
-    return {
-      shape: "bullets",
-      criteria: bullets.map((text, n) => ({ id: `AC-${item}-${String(n + 1).padStart(2, "0")}`, text, proof: null })),
-    };
-  }
-  return { shape: "none", criteria: [] };
+  const entries = input.criteria.map((entry, n) => {
+    if (typeof entry !== "object" || entry === null || typeof entry.text !== "string" || entry.text.trim() === "") {
+      throw new CriteriaFileError(`criteria[${n}] needs the criterion's text`);
+    }
+    return { id: entry.id, text: entry.text.trim(), proof: entry.proof };
+  });
+  const problem = drafted ? "the build drafted them" : idProblem(entries);
+  const numbered = entries.length > 0 && problem !== null;
+  const criteria = entries.map((entry, n) => ({
+    id: numbered ? `AC-${item}-${String(n + 1).padStart(2, "0")}` : entry.id,
+    text: entry.text,
+    proof: proofOf(entry),
+  }));
+  return numbered ? { criteria, numbered, numberedBecause: problem } : { criteria, numbered };
 }
 
-/** Sorts a failed `emit criteria` into "the item already has a person's list" and any other refusal. */
+/** Sorts a failed `emit criteria` into "the item already has a list" and any other refusal. */
 export function classifyEmitFailure(message) {
   // Only the CLI's replace refusal reads "refused (409):". Other answers that
   // carry a 409, such as a lost race, read "emit failed (409):".
@@ -153,40 +105,39 @@ function readState(path) {
 }
 
 /**
- * Records the issue's criteria and notes the outcome in the state file.
- * `emit(file)` runs `outerlayer emit criteria <file>` and returns
- * `{ ok: true }` or `{ ok: false, message }`.
+ * Records the criteria and notes the outcome in the state file. `input` is
+ * the parsed criteria file. `emit(file)` runs `outerlayer emit criteria
+ * <file>` and returns `{ ok: true }` or `{ ok: false, message }`.
  */
-export async function recordCriteria({ body, item, reportsDir, statePath, emit }) {
-  const found = parseCriteria(body, item);
+export async function recordCriteria({ input, item, drafted = false, reportsDir, statePath, emit }) {
+  const read = readCriteria(input, item, { drafted });
+  const numbering = read.numbered ? { numbered: true, numberedBecause: read.numberedBecause } : { numbered: false };
   let outcome;
-  if (found.shape === "none") {
-    outcome = { source: "none", recorded: false, count: 0, list: [], ...(found.note ? { note: found.note } : {}) };
+  if (read.criteria.length === 0) {
+    outcome = { source: "none", recorded: false, count: 0, list: [] };
   } else {
     mkdirSync(reportsDir, { recursive: true });
     const file = join(reportsDir, "criteria.json");
-    writeFileSync(file, `${JSON.stringify({ criteria: found.criteria }, null, 2)}\n`);
+    const list = drafted ? { criteria: read.criteria, drafted: true } : { criteria: read.criteria };
+    writeFileSync(file, `${JSON.stringify(list, null, 2)}\n`);
     const result = await emit(file);
-    const base = { count: found.criteria.length, list: found.criteria };
+    const source = drafted ? "drafted" : "issue";
+    const base = { count: read.criteria.length, list: read.criteria, ...numbering };
     if (result.ok) {
-      outcome = { source: found.shape === "ids" ? "issue-ids" : "issue-bullets", recorded: true, ...base };
+      outcome = { source, recorded: true, ...base };
     } else if (classifyEmitFailure(result.message) === "item-list-stands") {
-      // No command returns the item's own list, so `list` stays empty; the issue's reading goes under `issueReading`.
+      // No command returns the item's own list, so `list` stays empty; the build's reading goes under `issueReading`.
       outcome = {
         source: "item",
         recorded: false,
-        count: found.criteria.length,
+        count: read.criteria.length,
         list: [],
-        issueReading: found.criteria,
+        issueReading: read.criteria,
+        ...numbering,
         note: "the item already has a recorded list; it stands",
       };
     } else {
-      outcome = {
-        source: found.shape === "ids" ? "issue-ids" : "issue-bullets",
-        recorded: false,
-        ...base,
-        refusal: result.message,
-      };
+      outcome = { source, recorded: false, ...base, refusal: result.message };
     }
   }
   mkdirSync(dirname(statePath), { recursive: true });
@@ -197,12 +148,13 @@ export async function recordCriteria({ body, item, reportsDir, statePath, emit }
 export function summarize(outcome) {
   const n = outcome.count;
   const noun = n === 1 ? "criterion" : "criteria";
-  if (outcome.source === "none") return `no acceptance criteria found; none recorded${outcome.note ? ` (${outcome.note})` : ""}`;
-  if (outcome.source === "item") return `the item already has a recorded list; it stands, and the ${n} ${noun} read from the issue were not recorded`;
-  const shape = outcome.source === "issue-ids" ? "an Acceptance criteria section with ids" : "bullets under an Acceptance heading";
+  const ids = outcome.numbered ? `, numbered AC-<item>-NN because ${outcome.numberedBecause}` : ", with the issue's own ids";
+  if (outcome.source === "none") return "no criteria in the file; none recorded";
+  if (outcome.source === "item") return `the item already has a recorded list; it stands, and the ${n} ${noun} read here were not recorded`;
+  const what = outcome.source === "drafted" ? `drafted ${n} ${noun} from the issue's description` : `read ${n} ${noun} from the issue`;
   return outcome.recorded
-    ? `recorded ${n} ${noun} from ${shape}`
-    : `read ${n} ${noun} from ${shape} but the record was refused: ${outcome.refusal}`;
+    ? `${what} and recorded them${outcome.source === "drafted" ? " as drafted" : ids}`
+    : `${what} but the record was refused: ${outcome.refusal}`;
 }
 
 async function main(argv) {
@@ -211,9 +163,16 @@ async function main(argv) {
     return at === -1 ? undefined : argv[at + 1];
   };
   const item = arg("--item");
-  const issueFile = arg("--issue-file");
-  if (!item || !/^\d+$/.test(item) || !issueFile) {
-    process.stderr.write("usage: record-criteria.mjs --item <number> --issue-file <path>\n");
+  const criteriaFile = arg("--criteria-file");
+  if (!item || !/^\d+$/.test(item) || !criteriaFile) {
+    process.stderr.write("usage: record-criteria.mjs --item <number> --criteria-file <path> [--drafted]\n");
+    return 2;
+  }
+  let input;
+  try {
+    input = JSON.parse(readFileSync(criteriaFile, "utf8"));
+  } catch (err) {
+    process.stderr.write(`cannot read the criteria file "${criteriaFile}": ${err.message}\n`);
     return 2;
   }
   const git = spawnSync("git", ["rev-parse", "--absolute-git-dir"], { encoding: "utf8" });
@@ -222,15 +181,22 @@ async function main(argv) {
     return 2;
   }
   const gitDir = git.stdout.trim();
-  const outcome = await recordCriteria({
-    body: readFileSync(issueFile, "utf8"),
-    item,
-    reportsDir: join(gitDir, "build-reports"),
-    statePath: join(gitDir, "build-state.json"),
-    emit: makeEmit(spawnSync, item),
-  });
-  process.stdout.write(`${summarize(outcome)}\n`);
-  return 0;
+  try {
+    const outcome = await recordCriteria({
+      input,
+      item,
+      drafted: argv.includes("--drafted"),
+      reportsDir: join(gitDir, "build-reports"),
+      statePath: join(gitDir, "build-state.json"),
+      emit: makeEmit(spawnSync, item),
+    });
+    process.stdout.write(`${summarize(outcome)}\n`);
+    return 0;
+  } catch (err) {
+    if (!(err instanceof CriteriaFileError)) throw err;
+    process.stderr.write(`${err.message}; fix the criteria file and run again\n`);
+    return 2;
+  }
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) process.exitCode = await main(process.argv.slice(2));

package/skill-pack/validators/code-review.yaml

@@ -5,8 +5,10 @@
 # clean bill) as an .html file. Emit it as a report artifact with no --for:
 #   outerlayer emit artifact review.html --caption "Review of the change and what it found"
 # Then run `outerlayer sync`, and copy the report's deep link from the pull
-# request's evidence comment. Never build the link by hand, and never link a
-# pull request comment: a comment can be edited or deleted later.
+# request's evidence comment. The link can take up to a minute to appear
+# after the sync. If it is not there yet, wait a minute and read the comment
+# again; do not give up after one look. Never build the link by hand, and
+# never link a pull request comment: a comment can be edited or deleted later.
 #
 # Then record the verdict once, with that link as its proof:
 #   outerlayer emit code-review --item "$OUTERLAYER_WORK" --result pass --link <the report's deep link>

package/dist/chunk-T6OIJQRT.js

@@ -1,31 +0,0 @@
-#!/usr/bin/env node
-import { createRequire } from 'node:module';
-import { RUNNER_DIR_MODE, RUNNER_FILE_MODE } from './chunk-ZM2IMMYN.js';
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
-import { dirname } from 'path';
-
-createRequire(import.meta.url);
-function readJobFile(path) {
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return null;
-  }
-}
-function readJobFileChecked(path) {
-  if (!existsSync(path)) return { kind: "missing" };
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { kind: "unreadable" };
-    return { kind: "ok", job: parsed };
-  } catch {
-    return { kind: "unreadable" };
-  }
-}
-function writeJobFile(path, job) {
-  mkdirSync(dirname(path), { recursive: true, mode: RUNNER_DIR_MODE });
-  writeFileSync(path, JSON.stringify(job, null, 2), { mode: RUNNER_FILE_MODE });
-}
-
-export { readJobFile, readJobFileChecked, writeJobFile };