@mgiles/perk 2.1.0 → 2.3.0

package/extension/substrate/unifiedDiff.ts

@@ -0,0 +1,224 @@
+// A deliberately strict unified-diff applier for the plannotator "Direct Edits" feedback only
+// (`extension/adapters/planAdapterPlannotator.ts` extracts the ```diff fence; the plan arm of
+// `plan_review` applies it to the exact draft bytes it submitted) — this is NOT a general-purpose
+// patch tool.
+//
+// Why this exists: the extension must stay zero-runtime-dependency (the bare-clone invariant —
+// see `miniYaml.ts` / `miniJinja.ts`, the two prior vendored-engine precedents), so it cannot
+// import jsdiff at runtime. This module covers exactly the unified-diff subset jsdiff's
+// `createTwoFilesPatch(..., { context: 3 })` emits — the generator plannotator uses — pinned by
+// generator-parity tests in `unifiedDiff.test.ts` (jsdiff is a dev-only dependency there).
+//
+// Why it is STRICT (null on ANY anomaly, never throw, never fuzz): the consumer sits on a
+// fail-open ladder — a `null` merely falls back to today's behavior (the reviewed bytes are
+// saved verbatim and the diff stays in the feedback as guidance). A lenient/fuzzy apply could
+// silently save bytes the reviewer never approved, which is worse than declining to apply.
+//
+// One deliberate leniency, matching the generator: plannotator embeds `patch.trimEnd()` in the
+// fence, so trailing WHITESPACE-ONLY context lines of the final hunk may have been trimmed away.
+// The applier reconstructs them from the base (they are context — their bytes ARE the base's)
+// and still verifies each reconstructed line is whitespace-only (anything else is a genuine
+// truncation → null).
+
+/** A parsed `@@ -a[,b] +c[,d] @@` hunk header (counts default to 1 when omitted). */
+interface HunkHeader {
+  oldStart: number;
+  oldLines: number;
+  newLines: number;
+}
+
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+const NO_NEWLINE_MARKER = "\";
+
+/** One side's line entry: the text plus whether the file ends WITHOUT a newline at this line. */
+interface SideLine {
+  text: string;
+  noNewline: boolean;
+}
+
+/** A fully parsed hunk: the header plus the old/new side projections of its body. */
+interface Hunk {
+  header: HunkHeader;
+  oldSide: SideLine[];
+  newSide: SideLine[];
+}
+
+/**
+ * Split `text` into terminator-free lines plus the trailing-newline flag. An empty string is
+ * ZERO lines (not one empty line); `"\n"` is one empty line.
+ */
+function splitLines(text: string): { lines: string[]; endsWithNewline: boolean } {
+  if (text === "") return { lines: [], endsWithNewline: false };
+  const endsWithNewline = text.endsWith("\n");
+  const lines = text.split("\n");
+  if (endsWithNewline) lines.pop();
+  return { lines, endsWithNewline };
+}
+
+/** True for the optional pre-hunk header lines jsdiff's `formatPatch` emits (labels ignored). */
+function isFileHeaderLine(line: string): boolean {
+  return (
+    line.startsWith("Index: ") ||
+    line.startsWith("===") ||
+    line.startsWith("--- ") ||
+    line.startsWith("+++ ")
+  );
+}
+
+/**
+ * Attach a `` marker to the side(s) the preceding body line belongs
+ * to (context → both). False when there is no line to attach to (a leading or doubled marker).
+ */
+function attachNoNewline(
+  lastPrefix: " " | "-" | "+" | null,
+  oldSide: SideLine[],
+  newSide: SideLine[],
+): boolean {
+  if (lastPrefix === null) return false;
+  const flag = (side: SideLine[]): boolean => {
+    const last = side[side.length - 1];
+    if (last === undefined) return false;
+    last.noNewline = true;
+    return true;
+  };
+  if (lastPrefix === " ") return flag(oldSide) && flag(newSide);
+  if (lastPrefix === "-") return flag(oldSide);
+  return flag(newSide);
+}
+
+/**
+ * Parse the diff text into hunks, or null on any anomaly (malformed hunk header, unknown body
+ * prefix, a `\` marker with nothing to attach to, an over-long hunk body, an asymmetric or
+ * mid-diff shortfall, zero hunks, trailing garbage). The body is projected into old-side /
+ * new-side line lists as it parses: ` ` feeds both sides, `-` the old, `+` the new.
+ */
+function parseHunks(diff: string): Hunk[] | null {
+  const { lines } = splitLines(diff.endsWith("\n") ? diff : `${diff}\n`);
+  const hunks: Hunk[] = [];
+  let i = 0;
+  // Optional file-header preamble (Index: / === / --- / +++), before the first hunk only.
+  while (i < lines.length && isFileHeaderLine(lines[i] ?? "")) i++;
+  while (i < lines.length) {
+    const m = HUNK_HEADER.exec(lines[i] ?? "");
+    if (m === null) return null; // trailing garbage / malformed hunk header
+    const header: HunkHeader = {
+      oldStart: Number(m[1]),
+      oldLines: m[2] === undefined ? 1 : Number(m[2]),
+      newLines: m[4] === undefined ? 1 : Number(m[4]),
+    };
+    i++;
+    const oldSide: SideLine[] = [];
+    const newSide: SideLine[] = [];
+    let lastPrefix: " " | "-" | "+" | null = null;
+    while (
+      i < lines.length &&
+      (oldSide.length < header.oldLines ||
+        newSide.length < header.newLines ||
+        lines[i] === NO_NEWLINE_MARKER)
+    ) {
+      const line = lines[i] ?? "";
+      if (line === NO_NEWLINE_MARKER) {
+        if (!attachNoNewline(lastPrefix, oldSide, newSide)) return null;
+        lastPrefix = null; // a doubled marker is malformed
+        i++;
+        continue;
+      }
+      if (HUNK_HEADER.test(line)) break; // a new hunk began before this one's counts filled
+      const prefix = line[0];
+      const text = line.slice(1);
+      if (prefix === " ") {
+        oldSide.push({ text, noNewline: false });
+        newSide.push({ text, noNewline: false });
+        lastPrefix = " ";
+      } else if (prefix === "-") {
+        oldSide.push({ text, noNewline: false });
+        lastPrefix = "-";
+      } else if (prefix === "+") {
+        newSide.push({ text, noNewline: false });
+        lastPrefix = "+";
+      } else {
+        return null; // unknown body prefix (an empty line included — jsdiff never emits one)
+      }
+      i++;
+    }
+    // Over-long sides cannot happen (the loop stops on filled counts); short sides are tolerated
+    // ONLY as the generator's `trimEnd()` artifact — an equal shortfall on both sides, at the
+    // very end of the diff — and the applier reconstructs the missing context from the base.
+    const oldShort = header.oldLines - oldSide.length;
+    const newShort = header.newLines - newSide.length;
+    if (oldShort !== newShort || oldShort < 0) return null;
+    if (oldShort > 0 && i < lines.length) return null; // short mid-diff is a truncation
+    hunks.push({ header, oldSide, newSide });
+  }
+  if (hunks.length === 0) return null;
+  return hunks;
+}
+
+/**
+ * Apply a unified diff (the jsdiff `createTwoFilesPatch` subset — see the module header) to
+ * `base`, strictly and cleanly. Returns the patched text, or null on ANY anomaly: a context or
+ * `-` line that does not byte-match the base at the hunk's stated old-file offsets, malformed
+ * hunk headers, unknown prefixes, zero hunks, out-of-order/overlapping hunks, trailing garbage,
+ * or a no-newline marker that contradicts the base. Never throws.
+ */
+export function applyUnifiedDiff(base: string, diff: string): string | null {
+  const hunks = parseHunks(diff);
+  if (hunks === null) return null;
+
+  const { lines: baseLines, endsWithNewline: baseEndsWithNewline } = splitLines(base);
+  const output: string[] = [];
+  // Whether the CURRENT final output line ends without a newline. Every emission checks it:
+  // nothing may follow a no-newline line, so a mid-diff `\` marker on the new side (or a
+  // no-newline base tail followed by anything) fails strictly instead of mis-joining.
+  let resultNoNewline = false;
+  const emit = (text: string, noNewline: boolean): boolean => {
+    if (resultNoNewline) return false;
+    output.push(text);
+    resultNoNewline = noNewline;
+    return true;
+  };
+  /** Whether `index` is the base's final line and the base ends without a newline. */
+  const baseNoNewlineAt = (index: number): boolean =>
+    index === baseLines.length - 1 && !baseEndsWithNewline;
+
+  let cursor = 0; // 0-based index of the next unconsumed base line
+  for (const { header, oldSide, newSide } of hunks) {
+    // The 0-based old-file start. Unified-diff quirk: a zero-length old range states the line
+    // BEFORE the insertion point (0 = insert at the very start), i.e. already the 0-based index.
+    const start = header.oldLines === 0 ? header.oldStart : header.oldStart - 1;
+    if (start < cursor || start > baseLines.length) return null; // out-of-order / out-of-range
+    // Copy the untouched span before this hunk (all mid-file lines — always newline-terminated).
+    for (let i = cursor; i < start; i++) {
+      if (!emit(baseLines[i] as string, false)) return null;
+    }
+    cursor = start;
+    // Match the old side against the base at the stated offsets; the new side splices in.
+    for (const entry of oldSide) {
+      const line = baseLines[cursor];
+      if (line === undefined || line !== entry.text) return null;
+      if (entry.noNewline !== baseNoNewlineAt(cursor)) return null;
+      cursor++;
+    }
+    for (const entry of newSide) {
+      if (!emit(entry.text, entry.noNewline)) return null;
+    }
+    // Reconstruct trailing context the generator's trimEnd() ate (see parseHunks): consume the
+    // next shortfall base lines, verifying each is a whitespace-only, newline-terminated line
+    // (a non-whitespace or final-no-newline line could never have been trimmed → truncation).
+    const shortfall = header.oldLines - oldSide.length;
+    for (let i = 0; i < shortfall; i++) {
+      const line = baseLines[cursor];
+      if (line === undefined || line.trim() !== "" || baseNoNewlineAt(cursor)) return null;
+      if (!emit(line, false)) return null;
+      cursor++;
+    }
+  }
+
+  // Copy the untouched tail; its final line inherits the base's trailing-newline behavior.
+  for (let i = cursor; i < baseLines.length; i++) {
+    if (!emit(baseLines[i] as string, baseNoNewlineAt(i))) return null;
+  }
+
+  if (output.length === 0) return "";
+  return output.join("\n") + (resultNoNewline ? "" : "\n");
+}

