pi-pair-programmer 0.1.0

package/src/review-store.ts

@@ -0,0 +1,268 @@
+import { z } from "zod";
+
+const FindingSchema = z.object({
+  id: z.string(),
+  duplicateKey: z.string().optional(),
+  reviewer: z.string(),
+  file: z.string(),
+  revision: z.string(),
+  line: z.number(),
+  title: z.string(),
+  evidence: z.string(),
+});
+
+const VerdictSchema = z.enum(["accept", "reject"]);
+const EventSchema = z.discriminatedUnion("action", [
+  z.object({ action: z.literal("add"), finding: FindingSchema }),
+  z.object({ action: z.literal("deliver"), ids: z.array(z.string()) }),
+  z.object({
+    action: z.literal("decide"),
+    id: z.string(),
+    verdict: VerdictSchema,
+    reason: z.string().refine((reason) => reason.trim().length > 0),
+  }),
+  z.object({ action: z.literal("discard"), ids: z.array(z.string()) }),
+  z.object({ action: z.literal("enabled"), enabled: z.boolean() }),
+  z.object({ action: z.literal("clear") }),
+]);
+const EntrySchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("custom"),
+    customType: z.literal("pair-programmer"),
+    data: EventSchema,
+  }),
+  z.object({ type: z.literal("reset_boundary") }),
+]);
+
+export type Finding = z.infer<typeof FindingSchema>;
+export type Verdict = z.infer<typeof VerdictSchema>;
+type Event = z.infer<typeof EventSchema>;
+
+export interface StoredFinding {
+  finding: Finding;
+  verdict?: Verdict;
+  reason?: string;
+}
+
+interface FindingState extends StoredFinding {
+  delivered: boolean;
+  discarded: boolean;
+}
+
+export class ReviewStore {
+  private readonly findings = new Map<string, FindingState>();
+  private readonly append: (data: unknown) => void;
+  private active = true;
+
+  constructor(
+    append: (data: unknown) => void,
+    branchEntries: readonly unknown[] = [],
+  ) {
+    this.append = append;
+    for (const entry of branchEntries) {
+      const parsed = EntrySchema.safeParse(entry);
+      if (!parsed.success) continue;
+      if (parsed.data.type === "reset_boundary") this.findings.clear();
+      else this.apply(parsed.data.data);
+    }
+  }
+
+  get enabled(): boolean {
+    return this.active;
+  }
+
+  summary(): {
+    pending: number;
+    outstanding: number;
+    accepted: number;
+    rejected: number;
+    discarded: number;
+  } {
+    const counts = {
+      pending: 0,
+      outstanding: 0,
+      accepted: 0,
+      rejected: 0,
+      discarded: 0,
+    };
+    for (const state of this.findings.values()) {
+      if (state.verdict === "accept") counts.accepted += 1;
+      else if (state.verdict === "reject") counts.rejected += 1;
+      else if (state.discarded) counts.discarded += 1;
+      else if (state.delivered) counts.outstanding += 1;
+      else counts.pending += 1;
+    }
+    return counts;
+  }
+
+  clear(): void {
+    this.record({ action: "clear" });
+  }
+
+  setEnabled(enabled: boolean): void {
+    if (this.active === enabled) return;
+    if (!enabled) {
+      const ids: string[] = [];
+      for (const state of this.findings.values()) {
+        if (!state.delivered && !state.discarded) ids.push(state.finding.id);
+      }
+      if (ids.length > 0) this.record({ action: "discard", ids });
+    }
+    this.record({ action: "enabled", enabled });
+  }
+
+  history(file: string): readonly StoredFinding[] {
+    const result: StoredFinding[] = [];
+    for (const state of this.findings.values()) {
+      if (state.finding.file !== file) continue;
+      result.push({
+        finding: { ...state.finding },
+        ...(state.verdict === undefined ? {} : { verdict: state.verdict }),
+        ...(state.reason === undefined ? {} : { reason: state.reason }),
+      });
+    }
+    return result;
+  }
+
+  add(finding: Finding): boolean {
+    if (!this.active || this.findings.has(finding.id)) return false;
+    this.record({ action: "add", finding: { ...finding } });
+    return true;
+  }
+
+  ready(): readonly Finding[] {
+    if (!this.active) return [];
+    const result: Finding[] = [];
+    for (const state of this.findings.values()) {
+      if (!state.delivered && !state.discarded)
+        result.push({ ...state.finding });
+    }
+    return result;
+  }
+
+  deliver(ids: readonly string[]): void {
+    const eligible = [...new Set(ids)].filter((id) => {
+      const state = this.findings.get(id);
+      return (
+        this.active &&
+        state !== undefined &&
+        !state.delivered &&
+        !state.discarded
+      );
+    });
+    if (eligible.length > 0) this.record({ action: "deliver", ids: eligible });
+  }
+
+  outstanding(): readonly Finding[] {
+    const result: Finding[] = [];
+    for (const state of this.findings.values()) {
+      if (state.delivered && state.verdict === undefined) {
+        result.push({ ...state.finding });
+      }
+    }
+    return result;
+  }
+
+  deliveredFinding(id: string): Finding | undefined {
+    const state = this.findings.get(id);
+    return state?.delivered === true && state.verdict === undefined
+      ? { ...state.finding }
+      : undefined;
+  }
+
+  decide(id: string, verdict: Verdict, reason: string): boolean {
+    const state = this.findings.get(id);
+    if (
+      state?.delivered !== true ||
+      state.verdict !== undefined ||
+      reason.trim().length === 0
+    ) {
+      return false;
+    }
+    this.record({ action: "decide", id, verdict, reason });
+    return true;
+  }
+
+  discardStale(file: string, currentRevision: string): void {
+    const ids: string[] = [];
+    for (const state of this.findings.values()) {
+      if (
+        state.finding.file === file &&
+        state.finding.revision !== currentRevision &&
+        !state.delivered &&
+        !state.discarded
+      ) {
+        ids.push(state.finding.id);
+      }
+    }
+    if (ids.length > 0) this.record({ action: "discard", ids });
+  }
+
+  private record(event: Event): void {
+    this.append(event);
+    this.apply(event);
+  }
+
+  private apply(event: Event): void {
+    switch (event.action) {
+      case "add":
+        this.applyAdd(event.finding);
+        break;
+      case "deliver":
+        this.applyDelivery(event.ids);
+        break;
+      case "decide":
+        this.applyDecision(event.id, event.verdict, event.reason);
+        break;
+      case "discard":
+        this.applyDiscard(event.ids);
+        break;
+      case "enabled":
+        this.applyEnabled(event.enabled);
+        break;
+      case "clear":
+        this.findings.clear();
+        break;
+    }
+  }
+
+  private applyAdd(finding: Finding): void {
+    if (!this.active || this.findings.has(finding.id)) return;
+    this.findings.set(finding.id, {
+      finding: { ...finding },
+      delivered: false,
+      discarded: false,
+    });
+  }
+
+  private applyDelivery(ids: readonly string[]): void {
+    if (!this.active) return;
+    for (const id of ids) {
+      const state = this.findings.get(id);
+      if (state !== undefined && !state.discarded) state.delivered = true;
+    }
+  }
+
+  private applyDecision(id: string, verdict: Verdict, reason: string): void {
+    const state = this.findings.get(id);
+    if (state?.delivered !== true || state.verdict !== undefined) return;
+    state.verdict = verdict;
+    state.reason = reason;
+  }
+
+  private applyDiscard(ids: readonly string[]): void {
+    for (const id of ids) {
+      const state = this.findings.get(id);
+      if (state !== undefined && !state.delivered) state.discarded = true;
+    }
+  }
+
+  private applyEnabled(enabled: boolean): void {
+    this.active = enabled;
+    if (!enabled) {
+      for (const state of this.findings.values()) {
+        if (!state.delivered) state.discarded = true;
+      }
+    }
+  }
+}

