forgeos 0.1.0-alpha.0

package/src/forge/compiler/policy-registry/parse.ts

@@ -0,0 +1,81 @@
+const POLICY_ROLE_PATTERN =
+  /["']([^"']+)["']\s*:\s*canRole\s*\(\s*([^)]*)\)/g;
+
+const COMMAND_AUTH_CAN_PATTERN = /auth\s*:\s*can\s*\(\s*["']([^"']+)["']\s*\)/;
+const COMMAND_AUTH_PUBLIC_PATTERN = /auth\s*:\s*public_\s*\(\s*\)/;
+const COMMAND_AUTH_SYSTEM_PATTERN = /auth\s*:\s*system\s*\(\s*\)/;
+
+function parseRolesFromCanRoleArg(arg: string): string[] {
+  const roles: string[] = [];
+  for (const match of arg.matchAll(/["']([^"']+)["']/g)) {
+    const role = match[1];
+    if (role && !roles.includes(role)) {
+      roles.push(role);
+    }
+  }
+  return roles;
+}
+
+export function parsePoliciesFromSlice(sourceSlice: string): Array<{
+  name: string;
+  kind: "roles" | "public" | "system";
+  roles: string[];
+}> {
+  const policies: Array<{
+    name: string;
+    kind: "roles" | "public" | "system";
+    roles: string[];
+  }> = [];
+
+  for (const match of sourceSlice.matchAll(POLICY_ROLE_PATTERN)) {
+    const name = match[1];
+    const rolesArg = match[2] ?? "";
+    if (!name) {
+      continue;
+    }
+    policies.push({
+      name,
+      kind: "roles",
+      roles: parseRolesFromCanRoleArg(rolesArg),
+    });
+  }
+
+  return policies;
+}
+
+export function parseCommandAuthFromSlice(sourceSlice: string):
+  | { kind: "policy"; policy: string }
+  | { kind: "public" }
+  | { kind: "system" }
+  | { kind: "user" } {
+  return parseAuthFromSlice(sourceSlice);
+}
+
+export function parseQueryAuthFromSlice(sourceSlice: string):
+  | { kind: "policy"; policy: string }
+  | { kind: "public" }
+  | { kind: "system" }
+  | { kind: "user" } {
+  return parseAuthFromSlice(sourceSlice);
+}
+
+export function parseAuthFromSlice(sourceSlice: string):
+  | { kind: "policy"; policy: string }
+  | { kind: "public" }
+  | { kind: "system" }
+  | { kind: "user" } {
+  const canMatch = sourceSlice.match(COMMAND_AUTH_CAN_PATTERN);
+  if (canMatch?.[1]) {
+    return { kind: "policy", policy: canMatch[1] };
+  }
+
+  if (COMMAND_AUTH_PUBLIC_PATTERN.test(sourceSlice)) {
+    return { kind: "public" };
+  }
+
+  if (COMMAND_AUTH_SYSTEM_PATTERN.test(sourceSlice)) {
+    return { kind: "system" };
+  }
+
+  return { kind: "public" };
+}

package/src/forge/compiler/primitives/compare.ts

