@warpgogol/forge 5.2.3 → 5.2.4

package/src/tests/doctor-dist-freshness.test.ts

@@ -0,0 +1,110 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the dist-freshness doctor check — warns when a forge
+source checkout's dist/ is older than the newest src/ file (RFC-1151).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1151: initial dist-freshness tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile, utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDoctor } from "../onboarding/doctor.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../types.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "doctor-dist-test-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeContext(): ForgeRuntimeContext {
+  return {
+    workspaceRoot: tempDir,
+    // forgeRoot falls back to <workspaceRoot>/packages/forge when unresolvable
+    forgeRoot: join(tempDir, "packages", "forge"),
+    logger: {
+      section: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      info: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+const FORGE_YAML = `schema: "forge/config@1"
+project:
+  name: test-project
+  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
+`;
+
+async function makeForgeCheckout(srcMtime: Date, distMtime: Date): Promise<void> {
+  const forgeRoot = join(tempDir, "packages", "forge");
+  await mkdir(join(forgeRoot, "src"), { recursive: true });
+  await mkdir(join(forgeRoot, "dist"), { recursive: true });
+  await writeFile(join(forgeRoot, "package.json"), JSON.stringify({ name: "@warpgogol/forge" }));
+  await writeFile(join(forgeRoot, "src", "index.ts"), "export {};\n");
+  await writeFile(join(forgeRoot, "dist", "index.js"), "export {};\n");
+  await utimes(join(forgeRoot, "src", "index.ts"), srcMtime, srcMtime);
+  await utimes(join(forgeRoot, "dist"), distMtime, distMtime);
+}
+
+test("dist-freshness warns when dist is older than newest src file", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  const old = new Date("2026-01-01T00:00:00Z");
+  const recent = new Date("2026-09-01T00:00:00Z");
+  await makeForgeCheckout(recent, old);
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "dist-freshness");
+  expect(check).toBeDefined();
+  expect(check!.status).toBe("warn");
+  expect(check!.message).toContain("pnpm run build");
+});
+
+test("dist-freshness passes when dist is absent (npm consumer layout)", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  // No packages/forge at all — forgeRoot fallback dir doesn't exist
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "dist-freshness");
+  expect(check).toBeDefined();
+  expect(check!.status).toBe("pass");
+});
+
+test("dist-freshness passes when dist is newer than src", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  const old = new Date("2026-01-01T00:00:00Z");
+  const recent = new Date("2026-09-01T00:00:00Z");
+  await makeForgeCheckout(old, recent);
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "dist-freshness");
+  expect(check).toBeDefined();
+  expect(check!.status).toBe("pass");
+  expect(check!.message).toContain("fresh");
+});

package/src/tests/doctor-fix.test.ts

