forgeos 0.1.0-alpha.0

package/src/forge/compiler/orchestrator/fast-check.ts

@@ -0,0 +1,117 @@
+import { join, relative } from "node:path";
+import { nodeFileSystem } from "../fs/index.ts";
+import { forgeDrift, forgeOrphanedGeneratedFile } from "../diagnostics/create.ts";
+import { BARREL_INDEX_PATH, FORGE_LOCK_PATH, GENERATED_DIR } from "../emitter/constants.ts";
+import { hashStable } from "../primitives/hash.ts";
+import { stripDeterministicHeader } from "../primitives/header.ts";
+import type { GenerateResult } from "../types/cli.ts";
+import type { Diagnostic } from "../types/diagnostic.ts";
+import { discover } from "./discover.ts";
+import { loadManifest } from "./manifest.ts";
+
+export type FastGenerateCheckResult =
+  | {
+      kind: "hit";
+      result: GenerateResult;
+    }
+  | {
+      kind: "miss";
+      reason: string;
+    };
+
+function normalizePath(path: string): string {
+  return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function readBodyHash(workspaceRoot: string, relativePath: string): string | null {
+  const absolute = join(workspaceRoot, relativePath);
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+  return hashStable(stripDeterministicHeader((nodeFileSystem.readText(absolute) ?? "")));
+}
+
+function walkGeneratedFiles(workspaceRoot: string, dir = GENERATED_DIR): string[] {
+  const absolute = join(workspaceRoot, dir);
+  if (!nodeFileSystem.exists(absolute)) {
+    return [];
+  }
+  const files: string[] = [];
+  for (const entry of nodeFileSystem.readDir(absolute)) {
+    const child = join(absolute, entry.name);
+    const rel = normalizePath(relative(workspaceRoot, child));
+    if (entry.isDirectory) {
+      files.push(...walkGeneratedFiles(workspaceRoot, rel));
+    } else {
+      files.push(rel);
+    }
+  }
+  return files.sort();
+}
+
+export function runFastGenerateCheck(workspaceRootInput: string): FastGenerateCheckResult {
+  const workspaceRoot = workspaceRootInput.replace(/\\/g, "/");
+  const cacheDir = join(workspaceRoot, ".forge", "cache");
+  const manifest = loadManifest(cacheDir);
+  const trackedFiles = Object.keys(manifest.fileHashes).sort();
+
+  if (!manifest.inputFingerprint || trackedFiles.length === 0) {
+    return { kind: "miss", reason: "manifest missing input fingerprint or file hashes" };
+  }
+  if (!manifest.fileHashes[BARREL_INDEX_PATH] || !manifest.fileHashes[FORGE_LOCK_PATH]) {
+    return { kind: "miss", reason: "manifest missing critical generated file hashes" };
+  }
+
+  const priorSourcesByPath = new Map(
+    (manifest.sourceSnapshot ?? []).map((source) => [source.path, source]),
+  );
+  const ctx = discover({
+    workspaceRoot,
+    priorSourceIndex: manifest.sourceFileIndex,
+    priorSourcesByPath,
+  });
+
+  if (manifest.inputFingerprint !== ctx.inputFingerprint) {
+    return { kind: "miss", reason: "workspace input fingerprint changed" };
+  }
+
+  const changed: string[] = [];
+  const unchanged: string[] = [];
+  const warnings: Diagnostic[] = [];
+  const errors: Diagnostic[] = [];
+
+  for (const file of trackedFiles) {
+    const actualHash = readBodyHash(workspaceRoot, file);
+    if (actualHash === manifest.fileHashes[file]) {
+      unchanged.push(file);
+    } else {
+      changed.push(file);
+      warnings.push(forgeDrift(file));
+    }
+  }
+
+  const trackedGenerated = new Set(
+    trackedFiles.filter((file) => file.startsWith(`${GENERATED_DIR}/`)),
+  );
+  for (const generatedFile of walkGeneratedFiles(workspaceRoot)) {
+    if (!trackedGenerated.has(generatedFile)) {
+      errors.push(forgeOrphanedGeneratedFile(generatedFile));
+    }
+  }
+
+  return {
+    kind: "hit",
+    result: {
+      changed,
+      unchanged,
+      warnings,
+      errors,
+      cache: {
+        strategy: "generated-check",
+        result: "hit",
+      },
+      exitCode: changed.length > 0 || errors.length > 0 ? 1 : 0,
+      ...(changed.length > 0 || errors.length > 0 ? { failureKind: "generated_drift" } : {}),
+    },
+  };
+}

package/src/forge/compiler/orchestrator/generate-lock.ts

@@ -0,0 +1,138 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createDiagnostic } from "../diagnostics/create.ts";
+import type { Diagnostic } from "../types/diagnostic.ts";
+
+export const GENERATE_LOCK_FAILURE_KIND = "generate-lock-timeout";
+
+const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
+const DEFAULT_LOCK_POLL_MS = 50;
+
+export interface GenerateLockOptions {
+  timeoutMs?: number;
+  pollMs?: number;
+}
+
+export interface GenerateLockHandle {
+  lockPath: string;
+  release(): void;
+}
+
+export type GenerateLockResult =
+  | { ok: true; handle: GenerateLockHandle }
+  | { ok: false; diagnostic: Diagnostic; failureKind: typeof GENERATE_LOCK_FAILURE_KIND };
+
+function parsePositiveInteger(value: string | undefined): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return undefined;
+  }
+  return Math.floor(parsed);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function lockTimeoutDiagnostic(lockPath: string, timeoutMs: number): Diagnostic {
+  return createDiagnostic({
+    severity: "error",
+    code: "FORGE_GENERATE_LOCKED",
+    message: `forge generate is already running or a stale generate lock exists at ${lockPath} after ${timeoutMs}ms`,
+    file: lockPath,
+  });
+}
+
+function readLockOwnerPid(lockPath: string): number | null {
+  try {
+    const raw = readFileSync(join(lockPath, "owner.json"), "utf8");
+    const parsed = JSON.parse(raw) as { pid?: unknown };
+    return typeof parsed.pid === "number" && Number.isInteger(parsed.pid)
+      ? parsed.pid
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  if (pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ESRCH" || code === "EINVAL") {
+      return false;
+    }
+    return true;
+  }
+}
+
+function recoverStaleLock(lockPath: string): boolean {
+  const ownerPid = readLockOwnerPid(lockPath);
+  if (ownerPid === null || isProcessAlive(ownerPid)) {
+    return false;
+  }
+  rmSync(lockPath, { recursive: true, force: true });
+  return true;
+}
+
+export async function acquireGenerateLock(
+  workspaceRoot: string,
+  options: GenerateLockOptions = {},
+): Promise<GenerateLockResult> {
+  const timeoutMs =
+    options.timeoutMs ??
+    parsePositiveInteger(process.env.FORGE_GENERATE_LOCK_TIMEOUT_MS) ??
+    DEFAULT_LOCK_TIMEOUT_MS;
+  const pollMs = options.pollMs ?? DEFAULT_LOCK_POLL_MS;
+  const locksDir = join(workspaceRoot, ".forge", "locks");
+  const lockPath = join(locksDir, "generate.lock");
+  const startedAt = Date.now();
+
+  while (true) {
+    try {
+      mkdirSync(locksDir, { recursive: true });
+      mkdirSync(lockPath);
+      writeFileSync(
+        join(lockPath, "owner.json"),
+        `${JSON.stringify({ pid: process.pid }, null, 2)}\n`,
+        "utf8",
+      );
+      return {
+        ok: true,
+        handle: {
+          lockPath,
+          release() {
+            rmSync(lockPath, { recursive: true, force: true });
+          },
+        },
+      };
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "EEXIST") {
+        throw error;
+      }
+
+      if (recoverStaleLock(lockPath)) {
+        continue;
+      }
+
+      if (Date.now() - startedAt >= timeoutMs) {
+        return {
+          ok: false,
+          diagnostic: lockTimeoutDiagnostic(lockPath, timeoutMs),
+          failureKind: GENERATE_LOCK_FAILURE_KIND,
+        };
+      }
+
+      await sleep(pollMs);
+    }
+  }
+}

