forgeos 0.1.0-alpha.0

package/src/forge/compiler/app-graph/build.ts

@@ -0,0 +1,121 @@
+import { canonicalJson } from "../primitives/serialize.ts";
+import { hashStable } from "../primitives/hash.ts";
+import { normalizePath } from "../primitives/paths.ts";
+import { stableSortEdges, stableSortSymbols } from "../primitives/sort.ts";
+import type { AppGraph, SourceFile } from "../types/app-graph.ts";
+import { detectDuplicateSymbols } from "./dup-symbol.ts";
+import { buildModuleGraph } from "./module-graph.ts";
+import { incrementalParse } from "./parser.ts";
+import { buildForgeSymbols } from "./symbols.ts";
+import { hashTsconfigForWorkspace } from "./tsconfig-hash.ts";
+import type { ParseInvalidationKey } from "./types.ts";
+import { buildAnalyzerVersion } from "./types.ts";
+import {
+  APP_GRAPH_SCHEMA_VERSION,
+  FORGE_CLASSIFIER_VERSION,
+  GENERATOR_VERSION,
+  TREE_SITTER_GRAMMAR_VERSION,
+} from "./versions.ts";
+
+export interface AppGraphBuildOptions {
+  workspaceRoot: string;
+  sources: SourceFile[];
+  prior?: AppGraph;
+  tsconfigPath?: string;
+  /** When provided, skips re-reading and hashing tsconfig.json. */
+  tsconfigHash?: string;
+}
+
+function normalizeSources(sources: SourceFile[]): SourceFile[] {
+  return sources.map((source) => ({
+    ...source,
+    path: normalizePath(source.path),
+  }));
+}
+
+function computeInputHash(
+  sources: SourceFile[],
+  invalidation: ParseInvalidationKey,
+): string {
+  const payload = {
+    files: [...sources]
+      .map((source) => ({ path: source.path, contentHash: source.contentHash }))
+      .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+    invalidation,
+  };
+  return hashStable(canonicalJson(payload));
+}
+
+function parseInvalidationFromPrior(prior: AppGraph): ParseInvalidationKey | undefined {
+  const analyzer = prior.analyzerVersion;
+  const schemaMatch = /schema:([^+]+)/.exec(analyzer);
+  const grammarMatch = /grammar:([^+]+)/.exec(analyzer);
+  const classifierMatch = /classifier:([^+]+)/.exec(analyzer);
+  const tsconfigMatch = /tsconfig:([^+]+)/.exec(analyzer);
+
+  if (!schemaMatch || !grammarMatch || !classifierMatch || !tsconfigMatch) {
+    return undefined;
+  }
+
+  return {
+    schemaVersion: schemaMatch[1] ?? APP_GRAPH_SCHEMA_VERSION,
+    grammarVersion: grammarMatch[1] ?? TREE_SITTER_GRAMMAR_VERSION,
+    classifierVersion: classifierMatch[1] ?? FORGE_CLASSIFIER_VERSION,
+    tsconfigHash: tsconfigMatch[1] ?? "",
+  };
+}
+
+export async function buildAppGraph(
+  options: AppGraphBuildOptions,
+): Promise<AppGraph> {
+  const sources = normalizeSources(options.sources);
+  const tsconfigHash =
+    options.tsconfigHash ??
+    hashTsconfigForWorkspace(
+      options.workspaceRoot,
+      options.tsconfigPath,
+    );
+
+  const invalidation: ParseInvalidationKey = {
+    schemaVersion: APP_GRAPH_SCHEMA_VERSION,
+    grammarVersion: TREE_SITTER_GRAMMAR_VERSION,
+    classifierVersion: FORGE_CLASSIFIER_VERSION,
+    tsconfigHash,
+  };
+
+  const priorInvalidation = options.prior
+    ? parseInvalidationFromPrior(options.prior)
+    : undefined;
+
+  const { symbols: rawSymbols, diagnostics: parseDiagnostics } =
+    incrementalParse(
+      sources,
+      options.prior?.symbols,
+      priorInvalidation,
+      invalidation,
+    );
+
+  const forgeSymbols = buildForgeSymbols(rawSymbols, sources);
+  const dupDiagnostics = detectDuplicateSymbols(forgeSymbols);
+  const moduleGraph = buildModuleGraph(
+    sources,
+    rawSymbols,
+    options.workspaceRoot,
+    options.tsconfigPath,
+    options.prior,
+  );
+
+  return {
+    schemaVersion: APP_GRAPH_SCHEMA_VERSION,
+    generatorVersion: GENERATOR_VERSION,
+    analyzerVersion: buildAnalyzerVersion(invalidation),
+    inputHash: computeInputHash(sources, invalidation),
+    sourceHashes: Object.fromEntries(
+      sources.map((source) => [source.path, source.contentHash]),
+    ),
+    symbols: stableSortSymbols(forgeSymbols),
+    edges: stableSortEdges([]),
+    moduleGraph,
+    diagnostics: [...parseDiagnostics, ...dupDiagnostics],
+  };
+}