package/src/reviewers.ts

@@ -0,0 +1,165 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { minimatch } from "minimatch";
+import { z } from "zod";
+
+export interface ReviewerConfig {
+  model: string;
+  prompt: string;
+  include: readonly string[];
+  exclude: readonly string[];
+}
+
+export const DEFAULT_REVIEWERS: readonly ReviewerConfig[] = [
+  {
+    model: "current",
+    prompt: "Does it add entropy ?",
+    include: ["**/*"],
+    exclude: [],
+  },
+];
+
+const matchOptions = { dot: true, nonegate: true, nocomment: true } as const;
+
+function validGlobSyntax(pattern: string): boolean {
+  const closing: string[] = [];
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern.charAt(index);
+    if (character === "[" || character === "{") {
+      closing.push(character === "[" ? "]" : "}");
+      continue;
+    }
+    if (
+      character === "(" &&
+      ["@", "?", "+", "*", "!"].includes(pattern.charAt(index - 1))
+    ) {
+      closing.push(")");
+      continue;
+    }
+    if (
+      (character === "]" ||
+        character === "}" ||
+        (character === ")" && closing.at(-1) === ")")) &&
+      closing.pop() !== character
+    ) {
+      return false;
+    }
+  }
+  return closing.length === 0;
+}
+
+function validPattern(value: string): boolean {
+  return (
+    value.trim().length > 0 &&
+    value.trim() === value &&
+    !value.includes("\\") &&
+    !/\p{Cc}/u.test(value) &&
+    !path.posix.isAbsolute(value) &&
+    !path.win32.isAbsolute(value) &&
+    !/^[a-z]:/iu.test(value) &&
+    value
+      .split("/")
+      .every((part) => part !== "" && part !== "." && part !== "..") &&
+    validGlobSyntax(value)
+  );
+}
+
+const PatternSchema = z.string().refine(validPattern, {
+  message:
+    "must be a nonempty project-relative POSIX glob with balanced syntax",
+});
+const ReviewerSchema = z.strictObject({
+  model: z.string().refine((value) => value.trim().length > 0),
+  prompt: z.string().refine((value) => value.trim().length > 0),
+  include: z.array(PatternSchema).min(1),
+  exclude: z.array(PatternSchema),
+});
+const ConfigSchema = z.strictObject({ reviewers: z.array(ReviewerSchema) });
+const MissingConfigErrorSchema = z.object({ code: z.literal("ENOENT") });
+
+export async function loadReviewers(
+  cwd: string,
+): Promise<readonly ReviewerConfig[]> {
+  const file = path.join(cwd, "pair-programmer.reviewers.json");
+  let contents: string;
+  try {
+    contents = await readFile(file, "utf8");
+  } catch (error) {
+    if (MissingConfigErrorSchema.safeParse(error).success) {
+      return DEFAULT_REVIEWERS;
+    }
+    throw new Error(`${file}: could not read reviewer configuration`, {
+      cause: error,
+    });
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(contents) as unknown;
+  } catch (error) {
+    throw new Error(`${file}: invalid JSON`, { cause: error });
+  }
+  const result = ConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    const descriptions = result.error.issues.map((issue) => {
+      const segments = [
+        ...issue.path,
+        ...(issue.code === "unrecognized_keys" ? [issue.keys[0]] : []),
+      ];
+      const location =
+        segments.length === 0
+          ? "configuration"
+          : segments.reduce<string>((text, segment) => {
+              if (typeof segment === "number")
+                return `${text}[${String(segment)}]`;
+              const separator = text.length === 0 ? "" : ".";
+              return `${text}${separator}${String(segment)}`;
+            }, "");
+      return `${location} ${issue.message}`;
+    });
+    throw new Error(`${file}: ${descriptions.join("; ")}`);
+  }
+  return result.data.reviewers;
+}
+
+export function matchingReviewers(
+  file: string,
+  reviewers: readonly ReviewerConfig[],
+): ReviewerConfig[] {
+  if (
+    file.length === 0 ||
+    path.posix.isAbsolute(file) ||
+    path.win32.isAbsolute(file) ||
+    /^[a-z]:/iu.test(file) ||
+    /\p{Cc}/u.test(file)
+  ) {
+    return [];
+  }
+  const normalized = path.posix.normalize(file.replaceAll("\\", "/"));
+  return normalized === "." ||
+    normalized === ".." ||
+    normalized.startsWith("../")
+    ? []
+    : reviewers.filter(
+        (reviewer) =>
+          reviewer.include.some((pattern) =>
+            minimatch(normalized, pattern, matchOptions),
+          ) &&
+          reviewer.exclude.every(
+            (pattern) => !minimatch(normalized, pattern, matchOptions),
+          ),
+      );
+}
+
+export function reviewerKey(reviewer: ReviewerConfig): string {
+  return createHash("sha256")
+    .update(
+      JSON.stringify([
+        reviewer.model,
+        reviewer.prompt,
+        reviewer.include.toSorted((left, right) => left.localeCompare(right)),
+        reviewer.exclude.toSorted((left, right) => left.localeCompare(right)),
+      ]),
+    )
+    .digest("hex");
+}