package/src/forge/compiler/orchestrator/guards.ts

@@ -0,0 +1,5 @@
+export { propagateContexts } from "../guards/propagate-contexts.ts";
+export {
+  checkImportGuards,
+  isContextViolating,
+} from "../guards/check-import-guards.ts";

package/src/forge/compiler/orchestrator/index.ts

@@ -0,0 +1,27 @@
+export type {
+  DiscoverContext,
+  OrchestratorManifest,
+} from "./types.ts";
+export { ORCHESTRATOR_MANIFEST_VERSION } from "./types.ts";
+export { discover, type DiscoverOptions } from "./discover.ts";
+export { plan, type PlanInput } from "./plan.ts";
+export {
+  run,
+  createGenerationOrchestrator,
+  type GenerationOrchestrator,
+} from "./run.ts";
+export { loadManifest, saveManifest, updateManifestAfterWrite } from "./manifest.ts";
+export { verifyLockIntegrity } from "./verify.ts";
+export { detectOrphanedGeneratedFiles } from "./orphans.ts";
+export {
+  serializeAppGraphJson,
+  serializeAppGraphTs,
+  serializePackageGraphJson,
+  serializePackageGraphTs,
+  serializeRuntimeMatrixJson,
+  serializeRuntimeMatrixTs,
+  serializeImportGuardsJson,
+  serializeImportGuardsTs,
+  type ImportGuardsArtifact,
+} from "./serialize.ts";
+export { buildImportGuardsArtifact } from "../guards/artifacts.ts";