package/src/forge/compiler/app-graph/classify.ts

@@ -0,0 +1,10 @@
+import type { ForgeKind } from "../types/app-graph.ts";
+import { FORGE_BUILDER_APIS } from "./forge-apis.ts";
+
+/**
+ * Classify a Forge builder callee into exactly one ForgeKind, or null when
+ * the callee is not a known Forge builder API.
+ */
+export function classifyForgeCallee(callee: string): ForgeKind | null {
+  return FORGE_BUILDER_APIS[callee] ?? null;
+}

package/src/forge/compiler/app-graph/dup-symbol.ts

@@ -0,0 +1,29 @@
+import { forgeDupSymbol } from "../diagnostics/create.ts";
+import type { Diagnostic } from "../types/diagnostic.ts";
+import type { ForgeSymbol } from "../types/app-graph.ts";
+
+/**
+ * Emit FORGE_DUP_SYMBOL warnings for stable-id collisions without discarding symbols.
+ */
+export function detectDuplicateSymbols(symbols: ForgeSymbol[]): Diagnostic[] {
+  const groups = new Map<string, ForgeSymbol[]>();
+
+  for (const symbol of symbols) {
+    const list = groups.get(symbol.id) ?? [];
+    list.push(symbol);
+    groups.set(symbol.id, list);
+  }
+
+  const diagnostics: Diagnostic[] = [];
+
+  for (const group of groups.values()) {
+    if (group.length <= 1) {
+      continue;
+    }
+    for (const symbol of group) {
+      diagnostics.push(forgeDupSymbol(symbol.qualifiedName, symbol.file));
+    }
+  }
+
+  return diagnostics;
+}

package/src/forge/compiler/app-graph/extract.ts

@@ -0,0 +1,124 @@
+import type { SyntaxNode } from "tree-sitter";
+import { classifyForgeCallee } from "./classify.ts";
+import type { RawSymbol } from "./types.ts";
+
+export interface SymbolNameInfo {
+  name: string;
+  qualifiedName: string;
+  exportPath: string;
+}
+
+export function resolveCalleeName(functionNode: SyntaxNode): string | null {
+  if (functionNode.type === "identifier") {
+    return functionNode.text;
+  }
+
+  if (functionNode.type === "member_expression") {
+    const property = functionNode.childForFieldName("property");
+    if (property && (property.type === "property_identifier" || property.type === "identifier")) {
+      return property.text;
+    }
+  }
+
+  return null;
+}
+
+export function inferSymbolName(callNode: SyntaxNode): SymbolNameInfo {
+  let exportPath = "";
+  let parent: SyntaxNode | null = callNode.parent;
+
+  while (parent) {
+    if (parent.type === "variable_declarator") {
+      const nameNode = parent.childForFieldName("name");
+      if (nameNode) {
+        const name = nameNode.text;
+        return { name, qualifiedName: name, exportPath };
+      }
+    }
+
+    if (parent.type === "lexical_declaration" || parent.type === "variable_declaration") {
+      const declarator = parent.namedChildren.find(
+        (child) => child.type === "variable_declarator",
+      );
+      if (declarator) {
+        const nameNode = declarator.childForFieldName("name");
+        if (nameNode) {
+          const name = nameNode.text;
+          return { name, qualifiedName: name, exportPath };
+        }
+      }
+    }
+
+    if (parent.type === "export_statement") {
+      const declaration = parent.childForFieldName("declaration");
+      if (declaration?.type === "lexical_declaration" || declaration?.type === "variable_declaration") {
+        const declarator = declaration.namedChildren.find(
+          (child) => child.type === "variable_declarator",
+        );
+        if (declarator) {
+          const nameNode = declarator.childForFieldName("name");
+          if (nameNode) {
+            const name = nameNode.text;
+            return { name, qualifiedName: name, exportPath: "" };
+          }
+        }
+      }
+
+      const value = parent.childForFieldName("value");
+      if (value === callNode || value?.descendantsOfType("call_expression").includes(callNode)) {
+        exportPath = "default";
+        const fallback = "__default_export__";
+        return { name: fallback, qualifiedName: fallback, exportPath };
+      }
+    }
+
+    parent = parent.parent;
+  }
+
+  const fallback = `__forge_${callNode.startPosition.row}_${callNode.startPosition.column}`;
+  return { name: fallback, qualifiedName: fallback, exportPath };
+}
+
+export function extractSymbolsFromTree(
+  root: SyntaxNode,
+  file: string,
+  source: string,
+): RawSymbol[] {
+  const symbols: RawSymbol[] = [];
+  const visited = new Set<string>();
+
+  function visit(node: SyntaxNode): void {
+    if (node.type === "call_expression") {
+      const functionNode = node.childForFieldName("function");
+      if (functionNode && functionNode.type === "identifier") {
+        const callee = resolveCalleeName(functionNode);
+        if (callee) {
+          const kind = classifyForgeCallee(callee);
+          if (kind) {
+            const key = `${kind}:${node.startIndex}:${node.endIndex}`;
+            if (!visited.has(key)) {
+              visited.add(key);
+              const { name, qualifiedName, exportPath } = inferSymbolName(node);
+              symbols.push({
+                kind,
+                name,
+                qualifiedName,
+                file,
+                span: { start: node.startIndex, end: node.endIndex },
+                exportPath,
+                sourceSlice: source.slice(node.startIndex, node.endIndex),
+              });
+            }
+          }
+        }
+      }
+    }
+
+    for (const child of node.namedChildren) {
+      visit(child);
+    }
+  }
+
+  visit(root);
+  return symbols;
+}

