forgeos 0.1.0-alpha.0

package/src/forge/compiler/fs/memory.ts

@@ -0,0 +1,233 @@
+/**
+ * InMemoryFileSystem — a test/double {@link FileSystem} with no disk access.
+ *
+ * Paths are normalised to forward slashes and stored flat. Directories are
+ * tracked both explicitly (via {@link InMemoryFileSystem.mkdirp}) and implicitly
+ * (any ancestor of a written file). This mirrors the observable behaviour of
+ * {@link NodeFileSystem} closely enough for compiler/authoring unit tests.
+ */
+import type { DirEntry, FileStat, FileSystem } from "./types.ts";
+
+function normalize(path: string): string {
+  const slashed = path.replace(/\\/g, "/").replace(/\/+/g, "/");
+  if (slashed.length > 1 && slashed.endsWith("/")) {
+    return slashed.slice(0, -1);
+  }
+  return slashed;
+}
+
+function parentOf(path: string): string | null {
+  const idx = path.lastIndexOf("/");
+  if (idx <= 0) {
+    return null;
+  }
+  return path.slice(0, idx);
+}
+
+export class InMemoryFileSystem implements FileSystem {
+  private readonly files = new Map<string, string>();
+  private readonly dirs = new Set<string>();
+  private tempCounter = 0;
+
+  constructor(initial?: Record<string, string>) {
+    if (initial) {
+      for (const [path, content] of Object.entries(initial)) {
+        this.writeText(path, content);
+      }
+    }
+  }
+
+  /** Snapshot of all stored files keyed by normalised path. */
+  snapshot(): Record<string, string> {
+    return Object.fromEntries(this.files);
+  }
+
+  private addAncestors(path: string): void {
+    let parent = parentOf(path);
+    while (parent !== null) {
+      this.dirs.add(parent);
+      parent = parentOf(parent);
+    }
+  }
+
+  readText(path: string): string | null {
+    const key = normalize(path);
+    return this.files.has(key) ? (this.files.get(key) as string) : null;
+  }
+
+  writeText(path: string, content: string): void {
+    const key = normalize(path);
+    this.files.set(key, content);
+    this.addAncestors(key);
+  }
+
+  exists(path: string): boolean {
+    const key = normalize(path);
+    return this.files.has(key) || this.isDirectory(key);
+  }
+
+  isDirectory(path: string): boolean {
+    const key = normalize(path);
+    if (this.dirs.has(key)) {
+      return true;
+    }
+    const prefix = `${key}/`;
+    for (const file of this.files.keys()) {
+      if (file.startsWith(prefix)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  readDir(path: string): DirEntry[] {
+    const key = normalize(path);
+    const prefix = key === "" ? "" : `${key}/`;
+    const childDirs = new Set<string>();
+    const childFiles = new Set<string>();
+
+    const consider = (entry: string, isFile: boolean): void => {
+      if (!entry.startsWith(prefix) || entry === key) {
+        return;
+      }
+      const rest = entry.slice(prefix.length);
+      if (rest === "") {
+        return;
+      }
+      const slash = rest.indexOf("/");
+      if (slash === -1) {
+        if (isFile) {
+          childFiles.add(rest);
+        } else {
+          childDirs.add(rest);
+        }
+      } else {
+        childDirs.add(rest.slice(0, slash));
+      }
+    };
+
+    for (const file of this.files.keys()) {
+      consider(file, true);
+    }
+    for (const dir of this.dirs) {
+      consider(dir, false);
+    }
+
+    const entries: DirEntry[] = [];
+    for (const name of childDirs) {
+      entries.push({ name, isDirectory: true, isFile: false });
+    }
+    for (const name of childFiles) {
+      if (!childDirs.has(name)) {
+        entries.push({ name, isDirectory: false, isFile: true });
+      }
+    }
+    return entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  }
+
+  mkdirp(path: string): void {
+    const key = normalize(path);
+    this.dirs.add(key);
+    this.addAncestors(key);
+  }
+
+  rename(from: string, to: string): void {
+    const fromKey = normalize(from);
+    const toKey = normalize(to);
+
+    if (this.files.has(fromKey)) {
+      this.files.set(toKey, this.files.get(fromKey) as string);
+      this.files.delete(fromKey);
+      this.addAncestors(toKey);
+      return;
+    }
+
+    // Directory move: relocate every descendant file and dir.
+    const prefix = `${fromKey}/`;
+    for (const file of [...this.files.keys()]) {
+      if (file.startsWith(prefix)) {
+        const moved = `${toKey}/${file.slice(prefix.length)}`;
+        this.files.set(moved, this.files.get(file) as string);
+        this.files.delete(file);
+        this.addAncestors(moved);
+      }
+    }
+    for (const dir of [...this.dirs]) {
+      if (dir === fromKey || dir.startsWith(prefix)) {
+        this.dirs.delete(dir);
+        const moved = dir === fromKey ? toKey : `${toKey}/${dir.slice(prefix.length)}`;
+        this.dirs.add(moved);
+      }
+    }
+  }
+
+  remove(path: string): void {
+    const key = normalize(path);
+    this.files.delete(key);
+    this.dirs.delete(key);
+    const prefix = `${key}/`;
+    for (const file of [...this.files.keys()]) {
+      if (file.startsWith(prefix)) {
+        this.files.delete(file);
+      }
+    }
+    for (const dir of [...this.dirs]) {
+      if (dir.startsWith(prefix)) {
+        this.dirs.delete(dir);
+      }
+    }
+  }
+
+  copy(from: string, to: string): void {
+    const fromKey = normalize(from);
+    const toKey = normalize(to);
+
+    if (this.files.has(fromKey)) {
+      this.writeText(toKey, this.files.get(fromKey) as string);
+      return;
+    }
+
+    const prefix = `${fromKey}/`;
+    for (const file of [...this.files.keys()]) {
+      if (file.startsWith(prefix)) {
+        const copied = `${toKey}/${file.slice(prefix.length)}`;
+        this.writeText(copied, this.files.get(file) as string);
+      }
+    }
+    this.mkdirp(toKey);
+  }
+
+  appendText(path: string, content: string): void {
+    const existing = this.readText(path) ?? "";
+    this.writeText(path, existing + content);
+  }
+
+  makeTempDir(prefix: string): string {
+    this.tempCounter += 1;
+    const dir = `${normalize(prefix)}${this.tempCounter.toString(36)}${Date.now().toString(36)}`;
+    this.mkdirp(dir);
+    return dir;
+  }
+
+  stat(path: string): FileStat | null {
+    const key = normalize(path);
+    if (this.files.has(key)) {
+      const content = this.files.get(key) as string;
+      return {
+        size: content.length,
+        mtimeMs: 0,
+        isDirectory: false,
+        isFile: true,
+      };
+    }
+    if (this.isDirectory(key)) {
+      return {
+        size: 0,
+        mtimeMs: 0,
+        isDirectory: true,
+        isFile: false,
+      };
+    }
+    return null;
+  }
+}

package/src/forge/compiler/fs/node.ts

@@ -0,0 +1,139 @@
+/**
+ * NodeFileSystem — the production {@link FileSystem} backed by `node:fs`.
+ *
+ * This is the single place in the codebase that should reach for synchronous
+ * `node:fs` primitives. Everything else depends on the {@link FileSystem}
+ * interface so it can be unit-tested against {@link InMemoryFileSystem}.
+ */
+import {
+  appendFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+import type { DirEntry, FileStat, FileSystem } from "./types.ts";
+
+export class NodeFileSystem implements FileSystem {
+  readText(path: string): string | null {
+    try {
+      return readFileSync(path, "utf8");
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === "ENOENT" || code === "EISDIR") {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Atomic write: stages content in a sibling temp file and renames it into
+   * place, so a crash mid-write never leaves a partially written artifact.
+   */
+  writeText(path: string, content: string): void {
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true });
+    const temporaryPath = join(
+      directory,
+      `.${basename(path)}.${process.pid}.tmp`,
+    );
+    try {
+      writeFileSync(temporaryPath, content, "utf8");
+      try {
+        renameSync(temporaryPath, path);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (process.platform !== "win32" || (code !== "EEXIST" && code !== "EPERM")) {
+          throw error;
+        }
+        rmSync(path, { force: true });
+        renameSync(temporaryPath, path);
+      }
+    } catch (error) {
+      try {
+        rmSync(temporaryPath, { force: true });
+      } catch {
+        // Ignore cleanup failures while surfacing the original write error.
+      }
+      throw error;
+    }
+  }
+
+  exists(path: string): boolean {
+    return existsSync(path);
+  }
+
+  readDir(path: string): DirEntry[] {
+    if (!existsSync(path)) {
+      return [];
+    }
+    return readdirSync(path, { withFileTypes: true }).map((entry) => ({
+      name: entry.name,
+      isDirectory: entry.isDirectory(),
+      isFile: entry.isFile(),
+    }));
+  }
+
+  mkdirp(path: string): void {
+    mkdirSync(path, { recursive: true });
+  }
+
+  rename(from: string, to: string): void {
+    mkdirSync(dirname(to), { recursive: true });
+    renameSync(from, to);
+  }
+
+  copy(from: string, to: string): void {
+    mkdirSync(dirname(to), { recursive: true });
+    cpSync(from, to, { recursive: true, force: true });
+  }
+
+  appendText(path: string, content: string): void {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, content, "utf8");
+  }
+
+  makeTempDir(prefix: string): string {
+    mkdirSync(dirname(prefix), { recursive: true });
+    return mkdtempSync(prefix);
+  }
+
+  remove(path: string): void {
+    if (existsSync(path)) {
+      rmSync(path, { recursive: true, force: true });
+    }
+  }
+
+  isDirectory(path: string): boolean {
+    return existsSync(path) && statSync(path).isDirectory();
+  }
+
+  stat(path: string): FileStat | null {
+    try {
+      const entry = statSync(path);
+      return {
+        size: entry.size,
+        mtimeMs: entry.mtimeMs,
+        isDirectory: entry.isDirectory(),
+        isFile: entry.isFile(),
+      };
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === "ENOENT") {
+        return null;
+      }
+      throw error;
+    }
+  }
+}
+
+/** Shared singleton for production call sites that want a default backend. */
+export const nodeFileSystem = new NodeFileSystem();

package/src/forge/compiler/fs/profile.ts

@@ -0,0 +1,108 @@
+import type { DirEntry, FileStat, FileSystem } from "./types.ts";
+
+export interface FileSystemProfile {
+  readText: number;
+  readTextBytes: number;
+  writeText: number;
+  writeTextBytes: number;
+  readDir: number;
+  stat: number;
+  exists: number;
+}
+
+function emptyProfile(): FileSystemProfile {
+  return {
+    readText: 0,
+    readTextBytes: 0,
+    writeText: 0,
+    writeTextBytes: 0,
+    readDir: 0,
+    stat: 0,
+    exists: 0,
+  };
+}
+
+let activeProfile: FileSystemProfile | null = null;
+
+export function isForgeProfileEnabled(): boolean {
+  return process.env.FORGE_PROFILE === "1" || process.env.FORGE_PROFILE === "true";
+}
+
+export function getFileSystemProfile(): FileSystemProfile | null {
+  return activeProfile;
+}
+
+export function resetFileSystemProfile(): void {
+  activeProfile = isForgeProfileEnabled() ? emptyProfile() : null;
+}
+
+export function formatFileSystemProfile(profile: FileSystemProfile): string {
+  return [
+    "forge fs profile:",
+    `  readText: ${profile.readText} (${profile.readTextBytes} bytes)`,
+    `  writeText: ${profile.writeText} (${profile.writeTextBytes} bytes)`,
+    `  readDir: ${profile.readDir}`,
+    `  stat: ${profile.stat}`,
+    `  exists: ${profile.exists}`,
+  ].join("\n");
+}
+
+export function createProfiledFileSystem(inner: FileSystem): FileSystem {
+  if (!activeProfile) {
+    activeProfile = emptyProfile();
+  }
+
+  const profile = activeProfile;
+
+  return {
+    readText(path: string): string | null {
+      const content = inner.readText(path);
+      profile.readText += 1;
+      if (content !== null) {
+        profile.readTextBytes += content.length;
+      }
+      return content;
+    },
+    writeText(path: string, content: string): void {
+      profile.writeText += 1;
+      profile.writeTextBytes += content.length;
+      inner.writeText(path, content);
+    },
+    exists(path: string): boolean {
+      profile.exists += 1;
+      return inner.exists(path);
+    },
+    readDir(path: string): DirEntry[] {
+      profile.readDir += 1;
+      return inner.readDir(path);
+    },
+    mkdirp(path: string): void {
+      inner.mkdirp(path);
+    },
+    rename(from: string, to: string): void {
+      inner.rename(from, to);
+    },
+    copy(from: string, to: string): void {
+      inner.copy(from, to);
+    },
+    appendText(path: string, content: string): void {
+      profile.writeText += 1;
+      profile.writeTextBytes += content.length;
+      inner.appendText(path, content);
+    },
+    makeTempDir(prefix: string): string {
+      return inner.makeTempDir(prefix);
+    },
+    remove(path: string): void {
+      inner.remove(path);
+    },
+    isDirectory(path: string): boolean {
+      profile.exists += 1;
+      return inner.isDirectory(path);
+    },
+    stat(path: string): FileStat | null {
+      profile.stat += 1;
+      return inner.stat(path);
+    },
+  };
+}

package/src/forge/compiler/fs/types.ts

@@ -0,0 +1,52 @@
+/**
+ * FileSystem — a minimal, injectable I/O abstraction.
+ *
+ * ForgeOS leaf code calls `node:fs` synchronous APIs directly, which makes pure
+ * unit testing impossible without touching the real disk or monkey-patching
+ * modules. This interface captures exactly the operations the compiler and
+ * authoring tools need, so production code can run on {@link NodeFileSystem}
+ * while tests run on an in-memory backend.
+ *
+ * The surface is intentionally synchronous to match the existing call sites and
+ * the deterministic, single-shot nature of the generators.
+ */
+
+export interface DirEntry {
+  name: string;
+  isDirectory: boolean;
+  isFile: boolean;
+}
+
+export interface FileStat {
+  size: number;
+  mtimeMs: number;
+  isDirectory: boolean;
+  isFile: boolean;
+}
+
+export interface FileSystem {
+  /** Return file contents as UTF-8, or `null` when the path does not exist. */
+  readText(path: string): string | null;
+  /** Write UTF-8 contents, creating parent directories as needed. */
+  writeText(path: string, content: string): void;
+  /** Whether a file or directory exists at the path. */
+  exists(path: string): boolean;
+  /** List immediate entries of a directory. Returns `[]` for a missing dir. */
+  readDir(path: string): DirEntry[];
+  /** Create a directory (and parents). No-op if it already exists. */
+  mkdirp(path: string): void;
+  /** Rename/move a file or directory. */
+  rename(from: string, to: string): void;
+  /** Recursively copy a file or directory tree (overwrites the target). */
+  copy(from: string, to: string): void;
+  /** Append UTF-8 text, creating the file and parent directories as needed. */
+  appendText(path: string, content: string): void;
+  /** Create a unique temporary directory for `prefix`; returns its path. */
+  makeTempDir(prefix: string): string;
+  /** Remove a file or directory tree. No-op if the path is absent. */
+  remove(path: string): void;
+  /** Whether the path exists and is a directory. */
+  isDirectory(path: string): boolean;
+  /** Metadata for an existing path, or `null` when absent. */
+  stat(path: string): FileStat | null;
+}

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

@@ -0,0 +1,96 @@
+import { GENERATED_DIR } from "../emitter/constants.ts";
+import { hashStable, serializeCanonical } from "../primitives/index.ts";
+import type { EmitFile } from "../types/emit.ts";
+import type { ModuleGraph } from "../types/app-graph.ts";
+import type { ImportGuardsArtifact } from "../types/import-guards.ts";
+import type { RuntimeMatrix } from "../types/runtime-matrix.ts";
+import { propagateContexts } from "./propagate-contexts.ts";
+
+export function buildImportGuardsArtifact(
+  matrix: RuntimeMatrix,
+  moduleGraph?: ModuleGraph,
+): ImportGuardsArtifact {
+  const entries = matrix.entries.map((entry) => ({
+    packageName: entry.packageName,
+    alias: entry.alias,
+    compatible: [...entry.compatible],
+    incompatible: [...entry.incompatible],
+    rationale: { ...entry.rationale },
+  }));
+
+  let moduleContexts: ImportGuardsArtifact["moduleContexts"] = [];
+  if (moduleGraph) {
+    propagateContexts(moduleGraph);
+    moduleContexts = moduleGraph.nodes
+      .filter((node) => node.effectiveContexts.length > 0)
+      .map((node) => ({
+        file: node.file,
+        effectiveContexts: [...node.effectiveContexts],
+      }))
+      .sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  }
+
+  return {
+    schemaVersion: matrix.schemaVersion,
+    entries,
+    moduleContexts,
+  };
+}
+
+function renderRuntimeMatrixTs(matrix: RuntimeMatrix): string {
+  return `export const runtimeMatrix = ${serializeCanonical(matrix).trim()} as const;\n`;
+}
+
+function renderImportGuardsTs(artifact: ImportGuardsArtifact): string {
+  return `export const importGuards = ${serializeCanonical(artifact).trim()} as const;\n`;
+}
+
+export function buildRuntimeMatrixEmitFiles(matrix: RuntimeMatrix): EmitFile[] {
+  const jsonBody = serializeCanonical(matrix);
+  const tsBody = renderRuntimeMatrixTs(matrix);
+
+  return [
+    {
+      path: `${GENERATED_DIR}/runtimeMatrix.json`,
+      content: jsonBody,
+      contentHash: hashStable(jsonBody),
+    },
+    {
+      path: `${GENERATED_DIR}/runtimeMatrix.ts`,
+      content: tsBody,
+      contentHash: hashStable(tsBody),
+    },
+  ];
+}
+
+export function buildImportGuardsEmitFiles(
+  matrix: RuntimeMatrix,
+  moduleGraph?: ModuleGraph,
+): EmitFile[] {
+  const artifact = buildImportGuardsArtifact(matrix, moduleGraph);
+  const jsonBody = serializeCanonical(artifact);
+  const tsBody = renderImportGuardsTs(artifact);
+
+  return [
+    {
+      path: `${GENERATED_DIR}/importGuards.json`,
+      content: jsonBody,
+      contentHash: hashStable(jsonBody),
+    },
+    {
+      path: `${GENERATED_DIR}/importGuards.ts`,
+      content: tsBody,
+      contentHash: hashStable(tsBody),
+    },
+  ];
+}
+
+export function buildGuardArtifactEmitFiles(
+  matrix: RuntimeMatrix,
+  moduleGraph?: ModuleGraph,
+): EmitFile[] {
+  return [
+    ...buildRuntimeMatrixEmitFiles(matrix),
+    ...buildImportGuardsEmitFiles(matrix, moduleGraph),
+  ];
+}