@jwilger/pi-development-system 0.59.0 → 0.61.0

package/package.json

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

package/src/planning/task-record.ts

@@ -38,6 +38,39 @@ const PLACEHOLDER =
 
 const isSection = (name: string): name is Section => SECTIONS.some((s) => s === name);
 
+const FENCE_LINE = /^\s*(`{3,}|~{3,})(.*)$/;
+const HEADING = /^#{1,6}\s/;
+
+/** Opening fence: its character and length. Backtick fences cannot carry backticks in the info string. */
+const opening = (line: string): { char: string; length: number } | undefined => {
+  const m = FENCE_LINE.exec(line);
+  const run = m?.[1];
+  if (run === undefined || (run.startsWith("`") && (m?.[2] ?? "").includes("`"))) return undefined;
+  return { char: run.slice(0, 1), length: run.length };
+};
+
+/** A closing fence repeats the opening character at least as many times and carries no text. */
+const closes = (line: string, open: { char: string; length: number }): boolean => {
+  const m = FENCE_LINE.exec(line);
+  const run = m?.[1];
+  return (
+    run?.startsWith(open.char) === true && run.length >= open.length && (m?.[2] ?? "").trim() === ""
+  );
+};
+
+/** For each line, whether it sits inside (or on the edge of) a fenced code block, as CommonMark reads fences. */
+const fencedFlags = (lines: readonly string[]): boolean[] => {
+  let open: { char: string; length: number } | undefined;
+  return lines.map((line) => {
+    if (open === undefined) {
+      open = opening(line);
+      return open !== undefined;
+    }
+    if (closes(line, open)) open = undefined;
+    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. */
@@ -45,8 +78,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);
@@ -60,12 +94,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
@@ -77,13 +112,26 @@ 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");
+  const fence = opening(lines[0] ?? "");
+  if (fence !== undefined) {
+    const body = lines.slice(1);
+    if (closes(body.at(-1) ?? "", fence)) 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);
@@ -130,10 +178,13 @@ function locate(markdown: string, id: string | undefined): Located | ParseError
   const records = recordsIn(markdown.split("\n"));
   const names = records.map((r) => r.id).join(", ");
   if (id !== undefined) {
-    return (
-      records.find((r) => r.id === id) ??
-      parseError(`no task record "${id}" (found: ${names || "none"})`)
-    );
+    const named = records.filter((r) => r.id === id);
+    const [first] = named;
+    if (first === undefined)
+      return parseError(`no task record "${id}" (found: ${names || "none"})`);
+    return named.length === 1
+      ? first
+      : parseError(`task record "${id}" appears ${named.length} times; ids must be unique`);
   }
   const [only, ...rest] = records;
   if (only === undefined) return parseError(NO_HEADER);

package/src/tracker/github.ts

@@ -1,6 +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.some(isMarker)
+    ? '"in-progress" is reserved for the in-progress status; set status instead'
+    : unwritable(item);
+
 import {
   type ItemFilter,
   type NewWorkItem,
@@ -14,6 +21,8 @@ import {
 
 const FIELDS = "number,title,body,state,labels,comments";
 const IN_PROGRESS = "in-progress";
+/** GitHub label names are case-insensitive, so `In-Progress` is our marker too. */
+const isMarker = (name: string): boolean => name.toLowerCase() === IN_PROGRESS;
 const ISSUE_NUMBER = /^[1-9][0-9]*$/;
 const STATE_ARG = { open: "open", "in-progress": "open", done: "closed" } as const;
 
@@ -38,7 +47,7 @@ const isIssue = (value: unknown): value is GhIssue =>
 
 const statusOf = (state: string, labels: readonly string[]): WorkStatus => {
   if (state === "CLOSED") return "done";
-  return labels.includes(IN_PROGRESS) ? "in-progress" : "open";
+  return labels.some(isMarker) ? "in-progress" : "open";
 };
 
 const toItem = (issue: GhIssue): WorkItem => {
@@ -48,7 +57,7 @@ const toItem = (issue: GhIssue): WorkItem => {
     title: issue.title,
     body: issue.body ?? "",
     status: statusOf(issue.state, names),
-    labels: names.filter((n) => n !== IN_PROGRESS),
+    labels: names.filter((n) => !isMarker(n)),
     comments: (issue.comments ?? []).map((c) => c.body),
   };
 };
@@ -108,7 +117,7 @@ const view = async (gh: Gh, id: string): Promise<TrackerResult<WorkItem>> => {
   return raw.ok ? ok(toItem(raw.value)) : raw;
 };
 
-const LIST_LIMIT = 500;
+const LIST_LIMIT = 1000;
 
 /** 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[] => {
@@ -132,9 +141,14 @@ const listIssues = async (gh: Gh, filter: ItemFilter): Promise<TrackerResult<Wor
   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) {
+  // gh lists newest first. Cutting off old closed issues is harmless; cutting off open work is not.
+  if (parsed.length >= LIST_LIMIT && filter.status !== "done") {
+    const advice =
+      filter.status === undefined
+        ? "; ask for one status to narrow it"
+        : "; this adapter lists at most that many";
     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`,
+      `gh issue list returned ${LIST_LIMIT} issues, so the list may be cut short${advice}`,
     );
   }
   const items = parsed.map(toItem);