package/src/forge/compiler/app-graph/forge-apis.ts

@@ -0,0 +1,29 @@
+import type { ForgeKind } from "../types/app-graph.ts";
+import type { RuntimeContext } from "../types/runtime.ts";
+
+/** Forge builder callee names mapped to semantic kinds. */
+export const FORGE_BUILDER_APIS: Readonly<Record<string, ForgeKind>> = {
+  defineTable: "schema.table",
+  query: "query",
+  liveQuery: "liveQuery",
+  command: "command",
+  action: "action",
+  endpoint: "endpoint",
+  policy: "policy",
+  definePolicies: "policy",
+  workflow: "workflow",
+  agent: "agent",
+  telemetryEvent: "telemetryEvent",
+};
+
+/** Runtime contexts declared by Forge entrypoint kinds in a module. */
+export const FORGE_KIND_TO_CONTEXT: Readonly<
+  Partial<Record<ForgeKind, RuntimeContext>>
+> = {
+  command: "command",
+  action: "action",
+  query: "query",
+  liveQuery: "liveQuery",
+  endpoint: "endpoint",
+  workflow: "workflow",
+};

package/src/forge/compiler/app-graph/index.ts

@@ -0,0 +1,15 @@
+export { buildAppGraph } from "./build.ts";
+export type { AppGraphBuildOptions } from "./build.ts";
+export { classifyForgeCallee } from "./classify.ts";
+export { FORGE_BUILDER_APIS, FORGE_KIND_TO_CONTEXT } from "./forge-apis.ts";
+export { buildModuleGraph, moduleIdForFile, parsePackageSpecifier } from "./module-graph.ts";
+export { incrementalParse } from "./parser.ts";
+export { detectDuplicateSymbols } from "./dup-symbol.ts";
+export { extractSymbolsFromTree } from "./extract.ts";
+export type { RawSymbol, ParseInvalidationKey } from "./types.ts";
+export {
+  APP_GRAPH_SCHEMA_VERSION,
+  APP_GRAPH_ANALYZER_VERSION,
+  TREE_SITTER_GRAMMAR_VERSION,
+  FORGE_CLASSIFIER_VERSION,
+} from "./versions.ts";

package/src/forge/compiler/app-graph/module-graph.ts

