@warpgogol/forge 2.8.0 → 2.8.1

package/os/compass/handlers/resolve-scan-root-workpiece.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { resolveCompassScanRoot } from "./resolve-scan-root.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../src/types.ts";
+
+function makeContext(workspaceRoot: string, siteExplicit = false): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    site: undefined,
+    siteExplicit,
+    dryRun: false,
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+  } as unknown as ForgeRuntimeContext;
+}
+
+function makeInput(flags: Record<string, unknown> = {}): ForgeCommandInput {
+  return { flags } as ForgeCommandInput;
+}
+
+describe("resolveCompassScanRoot --workpiece (RFC-0617)", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "compass-workpiece-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("returns the resolved workpiece path when --workpiece is set", () => {
+    const relPath = "missions/test-mission/workpiece";
+    mkdirSync(join(tempDir, relPath), { recursive: true });
+    const result = resolveCompassScanRoot(makeInput({ workpiece: relPath }), makeContext(tempDir));
+    expect(result).toBe(join(tempDir, relPath));
+  });
+
+  it("throws when --workpiece and --packages are both set", () => {
+    expect(() =>
+      resolveCompassScanRoot(
+        makeInput({ workpiece: "some/path", packages: true }),
+        makeContext(tempDir),
+      ),
+    ).toThrow("--workpiece and --packages are mutually exclusive");
+  });
+
+  it("throws when --workpiece and --site are both set", () => {
+    expect(() =>
+      resolveCompassScanRoot(makeInput({ workpiece: "some/path" }), makeContext(tempDir, true)),
+    ).toThrow("--workpiece and --site are mutually exclusive");
+  });
+
+  it("throws when workpiece path does not exist", () => {
+    expect(() =>
+      resolveCompassScanRoot(makeInput({ workpiece: "nonexistent/path" }), makeContext(tempDir)),
+    ).toThrow("workpiece path not found");
+  });
+
+  it("ignores --workpiece when not set and falls through to site resolution", () => {
+    const result = resolveCompassScanRoot(makeInput({}), makeContext(tempDir));
+    expect(result).toBeUndefined();
+  });
+});

package/os/compass/handlers/resolve-scan-root.ts

@@ -0,0 +1,79 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Canonical Compass scan-root resolution for all Compass commands.
+Moved from @warpgogol/site-kernel to @warpgogol/forge for full autonomous mode (RFC-0556).</purpose>
+<non-goals>
+  <item>Do not implement Compass scanning or file processing logic here.</item>
+  <item>Do not register commands or modify runtime context.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Introduced as part of RFC-0015 to extend Compass commands to packages/.</item>
+  <item>RFC-0556: moved canonical implementation from @warpgogol/site-kernel to @warpgogol/forge for autonomous mode.</item>
+  <item>RFC-0617: added --workpiece flag for mission workpiece directory scanning.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../../src/types.ts";
+
+export function resolveCompassScanRoot(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): string | undefined {
+  const hasPackages = input.flags["packages"] === true;
+  const workpiecePath = input.flags["workpiece"];
+  const hasWorkpiece = typeof workpiecePath === "string" && workpiecePath.length > 0;
+
+  if (hasWorkpiece && hasPackages) {
+    throw new Error(
+      "[compass] --workpiece and --packages are mutually exclusive. Use one or the other.",
+    );
+  }
+
+  if (hasWorkpiece && context.siteExplicit) {
+    throw new Error(
+      "[compass] --workpiece and --site are mutually exclusive. Use one or the other.",
+    );
+  }
+
+  if (hasWorkpiece) {
+    const resolved = resolve(context.workspaceRoot, workpiecePath as string);
+    if (!existsSync(resolved)) {
+      throw new Error(`[compass] workpiece path not found: ${workpiecePath}`);
+    }
+    return resolved;
+  }
+
+  if (context.siteExplicit && hasPackages) {
+    throw new Error(
+      "[compass] --site and --packages are mutually exclusive. Use one or the other.",
+    );
+  }
+
+  if (!hasPackages) {
+    return context.site ? context.site.directory : undefined;
+  }
+
+  const packageName = input.flags["package"];
+  if (!packageName || typeof packageName !== "string") {
+    return resolve(context.workspaceRoot, "packages");
+  }
+
+  const candidates = [
+    resolve(context.workspaceRoot, "packages", "os", packageName),
+    resolve(context.workspaceRoot, "packages", packageName),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      const srcPath = resolve(candidate, "src");
+      return existsSync(srcPath) ? srcPath : candidate;
+    }
+  }
+
+  throw new Error(
+    `[compass] Package "${packageName}" not found. Tried:\n${candidates.map((c) => `  ${c}`).join("\n")}`,
+  );
+}

package/os/compass/index.ts

@@ -0,0 +1,33 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Expose the forge Compass kernel module through a stable package subpath.</purpose>
+<non-goals>
+  <item>Do not implement compass handler logic.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial compass module barrel.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { forgeCompassModule } from "./compass.module.ts";
+export {
+  createCompassInventoryEntries,
+  type CompassInventoryEntry,
+} from "./handlers/compass-inventory.ts";
+export { resolveCompassScanRoot } from "./handlers/resolve-scan-root.ts";
+export { getRevisionByPath, type RevisionByPathResult } from "./handlers/git-revision.ts";
+export { runCompassInventory, runCompassValidation } from "./handlers/compass-inventory-handler.ts";
+export {
+  runCompassAuditPlan,
+  runCompassAuditRecord,
+  runCompassAuditBaseline,
+  runCompassAuditValidate,
+  isAuditDue,
+} from "./handlers/compass-audit-handler.ts";
+export {
+  runCompassChangeSummaryValidate,
+  runCompassSummaryTrim,
+  classifyChangeSummaryItem,
+  type ChangeSummaryItemClass,
+} from "./handlers/compass-change-summary-handler.ts";