package/src/forge/compiler/orchestrator/manifest-hashes.ts

@@ -0,0 +1,21 @@
+import { buildBarrelIndexBody } from "../emitter/barrel.ts";
+import { BARREL_INDEX_PATH, FORGE_LOCK_PATH } from "../emitter/constants.ts";
+import { serializeForgeLock } from "../emitter/lock.ts";
+import { renderBody } from "../emitter/render.ts";
+import { hashStable } from "../primitives/hash.ts";
+import type { EmitPlan } from "../types/emit.ts";
+
+export function buildManifestFileHashes(plan: EmitPlan): Record<string, string> {
+  const hashes: Record<string, string> = {};
+  const exportPaths = plan.files.map((file) => file.path);
+
+  for (const file of plan.files) {
+    hashes[file.path] = hashStable(renderBody(file));
+  }
+
+  const barrelBody = buildBarrelIndexBody(exportPaths);
+  hashes[BARREL_INDEX_PATH] = hashStable(barrelBody);
+  hashes[FORGE_LOCK_PATH] = hashStable(serializeForgeLock(plan.lock));
+
+  return hashes;
+}

package/src/forge/compiler/orchestrator/manifest.ts

@@ -0,0 +1,92 @@
+import { join } from "node:path";
+import { nodeFileSystem } from "../fs/index.ts";
+import type { AppGraph } from "../types/app-graph.ts";
+import { canonicalJson } from "../primitives/serialize.ts";
+import {
+  ORCHESTRATOR_MANIFEST_VERSION,
+  type OrchestratorManifest,
+} from "./types.ts";
+
+const MANIFEST_FILENAME = "manifest.json";
+
+export function manifestPath(cacheDir: string): string {
+  return join(cacheDir, MANIFEST_FILENAME);
+}
+
+export function loadManifest(cacheDir: string): OrchestratorManifest {
+  nodeFileSystem.mkdirp(cacheDir);
+  const path = manifestPath(cacheDir);
+
+  const raw = nodeFileSystem.readText(path);
+  if (raw !== null) {
+    try {
+      const parsed = JSON.parse(raw) as OrchestratorManifest;
+      return {
+        schemaVersion: parsed.schemaVersion ?? ORCHESTRATOR_MANIFEST_VERSION,
+        fileHashes: parsed.fileHashes ?? {},
+        ...(parsed.priorAppGraph !== undefined
+          ? { priorAppGraph: parsed.priorAppGraph }
+          : {}),
+        ...(parsed.inputFingerprint !== undefined
+          ? { inputFingerprint: parsed.inputFingerprint }
+          : {}),
+        ...(parsed.sourceFileIndex !== undefined
+          ? { sourceFileIndex: parsed.sourceFileIndex }
+          : {}),
+        ...(parsed.sourceSnapshot !== undefined
+          ? { sourceSnapshot: parsed.sourceSnapshot }
+          : {}),
+      };
+    } catch {
+      // fall through to the default manifest below
+    }
+  }
+  return {
+    schemaVersion: ORCHESTRATOR_MANIFEST_VERSION,
+    fileHashes: {},
+  };
+}
+
+export function saveManifest(
+  cacheDir: string,
+  manifest: OrchestratorManifest,
+): void {
+  const path = manifestPath(cacheDir);
+
+  const payload: OrchestratorManifest = {
+    schemaVersion: ORCHESTRATOR_MANIFEST_VERSION,
+    fileHashes: manifest.fileHashes,
+    ...(manifest.priorAppGraph !== undefined
+      ? { priorAppGraph: manifest.priorAppGraph }
+      : {}),
+    ...(manifest.inputFingerprint !== undefined
+      ? { inputFingerprint: manifest.inputFingerprint }
+      : {}),
+    ...(manifest.sourceFileIndex !== undefined
+      ? { sourceFileIndex: manifest.sourceFileIndex }
+      : {}),
+    ...(manifest.sourceSnapshot !== undefined
+      ? { sourceSnapshot: manifest.sourceSnapshot }
+      : {}),
+  };
+
+  nodeFileSystem.writeText(path, `${canonicalJson(payload)}\n`);
+}
+
+export function updateManifestAfterWrite(
+  manifest: OrchestratorManifest,
+  fileHashes: Record<string, string>,
+  priorAppGraph: AppGraph,
+  inputFingerprint: string,
+  sourceFileIndex?: OrchestratorManifest["sourceFileIndex"],
+  sourceSnapshot?: OrchestratorManifest["sourceSnapshot"],
+): OrchestratorManifest {
+  return {
+    ...manifest,
+    fileHashes: { ...manifest.fileHashes, ...fileHashes },
+    priorAppGraph,
+    inputFingerprint,
+    ...(sourceFileIndex !== undefined ? { sourceFileIndex } : {}),
+    ...(sourceSnapshot !== undefined ? { sourceSnapshot } : {}),
+  };
+}