@@ -0,0 +1,145 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for forge doctor --fix — safe remediations for warn/fail
+checks: nested-AGENTS.md regeneration and memory-layer compaction (RFC-1151).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1151: initial doctor --fix tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDoctor } from "../onboarding/doctor.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../types.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "doctor-fix-test-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeContext(dryRun = false): ForgeRuntimeContext {
+  return {
+    workspaceRoot: tempDir,
+    logger: {
+      section: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      info: () => {},
+    },
+    dryRun,
+    outputFormat: "json",
+  };
+}
+
+const FORGE_YAML = `schema: "forge/config@1"
+project:
+  name: test-project
+  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
+`;
+
+const GENERATED_MARKER =
+  "<!--\n  GENERATED. Do not change this line unless the file contains project specific changes.\n-->\n";
+
+async function makeStaleWorkspace(): Promise<void> {
+  await mkdir(join(tempDir, "packages", "my-pkg"), { recursive: true });
+  await writeFile(
+    join(tempDir, "packages", "my-pkg", "package.json"),
+    JSON.stringify({ name: "@test/my-pkg" }),
+  );
+  // Generated marker + outdated content → stale
+  await writeFile(
+    join(tempDir, "packages", "my-pkg", "AGENTS.md"),
+    `${GENERATED_MARKER}# Old content\n`,
+    "utf8",
+  );
+}
+
+test("doctor --fix regenerates stale nested AGENTS.md and subsequent run passes", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await makeStaleWorkspace();
+
+  const fixInput: ForgeCommandInput = { argv: [], flags: { fix: true } };
+  const fixResult = await runDoctor(fixInput, makeContext());
+
+  const fixEntry = fixResult.data!.fixes?.find((f) => f.check === "nested-AGENTS.md");
+  expect(fixEntry).toBeDefined();
+  expect(fixEntry!.action).toBe("fixed");
+
+  const regenerated = await readFile(
+    join(tempDir, "packages", "my-pkg", "AGENTS.md"),
+    "utf8",
+  );
+  expect(regenerated).toContain("`@test/my-pkg` — Agent Guide");
+  expect(regenerated).not.toContain("Old content");
+
+  // Subsequent doctor run: nested-AGENTS.md no longer reports this file stale
+  const verifyResult = await runDoctor({ argv: [], flags: {} }, makeContext());
+  const check = verifyResult.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(check!.message).not.toContain("my-pkg/AGENTS.md stale");
+});
+
+test("doctor --fix does not modify hand-written nested AGENTS.md", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await mkdir(join(tempDir, "packages", "my-pkg"), { recursive: true });
+  await writeFile(
+    join(tempDir, "packages", "my-pkg", "package.json"),
+    JSON.stringify({ name: "@test/my-pkg" }),
+  );
+  const handwritten = "# Custom\nNo marker.\n";
+  await writeFile(join(tempDir, "packages", "my-pkg", "AGENTS.md"), handwritten, "utf8");
+
+  const result = await runDoctor({ argv: [], flags: { fix: true } }, makeContext());
+  expect(result.data!.fixes).toBeDefined();
+
+  const after = await readFile(join(tempDir, "packages", "my-pkg", "AGENTS.md"), "utf8");
+  expect(after).toBe(handwritten);
+});
+
+test("doctor --fix compacts over-budget MEMORY.md", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await mkdir(join(tempDir, ".agents", "memory"), { recursive: true });
+  const env = Array.from({ length: 30 }, (_, i) => `- env ${i} ${"x".repeat(200)}`).join("\n");
+  await writeFile(
+    join(tempDir, ".agents", "memory", "MEMORY.md"),
+    `# Project Memory\n\n## Current focus\n\n- keep\n\n## Environment notes\n\n${env}\n`,
+    "utf8",
+  );
+
+  const result = await runDoctor({ argv: [], flags: { fix: true } }, makeContext());
+  const fixEntry = result.data!.fixes?.find((f) => f.check === "memory-layer");
+  expect(fixEntry).toBeDefined();
+  expect(fixEntry!.action).toBe("fixed");
+
+  const after = await readFile(join(tempDir, ".agents", "memory", "MEMORY.md"), "utf8");
+  expect(after.length).toBeLessThanOrEqual(4096);
+  expect(after).toContain("- keep");
+});
+
+test("doctor without --fix produces no fixes array and does not mutate", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await makeStaleWorkspace();
+
+  const result = await runDoctor({ argv: [], flags: {} }, makeContext());
+  expect(result.data!.fixes).toBeUndefined();
+
+  const after = await readFile(join(tempDir, "packages", "my-pkg", "AGENTS.md"), "utf8");
+  expect(after).toContain("Old content");
+});

package/src/tests/doctor-nested-agents.test.ts

