dw-sdlc 0.5.1 → 0.7.0

package/dist/pr/state.d.ts

@@ -0,0 +1,54 @@
+export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName\n      viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n    }\n  }\n}";
+export type Bucket = "pass" | "fail" | "pending" | "skipping";
+export type CiCheck = {
+    name: string;
+    bucket: Bucket;
+    required: boolean;
+    link: string | null;
+    /** The command that prints a failed GitHub Actions job's log; null for any other CI. */
+    log: string[] | null;
+    startedAt: string | null;
+};
+export type Thread = {
+    id: string;
+    path: string;
+    line: number | null;
+    author: string;
+    body: string;
+    /** Whether the viewer, the account gh reads as, wrote the thread's last comment. */
+    lastByViewer: boolean;
+};
+declare const STATES: readonly ["OPEN", "CLOSED", "MERGED"];
+declare const MERGEABLE: readonly ["MERGEABLE", "CONFLICTING", "UNKNOWN"];
+declare const REVIEW_DECISIONS: readonly ["APPROVED", "CHANGES_REQUESTED", "REVIEW_REQUIRED"];
+export type PrState = {
+    url: string;
+    repo: string;
+    number: number;
+    state: (typeof STATES)[number];
+    draft: boolean;
+    mergeable: (typeof MERGEABLE)[number];
+    /** BEHIND, BLOCKED, CLEAN, DIRTY, HAS_HOOKS, UNKNOWN or UNSTABLE, as GitHub reports it. */
+    mergeStateStatus: string;
+    reviewDecision: (typeof REVIEW_DECISIONS)[number] | null;
+    viewerDidAuthor: boolean;
+    head: string;
+    headCommittedAt: string;
+    branch: string;
+    base: string;
+    mergeCommit: string | null;
+    checks: CiCheck[];
+    /** The threads neither resolved nor outdated. */
+    unresolvedThreads: Thread[];
+};
+/** A reply that is not the shape the query asks for; the message names the field. */
+export declare class ReplyError extends Error {
+}
+/** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
+export declare function parseView(reply: string): {
+    repo: string;
+    number: number;
+};
+/** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
+export declare function parsePr(reply: string, repo: string): PrState;
+export {};

package/dist/pr/state.js

@@ -0,0 +1,220 @@
+// One pull request as the Ship script reads it: the one GraphQL query, and its reply parsed into the
+// state the decision reads. Every field the state needs is checked; a reply that fails names the field.
+export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName
+      viewerDidAuthor mergeCommit { oid }
+      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line
+        comments(first: 1) { nodes { author { login } body } }
+        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }
+      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {
+        contexts(first: 50) { nodes {
+          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }
+          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }
+    }
+  }
+}`;
+const STATES = ["OPEN", "CLOSED", "MERGED"];
+const MERGEABLE = ["MERGEABLE", "CONFLICTING", "UNKNOWN"];
+const REVIEW_DECISIONS = ["APPROVED", "CHANGES_REQUESTED", "REVIEW_REQUIRED"];
+/** A reply that is not the shape the query asks for; the message names the field. */
+export class ReplyError extends Error {
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function shown(value) {
+    return value === undefined ? "missing" : JSON.stringify(value);
+}
+/** The JSON object `reply` holds, the root its fields' paths start from; `what` names it in a problem. */
+function rootOf(reply, what) {
+    let json;
+    try {
+        json = JSON.parse(reply);
+    }
+    catch {
+        throw new ReplyError(`${what} is not JSON`);
+    }
+    if (!isRecord(json)) {
+        throw new ReplyError(`${what} is not a JSON object`);
+    }
+    return { value: json, at: "" };
+}
+function fieldOf(node, key) {
+    return { value: node.value[key], at: node.at === "" ? key : `${node.at}.${key}` };
+}
+function object(value, at) {
+    if (!isRecord(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not an object`);
+    }
+    return { value, at };
+}
+function child(node, key) {
+    const { value, at } = fieldOf(node, key);
+    return object(value, at);
+}
+function childOrNull(node, key) {
+    const { value, at } = fieldOf(node, key);
+    return value === null ? null : object(value, at);
+}
+function string(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (typeof value !== "string") {
+        throw new ReplyError(`${at} is ${shown(value)}, not a string`);
+    }
+    return value;
+}
+function stringOrNull(node, key) {
+    return node.value[key] === null ? null : string(node, key);
+}
+function boolean(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (typeof value !== "boolean") {
+        throw new ReplyError(`${at} is ${shown(value)}, not a boolean`);
+    }
+    return value;
+}
+function integer(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not an integer`);
+    }
+    return value;
+}
+function integerOrNull(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (value !== null && !Number.isInteger(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not an integer or null`);
+    }
+    return typeof value === "number" ? value : null;
+}
+/** A time as GitHub writes it, ISO 8601; the decision reads it as one. */
+function time(node, key) {
+    const value = string(node, key);
+    if (Number.isNaN(Date.parse(value))) {
+        throw new ReplyError(`${fieldOf(node, key).at} is ${shown(value)}, not a time`);
+    }
+    return value;
+}
+function timeOrNull(node, key) {
+    return node.value[key] === null ? null : time(node, key);
+}
+function isOneOf(values, value) {
+    return values.some((known) => known === value);
+}
+function oneOf(node, key, values) {
+    const { value, at } = fieldOf(node, key);
+    if (!isOneOf(values, value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not one of ${values.join(", ")}`);
+    }
+    return value;
+}
+/** The objects of a connection's `nodes`. */
+function nodes(node, key) {
+    const { value, at } = fieldOf(child(node, key), "nodes");
+    if (!Array.isArray(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not a list`);
+    }
+    return value.map((item, index) => object(item, `${at}[${index}]`));
+}
+/** The first object of a connection's `nodes`; an empty connection does not parse. */
+function firstNode(node, key) {
+    const [first] = nodes(node, key);
+    if (first === undefined) {
+        throw new ReplyError(`${node.at}.${key}.nodes is empty`);
+    }
+    return first;
+}
+const FAIL = new Set(["ERROR", "FAILURE", "TIMED_OUT", "ACTION_REQUIRED", "CANCELLED", "STARTUP_FAILURE"]);
+const SKIPPING = new Set(["SKIPPED", "NEUTRAL"]);
+/** A check's bucket as `gh pr checks` sorts it: every word not passed, failed or skipped is pending. */
+function bucketOf(word) {
+    if (word === "SUCCESS") {
+        return "pass";
+    }
+    if (word !== null && FAIL.has(word)) {
+        return "fail";
+    }
+    return word !== null && SKIPPING.has(word) ? "skipping" : "pending";
+}
+function logCommand(link, repo) {
+    const job = link?.match(/\/actions\/runs\/\d+\/job\/(\d+)/)?.[1];
+    return job === undefined ? null : ["gh", "run", "view", "--job", job, "-R", repo, "--log-failed"];
+}
+/** A CheckRun has a name and a status; a StatusContext has a context and a state. */
+function checkOf(context, repo) {
+    if ("name" in context.value) {
+        const status = string(context, "status");
+        const link = stringOrNull(context, "detailsUrl");
+        return {
+            name: string(context, "name"),
+            bucket: bucketOf(status === "COMPLETED" ? stringOrNull(context, "conclusion") : status),
+            required: boolean(context, "isRequired"),
+            link,
+            log: logCommand(link, repo),
+            startedAt: timeOrNull(context, "startedAt")
+        };
+    }
+    if ("context" in context.value) {
+        const link = stringOrNull(context, "targetUrl");
+        return {
+            name: string(context, "context"),
+            bucket: bucketOf(string(context, "state")),
+            required: boolean(context, "isRequired"),
+            link,
+            log: logCommand(link, repo),
+            startedAt: time(context, "createdAt")
+        };
+    }
+    throw new ReplyError(`${context.at} is neither a CheckRun nor a StatusContext`);
+}
+/** A thread by its opening comment; a deleted account's comment has no author and reads as GitHub's ghost. */
+function threadOf(thread) {
+    const first = firstNode(thread, "comments");
+    const author = childOrNull(first, "author");
+    return {
+        id: string(thread, "id"),
+        path: string(thread, "path"),
+        line: integerOrNull(thread, "line"),
+        author: author === null ? "ghost" : string(author, "login"),
+        body: string(first, "body"),
+        lastByViewer: boolean(firstNode(thread, "latest"), "viewerDidAuthor")
+    };
+}
+/** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
+export function parseView(reply) {
+    const url = string(rootOf(reply, "the reply of gh pr view"), "url");
+    const [, repo, number] = /^https:\/\/[^/]+\/([^/]+\/[^/]+)\/pull\/(\d+)$/.exec(url) ?? [];
+    if (repo === undefined || number === undefined) {
+        throw new ReplyError(`url is ${JSON.stringify(url)}, not a pull request's URL`);
+    }
+    return { repo, number: Number(number) };
+}
+/** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
+export function parsePr(reply, repo) {
+    const pr = child(child(child(rootOf(reply, "the reply"), "data"), "repository"), "pullRequest");
+    const commit = child(firstNode(pr, "commits"), "commit");
+    const rollup = childOrNull(commit, "statusCheckRollup");
+    const mergeCommit = childOrNull(pr, "mergeCommit");
+    return {
+        url: string(pr, "url"),
+        repo,
+        number: integer(pr, "number"),
+        state: oneOf(pr, "state", STATES),
+        draft: boolean(pr, "isDraft"),
+        mergeable: oneOf(pr, "mergeable", MERGEABLE),
+        mergeStateStatus: string(pr, "mergeStateStatus"),
+        reviewDecision: pr.value.reviewDecision === null ? null : oneOf(pr, "reviewDecision", REVIEW_DECISIONS),
+        viewerDidAuthor: boolean(pr, "viewerDidAuthor"),
+        head: string(pr, "headRefOid"),
+        headCommittedAt: time(commit, "committedDate"),
+        branch: string(pr, "headRefName"),
+        base: string(pr, "baseRefName"),
+        mergeCommit: mergeCommit === null ? null : string(mergeCommit, "oid"),
+        checks: rollup === null ? [] : nodes(rollup, "contexts").map((context) => checkOf(context, repo)),
+        unresolvedThreads: nodes(pr, "reviewThreads")
+            .filter((thread) => !boolean(thread, "isResolved") && !boolean(thread, "isOutdated"))
+            .map(threadOf)
+    };
+}

package/dist/references-key.d.ts

@@ -1,4 +1,6 @@
-/** The committed config, the only file the key is read from. */
+/** The committed file the References are read from; no local layer adds to it. */
+export declare const REFERENCES_FILE = ".ai/references.json";
+/** The committed agentic config: a `references` key in it is refused, so the file stays the one list. */
 export declare const CONFIG = ".ai/agentic.config.json";
 export type Reference = {
     dir: string;
@@ -20,12 +22,29 @@ export declare function parseReferences(value: unknown): {
 } | {
     problem: KeyProblem;
 };
+/** The References the file's parsed `value` declares, or the first problem in it; `""` names its root. */
+export declare function parseFile(value: unknown): {
+    references: Reference[];
+} | {
+    problem: KeyProblem;
+};
+/** The `references` key the agentic config at `root` still holds, `undefined` without one or the config. */
+export declare function leftoverKey(root: string): unknown;
+/** Why a `references` key left in the config stops a read, by whether the file is there beside it. */
+export declare function leftoverProblem(fileExists: boolean): string;
 /**
- * The References the committed config at `root` declares, `undefined` without the file or the key,
- * or the problem that stops the read: the file is not a JSON object, or the key fails the parser.
+ * The References the file at `root` declares, `undefined` without the file, or the problem that stops
+ * the read: a `references` key left in the agentic config, a file that is not JSON, or one the parser
+ * refuses. A config that is not JSON is the guards' to report, not the read's.
  */
 export declare function readReferences(root: string): {
     references: Reference[] | undefined;
 } | {
     problem: string;
 };
+/** The References the file at `root` declares, `undefined` without it, the agentic config unread. */
+export declare function readFile(root: string): {
+    references: Reference[] | undefined;
+} | {
+    problem: string;
+};

package/dist/references-key.js

@@ -1,10 +1,13 @@
-// The strict parser of the `references` key, the authority at runtime, and the reader of the committed
-// config that holds it. `config/references.schema.json` documents the same contract, and
-// `test/references-key.test.ts` runs one case list through both. The first problem stops the parse.
+// The strict parser of `.ai/references.json`, the authority at runtime, and its reader. The file's
+// `references` key holds the entries. `config/references.schema.json` documents the same contract,
+// and `test/references-key.test.ts` runs one case list through both. The first problem stops the parse.
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-/** The committed config, the only file the key is read from. */
+/** The committed file the References are read from; no local layer adds to it. */
+export const REFERENCES_FILE = ".ai/references.json";
+/** The committed agentic config: a `references` key in it is refused, so the file stays the one list. */
 export const CONFIG = ".ai/agentic.config.json";
+const FILE_FIELDS = ["$schema", "version", "references"];
 const FIELDS = ["dir", "repository", "ref", "only", "skip", "what", "when"];
 const REQUIRED = ["dir", "repository", "ref", "what", "when"];
 const DIR_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
@@ -119,31 +122,78 @@ export function parseReferences(value) {
         throw error;
     }
 }
-/**
- * The References the committed config at `root` declares, `undefined` without the file or the key,
- * or the problem that stops the read: the file is not a JSON object, or the key fails the parser.
- */
-export function readReferences(root) {
-    const path = join(root, CONFIG);
+/** The References the file's parsed `value` declares, or the first problem in it; `""` names its root. */
+export function parseFile(value) {
+    if (!isObject(value)) {
+        return { problem: { path: "", message: `must be an object, not ${kind(value)}` } };
+    }
+    const unknown = Object.keys(value).find((field) => !FILE_FIELDS.includes(field));
+    if (unknown !== undefined) {
+        return { problem: { path: "", message: `unknown key ${JSON.stringify(unknown)}` } };
+    }
+    const missing = ["version", "references"].find((field) => !Object.hasOwn(value, field));
+    if (missing !== undefined) {
+        return { problem: { path: "", message: `missing key ${JSON.stringify(missing)}` } };
+    }
+    if (value.$schema !== undefined && typeof value.$schema !== "string") {
+        return { problem: { path: "$schema", message: `must be a string, not ${kind(value.$schema)}` } };
+    }
+    if (value.version !== 1) {
+        return { problem: { path: "version", message: `must be 1, not ${JSON.stringify(value.version)}` } };
+    }
+    return parseReferences(value.references);
+}
+/** The JSON object at `path`, `undefined` without the file, or why it is not one. */
+function readObject(path, name) {
     if (!existsSync(path)) {
-        return { references: undefined };
+        return { value: undefined };
     }
-    let config;
+    let value;
     try {
-        config = JSON.parse(readFileSync(path, "utf8"));
+        value = JSON.parse(readFileSync(path, "utf8"));
     }
     catch (error) {
-        return { problem: `${CONFIG}: not JSON: ${error instanceof Error ? error.message : String(error)}` };
+        return { problem: `${name}: not JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    return isObject(value) ? { value } : { problem: `${name}: not a JSON object` };
+}
+/** The `references` key the agentic config at `root` still holds, `undefined` without one or the config. */
+export function leftoverKey(root) {
+    const read = readObject(join(root, CONFIG), CONFIG);
+    return "value" in read && read.value !== undefined && Object.hasOwn(read.value, "references")
+        ? read.value.references
+        : undefined;
+}
+/** Why a `references` key left in the config stops a read, by whether the file is there beside it. */
+export function leftoverProblem(fileExists) {
+    return fileExists
+        ? `${CONFIG} has a references key beside ${REFERENCES_FILE}; merge it into the file and remove the key by hand`
+        : `${CONFIG}: the references key belongs in ${REFERENCES_FILE}; move it there with \`dw-sdlc references setup\``;
+}
+/**
+ * The References the file at `root` declares, `undefined` without the file, or the problem that stops
+ * the read: a `references` key left in the agentic config, a file that is not JSON, or one the parser
+ * refuses. A config that is not JSON is the guards' to report, not the read's.
+ */
+export function readReferences(root) {
+    if (leftoverKey(root) !== undefined) {
+        return { problem: leftoverProblem(existsSync(join(root, REFERENCES_FILE))) };
     }
-    if (!isObject(config)) {
-        return { problem: `${CONFIG}: not a JSON object` };
+    return readFile(root);
+}
+/** The References the file at `root` declares, `undefined` without it, the agentic config unread. */
+export function readFile(root) {
+    const read = readObject(join(root, REFERENCES_FILE), REFERENCES_FILE);
+    if ("problem" in read) {
+        return read;
     }
-    if (!Object.hasOwn(config, "references")) {
+    if (read.value === undefined) {
         return { references: undefined };
     }
-    const parsed = parseReferences(config.references);
+    const parsed = parseFile(read.value);
     if ("problem" in parsed) {
-        return { problem: `${CONFIG}: ${parsed.problem.path}: ${parsed.problem.message}` };
+        const where = parsed.problem.path === "" ? "" : `${parsed.problem.path}: `;
+        return { problem: `${REFERENCES_FILE}: ${where}${parsed.problem.message}` };
     }
     return { references: parsed.references };
 }

package/dist/router-block.d.ts

@@ -1,5 +1,5 @@
 import type { Reference } from "./references-key.ts";
-/** The block the key gives: one row per Reference in the key's order, or one line when it has none. */
+/** The block the file gives: one row per Reference in the file's order, or one line when it has none. */
 export declare function renderBlock(references: Reference[]): string;
 /**
  * The Router's text with `block` in place of the one between its markers: as it is when the two say

package/dist/router-block.js

@@ -1,12 +1,12 @@
-// The Router's block: a table of each Reference's `dir` and `when`, written from the `references` key
+// The Router's block: a table of each Reference's `dir` and `when`, written from `.ai/references.json`
 // between two markers. The setup writes it and the Sync checks it; the rest of the Router is the
-// author's. A block is in step when its rows say what the key says, not its bytes, which a formatter pads.
-const START = "<!-- references:start — written from .ai/agentic.config.json by the setup; edit the key -->";
+// author's. A block is in step when its rows say what the file says, not its bytes, which a formatter pads.
+const START = "<!-- references:start — written from .ai/references.json by the setup; edit the file -->";
 const END = "<!-- references:end -->";
 const START_LINE = /^<!-- references:start\b.*-->\s*$/;
 const END_LINE = /^<!-- references:end -->\s*$/;
 const NONE = "No Reference is declared yet: `/sdlc-references-add <repository>` adds one.";
-/** The block the key gives: one row per Reference in the key's order, or one line when it has none. */
+/** The block the file gives: one row per Reference in the file's order, or one line when it has none. */
 export function renderBlock(references) {
     const body = references.length === 0
         ? [NONE]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dw-sdlc",
-  "version": "0.5.1",
-  "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, and the Sync and setup of References; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
+  "version": "0.7.0",
+  "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, the Sync and setup of References, and the Ship script that drives a pull request to merged; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {
     "type": "git",

package/templates/router.md

@@ -9,11 +9,11 @@ file routes reference material only.
 
 ## The list
 
-The table below is written from the `references` key of `.ai/agentic.config.json` by the setup, so
-edit the key, never the table; the key also holds `what` each Reference is, its repository, its ref
-and the paths its clone skips. Before you research, open the clones whose `when` matches the task.
+The table below is written from `.ai/references.json` by the setup, so edit the file, never the
+table; the file also holds `what` each Reference is, its repository, its ref and the paths its clone
+skips. Before you research, open the clones whose `when` matches the task.
 
-<!-- references:start — written from .ai/agentic.config.json by the setup; edit the key -->
+<!-- references:start — written from .ai/references.json by the setup; edit the file -->
 
 No Reference is declared yet: `/sdlc-references-add <repository>` adds one.
 <!-- references:end -->