package/src/forge/compiler/orchestrator/orphans.ts

@@ -0,0 +1,51 @@
+import { join, relative } from "node:path";
+import { nodeFileSystem } from "../fs/index.ts";
+import { normalizePath } from "../primitives/paths.ts";
+import { stableSortByPath } from "../primitives/sort.ts";
+import { BARREL_INDEX_PATH } from "../emitter/constants.ts";
+
+function listGeneratedFiles(
+  workspaceRoot: string,
+  generatedDir: string,
+): string[] {
+  const absoluteGenerated = join(workspaceRoot, generatedDir);
+  if (!nodeFileSystem.exists(absoluteGenerated)) {
+    return [];
+  }
+
+  const files: string[] = [];
+
+  function walk(absoluteDir: string): void {
+    for (const entry of nodeFileSystem.readDir(absoluteDir)) {
+      const absolutePath = join(absoluteDir, entry.name);
+      if (entry.isDirectory) {
+        walk(absolutePath);
+        continue;
+      }
+      if (!entry.isFile) {
+        continue;
+      }
+      files.push(
+        normalizePath(relative(workspaceRoot, absolutePath)),
+      );
+    }
+  }
+
+  walk(absoluteGenerated);
+  return stableSortByPath(files);
+}
+
+export function detectOrphanedGeneratedFiles(
+  workspaceRoot: string,
+  generatedDir: string,
+  plannedPaths: ReadonlySet<string>,
+): string[] {
+  const existing = listGeneratedFiles(workspaceRoot, generatedDir);
+  const orphans = existing.filter((path) => {
+    if (path === BARREL_INDEX_PATH) {
+      return false;
+    }
+    return !plannedPaths.has(path);
+  });
+  return stableSortByPath(orphans);
+}