@@ -0,0 +1,108 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the nested-AGENTS.md doctor check — consumer-declared
+workspace discovery exclusions via bindings.workspaces.skipDirs (RFC-1150).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1150: initial nested-AGENTS.md skipDirs tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDoctor } from "../onboarding/doctor.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../types.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "doctor-nested-test-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeContext(): ForgeRuntimeContext {
+  return {
+    workspaceRoot: tempDir,
+    logger: {
+      section: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      info: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+function forgeYaml(skipDirs: string[]): string {
+  const skip = skipDirs.length > 0 ? `\n  workspaces:\n    skipDirs: [${skipDirs.join(", ")}]` : "";
+  return `schema: "forge/config@1"
+project:
+  name: test-project
+  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
+  paths:
+    invariantsFile: null
+    compassDocs: []
+    reviewsDir: null
+    handoffsDir: null
+    sessionsDir: null${skip}
+`;
+}
+
+test("nested-AGENTS.md check excludes dirs declared in workspaces.skipDirs", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), forgeYaml(["builds"]), "utf8");
+  // Artifact dir that would otherwise be discovered as a workspace
+  await mkdir(join(tempDir, "builds", "out"), { recursive: true });
+  await writeFile(join(tempDir, "builds", "out", "package.json"), "{}");
+  // Real workspace without AGENTS.md — must still be reported missing
+  await mkdir(join(tempDir, "packages", "real-pkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "real-pkg", "package.json"), "{}");
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(check).toBeDefined();
+  // missing-only reports pass (warn requires stale>0) — assert on message
+  expect(check!.message).toContain("packages/real-pkg");
+  expect(check!.message).not.toContain("builds");
+});
+
+test("nested-AGENTS.md check reports artifact dir as missing without skipDirs", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), forgeYaml([]), "utf8");
+  await mkdir(join(tempDir, "builds", "out"), { recursive: true });
+  await writeFile(join(tempDir, "builds", "out", "package.json"), "{}");
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = result.data!.checks.find((c) => c.name === "nested-AGENTS.md");
+  expect(check).toBeDefined();
+  expect(check!.message).toContain("builds");
+});

package/src/tests/memory-compact.test.ts

