@jwilger/pi-development-system 0.3.7 → 0.4.0

package/package.json

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

package/src/core/git-intent.ts

@@ -30,7 +30,10 @@ function splitLines(command: string): string[] {
   let quote: "'" | '"' | undefined;
   for (let i = 0; i < command.length; i++) {
     const ch = command.charAt(i);
-    if (quote !== undefined) {
+    if (quote === '"' && ch === "\\") {
+      current += ch + command.charAt(i + 1);
+      i++;
+    } else if (quote !== undefined) {
       if (ch === quote) quote = undefined;
       current += ch;
     } else if (ch === "\\" && command.charAt(i + 1) === "\n") {

package/src/core/models.ts

@@ -0,0 +1,205 @@
+import { err, ok, type Result } from "./result.ts";
+
+/** Capability tiers and roles the system asks models for (plan Appendix B `[models]`). */
+export const SLOTS = [
+  "frontier",
+  "strong",
+  "fast",
+  "planning",
+  "advisor",
+  "implementer",
+  "reviewer",
+  "lens",
+  "researcher",
+  "jev",
+] as const;
+
+export type Slot = (typeof SLOTS)[number];
+
+export const isSlot = (value: string): value is Slot => SLOTS.some((s) => s === value);
+
+/** `provider/id`; the id may contain `/` (gateway providers) and `*` (family pattern). */
+export type ModelRef = `${string}/${string}`;
+
+/** Ordered candidates per slot: `provider/id`, `provider/family-*`, or `@slot` indirection. */
+export type ModelMatrix = Readonly<Record<Slot, readonly string[]>>;
+
+export type Available = { readonly provider: string; readonly id: string };
+
+export type ModelError =
+  | { readonly kind: "unresolvable"; readonly slot: Slot }
+  | { readonly kind: "cycle"; readonly path: readonly Slot[] };
+
+export type Resolution = { readonly model: ModelRef; readonly via: string };
+
+type VersionKey = { readonly numbers: readonly number[]; readonly date: number | undefined };
+
+/** Date-like segments (YYYYMMDD) are snapshot suffixes, not versions. */
+const MIN_DATE_DIGITS = 6;
+
+function versionKey(id: string): VersionKey {
+  const numbers: number[] = [];
+  let date: number | undefined;
+  for (const run of id.match(/\d+/g) ?? []) {
+    if (run.length >= MIN_DATE_DIGITS) date = Number(run);
+    else numbers.push(Number(run));
+  }
+  return { numbers, date };
+}
+
+function compareNumbers(a: readonly number[], b: readonly number[]): number {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Natural version order over the numeric segments of two model ids. Dated snapshot suffixes rank
+ * below the undated alias with the same version, so `x-4-5` beats `x-4-5-20251001`.
+ */
+export function compareModelVersions(a: string, b: string): number {
+  const ka = versionKey(a);
+  const kb = versionKey(b);
+  const byNumbers = compareNumbers(ka.numbers, kb.numbers);
+  if (byNumbers !== 0) return byNumbers;
+  if (ka.date !== kb.date) {
+    if (ka.date === undefined) return 1;
+    if (kb.date === undefined) return -1;
+    return ka.date < kb.date ? -1 : 1;
+  }
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+/** `*`-only glob over a model id (no regular expressions built from configuration). */
+function matchesPattern(pattern: string, id: string): boolean {
+  const parts = pattern.split("*");
+  if (parts.length === 1) return pattern === id;
+  const first = parts[0] ?? "";
+  const last = parts.at(-1) ?? "";
+  if (id.length < first.length + last.length || !id.startsWith(first) || !id.endsWith(last)) {
+    return false;
+  }
+  let at = first.length;
+  const limit = id.length - last.length;
+  for (const middle of parts.slice(1, -1)) {
+    const found = id.indexOf(middle, at);
+    if (found === -1 || found + middle.length > limit) return false;
+    at = found + middle.length;
+  }
+  return true;
+}
+
+function splitRef(candidate: string): { provider: string; id: string } | undefined {
+  const slash = candidate.indexOf("/");
+  if (slash <= 0 || slash === candidate.length - 1) return undefined;
+  return { provider: candidate.slice(0, slash), id: candidate.slice(slash + 1) };
+}
+
+/** The exact model, or the newest available id matching the family pattern; `@slot` is not handled here. */
+export function resolveCandidate(
+  candidate: string,
+  available: readonly Available[],
+): ModelRef | undefined {
+  const ref = splitRef(candidate);
+  if (ref === undefined) return undefined;
+  const matches = available
+    .flatMap((m) => (m.provider === ref.provider && matchesPattern(ref.id, m.id) ? [m.id] : []))
+    .sort(compareModelVersions);
+  const best = matches.at(-1);
+  return best === undefined ? undefined : `${ref.provider}/${best}`;
+}
+
+function resolveFrom(
+  matrix: ModelMatrix,
+  slot: Slot,
+  available: readonly Available[],
+  trail: readonly Slot[],
+): Result<Resolution, ModelError> {
+  if (trail.includes(slot)) return err({ kind: "cycle", path: [...trail, slot] });
+  for (const candidate of matrix[slot]) {
+    if (candidate.startsWith("@")) {
+      const target = candidate.slice(1);
+      if (!isSlot(target)) continue;
+      const inner = resolveFrom(matrix, target, available, [...trail, slot]);
+      if (inner.ok || inner.error.kind === "cycle") return inner;
+      continue;
+    }
+    const model = resolveCandidate(candidate, available);
+    if (model !== undefined) return ok({ model, via: candidate });
+  }
+  return err({ kind: "unresolvable", slot });
+}
+
+/** First candidate of the slot that resolves against what this machine can use; `via` is the matching candidate. */
+export function resolveSlot(
+  matrix: ModelMatrix,
+  slot: Slot,
+  available: readonly Available[],
+): Result<Resolution, ModelError> {
+  return resolveFrom(matrix, slot, available, []);
+}
+
+/** Shipped defaults: model families only (no dated ids), so they roll forward as providers ship. */
+export function defaultMatrix(): ModelMatrix {
+  return {
+    frontier: [
+      "openai-codex/gpt-*-astra",
+      "openai/gpt-*-astra",
+      "anthropic/claude-fable-*",
+      "anthropic/claude-opus-*",
+      "openai-codex/gpt-*-sol",
+      "openai/gpt-*-sol",
+    ],
+    strong: [
+      "openai-codex/gpt-*-sol",
+      "openai/gpt-*-sol",
+      "anthropic/claude-sonnet-*",
+      "anthropic/claude-opus-*",
+      "openai-codex/gpt-*-terra",
+      "openai/gpt-*-terra",
+    ],
+    fast: [
+      "openai-codex/gpt-*-luna",
+      "openai/gpt-*-luna",
+      "anthropic/claude-haiku-*",
+      "openai-codex/gpt-*-terra",
+      "openai/gpt-*-terra",
+      "@strong",
+    ],
+    planning: ["@frontier"],
+    advisor: ["@frontier"],
+    implementer: ["@strong"],
+    reviewer: [
+      "anthropic/claude-opus-*",
+      "anthropic/claude-sonnet-*",
+      "openai-codex/gpt-*-sol",
+      "openai/gpt-*-sol",
+      "@strong",
+    ],
+    lens: ["@strong"],
+    researcher: ["@fast"],
+    jev: [
+      "typesafe/jev-latest",
+      "openrouter/typesafe/jev-latest",
+      "opencode/jev-1.13",
+      "cloudflare-workers-ai/typesafe/jev",
+      "vercel-ai-gateway/typesafe-ai/jev",
+    ],
+  };
+}
+
+const WIDTH = Math.max(...SLOTS.map((s) => s.length));
+
+/** The `[models]` TOML table for a matrix, one slot per line in declaration order. */
+export function renderMatrixToml(matrix: ModelMatrix): string {
+  const lines = SLOTS.map(
+    (slot) => `${slot.padEnd(WIDTH)} = [${matrix[slot].map((c) => JSON.stringify(c)).join(", ")}]`,
+  );
+  return `[models]\n${lines.join("\n")}\n`;
+}

package/src/core/test-paths.ts

@@ -49,6 +49,15 @@ export function isTestPath(path: string, profile?: TestPathProfile): boolean {
   return (profile?.testGlobs ?? []).some((g) => matchGlob(g, normalized));
 }
 
+/** A malformed `file://` URL is treated as the raw path rather than throwing out of a guard. */
+function decodeFileUrl(url: string): string {
+  try {
+    return fileURLToPath(url);
+  } catch {
+    return url;
+  }
+}
+
 /**
  * Repo-relative form of a path exactly as pi would resolve it: a leading `@` is dropped, `~` expands
  * to the home directory and `file://` URLs are decoded, so guards see the file that is really touched.
@@ -57,6 +66,6 @@ export function normalizeRepoPath(cwd: string, input: string, home: string): str
   let path = input.startsWith("@") ? input.slice(1) : input;
   if (path === "~") path = home;
   else if (path.startsWith("~/")) path = join(home, path.slice(2));
-  else if (/^file:\/\//.test(path)) path = fileURLToPath(path);
+  else if (/^file:\/\//.test(path)) path = decodeFileUrl(path);
   return isAbsolute(path) ? relative(cwd, path) : relative(cwd, resolve(cwd, path)) || ".";
 }

package/src/core/test-weakening.ts

@@ -6,7 +6,7 @@ export type WeakeningSignals = { addsSkip: boolean; emptied: boolean; commentedO
 const SKIP_MARKERS: readonly RegExp[] = [
   /\b(?:it|test|describe|context)\.(?:skip|only)\b/g,
   /\b(?:this|t|self|ctx)\.skip\(/g,
-  /\bskip:\s*true\b/g,
+  /\bskip:\s*(?:true\b|["'`])/g,
   /\bskipTest\(/g,
   /(?<![.\w])f(?:it|describe)\(/g,
   /(?<![.\w])x(?:it|describe|test)\(/g,
@@ -130,7 +130,13 @@ function splitLines(command: string): string {
   let quote: "'" | '"' | undefined;
   for (let i = 0; i < command.length; i++) {
     const c = command.charAt(i);
-    if (quote === undefined && c === "\\" && command.charAt(i + 1) === "\n") {
+    if (quote === undefined && c === "#" && (out === "" || /[\s;&|(]$/.test(out))) {
+      // A comment runs to the end of the line; keep the newline so the next command is still seen.
+      while (i + 1 < command.length && command.charAt(i + 1) !== "\n") i++;
+    } else if (quote === '"' && c === "\\") {
+      out += c + command.charAt(i + 1);
+      i++;
+    } else if (quote === undefined && c === "\\" && command.charAt(i + 1) === "\n") {
       out += " ";
       i++;
     } else if (quote === undefined && c === "\\") {

package/src/state/config.ts

@@ -0,0 +1,313 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { defaultMatrix, isSlot, type ModelMatrix, SLOTS, type Slot } from "../core/models.ts";
+import { err, ok, type Result } from "../core/result.ts";
+
+export const CONFIG_FILE = ".development-system.toml";
+
+const DELIVERY_MODES = ["trunk", "pull-request", "local-only"] as const;
+const TRACKER_KINDS = ["repo-files", "github", "jira", "linear"] as const;
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+export type DeliveryMode = (typeof DELIVERY_MODES)[number];
+export type TrackerKind = (typeof TRACKER_KINDS)[number];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export type ConfigError = {
+  readonly kind: "config-error";
+  readonly message: string;
+  readonly key?: string;
+};
+
+export type Route = { readonly slot: Slot; readonly thinkingLevel: ThinkingLevel };
+
+export type DevsysConfig = {
+  readonly delivery: {
+    readonly mode: DeliveryMode;
+    readonly trunk: string;
+    readonly remote: string;
+  };
+  readonly review: { readonly requiredCleanRounds: number; readonly minRounds: number };
+  readonly tracker: { readonly kind: TrackerKind; readonly repo?: string };
+  readonly profiles: { readonly override: readonly string[] };
+  readonly models: ModelMatrix;
+  readonly routing: Readonly<Record<string, Route>>;
+  readonly jev: { readonly timeoutMs: number; readonly confidenceFloor: number };
+  readonly verifier: { readonly maxPerSession: number };
+  readonly cadence: { readonly pushMinutes: number };
+  readonly eventModel: { readonly provider: string };
+};
+
+const DEFAULT_ROUTING: Readonly<Record<string, Route>> = {
+  "trivial/low": { slot: "fast", thinkingLevel: "low" },
+  "trivial/*": { slot: "implementer", thinkingLevel: "medium" },
+  "routine/low": { slot: "implementer", thinkingLevel: "medium" },
+  "routine/*": { slot: "strong", thinkingLevel: "high" },
+  "complex/*": { slot: "strong", thinkingLevel: "high" },
+  "expert/*": { slot: "frontier", thinkingLevel: "high" },
+};
+
+const fail = (message: string, key?: string): Result<never, ConfigError> =>
+  err(
+    key === undefined ? { kind: "config-error", message } : { kind: "config-error", message, key },
+  );
+
+type Table = Readonly<Record<string, unknown>>;
+
+const isTable = (value: unknown): value is Table =>
+  typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+
+const qualified = (path: string, key: string): string => (path === "" ? key : `${path}.${key}`);
+
+/** The `[path]` table (or defaults when absent), rejecting any key outside `allowed`. */
+function section(
+  root: Table,
+  name: string,
+  allowed: readonly string[],
+): Result<Table, ConfigError> {
+  const raw = root[name];
+  if (raw === undefined) return ok({});
+  if (!isTable(raw)) return fail(`${name} must be a table`, name);
+  const unknown = Object.keys(raw).find((k) => !allowed.includes(k));
+  return unknown === undefined
+    ? ok(raw)
+    : fail(`unknown key ${qualified(name, unknown)}`, qualified(name, unknown));
+}
+
+function text(t: Table, path: string, key: string, fallback: string): Result<string, ConfigError> {
+  const v = t[key];
+  if (v === undefined) return ok(fallback);
+  return typeof v === "string" && v !== ""
+    ? ok(v)
+    : fail(`${qualified(path, key)} must be a non-empty string`, qualified(path, key));
+}
+
+function choice<T extends string>(
+  t: Table,
+  path: string,
+  key: string,
+  options: readonly T[],
+  fallback: T,
+): Result<T, ConfigError> {
+  const v = t[key];
+  if (v === undefined) return ok(fallback);
+  const found = options.find((o) => o === v);
+  return found !== undefined
+    ? ok(found)
+    : fail(`${qualified(path, key)} must be one of ${options.join(" | ")}`, qualified(path, key));
+}
+
+function number(
+  t: Table,
+  path: string,
+  key: string,
+  fallback: number,
+  bounds: { min: number; max: number; integer: boolean },
+): Result<number, ConfigError> {
+  const v = t[key];
+  if (v === undefined) return ok(fallback);
+  const valid =
+    typeof v === "number" &&
+    v >= bounds.min &&
+    v <= bounds.max &&
+    (!bounds.integer || Number.isInteger(v));
+  if (valid) return ok(v);
+  const kind = bounds.integer ? "an integer" : "a number";
+  return fail(
+    `${qualified(path, key)} must be ${kind} between ${bounds.min} and ${bounds.max}`,
+    qualified(path, key),
+  );
+}
+
+const POSITIVE = { min: 1, max: 1_000_000, integer: true };
+
+const MODEL_CANDIDATE = /^(@[a-z]+|[^/\s]+\/\S+)$/;
+
+function candidates(raw: unknown, key: string): Result<readonly string[], ConfigError> {
+  const valid =
+    Array.isArray(raw) &&
+    raw.length > 0 &&
+    raw.every((c) => typeof c === "string" && MODEL_CANDIDATE.test(c));
+  return valid
+    ? ok(raw.map(String))
+    : fail(
+        `${key} must be a non-empty array of "provider/id", "provider/family-*" or "@slot" strings`,
+        key,
+      );
+}
+
+function models(root: Table): Result<ModelMatrix, ConfigError> {
+  const table = section(root, "models", SLOTS);
+  if (!table.ok) return table;
+  const merged: Record<Slot, readonly string[]> = { ...defaultMatrix() };
+  for (const [slot, raw] of Object.entries(table.value)) {
+    if (!isSlot(slot)) continue;
+    const parsed = candidates(raw, `models.${slot}`);
+    if (!parsed.ok) return parsed;
+    merged[slot] = parsed.value;
+  }
+  return ok(merged);
+}
+
+function route(raw: unknown, key: string): Result<Route, ConfigError> {
+  const [slot, level] = Array.isArray(raw) ? raw : [];
+  const valid =
+    Array.isArray(raw) &&
+    raw.length === 2 &&
+    typeof slot === "string" &&
+    isSlot(slot) &&
+    THINKING_LEVELS.some((l) => l === level);
+  if (!valid || typeof slot !== "string" || !isSlot(slot)) {
+    return fail(
+      `${key} must be [slot, thinkingLevel] (levels: ${THINKING_LEVELS.join(", ")})`,
+      key,
+    );
+  }
+  const thinkingLevel = THINKING_LEVELS.find((l) => l === level);
+  return thinkingLevel === undefined
+    ? fail(`${key} has an unknown thinking level`, key)
+    : ok({ slot, thinkingLevel });
+}
+
+function routing(root: Table): Result<Readonly<Record<string, Route>>, ConfigError> {
+  const raw = root.routing;
+  if (raw === undefined) return ok(DEFAULT_ROUTING);
+  if (!isTable(raw)) return fail("routing must be a table", "routing");
+  const result: Record<string, Route> = {};
+  for (const [pattern, value] of Object.entries(raw)) {
+    const parsed = route(value, `routing.${pattern}`);
+    if (!parsed.ok) return parsed;
+    result[pattern] = parsed.value;
+  }
+  return ok(result);
+}
+
+function profiles(root: Table): Result<readonly string[], ConfigError> {
+  const table = section(root, "profiles", ["override"]);
+  if (!table.ok) return table;
+  const raw = table.value.override;
+  if (raw === undefined) return ok([]);
+  return Array.isArray(raw) && raw.every((p) => typeof p === "string")
+    ? ok(raw.map(String))
+    : fail("profiles.override must be an array of strings", "profiles.override");
+}
+
+const TOP_LEVEL = [
+  "version",
+  "delivery",
+  "review",
+  "tracker",
+  "profiles",
+  "models",
+  "routing",
+  "jev",
+  "verifier",
+  "cadence",
+  "event_model",
+];
+
+function deliveryAndReview(
+  root: Table,
+): Result<Pick<DevsysConfig, "delivery" | "review" | "tracker">, ConfigError> {
+  const d = section(root, "delivery", ["mode", "trunk", "remote"]);
+  const r = section(root, "review", ["required_clean_rounds", "min_rounds"]);
+  const t = section(root, "tracker", ["kind", "repo"]);
+  if (!d.ok) return d;
+  if (!r.ok) return r;
+  if (!t.ok) return t;
+  const mode = choice(d.value, "delivery", "mode", DELIVERY_MODES, "trunk");
+  const trunk = text(d.value, "delivery", "trunk", "main");
+  const remote = text(d.value, "delivery", "remote", "origin");
+  const required = number(r.value, "review", "required_clean_rounds", 3, POSITIVE);
+  const min = number(r.value, "review", "min_rounds", 1, POSITIVE);
+  const kind = choice(t.value, "tracker", "kind", TRACKER_KINDS, "repo-files");
+  const repo = t.value.repo === undefined ? ok(undefined) : text(t.value, "tracker", "repo", "");
+  for (const field of [mode, trunk, remote, required, min, kind, repo]) if (!field.ok) return field;
+  if (!(mode.ok && trunk.ok && remote.ok && required.ok && min.ok && kind.ok && repo.ok)) {
+    return fail("unreachable");
+  }
+  return ok({
+    delivery: { mode: mode.value, trunk: trunk.value, remote: remote.value },
+    review: { requiredCleanRounds: required.value, minRounds: min.value },
+    tracker:
+      repo.value === undefined ? { kind: kind.value } : { kind: kind.value, repo: repo.value },
+  });
+}
+
+function limits(
+  root: Table,
+): Result<Pick<DevsysConfig, "jev" | "verifier" | "cadence" | "eventModel">, ConfigError> {
+  const j = section(root, "jev", ["timeout_ms", "confidence_floor"]);
+  const v = section(root, "verifier", ["max_per_session"]);
+  const c = section(root, "cadence", ["push_minutes"]);
+  const e = section(root, "event_model", ["provider"]);
+  if (!j.ok) return j;
+  if (!v.ok) return v;
+  if (!c.ok) return c;
+  if (!e.ok) return e;
+  const timeout = number(j.value, "jev", "timeout_ms", 4000, POSITIVE);
+  const floor = number(j.value, "jev", "confidence_floor", 0.6, { min: 0, max: 1, integer: false });
+  const max = number(v.value, "verifier", "max_per_session", 6, POSITIVE);
+  const push = number(c.value, "cadence", "push_minutes", 60, POSITIVE);
+  const provider = text(e.value, "event_model", "provider", "builtin");
+  if (!timeout.ok) return timeout;
+  if (!floor.ok) return floor;
+  if (!max.ok) return max;
+  if (!push.ok) return push;
+  if (!provider.ok) return provider;
+  return ok({
+    jev: { timeoutMs: timeout.value, confidenceFloor: floor.value },
+    verifier: { maxPerSession: max.value },
+    cadence: { pushMinutes: push.value },
+    eventModel: { provider: provider.value },
+  });
+}
+
+/** Parses the text of `.development-system.toml` (plan Appendix B); absent keys take defaults. */
+export function parseConfig(source: string): Result<DevsysConfig, ConfigError> {
+  let root: Table;
+  try {
+    root = parseToml(source);
+  } catch (cause) {
+    return fail(`invalid TOML: ${cause instanceof Error ? cause.message : String(cause)}`);
+  }
+  const unknown = Object.keys(root).find((k) => !TOP_LEVEL.includes(k));
+  if (unknown !== undefined) return fail(`unknown key ${unknown}`, unknown);
+  if (root.version !== undefined && root.version !== 1) {
+    return fail("version must be 1", "version");
+  }
+  const delivery = deliveryAndReview(root);
+  const lim = limits(root);
+  const matrix = models(root);
+  const route = routing(root);
+  const prof = profiles(root);
+  if (!delivery.ok) return delivery;
+  if (!lim.ok) return lim;
+  if (!matrix.ok) return matrix;
+  if (!route.ok) return route;
+  if (!prof.ok) return prof;
+  return ok({
+    ...delivery.value,
+    ...lim.value,
+    profiles: { override: prof.value },
+    models: matrix.value,
+    routing: route.value,
+  });
+}
+
+/** Reads `<repoRoot>/.development-system.toml`; a missing file means all defaults. */
+export async function loadConfig(repoRoot: string): Promise<Result<DevsysConfig, ConfigError>> {
+  let source: string;
+  try {
+    source = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
+  } catch (cause) {
+    if (typeof cause === "object" && cause !== null && "code" in cause && cause.code === "ENOENT") {
+      return parseConfig("");
+    }
+    return fail(
+      `cannot read ${CONFIG_FILE}: ${cause instanceof Error ? cause.message : String(cause)}`,
+    );
+  }
+  return parseConfig(source);
+}