package/extension/waves/learnWave.ts

@@ -0,0 +1,155 @@
+// The `/learn` flow's per-flow wave entrypoint over the shared report-wave runner: the analyst
+// fan-out as CODE. It owns the four learn angles, the analyst report schema, the tool-enforced
+// angle policy (2–4 angles, `session-deviations` mandatory), and the lane/task composition —
+// delegating spawn/timeout/aggregate mechanics to `runReportWave` under the `best-effort`
+// completeness policy (a failed analyst is an explicitly-reported skipped angle, never a failed
+// pass). Analyst reports come back as engine-validated structured output (the workflow-level
+// `outputSchema` → the injected `structured_output` tool), replacing fenced-JSON scraping.
+
+import { runReportWave, type WaveAdapter, type WaveLane, type WaveResult } from "./reportWave.ts";
+
+/** The four learn angles; `session-deviations` is the mandatory member of every selection. */
+export const LEARN_ANGLES = [
+  "session-deviations",
+  "plan-vs-implementation",
+  "existing-docs",
+  "validation-risk",
+] as const;
+
+const MANDATORY_ANGLE = "session-deviations";
+
+/**
+ * The per-lane analyst report schema (the workflow-level `outputSchema`): closed shape,
+ * all-required, enums, `target` required-nullable ({angle, verdict, candidates, fyi} — the same
+ * field semantics as the agent def's report contract). DELIBERATE DIVERGENCE from
+ * `PR_REVIEW_REPORT_SCHEMA`: no if/then verdict↔candidates conditional. Under `best-effort`
+ * completeness, salvaging an internally inconsistent report beats failing its lane — the parent
+ * derives the real verdict from `candidates[]` (`verdict` is derived data), so an inconsistent
+ * verdict costs nothing while a failed lane loses the whole angle.
+ */
+export const LEARN_ANALYST_REPORT_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["angle", "verdict", "candidates", "fyi"],
+  properties: {
+    angle: {
+      type: "string",
+      enum: [...LEARN_ANGLES],
+    },
+    verdict: {
+      type: "string",
+      enum: ["clean", "actionable"],
+    },
+    candidates: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["decision", "summary", "target", "evidence"],
+        properties: {
+          decision: {
+            type: "string",
+            enum: [
+              "CAPTURE_LEARN",
+              "SHOULD_BE_CODE",
+              "UPDATE_EXISTING_DOC",
+              "NEW_DOC",
+              "STALE_DOC",
+              "SKIP",
+            ],
+          },
+          summary: { type: "string" },
+          target: { type: ["string", "null"] },
+          evidence: { type: "string" },
+        },
+      },
+    },
+    fyi: {
+      type: "array",
+      items: { type: "string" },
+    },
+  },
+};
+
+/** One chosen angle + the parent's optional plan-specific emphasis for its task text. */
+export interface LearnAngleSelection {
+  angle: string;
+  emphasis?: string;
+}
+
+/**
+ * The angle policy as one pure function (tested implementation, not guidance): 2–4 angles, no
+ * duplicates, only the four known slugs, and `session-deviations` always included. Returns the
+ * human-readable rule violation, or null when the selection is valid.
+ */
+export function angleSelectionError(selections: LearnAngleSelection[]): string | null {
+  if (selections.length < 2 || selections.length > 4) {
+    return `choose 2–4 angles (got ${selections.length})`;
+  }
+  const seen = new Set<string>();
+  for (const { angle } of selections) {
+    if (!(LEARN_ANGLES as readonly string[]).includes(angle)) {
+      return `unknown angle '${angle}' — the valid angles are ${LEARN_ANGLES.join(", ")}`;
+    }
+    if (seen.has(angle)) {
+      return `duplicate angle '${angle}' — each angle at most once`;
+    }
+    seen.add(angle);
+  }
+  if (!seen.has(MANDATORY_ANGLE)) {
+    return `the '${MANDATORY_ANGLE}' angle is mandatory — always include it`;
+  }
+  return null;
+}
+
+/**
+ * Compose one lane's task text IN CODE (the prompt-drift-proof half of the migration): the
+ * assigned angle, the absolute manifest path (read first), the bundle dir, and the parent's
+ * optional emphasis appended verbatim. Deliberately short — the angle rubric lives in the agent
+ * def, not the task.
+ */
+function laneTask(selection: LearnAngleSelection, manifestPath: string, bundleDir: string): string {
+  const base =
+    `angle: ${selection.angle} — analyze ONLY this angle. ` +
+    `Read the evidence-bundle manifest FIRST: ${manifestPath} (bundle dir: ${bundleDir}). ` +
+    "Do not re-gather the bundle.";
+  const emphasis = selection.emphasis?.trim();
+  return emphasis !== undefined && emphasis !== "" ? `${base} Emphasis: ${emphasis}` : base;
+}
+
+/**
+ * Run the learn analyst wave: one `perk.learn-analyst` lane per selected angle over the shared
+ * evidence bundle, `best-effort` completeness (lane failure = a skipped angle; only a wave-level
+ * failure makes the result incomplete). Assumes a validated selection — the `run_learn_wave` tool
+ * runs `angleSelectionError` first; `renderWaveScript`'s programmer-error throws (empty/duplicate
+ * keys) remain the backstop.
+ */
+export async function runLearnWave(
+  adapter: WaveAdapter,
+  opts: {
+    selections: LearnAngleSelection[];
+    manifestPath: string;
+    bundleDir: string;
+    model?: string;
+  },
+  signal?: AbortSignal,
+): Promise<WaveResult> {
+  const lanes: WaveLane[] = opts.selections.map((selection) => ({
+    key: selection.angle,
+    label: selection.angle,
+    agent: "perk.learn-analyst",
+    phase: "learn",
+    task: laneTask(selection, opts.manifestPath, opts.bundleDir),
+  }));
+  return await runReportWave(
+    adapter,
+    {
+      flow: "learn",
+      lanes,
+      outputSchema: LEARN_ANALYST_REPORT_SCHEMA,
+      completeness: "best-effort",
+      ...(opts.model !== undefined ? { model: opts.model } : {}),
+    },
+    signal,
+  );
+}