@@ -0,0 +1,143 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for forge memory.compact — mechanical MEMORY.md budget
+enforcement via oldest-first Environment notes truncation (RFC-1151).</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1151: initial memory.compact tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runMemoryCompact, compactMemoryMd } from "../onboarding/memory-compact.ts";
+import type { ForgeRuntimeContext } from "../types.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "memory-compact-test-"));
+  await mkdir(join(tempDir, ".agents", "memory"), { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeContext(dryRun = false): ForgeRuntimeContext {
+  return {
+    workspaceRoot: tempDir,
+    logger: {
+      section: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      info: () => {},
+    },
+    dryRun,
+    outputFormat: "json",
+  };
+}
+
+function memoryMd(envBullets: number, bulletSize = 200): string {
+  const env = Array.from(
+    { length: envBullets },
+    (_, i) => `- env note ${i} ${"x".repeat(bulletSize)}`,
+  ).join("\n");
+  return [
+    "# Project Memory",
+    "",
+    "## Current focus",
+    "",
+    "- keep me",
+    "",
+    "## Decisions in flight",
+    "",
+    "- keep me too",
+    "",
+    "## Environment notes",
+    "",
+    env,
+    "",
+  ].join("\n");
+}
+
+test("compactMemoryMd removes oldest Environment notes bullets until within budget", () => {
+  const content = memoryMd(20);
+  const budget = 2000;
+  const { lines, removedLines, fitsBudget } = compactMemoryMd(content, budget);
+
+  expect(fitsBudget).toBe(true);
+  expect(removedLines.length).toBeGreaterThan(0);
+  // Oldest-first: env note 0 removed before env note 19
+  expect(removedLines[0]).toContain("env note 0");
+  expect(lines.join("\n").length).toBeLessThanOrEqual(budget);
+  // Protected sections untouched
+  expect(lines.join("\n")).toContain("- keep me");
+  expect(lines.join("\n")).toContain("- keep me too");
+});
+
+test("compactMemoryMd returns empty removedLines when already within budget", () => {
+  const content = memoryMd(2, 10);
+  const { removedLines, fitsBudget } = compactMemoryMd(content, 4096);
+  expect(removedLines).toHaveLength(0);
+  expect(fitsBudget).toBe(true);
+});
+
+test("runMemoryCompact writes compacted file and reports removed count", async () => {
+  const content = memoryMd(30);
+  await writeFile(join(tempDir, ".agents", "memory", "MEMORY.md"), content, "utf8");
+
+  const result = await runMemoryCompact({ argv: [], flags: {} }, makeContext());
+  expect(result.exitCode).toBe(0);
+  expect(result.data?.status).toBe("pass");
+  expect(result.data?.removed).toBeGreaterThan(0);
+  expect(result.data?.remainingChars).toBeLessThanOrEqual(result.data!.budget);
+
+  const after = await readFile(join(tempDir, ".agents", "memory", "MEMORY.md"), "utf8");
+  expect(after.length).toBeLessThanOrEqual(result.data!.budget);
+  expect(after).toContain("- keep me");
+});
+
+test("runMemoryCompact dryRun reports without writing", async () => {
+  const content = memoryMd(30);
+  await writeFile(join(tempDir, ".agents", "memory", "MEMORY.md"), content, "utf8");
+
+  const result = await runMemoryCompact({ argv: [], flags: {} }, makeContext(true));
+  expect(result.exitCode).toBe(0);
+  expect(result.data?.removed).toBeGreaterThan(0);
+  expect(result.data?.removedLines?.length).toBe(result.data?.removed);
+
+  const after = await readFile(join(tempDir, ".agents", "memory", "MEMORY.md"), "utf8");
+  expect(after).toBe(content);
+});
+
+test("runMemoryCompact passes when MEMORY.md absent", async () => {
+  const result = await runMemoryCompact({ argv: [], flags: {} }, makeContext());
+  expect(result.exitCode).toBe(0);
+  expect(result.data?.removed).toBe(0);
+});
+
+test("runMemoryCompact fails when protected sections alone exceed budget", async () => {
+  // Huge Current focus — Environment notes empty, nothing removable
+  const content = [
+    "# Project Memory",
+    "",
+    "## Current focus",
+    "",
+    `- ${"y".repeat(6000)}`,
+    "",
+    "## Environment notes",
+    "",
+    "- small note",
+    "",
+  ].join("\n");
+  await writeFile(join(tempDir, ".agents", "memory", "MEMORY.md"), content, "utf8");
+
+  const result = await runMemoryCompact({ argv: [], flags: {} }, makeContext());
+  expect(result.exitCode).toBe(1);
+  expect(result.data?.status).toBe("fail");
+  expect(result.data?.errors[0]).toContain("manual editorial compaction");
+});

package/src/tests/workspace-discovery.test.ts

@@ -104,6 +104,34 @@ test("discoverWorkspaces skips node_modules, .git, dist, .turbo, .cache, .agents
   expect(workspaces).toHaveLength(0);
 });
 
+test("discoverWorkspaces skips missions, test-fixtures, .stryker-tmp", async () => {
+  // Pipeline-managed workpieces/archives, fixture workshops, and mutation-testing
+  // sandboxes are not project workspaces — their AGENTS.md is owned elsewhere.
+  for (const skip of ["missions", "test-fixtures", ".stryker-tmp"]) {
+    await mkdir(join(tempDir, skip, "sub"), { recursive: true });
+    await writeFile(join(tempDir, skip, "sub", "package.json"), "{}");
+  }
+
+  const workspaces = discoverWorkspaces(tempDir);
+  expect(workspaces).toHaveLength(0);
+});
+
+// RFC-1150: consumer-declared exclusions (bindings.workspaces.skipDirs)
+
+test("discoverWorkspaces honors extraSkipDirs for consumer artifact dirs", async () => {
+  await mkdir(join(tempDir, "builds", "out"), { recursive: true });
+  await writeFile(join(tempDir, "builds", "out", "package.json"), "{}");
+  await mkdir(join(tempDir, "packages", "real-pkg"), { recursive: true });
+  await writeFile(join(tempDir, "packages", "real-pkg", "package.json"), "{}");
+
+  const without = discoverWorkspaces(tempDir);
+  expect(without.map((w) => w.path)).toContain(join("builds", "out"));
+
+  const withSkip = discoverWorkspaces(tempDir, undefined, ["builds"]);
+  expect(withSkip.map((w) => w.path)).not.toContain(join("builds", "out"));
+  expect(withSkip.map((w) => w.path)).toContain(join("packages", "real-pkg"));
+});
+
 test("discoverWorkspaces detects generated AGENTS.md", async () => {
   await mkdir(join(tempDir, "packages", "my-pkg"), { recursive: true });
   await writeFile(join(tempDir, "packages", "my-pkg", "package.json"), "{}");