@agjs/tsforge 0.1.0

package/src/spec/index.ts

@@ -0,0 +1,5 @@
+export * from "./spec.types";
+export * from "./spec.constants";
+export { parseSpec } from "./parse";
+export { generateTests } from "./generate-tests";
+export { reviewTests, reviewAndFixSuite } from "./review-tests";

package/src/spec/parse.ts

@@ -0,0 +1,152 @@
+import { SPEC_MODE } from "./spec.constants";
+import type { ISpec, ITask } from "./spec.types";
+
+/**
+ * Parse our minimal one-file spec format (see docs: /spec/format/).
+ *
+ * Deliberately small: enough for the walking skeleton — frontmatter keys plus a
+ * `## Tasks` list where each numbered task carries indented `accept:`/`files:`
+ * lines. Richer fields (needs/covers/docs) land in the spec-engine slice.
+ */
+export function parseSpec(markdown: string): ISpec {
+  const fm = parseFrontmatter(markdown);
+  const tasks = parseTasks(markdown);
+  const intent = parseSection(markdown, "Acceptance criteria");
+
+  if (intent.length > 0) {
+    for (const task of tasks) {
+      task.intent = intent;
+    }
+  }
+
+  return {
+    id: fm.id ?? "",
+    title: fm.title ?? "",
+    verify: fm.verify ?? "",
+    tasks,
+    mode:
+      fm.mode === SPEC_MODE.existing ? SPEC_MODE.existing : SPEC_MODE.scratch,
+  };
+}
+
+/** Return the text under a `## <heading>` block, up to the next `##` or EOF. */
+function parseSection(md: string, heading: string): string {
+  const out: string[] = [];
+  let capturing = false;
+
+  for (const line of md.split("\n")) {
+    if (/^##\s+/.test(line)) {
+      if (capturing) {
+        break;
+      }
+
+      if (line.slice(2).trim().toLowerCase() === heading.toLowerCase()) {
+        capturing = true;
+      }
+
+      continue;
+    }
+
+    if (capturing) {
+      out.push(line);
+    }
+  }
+
+  return out.join("\n").trim();
+}
+
+function parseFrontmatter(md: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const match = /^---\n([\s\S]*?)\n---/.exec(md);
+  const body = match?.[1];
+
+  if (body === undefined) {
+    return out;
+  }
+
+  for (const line of body.split("\n")) {
+    const idx = line.indexOf(":");
+
+    if (idx === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, idx).trim();
+    const val = line
+      .slice(idx + 1)
+      .trim()
+      .replace(/^["']|["']$/g, "");
+
+    if (key.length > 0) {
+      out[key] = val;
+    }
+  }
+
+  return out;
+}
+
+function splitList(value: string): string[] {
+  return value
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+function parseTasks(md: string): ITask[] {
+  const tasks: ITask[] = [];
+  let current: ITask | null = null;
+
+  for (const line of md.split("\n")) {
+    const start = /^(\d+)\.\s+/.exec(line);
+
+    if (start) {
+      if (current) {
+        tasks.push(current);
+      }
+
+      current = { id: start[1] ?? "", accept: "", files: [], context: [] };
+      continue;
+    }
+
+    if (!current) {
+      continue;
+    }
+
+    const acceptMatch = /^\s+accept:\s*(.+)$/.exec(line);
+    const acceptValue = acceptMatch?.[1];
+
+    if (acceptValue !== undefined) {
+      current.accept = acceptValue.trim();
+      continue;
+    }
+
+    const filesMatch = /^\s+files:\s*(.+)$/.exec(line);
+    const filesValue = filesMatch?.[1];
+
+    if (filesValue !== undefined) {
+      current.files = splitList(filesValue);
+      continue;
+    }
+
+    const contextMatch = /^\s+context:\s*(.+)$/.exec(line);
+    const contextValue = contextMatch?.[1];
+
+    if (contextValue !== undefined) {
+      current.context = splitList(contextValue);
+      continue;
+    }
+
+    const fixMatch = /^\s+fix:\s*(.+)$/.exec(line);
+    const fixValue = fixMatch?.[1];
+
+    if (fixValue !== undefined) {
+      current.fix = fixValue.trim();
+    }
+  }
+
+  if (current) {
+    tasks.push(current);
+  }
+
+  return tasks;
+}

package/src/spec/review-tests.ts

@@ -0,0 +1,162 @@
+import { join } from "node:path";
+import type { IProvider } from "../inference";
+import type { Reporter } from "../loop";
+import { isRecord, isArray } from "../lib/guards";
+import { extractJson } from "../lib/json";
+import { runTests, isRealRed } from "../validate";
+import { FINDING_KIND } from "./spec.constants";
+import type {
+  FindingKind,
+  ITestFinding,
+  IReviewResult,
+  IReviewInput,
+  IReviewFixOptions,
+  IReviewFixResult,
+} from "./spec.types";
+
+const FINDING_KINDS = new Set<string>(Object.values(FINDING_KIND));
+
+/**
+ * Offline teacher review of a generated suite: the `runTests` oracle proves a
+ * suite is real/runnable/RED, but NOT that its assertions are CORRECT. A live
+ * run found two ways a model's tests go wrong — assertions that are
+ * *unsatisfiable* given runtime reality (e.g. `1.005 * 100 === 100.4999…` under
+ * IEEE-754) and *ambiguity-overreach* (asserting one arbitrary resolution of a
+ * tie the criteria leave open). This vets for both, plus *over-strict* (testing
+ * behaviour the criteria never required).
+ *
+ * Point `provider` at a flagship — this is an OFFLINE teacher step, never a
+ * runtime dependency. It returns findings plus a corrected suite; the CALLER
+ * must re-run the RED oracle on `correctedSuite` (a fix must stay real + RED)
+ * before trusting it.
+ */
+const SYSTEM = [
+  "You are a senior TypeScript test reviewer. You are given acceptance criteria and a generated `bun:test` suite, and you find assertions that would block a CORRECT implementation.",
+  "Flag three kinds: (1) `unsatisfiable` — no correct implementation can pass it given JS/TS runtime reality (e.g. IEEE-754: `1.005 * 100` is `100.4999…`, so cents can't recover `101` from the number `1.005`); (2) `over-strict` — it asserts behaviour the criteria never required; (3) `ambiguous` — the criteria under-specify and the test asserts one arbitrary resolution (e.g. which index gets the leftover penny on a tie).",
+  'Respond with ONLY JSON: {"findings":[{"test":"<name>","kind":"unsatisfiable|over-strict|ambiguous|ok","reason":"<short>"}],"correctedSuite":"<full corrected test file, or empty string if nothing needs changing>"}.',
+  "When correcting: fix or remove ONLY the flawed assertions — keep all the sound coverage, keep the same imports, and do not weaken the suite otherwise.",
+].join("\n");
+
+export async function reviewTests(
+  provider: IProvider,
+  input: IReviewInput
+): Promise<IReviewResult> {
+  const res = await provider.complete(
+    [
+      { role: "system", content: SYSTEM },
+      {
+        role: "user",
+        content: `Goal: ${input.goal}\n\nAcceptance criteria:\n${input.criteria}\n\nThe suite imports the implementation from "${input.moduleSpecifier}".\n\nGenerated suite:\n${input.testCode}`,
+      },
+    ],
+    { temperature: 0 }
+  );
+
+  const empty: IReviewResult = { findings: [], correctedSuite: "" };
+
+  let data: unknown;
+
+  try {
+    data = JSON.parse(extractJson(res.content));
+  } catch {
+    return empty;
+  }
+
+  if (!isRecord(data)) {
+    return empty;
+  }
+
+  return {
+    findings: parseFindings(data.findings),
+    correctedSuite:
+      typeof data.correctedSuite === "string" ? data.correctedSuite : "",
+  };
+}
+
+function parseFindings(raw: unknown): ITestFinding[] {
+  if (!isArray(raw)) {
+    return [];
+  }
+
+  const findings: ITestFinding[] = [];
+
+  for (const entry of raw) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+
+    const { test, kind, reason } = entry;
+
+    if (typeof test === "string" && isFindingKind(kind)) {
+      findings.push({
+        test,
+        kind,
+        reason: typeof reason === "string" ? reason : "",
+      });
+    }
+  }
+
+  return findings;
+}
+
+function isFindingKind(value: unknown): value is FindingKind {
+  return typeof value === "string" && FINDING_KINDS.has(value);
+}
+
+/**
+ * Run the offline review against the suite on disk and apply a correction —
+ * but only if it survives the SAME RED oracle the suite originally passed. A
+ * proposed fix that breaks loadability or goes vacuous is reverted, so review
+ * can never hand the implement loop anything less sound than what it got.
+ */
+export async function reviewAndFixSuite(
+  provider: IProvider,
+  cwd: string,
+  opts: IReviewFixOptions
+): Promise<IReviewFixResult> {
+  const report: Reporter = opts.onEvent ?? (() => undefined);
+  const testPath = join(cwd, opts.testFile);
+  const original = await Bun.file(testPath).text();
+
+  const review = await reviewTests(provider, {
+    goal: opts.goal,
+    criteria: opts.criteria,
+    testCode: original,
+    moduleSpecifier: `./${opts.implFile.replace(/\.ts$/, "")}`,
+  });
+
+  for (const f of review.findings) {
+    report({
+      kind: "fix",
+      task: opts.testFile,
+      message: `review: ${f.kind} — ${f.test}: ${f.reason}`,
+    });
+  }
+
+  if (review.correctedSuite.length === 0) {
+    return { findings: review.findings, applied: false };
+  }
+
+  await Bun.write(testPath, review.correctedSuite);
+
+  const run = await runTests(opts.testFile, cwd);
+
+  if (!isRealRed(run)) {
+    await Bun.write(testPath, original);
+    report({
+      kind: "fix",
+      task: opts.testFile,
+      message: `review correction broke the RED guarantee (${run.pass} pass / ${run.errors} err) — reverted`,
+    });
+
+    return { findings: review.findings, applied: false };
+  }
+
+  report({
+    kind: "fix",
+    task: opts.testFile,
+    message: `review correction applied — ${run.total} tests, still RED`,
+  });
+
+  return { findings: review.findings, applied: true };
+}

package/src/spec/spec.constants.ts

@@ -0,0 +1,13 @@
+/** Spec run mode — compare against these, never the bare string. */
+export const SPEC_MODE = {
+  scratch: "scratch",
+  existing: "existing",
+} as const;
+
+/** Verdict on a generated test — compare against these, never the bare string. */
+export const FINDING_KIND = {
+  unsatisfiable: "unsatisfiable",
+  overStrict: "over-strict",
+  ambiguous: "ambiguous",
+  ok: "ok",
+} as const;

package/src/spec/spec.types.ts

@@ -0,0 +1,79 @@
+import type { Reporter } from "../loop";
+import { type SPEC_MODE, type FINDING_KIND } from "./spec.constants";
+
+export type SpecMode = (typeof SPEC_MODE)[keyof typeof SPEC_MODE];
+
+/** One chunk of work, derived from the spec's task breakdown. */
+export interface ITask {
+  /** Stable id (the task number in v1). */
+  id: string;
+  /** The per-chunk proof: a shell command that must pass to close the chunk. */
+  accept: string;
+  /** Editable scope globs. Edits/creates outside these are rejected (drift tripwire). */
+  files: string[];
+  /** Read-only files shown to the model for context but never edited (e.g. tests). */
+  context?: string[];
+  /**
+   * The spec's intent/contract (its `## Acceptance criteria` prose) shown to the
+   * implement agent so it works from the stated goal instead of reverse-engineering
+   * it from positional test calls — where one ambiguous case can mislead it.
+   */
+  intent?: string;
+  /** Optional auto-fix command run after each edit, before re-validating (e.g. `eslint --fix`). */
+  fix?: string;
+}
+
+/** A parsed spec: intent up top, decomposition in tasks. */
+export interface ISpec {
+  id: string;
+  title: string;
+  /** The whole-spec gate, run once all tasks are green. */
+  verify: string;
+  tasks: ITask[];
+  /**
+   * Run mode. `scratch` (default): the harness DELETES the editable files to
+   * start RED, and the model regenerates them from the spec. `existing`: the
+   * project already exists and is kept — RED comes from a new failing test /
+   * stated goal, and the model edits in place (a feature/bugfix/refactor).
+   */
+  mode?: SpecMode;
+}
+
+export type FindingKind = (typeof FINDING_KIND)[keyof typeof FINDING_KIND];
+
+/** A teacher-review verdict on one generated test. */
+export interface ITestFinding {
+  /** Name of the test the finding refers to. */
+  test: string;
+  kind: FindingKind;
+  reason: string;
+}
+
+export interface IReviewResult {
+  findings: ITestFinding[];
+  /** Full corrected test file, or "" when no change is needed. */
+  correctedSuite: string;
+}
+
+export interface IReviewInput {
+  goal: string;
+  criteria: string;
+  /** The generated test file's contents. */
+  testCode: string;
+  /** Module specifier the suite imports the impl from (e.g. "./money"). */
+  moduleSpecifier: string;
+}
+
+export interface IReviewFixOptions {
+  testFile: string;
+  implFile: string;
+  goal: string;
+  criteria: string;
+  onEvent?: Reporter;
+}
+
+export interface IReviewFixResult {
+  findings: ITestFinding[];
+  /** True only when a correction was written AND it stayed real + RED. */
+  applied: boolean;
+}

package/src/stack-detection/detect.ts

@@ -0,0 +1,246 @@
+import { join } from "node:path";
+import { isRecord } from "../lib/guards";
+import { resolveScopeFiles } from "../lib/fs";
+import type { IStackProfile } from "./stack-detection.types";
+import {
+  PACK_REGISTRY,
+  ALWAYS_ON_PACKS,
+  type IPackRegistry,
+  type IPackId,
+} from "./packs";
+
+/** Parse package.json and extract deps/devDeps, tolerating missing/invalid JSON. */
+async function loadPackageDeps(cwd: string): Promise<{
+  deps: Set<string>;
+  devDeps: Set<string>;
+  exists: boolean;
+  valid: boolean;
+}> {
+  const pkgPath = join(cwd, "package.json");
+  const file = Bun.file(pkgPath);
+
+  const exists = await file.exists();
+
+  if (!exists) {
+    return { deps: new Set(), devDeps: new Set(), exists: false, valid: false };
+  }
+
+  try {
+    const text = await file.text();
+    const parsed: unknown = JSON.parse(text);
+
+    const deps = extractDeps(parsed, "dependencies");
+    const devDeps = extractDeps(parsed, "devDependencies");
+
+    return { deps, devDeps, exists: true, valid: true };
+  } catch {
+    return { deps: new Set(), devDeps: new Set(), exists: true, valid: false };
+  }
+}
+
+/** Extract dependency keys from a parsed package.json object. */
+function extractDeps(obj: unknown, field: string): Set<string> {
+  if (!isRecord(obj)) {
+    return new Set();
+  }
+
+  const depsObj = obj[field];
+
+  if (!isRecord(depsObj)) {
+    return new Set();
+  }
+
+  return new Set(Object.keys(depsObj));
+}
+
+/** Check which packs have file-based matches, returning both match set and whether any were found. */
+async function checkFileMatches(
+  cwd: string,
+  registry: IPackRegistry
+): Promise<{ matches: Set<string>; anyFound: boolean }> {
+  const matches = new Set<string>();
+
+  for (const descriptor of Object.values(registry)) {
+    const filesOption =
+      "files" in descriptor.appliesWhen
+        ? descriptor.appliesWhen.files
+        : undefined;
+
+    if (!filesOption) {
+      continue;
+    }
+
+    const filesList = Array.from(filesOption);
+
+    if (filesList.length === 0) {
+      continue;
+    }
+
+    try {
+      const resolved = await resolveScopeFiles(cwd, filesList);
+
+      if (resolved.length > 0) {
+        matches.add(descriptor.id);
+      }
+    } catch {
+      // If file resolution fails, skip this pack's file checks
+    }
+  }
+
+  return { matches, anyFound: matches.size > 0 };
+}
+
+/** Check if any required dependencies are present. */
+function matchAnyDeps(
+  required: readonly string[] | undefined,
+  allDeps: Set<string>
+): string | undefined {
+  if (!required || required.length === 0) {
+    return undefined;
+  }
+
+  return Array.from(required).find((dep) => allDeps.has(dep));
+}
+
+/** Check if all required dependencies are present. */
+function matchAllDeps(
+  required: readonly string[] | undefined,
+  allDeps: Set<string>
+): boolean {
+  if (!required || required.length === 0) {
+    return false;
+  }
+
+  return Array.from(required).every((dep) => allDeps.has(dep));
+}
+
+/** Evaluate a single pack descriptor against available deps and file matches. */
+function evaluatePack(
+  packId: IPackId,
+  descriptor: IPackRegistry[IPackId],
+  allDeps: Set<string>,
+  fileMatches: Set<string>
+): { enabled: boolean; signal?: string } {
+  // Always-on packs are handled separately
+  if ("always" in descriptor.appliesWhen) {
+    return { enabled: false };
+  }
+
+  if ("anyDeps" in descriptor.appliesWhen) {
+    const matched = matchAnyDeps(descriptor.appliesWhen.anyDeps, allDeps);
+
+    if (matched !== undefined) {
+      return { enabled: true, signal: `${descriptor.label} (${matched})` };
+    }
+  }
+
+  if ("allDeps" in descriptor.appliesWhen) {
+    const hasAll = matchAllDeps(descriptor.appliesWhen.allDeps, allDeps);
+
+    if (hasAll) {
+      return { enabled: true, signal: descriptor.label };
+    }
+  }
+
+  if ("files" in descriptor.appliesWhen) {
+    const filesList = Array.from(descriptor.appliesWhen.files);
+
+    if (filesList.length > 0 && fileMatches.has(packId)) {
+      return { enabled: true, signal: `${descriptor.label} (file detected)` };
+    }
+  }
+
+  return { enabled: false };
+}
+
+/**
+ * Detect the target project's technology stack and return an IStackProfile
+ * that determines which rule packs should be enabled.
+ *
+ * Detection layers:
+ *  1. Parse package.json to extract dependencies and devDependencies
+ *  2. Check file existence for packs with file-based triggers
+ *  3. Evaluate every pack descriptor and collect enabled pack IDs
+ *
+ * Always-on packs are emitted first (deterministic), then framework/library packs.
+ */
+export async function detectStack(cwd: string): Promise<IStackProfile> {
+  const { deps, devDeps, exists, valid } = await loadPackageDeps(cwd);
+
+  // No package.json or invalid JSON — return minimal profile
+  if (!valid) {
+    const reason = exists ? "invalid package.json" : "no package.json found";
+
+    return {
+      name: "generic",
+      packs: ["generic-ts"],
+      confidence: "guess",
+      reason,
+    };
+  }
+
+  const allDeps = new Set([...deps, ...devDeps]);
+  const { matches: fileMatches, anyFound: filesFound } = await checkFileMatches(
+    cwd,
+    PACK_REGISTRY
+  );
+
+  const enabledPacks: string[] = [];
+  const matchedSignals: string[] = [];
+
+  // Add always-on packs first (deterministic order)
+  for (const packId of Array.from(ALWAYS_ON_PACKS)) {
+    enabledPacks.push(packId);
+  }
+
+  // Evaluate and add framework/library packs
+  const alwaysOnSet = new Set<string>(Array.from(ALWAYS_ON_PACKS));
+
+  for (const descriptor of Object.values(PACK_REGISTRY)) {
+    if (alwaysOnSet.has(descriptor.id)) {
+      continue;
+    }
+
+    const { enabled, signal } = evaluatePack(
+      descriptor.id,
+      descriptor,
+      allDeps,
+      fileMatches
+    );
+
+    if (enabled) {
+      enabledPacks.push(descriptor.id);
+
+      if (signal !== undefined) {
+        matchedSignals.push(signal);
+      }
+    }
+  }
+
+  // Determine confidence level
+  const hasDepMatches = matchedSignals.some(
+    (s) => !s.includes("(file detected)")
+  );
+  const confidence: "certain" | "likely" | "guess" = hasDepMatches
+    ? "certain"
+    : filesFound
+      ? "likely"
+      : "guess";
+
+  // Determine stack name (framework/library packs only, excluding always-on)
+  const frameworkPacks = enabledPacks.filter((p) => !alwaysOnSet.has(p));
+  const stackName =
+    frameworkPacks.length > 0 ? frameworkPacks.join("+") : "generic";
+
+  const reason =
+    matchedSignals.length > 0
+      ? `Detected: ${matchedSignals.join(", ")}`
+      : "Generic TypeScript project (no framework/library detected)";
+
+  return {
+    name: stackName,
+    packs: enabledPacks,
+    confidence,
+    reason,
+  };
+}

package/src/stack-detection/index.ts

@@ -0,0 +1,3 @@
+export * from "./stack-detection.types";
+export { detectStack } from "./detect";
+export { PACK_REGISTRY, ALWAYS_ON_PACKS } from "./packs";