@jwilger/pi-development-system 0.58.0 → 0.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/src/jev/questions/readiness.ts

@@ -27,6 +27,9 @@ export const READINESS_QUESTIONS = {
   steps: vague(
     "`task.steps` should be small steps a reviewer could reject independently. Are any steps large, combined ('implement and wire everything'), or out of order with the test-first step?",
   ),
+  check: vague(
+    "`task.run` should be an actual command a person can type, and `task.expected` an observable result such as a count, output or exit status. Is `run` prose or a placeholder rather than a command (for example 'run the tests'), or is `expected` a restatement of success (for example 'tests pass', 'should work') rather than something observed?",
+  ),
   tooBig: {
     type: "bool",
     instructions:
@@ -60,6 +63,8 @@ export async function judgeTaskReadiness(
         interfaces: clip(record.interfaces, 1500),
         firstFailingTest: clip(record.firstFailingTest, 600),
         steps: record.steps.slice(0, 10).map((s) => clip(s, 300)),
+        run: clip(record.run, 300),
+        expected: clip(record.expected, 300),
       },
     },
     READINESS_QUESTIONS,

package/src/planning/task-record.ts

@@ -28,15 +28,29 @@ type Section = (typeof SECTIONS)[number];
 
 const HEADER = /^## (\S+) [—-] (.+)$/;
 const SECTION_LINE = /^\*\*([^:*]+)(?::\*\*|\*\*:)\s*(.*)$/;
-const STEP = /^\s*(?:\d+[.)]|[-*])\s+(.*)$/;
+/** Top-level list items only; indented sub-items belong to the step above them. */
+const STEP = /^(?:\d+[.)]|[-*])\s+(.*)$/;
 const STEPS_MIN = 3;
 const STEPS_MAX = 7;
 /** Words that stand in for a command or an observable result. */
 const PLACEHOLDER =
-  /^(?:(?:todo|tbd|tbc)\b.*|n\/?a|none|-|…|\.\.\.|works?|it works|passes|ok)\.?$/i;
+  /^(?:(?:tbd|tbc)\b.*|todo\s*(?::.*)?|n\/?a|none|-|…|\.\.\.|works?|it works|passes|ok)\.?$/i;
 
 const isSection = (name: string): name is Section => SECTIONS.some((s) => s === name);
 