package/extension/waves/memoryAdapter.ts

@@ -0,0 +1,126 @@
+// The in-memory `WaveAdapter` test double — a FIRST-CLASS deliverable: the runner's own tests
+// and the future flow tests drive the whole wave lifecycle through it with no event bus, no
+// child processes, and no temp dirs. Every failure arm of `runReportWave` is reachable through
+// a config knob, and the recorded calls let tests assert the spawn contract (`mission: false`,
+// `context: "fresh"`, the rendered script) and the stop-on-timeout/cancel behavior.
+//
+// It honors the same sequencing contract as the production adapter: `onComplete()` before a
+// successful `ping()` throws (the async-complete channel is advertised by ping, not pinned).
+
+import type {
+  WaveAdapter,
+  WaveCompletion,
+  WavePing,
+  WaveRunHandle,
+  WaveSpawnParams,
+} from "./reportWave.ts";
+
+export interface MemoryWaveAdapterConfig {
+  /** The ping outcome; null exercises the unavailable arm. Defaults to a valid ping. */
+  ping?: WavePing | null;
+  /** When set, spawn throws this message (the spawn-failed arm). */
+  spawnError?: string;
+  /**
+   * Delivery ordering of the auto-completion relative to the spawn reply. The default delivers
+   * after the reply settles; `complete-then-reply` delivers synchronously inside spawn — the
+   * real completion-before-reply race the runner must buffer through.
+   */
+  ordering?: "reply-then-complete" | "complete-then-reply";
+  /** `false` ⇒ the run never completes (tests pair this with a tiny `spec.timeoutMs`). */
+  completion?: false;
+  /** What `readAggregate` returns. Defaults to a complete run with an empty aggregate. */
+  aggregate?: { state: string; error?: string; value: unknown };
+  /**
+   * Per-spawn aggregate FIFO for multi-wave tests (e.g. the pr-review retry): each spawn assigns
+   * the next queued aggregate to its handle (keyed by `asyncDir`), and `readAggregate(handle)`
+   * returns the handle's assigned aggregate. When the queue is exhausted (or absent), reads fall
+   * back to the single `aggregate`/`setAggregate` staging — the knob is purely additive.
+   */
+  aggregates?: { state: string; error?: string; value: unknown }[];
+  /** When true, `readAggregate` throws (the aggregate-unreadable arm). */
+  aggregateError?: boolean;
+}
+
+export interface MemoryWaveAdapter extends WaveAdapter {
+  calls: { spawn: WaveSpawnParams[]; stop: WaveRunHandle[] };
+  /** Deliver a completion to the subscribed handlers (contract-suite plumbing). */
+  emitCompletion(completion: WaveCompletion): void;
+  /** Replace the staged aggregate (contract-suite plumbing). */
+  setAggregate(aggregate: { state: string; error?: string; value: unknown }): void;
+}
+
+export function createMemoryWaveAdapter(config: MemoryWaveAdapterConfig = {}): MemoryWaveAdapter {
+  const ping =
+    config.ping === undefined ? { asyncCompleteEvent: "subagent:async-complete" } : config.ping;
+  let aggregate = config.aggregate ?? { state: "complete", value: [] as unknown[] };
+  const aggregateQueue = [...(config.aggregates ?? [])];
+  const assignedAggregates = new Map<string, { state: string; error?: string; value: unknown }>();
+  let pinged = false;
+  let spawnCount = 0;
+  const handlers = new Set<(completion: WaveCompletion) => void>();
+  const calls: MemoryWaveAdapter["calls"] = { spawn: [], stop: [] };
+
+  const deliver = (completion: WaveCompletion): void => {
+    for (const handler of handlers) handler(completion);
+  };
+
+  return {
+    calls,
+    emitCompletion: deliver,
+    setAggregate(next): void {
+      aggregate = next;
+    },
+
+    async ping(): Promise<WavePing | null> {
+      if (ping !== null) pinged = true;
+      return ping;
+    },
+
+    async spawn(params: WaveSpawnParams): Promise<WaveRunHandle> {
+      calls.spawn.push(params);
+      if (config.spawnError !== undefined) throw new Error(config.spawnError);
+      spawnCount += 1;
+      const handle = {
+        asyncId: `wave-async-${spawnCount}`,
+        asyncDir: `/memory/wave-async-${spawnCount}`,
+      };
+      const queued = aggregateQueue.shift();
+      if (queued !== undefined) assignedAggregates.set(handle.asyncDir, queued);
+      if (config.completion !== false) {
+        const completion = { asyncId: handle.asyncId, asyncDir: handle.asyncDir };
+        if (config.ordering === "complete-then-reply") {
+          // Deliver BEFORE the spawn promise resolves — the buffered-completion race.
+          deliver(completion);
+        } else {
+          // Deliver strictly after the caller's `await spawn(...)` continuation has run
+          // (a macrotask — a microtask would still beat the awaiting continuation).
+          setTimeout(() => deliver(completion), 0);
+        }
+      }
+      return handle;
+    },
+
+    onComplete(handler: (completion: WaveCompletion) => void): () => void {
+      if (!pinged) {
+        throw new Error(
+          "onComplete requires a successful ping first (the async-complete channel is advertised, not pinned)",
+        );
+      }
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+
+    async stop(handle: WaveRunHandle): Promise<void> {
+      calls.stop.push(handle);
+    },
+
+    async readAggregate(
+      handle: WaveRunHandle,
+    ): Promise<{ state: string; error?: string; value: unknown }> {
+      if (config.aggregateError === true) {
+        throw new Error("simulated unreadable status.json");
+      }
+      return assignedAggregates.get(handle.asyncDir) ?? aggregate;
+    },
+  };
+}