@warpgogol/forge 2.8.0 → 2.8.2

package/src/tests/bindings-schema.test.ts

@@ -0,0 +1,314 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for RFC-0639 semantic bindings schema extensions — semantic command keys, terminology resolution chain, applyCliBindingDefaults with 5 new keys.</purpose>
+<non-goals>
+  <item>Do not test resolveBinding — covered in forge-config.test.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0639: initial test suite for semantic command keys, terminology resolution, and applyCliBindingDefaults.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, expect, test } from "vitest";
+import {
+  forgeBindingsSchema,
+  applyCliBindingDefaults,
+  resolveTerminology,
+  defaultForgeConfig,
+  type ForgeConfig,
+} from "../config/forge-config.ts";
+import { TERMINOLOGY_DEFAULTS } from "../profiles/profile-schema.ts";
+
+describe("RFC-0639: Semantic command keys", () => {
+  test("forgeBindingsSchema accepts semantic keys with string values", () => {
+    const bindings = {
+      schema: "forge/bindings@1",
+      commands: {
+        validateRfc: null,
+        validateAdr: null,
+        implementStamp: null,
+        typecheck: null,
+        test: null,
+        scopedBuild: null,
+        specValidate: null,
+        sessionSave: null,
+        validate: "pnpm exec validator check",
+        produce: "pnpm exec builder build -o {output}",
+        verify: "pnpm exec builder build --dry-run",
+        preview: "pnpm exec preview serve",
+        lint: "pnpm exec validator check --strict",
+      },
+      paths: {
+        invariantsFile: null,
+        compassDocs: [],
+        reviewsDir: null,
+        handoffsDir: null,
+        sessionsDir: null,
+      },
+    };
+    const result = forgeBindingsSchema.safeParse(bindings);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.commands.validate).toBe("pnpm exec validator check");
+      expect(result.data.commands.produce).toBe("pnpm exec builder build -o {output}");
+    }
+  });
+
+  test("forgeBindingsSchema defaults semantic keys to null when absent", () => {
+    const bindings = {
+      schema: "forge/bindings@1",
+      commands: {
+        validateRfc: null,
+        validateAdr: null,
+        implementStamp: null,
+        typecheck: null,
+        test: null,
+        scopedBuild: null,
+        specValidate: null,
+        sessionSave: null,
+      },
+      paths: {
+        invariantsFile: null,
+        compassDocs: [],
+        reviewsDir: null,
+        handoffsDir: null,
+        sessionsDir: null,
+      },
+    };
+    const result = forgeBindingsSchema.safeParse(bindings);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.commands.validate).toBeNull();
+      expect(result.data.commands.produce).toBeNull();
+      expect(result.data.commands.verify).toBeNull();
+      expect(result.data.commands.preview).toBeNull();
+      expect(result.data.commands.lint).toBeNull();
+    }
+  });
+
+  test("existing forge.yaml with only original 8 keys parses without changes", () => {
+    const bindings = {
+      schema: "forge/bindings@1",
+      commands: {
+        validateRfc: "forge rfc.validate --id {id} --json",
+        validateAdr: "forge adr.validate --id {id} --json",
+        implementStamp: "forge rfc.implement.stamp --id {id} --implementation-commit {commit}",
+        typecheck: "pnpm --filter {workspace} run build:check",
+        test: "pnpm --filter {workspace} run test",
+        scopedBuild: "pnpm --filter {workspace} run build",
+        specValidate: "forge spec.validate --spec={id} --json",
+        sessionSave: "forge session.save --json",
+      },
+      paths: {
+        invariantsFile: "docs/architecture-dna.md",
+        compassDocs: [],
+        reviewsDir: "docs/reviews",
+        handoffsDir: "docs/handoffs",
+        sessionsDir: "docs/sessions",
+      },
+    };
+    const result = forgeBindingsSchema.safeParse(bindings);
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("RFC-0639: Terminology schema change", () => {
+  test("terminology defaults to empty record when absent", () => {
+    const bindings = {
+      schema: "forge/bindings@1",
+      commands: {
+        validateRfc: null,
+        validateAdr: null,
+        implementStamp: null,
+        typecheck: null,
+        test: null,
+        scopedBuild: null,
+        specValidate: null,
+        sessionSave: null,
+      },
+      paths: {
+        invariantsFile: null,
+        compassDocs: [],
+        reviewsDir: null,
+        handoffsDir: null,
+        sessionsDir: null,
+      },
+    };
+    const result = forgeBindingsSchema.safeParse(bindings);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.terminology).toEqual({});
+    }
+  });
+
+  test("terminology accepts a record of string-to-string", () => {
+    const bindings = {
+      schema: "forge/bindings@1",
+      commands: {
+        validateRfc: null,
+        validateAdr: null,
+        implementStamp: null,
+        typecheck: null,
+        test: null,
+        scopedBuild: null,
+        specValidate: null,
+        sessionSave: null,
+      },
+      paths: {
+        invariantsFile: null,
+        compassDocs: [],
+        reviewsDir: null,
+        handoffsDir: null,
+        sessionsDir: null,
+      },
+      terminology: { artifact: "composition", module: "scene" },
+    };
+    const result = forgeBindingsSchema.safeParse(bindings);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.terminology.artifact).toBe("composition");
+      expect(result.data.terminology.module).toBe("scene");
+    }
+  });
+});
+
+describe("RFC-0639: applyCliBindingDefaults", () => {
+  test("returns 13 keys with semantic keys as null", () => {
+    const commands = applyCliBindingDefaults("pnpm");
+    // CLI-backed keys are non-null
+    expect(commands.validateRfc).not.toBeNull();
+    expect(commands.validateAdr).not.toBeNull();
+    expect(commands.implementStamp).not.toBeNull();
+    expect(commands.specValidate).not.toBeNull();
+    expect(commands.sessionSave).not.toBeNull();
+    // Software-domain keys are null
+    expect(commands.typecheck).toBeNull();
+    expect(commands.test).toBeNull();
+    expect(commands.scopedBuild).toBeNull();
+    // Semantic keys (RFC-0639) are null
+    expect(commands.validate).toBeNull();
+    expect(commands.produce).toBeNull();
+    expect(commands.verify).toBeNull();
+    expect(commands.preview).toBeNull();
+    expect(commands.lint).toBeNull();
+  });
+});
+
+describe("RFC-0639: resolveTerminology", () => {
+  const baseConfig: ForgeConfig = {
+    schema: "forge/config@1",
+    project: { name: "test", stack: [], packageManager: "pnpm" },
+    paths: {
+      rfcsDir: "docs/rfcs",
+      adrsDir: "docs/adrs",
+      plansDir: "docs/plans",
+      auditsDir: "docs/audits",
+      specsDir: "docs/specs",
+      skillsDir: ".agents/skills",
+      sessionsDir: "docs/sessions",
+    },
+    bindings: {
+      schema: "forge/bindings@1",
+      commands: {
+        validateRfc: null,
+        validateAdr: null,
+        implementStamp: null,
+        typecheck: null,
+        test: null,
+        scopedBuild: null,
+        specValidate: null,
+        sessionSave: null,
+        validate: null,
+        produce: null,
+        verify: null,
+        preview: null,
+        lint: null,
+      },
+      paths: {
+        invariantsFile: null,
+        compassDocs: [],
+        reviewsDir: null,
+        handoffsDir: null,
+        sessionsDir: null,
+      },
+      terminology: {},
+    },
+  };
+
+  test("tier 1: returns bindings terminology override when present", () => {
+    const config: ForgeConfig = {
+      ...baseConfig,
+      bindings: {
+        ...baseConfig.bindings!,
+        terminology: { artifact: "composition" },
+      },
+    };
+    expect(resolveTerminology(config, undefined, "artifact")).toBe("composition");
+  });
+
+  test("tier 2: returns caller-provided terminology when bindings don't have the key", () => {
+    const config: ForgeConfig = {
+      ...baseConfig,
+      bindings: {
+        ...baseConfig.bindings!,
+        terminology: {},
+      },
+    };
+    const profileTerminology = { artifact: "scene" };
+    expect(resolveTerminology(config, profileTerminology, "artifact")).toBe("scene");
+  });
+
+  test("tier 3: returns universal default when neither bindings nor caller-provided have the key", () => {
+    const config: ForgeConfig = {
+      ...baseConfig,
+      bindings: {
+        ...baseConfig.bindings!,
+        terminology: {},
+      },
+    };
+    expect(resolveTerminology(config, undefined, "artifact")).toBe(TERMINOLOGY_DEFAULTS.artifact);
+    expect(resolveTerminology(config, undefined, "module")).toBe(TERMINOLOGY_DEFAULTS.module);
+    expect(resolveTerminology(config, undefined, "operator")).toBe(TERMINOLOGY_DEFAULTS.operator);
+  });
+
+  test("fallback: returns the key itself when not found in any tier", () => {
+    const config: ForgeConfig = {
+      ...baseConfig,
+      bindings: {
+        ...baseConfig.bindings!,
+        terminology: {},
+      },
+    };
+    expect(resolveTerminology(config, undefined, "nonexistent")).toBe("nonexistent");
+  });
+
+  test("works with undefined terminology parameter (skips tier 2)", () => {
+    const config: ForgeConfig = {
+      ...baseConfig,
+      bindings: {
+        ...baseConfig.bindings!,
+        terminology: {},
+      },
+    };
+    expect(resolveTerminology(config, undefined, "artifact")).toBe("artifact");
+  });
+
+  test("bindings override takes precedence over caller-provided terminology", () => {
+    const config: ForgeConfig = {
+      ...baseConfig,
+      bindings: {
+        ...baseConfig.bindings!,
+        terminology: { artifact: "composition" },
+      },
+    };
+    const profileTerminology = { artifact: "scene" };
+    expect(resolveTerminology(config, profileTerminology, "artifact")).toBe("composition");
+  });
+
+  test("works with defaultForgeConfig", () => {
+    const config = defaultForgeConfig("test-project", "pnpm");
+    expect(resolveTerminology(config, undefined, "artifact")).toBe("artifact");
+    expect(resolveTerminology(config, undefined, "source")).toBe("source file");
+  });
+});