@@ -142,7 +156,7 @@ const listIssues = async (gh: Gh, filter: ItemFilter): Promise<TrackerResult<Wor
 };
 
 const createIssue = async (gh: Gh, input: NewWorkItem): Promise<TrackerResult<WorkItem>> => {
-  const problem = unwritable({ title: input.title, labels: input.labels ?? [] });
+  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([
@@ -203,12 +217,12 @@ const updateIssue = async (
   id: string,
   patch: WorkItemPatch,
 ): Promise<TrackerResult<WorkItem>> => {
-  const problem = unwritable({ title: patch.title ?? "x", labels: patch.labels ?? [] });
+  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);
+  const hadMarker = (raw.value.labels ?? []).some((l) => isMarker(l.name));
   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]);

package/src/tracker/item-format.ts

@@ -7,6 +7,9 @@ import {
   type WorkStatus,
 } from "./types.ts";
 
+/** Every line terminator `.` in the item header pattern cannot cross, plus NEL for safety. */
+const LINE_BREAK = /[\r\n\u2028\u2029\u0085]/;
+
 const COMMENTS = "\n## Comments\n";
 
 /** Comment lines are quoted so nothing a comment says can look like one of our headings. */
@@ -24,25 +27,21 @@ const unquote = (text: string): string =>
 
 /** What the file format cannot hold, or undefined when the item can be written and read back. */
 export const unwritable = (item: Pick<WorkItem, "title" | "labels">): string | undefined => {
-  if (/[\r\n]/.test(item.title)) return "a work item title must be a single line";
+  if (LINE_BREAK.test(item.title)) return "a work item title must be a single line";
   if (item.title.trim() === "") return "a work item title cannot be blank";
-  const bad = item.labels.find((l) => /[\r\n,]/.test(l) || l.trim() === "");
+  const bad = item.labels.find((l) => LINE_BREAK.test(l) || l.includes(",") || l.trim() === "");
   return bad === undefined
     ? undefined
     : `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,7 +49,7 @@ 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+$/, "")));
 
@@ -59,7 +58,7 @@ export const parseItem = (id: string, raw: string): TrackerResult<WorkItem> => {
   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;

package/src/tracker/work-item-tool.ts

@@ -24,7 +24,8 @@ const Parameters = Type.Object({
   ),
   status: Type.Optional(
     Type.Union([Type.Literal("open"), Type.Literal("in-progress"), Type.Literal("done")], {
-      description: "Status (update), or a filter (list).",
+      description:
+        "Status (update), or a filter (list). On GitHub, listing done shows the newest 1000 closed issues.",
     }),
   ),
   labels: Type.Optional(Type.Array(Type.String(), { description: "Labels (create, update)." })),