package/src/stats-view.ts

@@ -0,0 +1,172 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MeasuredTotal, StatsSnapshot } from "./pair-stats.js";
+import type { ReviewStore } from "./review-store.js";
+
+function measured(
+  total: MeasuredTotal,
+  calls: number,
+  cost = false,
+  accountingComplete = true,
+): string {
+  if (total.measured === 0) return "unavailable";
+  const value = cost ? `$${total.value.toFixed(6)}` : String(total.value);
+  const coverage =
+    accountingComplete && total.measured === calls ? "complete" : "partial";
+  return `${value} (${coverage} ${String(total.measured)}/${String(calls)})`;
+}
+
+function terminalLabel(value: string): string {
+  let label = "";
+  for (const character of value)
+    label += character >= " " && character <= "~" ? character : "?";
+  return label;
+}
+
+export function statsLines(
+  stats: StatsSnapshot,
+  store: Pick<ReviewStore, "enabled" | "summary">,
+): string[] {
+  const review = stats.reviews;
+  const findings = store.summary();
+  const lines = [
+    `Pair Programmer statistics - ${store.enabled ? "on" : "off"}`,
+    "Snapshot on open; close and run /pair-stats again to refresh.",
+    "",
+    "Review activity: incurred in this session, across all branches",
+    `Running ${String(review.running)} | completed ${String(review.success)} | failed ${String(review.failed)}`,
+    `Cancelled ${String(review.cancelled)} | timed out ${String(review.timeout)} | obsolete ${String(review.obsolete)}`,
+    `Interrupted on reload ${String(review.interrupted)} (final outcome unknown)`,
+    stats.finished === 0
+      ? "Review latency: unavailable (no finalized jobs)"
+      : `Review latency: average ${String(Math.round(stats.durationMs / stats.finished))} ms | max ${String(Math.round(stats.maxDurationMs))} ms`,
+    "",
+    "Findings: selected branch only (authoritative review state)",
+    `Pending ${String(findings.pending)} | awaiting decision ${String(findings.outstanding)}`,
+    `Accepted ${String(findings.accepted)} | rejected ${String(findings.rejected)} | discarded ${String(findings.discarded)}`,
+    "",
+    "Extension model usage: separate from main-agent host totals",
+    ...(stats.incompleteJobs === 0
+      ? []
+      : [
+          `INCOMPLETE accounting: ${String(stats.incompleteJobs)} review job(s) may have unreported calls or usage.`,
+        ]),
+    "Per-field measured subtotals of recorded calls; missing usage is not zero.",
+    "Cost is an estimate in USD, not a billing total.",
+  ];
+  if (stats.persistenceFailures > 0)
+    lines.push(
+      `Storage unavailable for ${String(stats.persistenceFailures)} record(s); current process snapshot retained.`,
+    );
+  if (stats.pendingWrites > 0)
+    lines.push(
+      `${String(stats.pendingWrites)} unsaved record(s); reopen this session before exiting to retry persistence.`,
+    );
+  if (stats.usage.length === 0)
+    lines.push("No finalized extension model calls recorded.");
+  for (const group of stats.usage) {
+    const prefix = group.provider === undefined ? "" : `${group.provider}/`;
+    const model =
+      group.model === undefined
+        ? `unobserved (requested ${group.requestedModel})`
+        : `${prefix}${group.model}`;
+    lines.push(
+      "",
+      `${group.stage}: ${terminalLabel(model)}`,
+      `Calls ${String(group.calls)} | success ${String(group.outcomes.success)} | failed ${String(group.outcomes.failed)} | cancelled ${String(group.outcomes.cancelled)} | timed out ${String(group.outcomes.timeout)}`,
+      `Call latency average ${String(Math.round(group.durationMs / group.calls))} ms`,
+      `Input ${measured(group.inputTokens, group.calls, false, stats.incompleteJobs === 0)} | output ${measured(group.outputTokens, group.calls, false, stats.incompleteJobs === 0)}`,
+      `Cache read ${measured(group.cacheReadTokens, group.calls, false, stats.incompleteJobs === 0)} | cache write ${measured(group.cacheWriteTokens, group.calls, false, stats.incompleteJobs === 0)}`,
+      `Total tokens ${measured(group.totalTokens, group.calls, false, stats.incompleteJobs === 0)} | estimated cost ${measured(group.costUsd, group.calls, true, stats.incompleteJobs === 0)}`,
+    );
+  }
+  return lines;
+}
+
+export class StatsView {
+  private closeCurrent: (() => void) | undefined;
+
+  close(): void {
+    this.closeCurrent?.();
+    this.closeCurrent = undefined;
+  }
+
+  async open(ctx: ExtensionContext, lines: readonly string[]): Promise<void> {
+    this.close();
+    const unavailable = "/pair-stats requires an interactive terminal (TUI).";
+    if (!ctx.hasUI) throw new Error(unavailable);
+
+    const mode = (ctx as Partial<ExtensionContext>).mode;
+    if (mode !== undefined && mode !== "tui") {
+      ctx.ui.notify(unavailable, "warning");
+      return;
+    }
+    const state = { mounted: false };
+    let close: (() => void) | undefined;
+    try {
+      await ctx.ui.custom<undefined>(
+        (tui, _theme, keys, done) => {
+          state.mounted = true;
+          let offset = 0;
+          let pageSize = 1;
+          let disposed = false;
+          close = (): void => {
+            if (disposed) return;
+            disposed = true;
+            done(undefined);
+          };
+          this.closeCurrent = close;
+          return {
+            render(width: number): string[] {
+              const wrapped: string[] = [];
+              const columns = Math.max(1, width);
+              for (const line of lines) {
+                if (line.length === 0) wrapped.push("");
+                for (let index = 0; index < line.length; index += columns)
+                  wrapped.push(line.slice(index, index + columns));
+              }
+              pageSize = Math.max(1, tui.terminal.rows - 4);
+              offset = Math.min(offset, Math.max(0, wrapped.length - pageSize));
+              return [
+                ...wrapped.slice(offset, offset + pageSize),
+                "",
+                "Up/Down/PgUp/PgDn scroll | Enter/Esc/q close".slice(
+                  0,
+                  columns,
+                ),
+              ];
+            },
+            handleInput(data: string): void {
+              if (
+                data === "q" ||
+                keys.matches(data, "tui.select.confirm") ||
+                keys.matches(data, "tui.select.cancel") ||
+                keys.matches(data, "app.clear")
+              )
+                close?.();
+              else {
+                if (keys.matches(data, "tui.select.up"))
+                  offset = Math.max(0, offset - 1);
+                else if (keys.matches(data, "tui.select.down")) offset += 1;
+                else if (keys.matches(data, "tui.select.pageUp"))
+                  offset = Math.max(0, offset - pageSize);
+                else if (keys.matches(data, "tui.select.pageDown"))
+                  offset += pageSize;
+                tui.requestRender();
+              }
+            },
+            invalidate(): void {
+              return;
+            },
+            dispose(): void {
+              disposed = true;
+            },
+          };
+        },
+        { overlay: true },
+      );
+      if (!state.mounted) throw new Error(unavailable);
+    } finally {
+      if (this.closeCurrent === close) this.closeCurrent = undefined;
+    }
+  }
+}