package/src/tests/budgets.test.ts

@@ -0,0 +1,213 @@
+import { test, expect, describe } from "vitest";
+import {
+  computeLayerBudgets,
+  resolveKnowledgeBudgets,
+  DEFAULT_KNOWLEDGE_BUDGETS,
+} from "../knowledge/budgets.ts";
+import type { ParsedKnowledgeFile, KnowledgeLayer } from "../knowledge/schema.ts";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const testDir = path.join(os.tmpdir(), "test");
+
+// Helper: create a minimal ParsedKnowledgeFile for testing
+function makeParsedFile(overrides: Partial<ParsedKnowledgeFile> = {}): ParsedKnowledgeFile {
+  return {
+    path: path.join(testDir, "learned-principles.md"),
+    layer: "L2",
+    preamble: "",
+    entries: [],
+    legacySections: [],
+    parseIssues: [],
+    isKnowledgeAdjacent: false,
+    ...overrides,
+  };
+}
+
+// Helper: create an active L2 entry
+function makeActiveEntry(id: string, body: string) {
+  return {
+    meta: {
+      id,
+      layer: "L2" as KnowledgeLayer,
+      created: "2026-01-01",
+      lastConfirmedAt: "2026-01-10",
+      confirmations: 3,
+      status: "active" as const,
+    },
+    title: `Entry ${id}`,
+    body,
+    lineStart: 1,
+  };
+}
+
+describe("resolveKnowledgeBudgets", () => {
+  test("returns defaults when forge.yaml not found", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "budget-test-"));
+    try {
+      const budgets = resolveKnowledgeBudgets(tmpDir);
+      expect(budgets).toEqual(DEFAULT_KNOWLEDGE_BUDGETS);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns defaults when no knowledge.budgets override", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "budget-test-"));
+    try {
+      fs.writeFileSync(
+        path.join(tmpDir, "forge.yaml"),
+        "schema: forge/bindings@1\nbindings:\n  commands:\n    validateRfc: null\n",
+      );
+      const budgets = resolveKnowledgeBudgets(tmpDir);
+      expect(budgets).toEqual(DEFAULT_KNOWLEDGE_BUDGETS);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("applies override when present and valid", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "budget-test-"));
+    try {
+      fs.writeFileSync(
+        path.join(tmpDir, "forge.yaml"),
+        "schema: forge/bindings@1\nbindings:\n  knowledge:\n    budgets:\n      hot: 2048\n      warm: 4096\n",
+      );
+      const budgets = resolveKnowledgeBudgets(tmpDir);
+      expect(budgets).toEqual({ hot: 2048, warm: 4096 });
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("falls back to defaults when override values are invalid (non-positive)", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "budget-test-"));
+    try {
+      fs.writeFileSync(
+        path.join(tmpDir, "forge.yaml"),
+        "schema: forge/bindings@1\nbindings:\n  knowledge:\n    budgets:\n      hot: 0\n      warm: -1\n",
+      );
+      const budgets = resolveKnowledgeBudgets(tmpDir);
+      expect(budgets).toEqual(DEFAULT_KNOWLEDGE_BUDGETS);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("falls back to defaults when override values are non-integer", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "budget-test-"));
+    try {
+      fs.writeFileSync(
+        path.join(tmpDir, "forge.yaml"),
+        "schema: forge/bindings@1\nbindings:\n  knowledge:\n    budgets:\n      hot: 3.5\n      warm: 8192\n",
+      );
+      const budgets = resolveKnowledgeBudgets(tmpDir);
+      expect(budgets).toEqual({ hot: DEFAULT_KNOWLEDGE_BUDGETS.hot, warm: 8192 });
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("computeLayerBudgets", () => {
+  test("counts only active entries", () => {
+    const file = makeParsedFile({
+      entries: [
+        makeActiveEntry("K-0001", "Short body."),
+        {
+          meta: {
+            id: "K-0002",
+            layer: "L2",
+            created: "2026-01-01",
+            lastConfirmedAt: "2026-01-10",
+            confirmations: 2,
+            status: "stale",
+          },
+          title: "Stale entry",
+          body: "This should not be counted.",
+          lineStart: 10,
+        },
+      ],
+    });
+    const skillNames = new Map([[path.join(testDir, "learned-principles.md"), "test-skill"]]);
+    const reports = computeLayerBudgets([file], DEFAULT_KNOWLEDGE_BUDGETS, skillNames);
+    expect(reports).toHaveLength(1);
+    // Only K-0001 (active) should be counted
+    expect(reports[0].activeChars).toBeLessThan(DEFAULT_KNOWLEDGE_BUDGETS.hot);
+    expect(reports[0].exceededBy).toBe(0);
+  });
+
+  test("reports exceeded budget for hot layer", () => {
+    const longBody = "x".repeat(5000);
+    const file = makeParsedFile({
+      entries: [makeActiveEntry("K-0001", longBody)],
+    });
+    const skillNames = new Map([[path.join(testDir, "learned-principles.md"), "test-skill"]]);
+    const reports = computeLayerBudgets([file], DEFAULT_KNOWLEDGE_BUDGETS, skillNames);
+    expect(reports).toHaveLength(1);
+    expect(reports[0].layer).toBe("L2");
+    expect(reports[0].activeChars).toBeGreaterThan(DEFAULT_KNOWLEDGE_BUDGETS.hot);
+    expect(reports[0].exceededBy).toBeGreaterThan(0);
+  });
+
+  test("skips files with undeterminable layer (null)", () => {
+    const file = makeParsedFile({ layer: null });
+    const skillNames = new Map([[path.join(testDir, "unknown.md"), "test-skill"]]);
+    const reports = computeLayerBudgets([file], DEFAULT_KNOWLEDGE_BUDGETS, skillNames);
+    expect(reports).toHaveLength(0);
+  });
+
+  test("skips L0 (cold) files — no budget by design", () => {
+    const file = makeParsedFile({ layer: "L0" });
+    const skillNames = new Map([[path.join(testDir, "qa-log.md"), "test-skill"]]);
+    const reports = computeLayerBudgets([file], DEFAULT_KNOWLEDGE_BUDGETS, skillNames);
+    expect(reports).toHaveLength(0);
+  });
+
+  test("skips files with parse issues", () => {
+    const file = makeParsedFile({
+      parseIssues: [{ line: 1, message: "Bad YAML" }],
+    });
+    const skillNames = new Map([[path.join(testDir, "learned-principles.md"), "test-skill"]]);
+    const reports = computeLayerBudgets([file], DEFAULT_KNOWLEDGE_BUDGETS, skillNames);
+    expect(reports).toHaveLength(0);
+  });
+
+  test("skips knowledge-adjacent files", () => {
+    const file = makeParsedFile({ isKnowledgeAdjacent: true });
+    const skillNames = new Map([[path.join(testDir, "learned-principles.md"), "test-skill"]]);
+    const reports = computeLayerBudgets([file], DEFAULT_KNOWLEDGE_BUDGETS, skillNames);
+    expect(reports).toHaveLength(0);
+  });
+
+  test("uses warm budget for L1 files", () => {
+    const file = makeParsedFile({
+      layer: "L1",
+      path: path.join(testDir, "fix-patterns.md"),
+      entries: [
+        {
+          meta: { id: "K-0001", layer: "L1", created: "2026-01-01", status: "active" },
+          title: "Fix pattern",
+          body: "x".repeat(9000),
+          lineStart: 1,
+        },
+      ],
+    });
+    const skillNames = new Map([[path.join(testDir, "fix-patterns.md"), "test-skill"]]);
+    const reports = computeLayerBudgets([file], DEFAULT_KNOWLEDGE_BUDGETS, skillNames);
+    expect(reports).toHaveLength(1);
+    expect(reports[0].layer).toBe("L1");
+    expect(reports[0].budget).toBe(DEFAULT_KNOWLEDGE_BUDGETS.warm);
+    expect(reports[0].exceededBy).toBeGreaterThan(0);
+  });
+
+  test("empty file produces zero-size report", () => {
+    const file = makeParsedFile({ entries: [] });
+    const skillNames = new Map([[path.join(testDir, "learned-principles.md"), "test-skill"]]);
+    const reports = computeLayerBudgets([file], DEFAULT_KNOWLEDGE_BUDGETS, skillNames);
+    expect(reports).toHaveLength(1);
+    expect(reports[0].activeChars).toBe(0);
+    expect(reports[0].exceededBy).toBe(0);
+  });
+});