@@ -0,0 +1,320 @@
+import path from "node:path";
+import ts from "typescript";
+import { compareBytes } from "../primitives/compare.ts";
+import { hashStable } from "../primitives/hash.ts";
+import { normalizePath } from "../primitives/paths.ts";
+import { stableSortStrings } from "../primitives/sort.ts";
+import type {
+  AppGraph,
+  ImportKind,
+  LocalImport,
+  ModuleGraph,
+  ModuleNode,
+  PackageImport,
+  SourceFile,
+} from "../types/app-graph.ts";
+import type { RuntimeContext } from "../types/runtime.ts";
+import { FORGE_KIND_TO_CONTEXT } from "./forge-apis.ts";
+import { loadTsconfig } from "./tsconfig-hash.ts";
+import type { RawSymbol } from "./types.ts";
+
+export function moduleIdForFile(file: string): string {
+  return hashStable(normalizePath(file));
+}
+
+export function parsePackageSpecifier(
+  specifier: string,
+): { packageName: string; subpath: string } | null {
+  if (
+    specifier.startsWith(".") ||
+    specifier.startsWith("/") ||
+    specifier.startsWith("node:")
+  ) {
+    return null;
+  }
+
+  const parts = specifier.split("/");
+  if (specifier.startsWith("@") && parts.length >= 2) {
+    return {
+      packageName: `${parts[0]}/${parts[1]}`,
+      subpath: parts.length > 2 ? `/${parts.slice(2).join("/")}` : "",
+    };
+  }
+
+  return {
+    packageName: parts[0] ?? specifier,
+    subpath: parts.length > 1 ? `/${parts.slice(1).join("/")}` : "",
+  };
+}
+
+function compareModuleNodes(a: ModuleNode, b: ModuleNode): number {
+  return compareBytes(a.id, b.id);
+}
+
+function stableSortModuleNodes(nodes: ModuleNode[]): ModuleNode[] {
+  return [...nodes].sort(compareModuleNodes);
+}
+
+function declaredContextsForFile(
+  file: string,
+  symbols: RawSymbol[],
+): RuntimeContext[] {
+  const contexts = new Set<RuntimeContext>();
+  for (const symbol of symbols) {
+    if (symbol.file !== file) {
+      continue;
+    }
+    const context = FORGE_KIND_TO_CONTEXT[symbol.kind];
+    if (context) {
+      contexts.add(context);
+    }
+  }
+  return stableSortStrings([...contexts]) as RuntimeContext[];
+}
+
+function spanFromNode(node: ts.Node, sourceFile: ts.SourceFile): {
+  start: number;
+  end: number;
+} {
+  const start = node.getStart(sourceFile);
+  const end = node.getEnd();
+  return { start, end };
+}
+
+function toWorkspaceRelativePath(
+  absoluteOrRelativePath: string,
+  workspaceRoot: string,
+): string {
+  const normalized = normalizePath(absoluteOrRelativePath);
+  const root = normalizePath(path.resolve(workspaceRoot).replace(/\\/g, "/"));
+  const rootWithSlash = root.endsWith("/") ? root : `${root}/`;
+
+  if (normalized.startsWith(rootWithSlash)) {
+    return normalized.slice(rootWithSlash.length);
+  }
+
+  if (normalized === root) {
+    return "";
+  }
+
+  return normalized;
+}
+
+function resolveLocalTarget(
+  specifier: string,
+  fromFile: string,
+  program: ts.Program,
+  workspaceRoot: string,
+): string | null {
+  const resolved = ts.resolveModuleName(
+    specifier,
+    fromFile,
+    program.getCompilerOptions(),
+    ts.sys,
+  );
+
+  const fileName = resolved.resolvedModule?.resolvedFileName;
+  if (!fileName) {
+    return null;
+  }
+
+  return toWorkspaceRelativePath(fileName, workspaceRoot);
+}
+
+function collectImports(
+  sourceFile: ts.SourceFile,
+  program: ts.Program,
+  workspaceRoot: string,
+): { packageImports: PackageImport[]; localImports: LocalImport[] } {
+  const packageImports: PackageImport[] = [];
+  const localImports: LocalImport[] = [];
+  const fromFile = normalizePath(sourceFile.fileName);
+
+  function recordPackageImport(
+    specifier: string,
+    span: { start: number; end: number },
+    importKind: ImportKind,
+  ): void {
+    const parsed = parsePackageSpecifier(specifier);
+    if (!parsed) {
+      return;
+    }
+    packageImports.push({
+      specifier,
+      packageName: parsed.packageName,
+      subpath: parsed.subpath,
+      span,
+      importKind,
+    });
+  }
+
+  function visit(node: ts.Node): void {
+    if (ts.isImportDeclaration(node) && node.moduleSpecifier) {
+      if (ts.isStringLiteral(node.moduleSpecifier)) {
+        const specifier = node.moduleSpecifier.text;
+        const span = spanFromNode(node.moduleSpecifier, sourceFile);
+        const parsed = parsePackageSpecifier(specifier);
+        if (parsed) {
+          recordPackageImport(specifier, span, "static");
+        } else {
+          const target = resolveLocalTarget(
+            specifier,
+            fromFile,
+            program,
+            workspaceRoot,
+          );
+          if (target) {
+            localImports.push({
+              toModuleId: moduleIdForFile(target),
+              span,
+            });
+          }
+        }
+      }
+    }
+
+    if (
+      ts.isCallExpression(node) &&
+      node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+      node.arguments[0] &&
+      ts.isStringLiteral(node.arguments[0])
+    ) {
+      const specifier = node.arguments[0].text;
+      const span = spanFromNode(node.arguments[0], sourceFile);
+      const parsed = parsePackageSpecifier(specifier);
+      if (parsed) {
+        recordPackageImport(specifier, span, "dynamic");
+      } else {
+        const target = resolveLocalTarget(
+          specifier,
+          fromFile,
+          program,
+          workspaceRoot,
+        );
+        if (target) {
+          localImports.push({
+            toModuleId: moduleIdForFile(target),
+            span,
+          });
+        }
+      }
+    }
+
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === "require" &&
+      node.arguments[0] &&
+      ts.isStringLiteral(node.arguments[0])
+    ) {
+      const specifier = node.arguments[0].text;
+      const span = spanFromNode(node.arguments[0], sourceFile);
+      const parsed = parsePackageSpecifier(specifier);
+      if (parsed) {
+        recordPackageImport(specifier, span, "require");
+      } else {
+        const target = resolveLocalTarget(
+          specifier,
+          fromFile,
+          program,
+          workspaceRoot,
+        );
+        if (target) {
+          localImports.push({
+            toModuleId: moduleIdForFile(target),
+            span,
+          });
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return { packageImports, localImports };
+}
+
+function sourcesUnchangedSincePrior(
+  sources: SourceFile[],
+  prior?: AppGraph,
+): boolean {
+  if (!prior) {
+    return false;
+  }
+  const priorHashes = new Map(Object.entries(prior.sourceHashes ?? {}));
+  if (priorHashes.size !== sources.length) {
+    return false;
+  }
+  for (const source of sources) {
+    if (priorHashes.get(source.path) !== source.contentHash) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function buildModuleGraph(
+  sources: SourceFile[],
+  rawSymbols: RawSymbol[],
+  workspaceRoot: string,
+  tsconfigPath?: string,
+  prior?: AppGraph,
+): ModuleGraph {
+  if (sourcesUnchangedSincePrior(sources, prior)) {
+    return prior!.moduleGraph;
+  }
+
+  const parsedConfig = loadTsconfig(workspaceRoot, tsconfigPath);
+  const fileNames = sources.map((source) =>
+    path.resolve(workspaceRoot, source.path).replace(/\\/g, "/"),
+  );
+
+  const program = ts.createProgram(fileNames, {
+    ...parsedConfig.options,
+    noEmit: true,
+    skipLibCheck: true,
+  });
+
+  const nodes: ModuleNode[] = [];
+
+  for (const source of sources) {
+    const normalizedFile = normalizePath(source.path);
+    const absolutePath = fileNames.find(
+      (name) => normalizePath(name).endsWith(normalizedFile),
+    );
+
+    const sourceFile = absolutePath
+      ? program.getSourceFile(absolutePath)
+      : undefined;
+
+    if (!sourceFile) {
+      nodes.push({
+        id: moduleIdForFile(normalizedFile),
+        file: normalizedFile,
+        directPackageImports: [],
+        localImports: [],
+        declaredContexts: declaredContextsForFile(normalizedFile, rawSymbols),
+        effectiveContexts: [],
+      });
+      continue;
+    }
+
+    const { packageImports, localImports } = collectImports(
+      sourceFile,
+      program,
+      workspaceRoot,
+    );
+
+    nodes.push({
+      id: moduleIdForFile(normalizedFile),
+      file: normalizedFile,
+      directPackageImports: packageImports,
+      localImports,
+      declaredContexts: declaredContextsForFile(normalizedFile, rawSymbols),
+      effectiveContexts: [],
+    });
+  }
+
+  return { nodes: stableSortModuleNodes(nodes) };
+}