+const FENCE = /^\s*(?:```|~~~)/;
+const HEADING = /^#{1,6}\s/;
+
+/** For each line, whether it sits inside (or on the edge of) a fenced code block. */
+const fencedFlags = (lines: readonly string[]): boolean[] => {
+  let open = false;
+  return lines.map((line) => {
+    if (!FENCE.test(line)) return open;
+    open = !open;
+    return true;
+  });
+};
+
 type Sections = { readonly text: Map<Section, string>; readonly duplicates: Section[] };
 
 /** Splits the body into section texts keyed by name; text may continue over several lines. */
@@ -44,8 +58,9 @@ function splitSections(lines: readonly string[]): Sections {
   const found = new Map<Section, string[]>();
   const duplicates: Section[] = [];
   let current: string[] | undefined;
-  for (const line of lines) {
-    const match = SECTION_LINE.exec(line);
+  const fenced = fencedFlags(lines);
+  for (const [at, line] of lines.entries()) {
+    const match = fenced[at] === true ? null : SECTION_LINE.exec(line);
     const name = match?.[1]?.trim();
     if (match !== null && name !== undefined && isSection(name)) {
       if (found.has(name)) duplicates.push(name);
@@ -59,12 +74,13 @@ function splitSections(lines: readonly string[]): Sections {
 
 type Located = { readonly id: string; readonly title: string; readonly lines: readonly string[] };
 
-/** Every `## <id> — <title>` block; any other `## ` heading ends the block before it. */
+/** Every `## <id> — <title>` block; any other heading (outside code fences) ends the block before it. */
 function recordsIn(lines: readonly string[]): Located[] {
   const records: { id: string; title: string; lines: string[] }[] = [];
   let open: { id: string; title: string; lines: string[] } | undefined;
-  for (const line of lines) {
-    if (line.startsWith("## ")) {
+  const fenced = fencedFlags(lines);
+  for (const [at, line] of lines.entries()) {
+    if (fenced[at] !== true && HEADING.test(line)) {
       const header = HEADER.exec(line);
       open =
         header === null
@@ -76,13 +92,25 @@ function recordsIn(lines: readonly string[]): Located[] {
   return records;
 }
 
-const stripTicks = (text: string): string => text.replace(/^`+|`+$/g, "").trim();
+/** A command or result without its backticks, or the body of a fenced block (its info string dropped). */
+const stripTicks = (text: string): string => {
+  const lines = text.split("\n");
+  if (FENCE.test(lines[0] ?? "")) {
+    const body = lines.slice(1);
+    if (FENCE.test(body.at(-1) ?? "")) body.pop();
+    return body.join("\n").trim();
+  }
+  return text.replace(/^`+|`+$/g, "").trim();
+};
 
-const stepsOf = (text: string): string[] =>
-  text.split("\n").flatMap((line) => {
-    const item = STEP.exec(line)?.[1]?.trim();
+const stepsOf = (text: string): string[] => {
+  const lines = text.split("\n");
+  const fenced = fencedFlags(lines);
+  return lines.flatMap((line, at) => {
+    const item = fenced[at] === true ? undefined : STEP.exec(line)?.[1]?.trim();
     return item === undefined || item === "" ? [] : [item];
   });
+};
 
 function concrete(name: "Run" | "Expected", text: string): string | undefined {
   const bare = stripTicks(text);

package/src/tracker/github.ts

@@ -1,5 +1,13 @@
 import type { Exec } from "../core/exec.ts";
 import { ok } from "../core/result.ts";
+import { unwritable } from "./item-format.ts";
+
+/** Our status marker is a label; a user label with that name would change the status as a side effect. */
+const unusable = (item: { title: string; labels: readonly string[] }): string | undefined =>
+  item.labels.includes("in-progress")
+    ? '"in-progress" is reserved for the in-progress status; set status instead'
+    : unwritable(item);
+
 import {
   type ItemFilter,
   type NewWorkItem,
@@ -94,27 +102,55 @@ const bindGh =
     return trackerError(`gh ${args.slice(0, 2).join(" ")} failed: ${why}`);
   };
 
-const view = async (gh: Gh, id: string): Promise<TrackerResult<WorkItem>> => {
+const viewRaw = async (gh: Gh, id: string): Promise<TrackerResult<GhIssue>> => {
   if (!ISSUE_NUMBER.test(id)) return notNumber(id);
   const out = await gh(["issue", "view", id, "--json", FIELDS]);
   if (!out.ok) return out;
   const parsed = parseIssue(out.value);
-  return parsed === undefined
-    ? trackerError(`gh issue view ${id}: unexpected output`)
-    : ok(toItem(parsed));
+  return parsed === undefined ? trackerError(`gh issue view ${id}: unexpected output`) : ok(parsed);
+};
+
+const view = async (gh: Gh, id: string): Promise<TrackerResult<WorkItem>> => {
+  const raw = await viewRaw(gh, id);
+  return raw.ok ? ok(toItem(raw.value)) : raw;
+};
+
+const LIST_LIMIT = 500;
+
+/** The `gh issue list` arguments that select exactly the wanted status where gh can, so the limit bites last. */
+const listArgs = (status: WorkStatus | undefined): string[] => {
+  const state = status === undefined ? "all" : STATE_ARG[status];
+  const marker = status === "in-progress" ? ["--label", IN_PROGRESS] : [];
+  return [
+    "issue",
+    "list",
+    "--state",
+    state,
+    ...marker,
+    "--limit",
+    String(LIST_LIMIT),
+    "--json",
+    FIELDS,
+  ];
 };
 
 const listIssues = async (gh: Gh, filter: ItemFilter): Promise<TrackerResult<WorkItem[]>> => {
-  const state = filter.status === undefined ? "all" : STATE_ARG[filter.status];
-  const out = await gh(["issue", "list", "--state", state, "--limit", "200", "--json", FIELDS]);
+  const out = await gh(listArgs(filter.status));
   if (!out.ok) return out;
   const parsed = parseIssues(out.value);
   if (parsed === undefined) return trackerError("gh issue list: unexpected output");
+  if (parsed.length >= LIST_LIMIT) {
+    return trackerError(
+      `gh issue list returned ${LIST_LIMIT} issues, so the list may be cut short; ask for one status (open, in-progress or done) to narrow it`,
+    );
+  }
   const items = parsed.map(toItem);
   return ok(filter.status === undefined ? items : items.filter((i) => i.status === filter.status));
 };
 
 const createIssue = async (gh: Gh, input: NewWorkItem): Promise<TrackerResult<WorkItem>> => {
+  const problem = unusable({ title: input.title, labels: input.labels ?? [] });
+  if (problem !== undefined) return trackerError(problem);
   const labels = (input.labels ?? []).flatMap((l) => ["--label", l]);
   const out = await gh([
     "issue",
@@ -132,10 +168,9 @@ const createIssue = async (gh: Gh, input: NewWorkItem): Promise<TrackerResult<Wo
 };
 
 /** Label changes that make the issue's labels exactly `wanted` (plus the in-progress marker when asked for). */
-const labelFlags = (current: WorkItem, patch: WorkItemPatch): string[] => {
+const labelFlags = (current: WorkItem, hadMarker: boolean, patch: WorkItemPatch): string[] => {
   const wanted = patch.labels ?? current.labels;
   const marked = (patch.status ?? current.status) === "in-progress";
-  const hadMarker = current.status === "in-progress";
   const add = [
     ...wanted.filter((l) => !current.labels.includes(l)),
     ...(marked && !hadMarker ? [IN_PROGRESS] : []),
@@ -150,10 +185,12 @@ const labelFlags = (current: WorkItem, patch: WorkItemPatch): string[] => {
   ];
 };
 
-const editFlags = (current: WorkItem, patch: WorkItemPatch): string[] => [
+const editFlags = (current: WorkItem, hadMarker: boolean, patch: WorkItemPatch): string[] => [
   ...(patch.title === undefined ? [] : ["--title", patch.title]),
   ...(patch.body === undefined ? [] : ["--body", patch.body]),
-  ...(patch.labels === undefined && patch.status === undefined ? [] : labelFlags(current, patch)),
+  ...(patch.labels === undefined && patch.status === undefined
+    ? []
+    : labelFlags(current, hadMarker, patch)),
 ];
 
 /** Closing or reopening only when the issue is not already in the wanted state. */
@@ -173,19 +210,23 @@ const updateIssue = async (
   id: string,
   patch: WorkItemPatch,
 ): Promise<TrackerResult<WorkItem>> => {
-  const current = await view(gh, id);
-  if (!current.ok) return current;
+  const problem = unusable({ title: patch.title ?? "x", labels: patch.labels ?? [] });
+  if (problem !== undefined) return trackerError(problem);
+  const raw = await viewRaw(gh, id);
+  if (!raw.ok) return raw;
+  const current = toItem(raw.value);
+  const hadMarker = (raw.value.labels ?? []).some((l) => l.name === IN_PROGRESS);
   if (patch.status === "in-progress") {
     // No --force: that would recolour the team's existing label. "Already exists" is success.
     const made = await gh(["label", "create", IN_PROGRESS]);
     if (!(made.ok || /already exists/i.test(made.error.message))) return made;
   }
-  const flags = editFlags(current.value, patch);
+  const flags = editFlags(current, hadMarker, patch);
   if (flags.length > 0) {
     const edited = await gh(["issue", "edit", id, ...flags]);
     if (!edited.ok) return edited;
   }
-  const command = stateCommand(current.value, patch.status);
+  const command = stateCommand(current, patch.status);
   if (command !== undefined) {
     const changed = await gh(["issue", command, id]);
     if (!changed.ok) return changed;

package/src/tracker/item-format.ts

@@ -32,17 +32,13 @@ export const unwritable = (item: Pick<WorkItem, "title" | "labels">): string | u
     : `label ${JSON.stringify(bad)} is blank or holds a comma or line break`;
 };
 
+/** Written to pass our own markdownlint: no trailing space, no repeated heading text, no stacked blank lines. */
 export const renderItem = (item: WorkItem): string => {
-  const comments = item.comments.map((c) => `\n### Comment\n\n${quote(c)}\n`).join("");
-  return [
-    `# ${item.title}`,
-    "",
-    `Status: ${item.status}`,
-    `Labels: ${item.labels.join(", ")}`,
-    "",
-    item.body,
-    COMMENTS + comments,
-  ].join("\n");
+  const labels = item.labels.length === 0 ? "" : ` ${item.labels.join(", ")}`;
+  const top = `# ${item.title}\n\nStatus: ${item.status}\nLabels:${labels}`;
+  const body = item.body === "" ? [] : [item.body];
+  const comments = item.comments.map((c, n) => `\n### Comment ${n + 1}\n\n${quote(c)}\n`);
+  return `${[top, ...body, "## Comments"].join("\n\n")}\n${comments.join("")}`;
 };
 
 const isStatus = (value: string): value is WorkStatus =>
@@ -50,15 +46,16 @@ const isStatus = (value: string): value is WorkStatus =>
 
 const commentsOf = (section: string): string[] =>
   section
-    .split(/^### Comment\n\n/m)
+    .split(/^### Comment(?: \d+)?\n\n/m)
     .slice(1)
     .map((c) => unquote(c.replace(/\n+$/, "")));
 
-export const parseItem = (id: string, text: string): TrackerResult<WorkItem> => {
+export const parseItem = (id: string, raw: string): TrackerResult<WorkItem> => {
+  const text = raw.replace(/\r\n?/g, "\n");
   const marker = text.lastIndexOf(COMMENTS);
   const main = marker < 0 ? text : text.slice(0, marker);
   const comments = marker < 0 ? [] : commentsOf(text.slice(marker + COMMENTS.length));
-  const head = /^# (.+)\n\nStatus: (.*)\nLabels: (.*)\n\n?/.exec(main);
+  const head = /^# (.+)\n\nStatus: (.*)\nLabels:[ ]?(.*)(?:\n\n|\n$|$)/.exec(main);
   if (head === null)
     return trackerError(`work item ${id}: expected "# title", Status and Labels lines`);
   const [whole, title = "", status = "", labels = ""] = head;