@@ -0,0 +1,26 @@
+/**
+ * Compare two strings by UTF-8 byte sequence (case-sensitive, locale-independent).
+ * Returns negative if a < b, positive if a > b, zero if equal.
+ */
+export function compareBytes(a: string, b: string): number {
+  const aBytes = new TextEncoder().encode(a);
+  const bBytes = new TextEncoder().encode(b);
+  const len = Math.min(aBytes.length, bBytes.length);
+
+  for (let i = 0; i < len; i++) {
+    const diff = aBytes[i]! - bBytes[i]!;
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+
+  return aBytes.length - bBytes.length;
+}
+
+export function compareBytesAsc(a: string, b: string): number {
+  return compareBytes(a, b);
+}
+
+export function compareBytesDesc(a: string, b: string): number {
+  return compareBytes(b, a);
+}

package/src/forge/compiler/primitives/hash.ts

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import { stripDeterministicHeader } from "./header.ts";
+
+/**
+ * SHA-256 hash of UTF-8 content, returned as lowercase hex.
+ */
+export function hashStable(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+/**
+ * Hash content after stripping the deterministic header (for diff/cache keys).
+ */
+export function hashStableBody(content: string): string {
+  return hashStable(stripDeterministicHeader(content));
+}
+
+export interface StableSymbolIdInput {
+  kind: string;
+  canonicalModulePath: string;
+  qualifiedName: string;
+  exportPath: string;
+}
+
+/**
+ * Derive a collision-safe stable symbol id from kind + module + name + export path.
+ */
+export function deriveStableSymbolId(input: StableSymbolIdInput): string {
+  const parts = [
+    input.kind,
+    input.canonicalModulePath,
+    input.qualifiedName,
+    input.exportPath,
+  ];
+  return hashStable(parts.join("\0"));
+}
+
+export function hashUtf8Bytes(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}

package/src/forge/compiler/primitives/header.ts

@@ -0,0 +1,45 @@
+import { hashStable } from "./hash.ts";
+
+export const DETERMINISTIC_HEADER_PREFIX = "// @forge-generated";
+
+export interface DeterministicHeaderFields {
+  generatorVersion: string;
+  inputHash: string;
+  contentHash: string;
+}
+
+const HEADER_PATTERN =
+  /^\/\/ @forge-generated generator=([^\s]+) input=([^\s]+) content=([^\s]+)\r?\n/;
+
+export function formatDeterministicHeader(
+  fields: DeterministicHeaderFields,
+): string {
+  return `${DETERMINISTIC_HEADER_PREFIX} generator=${fields.generatorVersion} input=${fields.inputHash} content=${fields.contentHash}\n`;
+}
+
+export function parseDeterministicHeader(
+  content: string,
+): DeterministicHeaderFields | null {
+  const match = content.match(HEADER_PATTERN);
+  if (match === null) {
+    return null;
+  }
+
+  return {
+    generatorVersion: match[1]!,
+    inputHash: match[2]!,
+    contentHash: match[3]!,
+  };
+}
+
+export function stripDeterministicHeader(content: string): string {
+  return content.replace(HEADER_PATTERN, "");
+}
+
+export function prependDeterministicHeader(
+  body: string,
+  fields: Omit<DeterministicHeaderFields, "contentHash">,
+): string {
+  const contentHash = hashStable(body);
+  return formatDeterministicHeader({ ...fields, contentHash }) + body;
+}

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

@@ -0,0 +1,45 @@
+export { Result, ok, err, isOk, isErr } from "./result.ts";
+export type { Ok, Err } from "./result.ts";
+export {
+  compareBytes,
+  compareBytesAsc,
+  compareBytesDesc,
+} from "./compare.ts";
+export { normalizePath, comparePaths } from "./paths.ts";
+export {
+  hashStable,
+  hashStableBody,
+  deriveStableSymbolId,
+  hashUtf8Bytes,
+} from "./hash.ts";
+export type { StableSymbolIdInput } from "./hash.ts";
+export {
+  DETERMINISTIC_HEADER_PREFIX,
+  formatDeterministicHeader,
+  parseDeterministicHeader,
+  stripDeterministicHeader,
+  prependDeterministicHeader,
+} from "./header.ts";
+export type { DeterministicHeaderFields } from "./header.ts";
+export {
+  normalizeNewlines,
+  canonicalJson,
+  serializeCanonical,
+  serializeJsonValue,
+} from "./serialize.ts";
+export {
+  compareSymbols,
+  compareEdges,
+  comparePackages,
+  compareEntrypoints,
+  compareExports,
+  compareEmitFiles,
+  stableSortSymbols,
+  stableSortEdges,
+  stableSortPackages,
+  stableSortEntrypoints,
+  stableSortExports,
+  stableSortEmitFiles,
+  stableSortStrings,
+  stableSortByPath,
+} from "./sort.ts";

package/src/forge/compiler/primitives/paths.ts

@@ -0,0 +1,24 @@
+import { compareBytes } from "./compare.ts";
+
+/**
+ * Normalize a path to workspace-relative POSIX form with `/` separators.
+ */
+export function normalizePath(path: string): string {
+  let normalized = path.replace(/\\/g, "/");
+
+  while (normalized.startsWith("./")) {
+    normalized = normalized.slice(2);
+  }
+
+  normalized = normalized.replace(/\/+/g, "/");
+
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  return normalized;
+}
+
+export function comparePaths(a: string, b: string): number {
+  return compareBytes(normalizePath(a), normalizePath(b));
+}

package/src/forge/compiler/primitives/result.ts

@@ -0,0 +1,164 @@
+/**
+ * Result<T, E> — a unified, type-safe success/failure value.
+ *
+ * ForgeOS historically mixed three error-signalling styles: thrown exceptions
+ * from I/O code, `null` returns from lookups, and `Diagnostic[]` from the
+ * compiler pipeline. `Result` gives leaf code a single, composable primitive so
+ * callers can no longer confuse "produced nothing" with "failed".
+ *
+ * Conventions:
+ * - The default error type is `Diagnostic[]`, matching the compiler pipeline.
+ * - Construct with {@link ok} / {@link err}.
+ * - Narrow with the `result.ok` discriminant, or use the combinators below.
+ * - Keep these helpers pure and dependency-free (primitive layer rules).
+ */
+import type { Diagnostic } from "../types/diagnostic.ts";
+
+export interface Ok<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+
+export interface Err<E> {
+  readonly ok: false;
+  readonly error: E;
+}
+
+export type Result<T, E = Diagnostic[]> = Ok<T> | Err<E>;
+
+/** Wrap a success value. */
+export function ok<T>(value: T): Ok<T> {
+  return { ok: true, value };
+}
+
+/** Wrap a failure value. */
+export function err<E>(error: E): Err<E> {
+  return { ok: false, error };
+}
+
+/** Type guard narrowing a `Result` to its success branch. */
+export function isOk<T, E>(result: Result<T, E>): result is Ok<T> {
+  return result.ok;
+}
+
+/** Type guard narrowing a `Result` to its failure branch. */
+export function isErr<T, E>(result: Result<T, E>): result is Err<E> {
+  return !result.ok;
+}
+
+/** Transform the success value, leaving failures untouched. */
+export function map<T, U, E>(
+  result: Result<T, E>,
+  fn: (value: T) => U,
+): Result<U, E> {
+  return result.ok ? ok(fn(result.value)) : result;
+}
+
+/** Transform the failure value, leaving successes untouched. */
+export function mapErr<T, E, F>(
+  result: Result<T, E>,
+  fn: (error: E) => F,
+): Result<T, F> {
+  return result.ok ? result : err(fn(result.error));
+}
+
+/** Chain a fallible computation onto a success (monadic bind). */
+export function flatMap<T, U, E>(
+  result: Result<T, E>,
+  fn: (value: T) => Result<U, E>,
+): Result<U, E> {
+  return result.ok ? fn(result.value) : result;
+}
+
+/** Return the success value or a fallback when the result is a failure. */
+export function unwrapOr<T, E>(result: Result<T, E>, fallback: T): T {
+  return result.ok ? result.value : fallback;
+}
+
+/** Return the success value or compute a fallback from the error. */
+export function unwrapOrElse<T, E>(
+  result: Result<T, E>,
+  fn: (error: E) => T,
+): T {
+  return result.ok ? result.value : fn(result.error);
+}
+
+/**
+ * Return the success value or throw. Use only at boundaries where a failure is
+ * genuinely unexpected; prefer the combinators above in normal flow.
+ */
+export function unwrap<T, E>(result: Result<T, E>, message?: string): T {
+  if (result.ok) {
+    return result.value;
+  }
+  throw new Error(message ?? `unwrap called on Err: ${stringifyError(result.error)}`);
+}
+
+/**
+ * Collect an array of results into a single result. Returns the first failure
+ * encountered, or an array of all success values when every result is `ok`.
+ */
+export function all<T, E>(results: ReadonlyArray<Result<T, E>>): Result<T[], E> {
+  const values: T[] = [];
+  for (const result of results) {
+    if (!result.ok) {
+      return result;
+    }
+    values.push(result.value);
+  }
+  return ok(values);
+}
+
+/**
+ * Run a throwing function and capture any exception as an `Err`. The optional
+ * `onError` mapper converts the caught value into the desired error type
+ * (defaults to the raw `unknown`).
+ */
+export function fromThrowable<T>(fn: () => T): Result<T, unknown>;
+export function fromThrowable<T, E>(
+  fn: () => T,
+  onError: (error: unknown) => E,
+): Result<T, E>;
+export function fromThrowable<T, E>(
+  fn: () => T,
+  onError?: (error: unknown) => E,
+): Result<T, E | unknown> {
+  try {
+    return ok(fn());
+  } catch (error) {
+    return err(onError ? onError(error) : error);
+  }
+}
+
+/**
+ * Value-namespace companion to the `Result` type. Lets consumers import a
+ * single symbol and call `Result.ok(...)`, `Result.map(...)`, etc., without
+ * leaking generic helper names (`map`, `all`, ...) through barrel re-exports.
+ */
+export const Result = {
+  ok,
+  err,
+  isOk,
+  isErr,
+  map,
+  mapErr,
+  flatMap,
+  unwrapOr,
+  unwrapOrElse,
+  unwrap,
+  all,
+  fromThrowable,
+} as const;
+
+function stringifyError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (Array.isArray(error)) {
+    return error.map((item) => stringifyError(item)).join("; ");
+  }
+  if (typeof error === "object" && error !== null && "message" in error) {
+    return String((error as { message: unknown }).message);
+  }
+  return String(error);
+}

package/src/forge/compiler/primitives/serialize.ts

@@ -0,0 +1,66 @@
+import type { JsonValue } from "../types/json.ts";
+import { compareBytes } from "./compare.ts";
+
+/**
+ * Normalize line endings to LF and ensure exactly one trailing newline.
+ */
+export function normalizeNewlines(content: string): string {
+  const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (normalized.length === 0) {
+    return "\n";
+  }
+  return normalized.endsWith("\n") ? normalized : `${normalized}\n`;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+function sortObjectKeys(value: Record<string, unknown>): Record<string, unknown> {
+  const sorted: Record<string, unknown> = {};
+  const keys = Object.keys(value).sort(compareBytes);
+  for (const key of keys) {
+    sorted[key] = canonicalizeValue(value[key]);
+  }
+  return sorted;
+}
+
+function canonicalizeValue(value: unknown): unknown {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(canonicalizeValue);
+  }
+
+  if (isPlainObject(value)) {
+    return sortObjectKeys(value);
+  }
+
+  return value;
+}
+
+/**
+ * Serialize a value to canonical JSON with stable key ordering.
+ */
+export function canonicalJson(value: unknown): string {
+  const canonical = canonicalizeValue(value);
+  return JSON.stringify(canonical);
+}
+
+/**
+ * Serialize to canonical JSON with normalized newlines and trailing newline.
+ */
+export function serializeCanonical(value: unknown): string {
+  return normalizeNewlines(canonicalJson(value));
+}
+
+export function serializeJsonValue(value: JsonValue): string {
+  return serializeCanonical(value);
+}

package/src/forge/compiler/primitives/sort.ts

@@ -0,0 +1,87 @@
+import type { ForgeEdge, ForgeSymbol } from "../types/app-graph.ts";
+import type { EmitFile } from "../types/emit.ts";
+import type {
+  Entrypoint,
+  ExportSignature,
+  PackageApi,
+} from "../types/package-graph.ts";
+import { compareBytes } from "./compare.ts";
+import { comparePaths } from "./paths.ts";
+
+function stableSortInPlace<T>(items: T[], compare: (a: T, b: T) => number): T[] {
+  items.sort(compare);
+  return items;
+}
+
+export function compareSymbols(a: ForgeSymbol, b: ForgeSymbol): number {
+  let cmp = compareBytes(a.kind, b.kind);
+  if (cmp !== 0) return cmp;
+
+  cmp = compareBytes(a.name, b.name);
+  if (cmp !== 0) return cmp;
+
+  cmp = comparePaths(a.file, b.file);
+  if (cmp !== 0) return cmp;
+
+  return a.span.start - b.span.start;
+}
+
+export function compareEdges(a: ForgeEdge, b: ForgeEdge): number {
+  let cmp = compareBytes(a.from, b.from);
+  if (cmp !== 0) return cmp;
+
+  cmp = compareBytes(a.to, b.to);
+  if (cmp !== 0) return cmp;
+
+  return compareBytes(a.kind, b.kind);
+}
+
+export function comparePackages(a: PackageApi, b: PackageApi): number {
+  return compareBytes(a.name, b.name);
+}
+
+export function compareEntrypoints(a: Entrypoint, b: Entrypoint): number {
+  return compareBytes(a.subpath, b.subpath);
+}
+
+export function compareExports(a: ExportSignature, b: ExportSignature): number {
+  return compareBytes(a.name, b.name);
+}
+
+export function compareEmitFiles(a: EmitFile, b: EmitFile): number {
+  return comparePaths(a.path, b.path);
+}
+
+export function stableSortSymbols(symbols: ForgeSymbol[]): ForgeSymbol[] {
+  return stableSortInPlace([...symbols], compareSymbols);
+}
+
+export function stableSortEdges(edges: ForgeEdge[]): ForgeEdge[] {
+  return stableSortInPlace([...edges], compareEdges);
+}
+
+export function stableSortPackages(packages: PackageApi[]): PackageApi[] {
+  return stableSortInPlace([...packages], comparePackages);
+}
+
+export function stableSortEntrypoints(
+  entrypoints: Entrypoint[],
+): Entrypoint[] {
+  return stableSortInPlace([...entrypoints], compareEntrypoints);
+}
+
+export function stableSortExports(exports: ExportSignature[]): ExportSignature[] {
+  return stableSortInPlace([...exports], compareExports);
+}
+
+export function stableSortEmitFiles(files: EmitFile[]): EmitFile[] {
+  return stableSortInPlace([...files], compareEmitFiles);
+}
+
+export function stableSortStrings(items: string[]): string[] {
+  return stableSortInPlace([...items], compareBytes);
+}
+
+export function stableSortByPath(items: string[]): string[] {
+  return stableSortInPlace([...items], comparePaths);
+}

package/src/forge/compiler/query-registry/build.ts

@@ -0,0 +1,114 @@
+import { createDiagnostic } from "../diagnostics/create.ts";
+import { GENERATOR_VERSION } from "../emitter/constants.ts";
+import { hashStable } from "../primitives/hash.ts";
+import { canonicalJson } from "../primitives/serialize.ts";
+import type { AppGraph } from "../types/app-graph.ts";
+import type { QueryDefinition, QueryRegistry } from "../types/query-registry.ts";
+import {
+  QUERY_REGISTRY_ANALYZER_VERSION,
+  QUERY_REGISTRY_SCHEMA_VERSION,
+} from "./constants.ts";
+
+function moduleIdForFile(
+  moduleGraph: AppGraph["moduleGraph"],
+  file: string,
+): string | null {
+  const node = moduleGraph.nodes.find((candidate) => candidate.file === file);
+  return node?.id ?? null;
+}
+
+function stableSortQueries(queries: QueryDefinition[]): QueryDefinition[] {
+  return [...queries].sort((a, b) => {
+    if (a.name !== b.name) {
+      return a.name < b.name ? -1 : 1;
+    }
+    return a.file < b.file ? -1 : a.file > b.file ? 1 : 0;
+  });
+}
+
+function detectDuplicateQueryNames(queries: QueryDefinition[]): QueryRegistry["diagnostics"] {
+  const byName = new Map<string, QueryDefinition[]>();
+
+  for (const query of queries) {
+    const list = byName.get(query.name) ?? [];
+    list.push(query);
+    byName.set(query.name, list);
+  }
+
+  const diagnostics: QueryRegistry["diagnostics"] = [];
+
+  for (const [name, group] of byName) {
+    if (group.length <= 1) {
+      continue;
+    }
+
+    for (const query of group) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "warning",
+          code: "FORGE_DUP_QUERY",
+          message: `duplicate query name '${name}'`,
+          file: query.file,
+        }),
+      );
+    }
+  }
+
+  return diagnostics.sort((a, b) => {
+    const fileA = a.file ?? "";
+    const fileB = b.file ?? "";
+    if (fileA !== fileB) {
+      return fileA < fileB ? -1 : 1;
+    }
+    return a.message < b.message ? -1 : a.message > b.message ? 1 : 0;
+  });
+}
+
+export function buildQueryRegistry(appGraph: AppGraph): QueryRegistry {
+  const queries: QueryDefinition[] = [];
+  const diagnostics: QueryRegistry["diagnostics"] = [];
+
+  for (const symbol of appGraph.symbols) {
+    if (symbol.kind !== "query") {
+      continue;
+    }
+
+    const moduleId = moduleIdForFile(appGraph.moduleGraph, symbol.file);
+    if (moduleId === null) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "warning",
+          code: "FORGE_QUERY_UNRESOLVABLE",
+          message: `cannot resolve module for query '${symbol.qualifiedName}'`,
+          file: symbol.file,
+          span: symbol.span,
+        }),
+      );
+      continue;
+    }
+
+    queries.push({
+      name: symbol.name,
+      qualifiedName: symbol.qualifiedName,
+      file: symbol.file,
+      symbolId: symbol.id,
+      moduleId,
+    });
+  }
+
+  const dupDiagnostics = detectDuplicateQueryNames(queries);
+
+  return {
+    schemaVersion: QUERY_REGISTRY_SCHEMA_VERSION,
+    generatorVersion: GENERATOR_VERSION,
+    analyzerVersion: QUERY_REGISTRY_ANALYZER_VERSION,
+    inputHash: hashStable(
+      canonicalJson({
+        appInputHash: appGraph.inputHash,
+        analyzerVersion: QUERY_REGISTRY_ANALYZER_VERSION,
+      }),
+    ),
+    queries: stableSortQueries(queries),
+    diagnostics: [...diagnostics, ...dupDiagnostics],
+  };
+}

package/src/forge/compiler/query-registry/constants.ts

@@ -0,0 +1,2 @@
+export const QUERY_REGISTRY_SCHEMA_VERSION = "1.0.0";
+export const QUERY_REGISTRY_ANALYZER_VERSION = "1.0.0";