@tsonic/frontend 0.0.1

package/src/program/dependency-graph.ts

@@ -0,0 +1,245 @@
+/**
+ * Dependency graph builder - Multi-file compilation
+ * Traverses local imports using ts.resolveModuleName()
+ */
+
+import * as ts from "typescript";
+import { relative, resolve } from "path";
+import { Result, ok, error } from "../types/result.js";
+import { Diagnostic, createDiagnostic } from "../types/diagnostic.js";
+import { IrModule } from "../ir/types.js";
+import { buildIrModule } from "../ir/builder/orchestrator.js";
+import { createProgram, createCompilerOptions } from "./creation.js";
+import { CompilerOptions } from "./types.js";
+
+export type ModuleDependencyGraphResult = {
+  readonly modules: readonly IrModule[];
+  readonly entryModule: IrModule;
+};
+
+/**
+ * Extract module specifier from import or re-export declaration
+ * Returns the module specifier string literal, or null if not applicable
+ */
+const getModuleSpecifier = (stmt: ts.Statement): ts.StringLiteral | null => {
+  // Handle: import { x } from "./module"
+  if (
+    ts.isImportDeclaration(stmt) &&
+    ts.isStringLiteral(stmt.moduleSpecifier)
+  ) {
+    return stmt.moduleSpecifier;
+  }
+
+  // Handle: export { x } from "./module" (re-exports)
+  if (
+    ts.isExportDeclaration(stmt) &&
+    stmt.moduleSpecifier &&
+    ts.isStringLiteral(stmt.moduleSpecifier)
+  ) {
+    return stmt.moduleSpecifier;
+  }
+
+  return null;
+};
+
+/**
+ * Build complete module dependency graph from entry point
+ * Traverses all local imports and builds IR for all discovered modules
+ * Uses TypeScript's ts.resolveModuleName() for correct module resolution
+ */
+export const buildModuleDependencyGraph = (
+  entryFile: string,
+  options: CompilerOptions
+): Result<ModuleDependencyGraphResult, readonly Diagnostic[]> => {
+  const diagnostics: Diagnostic[] = [];
+
+  // Normalize entry file and source root to absolute paths
+  const entryAbs = resolve(entryFile);
+  const sourceRootAbs = resolve(options.sourceRoot);
+
+  // Get TypeScript compiler options for module resolution
+  const compilerOptions = createCompilerOptions(options);
+
+  // Track all discovered files for later type checking
+  const allDiscoveredFiles: string[] = [];
+
+  // BFS to discover all local imports
+  const visited = new Set<string>();
+  const queue: string[] = [entryAbs];
+
+  // First pass: discover all files
+  while (queue.length > 0) {
+    const currentFile = queue.shift()!;
+
+    // Dedup by realpath (handles symlinks, relative paths)
+    const realPath = ts.sys.realpath?.(currentFile) ?? currentFile;
+    if (visited.has(realPath)) {
+      continue;
+    }
+    visited.add(realPath);
+    allDiscoveredFiles.push(realPath);
+
+    // Read source file directly from filesystem
+    const sourceText = ts.sys.readFile(currentFile);
+    if (!sourceText) {
+      // Missing file - add diagnostic but continue traversal
+      const relativeCurrent = relative(sourceRootAbs, currentFile);
+      diagnostics.push(
+        createDiagnostic(
+          "TSN1002",
+          "error",
+          `Cannot find module '${relativeCurrent}'`,
+          {
+            file: currentFile,
+            line: 1,
+            column: 1,
+            length: 1,
+          }
+        )
+      );
+      continue;
+    }
+
+    // Parse source file to extract imports
+    const sourceFile = ts.createSourceFile(
+      currentFile,
+      sourceText,
+      ts.ScriptTarget.Latest,
+      true
+    );
+
+    // Extract local imports and re-exports using TypeScript's resolution
+    for (const stmt of sourceFile.statements) {
+      // Handle import declarations: import { x } from "./module"
+      // Handle re-export declarations: export { x } from "./module"
+      const moduleSpecifier = getModuleSpecifier(stmt);
+      if (!moduleSpecifier) {
+        continue;
+      }
+
+      const importSpecifier = moduleSpecifier.text;
+
+      // Only process local imports (starts with . or /)
+      if (
+        !importSpecifier.startsWith(".") &&
+        !importSpecifier.startsWith("/")
+      ) {
+        continue;
+      }
+
+      // Resolve using TypeScript's module resolution
+      const resolved = ts.resolveModuleName(
+        importSpecifier,
+        currentFile,
+        compilerOptions,
+        ts.sys
+      );
+
+      if (resolved.resolvedModule?.resolvedFileName) {
+        const resolvedPath = resolved.resolvedModule.resolvedFileName;
+
+        // Only include .ts files (not .d.ts) within source root
+        if (
+          resolvedPath.startsWith(sourceRootAbs) &&
+          resolvedPath.endsWith(".ts") &&
+          !resolvedPath.endsWith(".d.ts")
+        ) {
+          queue.push(resolvedPath);
+        }
+      } else {
+        // Import resolution failed - add diagnostic with context
+        const relativeCurrent = relative(sourceRootAbs, currentFile);
+        diagnostics.push(
+          createDiagnostic(
+            "TSN1002",
+            "error",
+            `Cannot resolve import '${importSpecifier}' from '${relativeCurrent}'`,
+            {
+              file: currentFile,
+              line: stmt.getStart(sourceFile),
+              column: 1,
+              length: importSpecifier.length,
+            }
+          )
+        );
+      }
+    }
+  }
+
+  // If any diagnostics from discovery, fail the build
+  if (diagnostics.length > 0) {
+    return error(diagnostics);
+  }
+
+  // Ensure we discovered at least the entry file
+  if (allDiscoveredFiles.length === 0) {
+    return error([
+      createDiagnostic(
+        "TSN1002",
+        "error",
+        `No modules found starting from entry point '${entryFile}'`,
+        {
+          file: entryFile,
+          line: 1,
+          column: 1,
+          length: 1,
+        }
+      ),
+    ]);
+  }
+
+  // Second pass: Create TypeScript program with all discovered files for type checking
+  // Use absolute sourceRoot for consistency
+  const programResult = createProgram(allDiscoveredFiles, {
+    ...options,
+    sourceRoot: sourceRootAbs,
+  });
+
+  if (!programResult.ok) {
+    return error(programResult.error.diagnostics);
+  }
+
+  const tsonicProgram = programResult.value;
+
+  // Third pass: Build IR for all discovered modules
+  const modules: IrModule[] = [];
+
+  for (const filePath of allDiscoveredFiles) {
+    const sourceFile = tsonicProgram.program.getSourceFile(filePath);
+    if (!sourceFile) {
+      // This shouldn't happen since we already verified files exist
+      continue;
+    }
+
+    const moduleResult = buildIrModule(sourceFile, tsonicProgram, {
+      sourceRoot: sourceRootAbs,
+      rootNamespace: options.rootNamespace,
+    });
+
+    if (!moduleResult.ok) {
+      diagnostics.push(moduleResult.error);
+      continue;
+    }
+
+    modules.push(moduleResult.value);
+  }
+
+  // If any diagnostics from IR building, fail the build
+  if (diagnostics.length > 0) {
+    return error(diagnostics);
+  }
+
+  // Sort modules by relative path for deterministic output
+  modules.sort((a, b) => a.filePath.localeCompare(b.filePath));
+
+  // Entry module is the first one (after sorting, it should be the entry file)
+  // But let's find it by matching the entry file path
+  const entryRelative = relative(sourceRootAbs, entryAbs).replace(/\\/g, "/");
+  const entryModule =
+    modules.find((m) => m.filePath === entryRelative) ?? modules[0]!;
+
+  return ok({
+    modules,
+    entryModule,
+  });
+};

package/src/program/diagnostics.ts

@@ -0,0 +1,103 @@
+/**
+ * TypeScript diagnostics collection and conversion
+ */
+
+import * as ts from "typescript";
+import {
+  Diagnostic,
+  DiagnosticsCollector,
+  createDiagnosticsCollector,
+  addDiagnostic,
+  createDiagnostic,
+} from "../types/diagnostic.js";
+
+/**
+ * Collect all TypeScript diagnostics from a program
+ */
+export const collectTsDiagnostics = (
+  program: ts.Program
+): DiagnosticsCollector => {
+  const tsDiagnostics = [
+    ...program.getConfigFileParsingDiagnostics(),
+    ...program.getOptionsDiagnostics(),
+    ...program.getSyntacticDiagnostics(),
+    ...program.getGlobalDiagnostics(),
+    ...program.getSemanticDiagnostics(),
+  ];
+
+  return tsDiagnostics.reduce((collector, tsDiag) => {
+    const diagnostic = convertTsDiagnostic(tsDiag);
+    return diagnostic ? addDiagnostic(collector, diagnostic) : collector;
+  }, createDiagnosticsCollector());
+};
+
+/**
+ * Convert TypeScript diagnostic to Tsonic diagnostic
+ */
+export const convertTsDiagnostic = (
+  tsDiag: ts.Diagnostic
+): Diagnostic | null => {
+  if (tsDiag.category === ts.DiagnosticCategory.Suggestion) {
+    return null; // Ignore suggestions
+  }
+
+  const message = ts.flattenDiagnosticMessageText(tsDiag.messageText, "\n");
+
+  // Ignore "type used as value" errors for .NET types
+  // These are handled by the Tsonic compiler
+  if (
+    message.includes("only refers to a type, but is being used as a value") &&
+    tsDiag.file
+  ) {
+    // Check if this is a .NET import
+    const sourceText = tsDiag.file.getText();
+    if (
+      sourceText.includes('from "System') ||
+      sourceText.includes('from "Microsoft') ||
+      sourceText.includes('from "Windows')
+    ) {
+      return null; // Ignore - will be handled by Tsonic
+    }
+  }
+
+  const severity =
+    tsDiag.category === ts.DiagnosticCategory.Error
+      ? "error"
+      : tsDiag.category === ts.DiagnosticCategory.Warning
+        ? "warning"
+        : "info";
+
+  const location =
+    tsDiag.file && tsDiag.start !== undefined
+      ? getSourceLocation(tsDiag.file, tsDiag.start, tsDiag.length ?? 1)
+      : undefined;
+
+  return createDiagnostic(
+    "TSN2001", // Generic TypeScript error
+    severity,
+    message,
+    location
+  );
+};
+
+/**
+ * Get source location information from TypeScript source file
+ */
+export const getSourceLocation = (
+  file: ts.SourceFile,
+  start: number,
+  length: number
+): {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+  readonly length: number;
+} => {
+  const { line, character } = file.getLineAndCharacterOfPosition(start);
+  return {
+    file: file.fileName,
+    line: line + 1,
+    column: character + 1,
+    length,
+  };
+};

package/src/program/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Program - Public API
+ */
+
+export type { CompilerOptions, TsonicProgram, RuntimeMode } from "./types.js";
+export { defaultTsConfig } from "./config.js";
+export { loadDotnetMetadata } from "./metadata.js";
+export { BindingRegistry, loadBindings } from "./bindings.js";
+export {
+  collectTsDiagnostics,
+  convertTsDiagnostic,
+  getSourceLocation,
+} from "./diagnostics.js";
+export { createProgram, createCompilerOptions } from "./creation.js";
+export { getSourceFile } from "./queries.js";
+export {
+  buildModuleDependencyGraph,
+  type ModuleDependencyGraphResult,
+} from "./dependency-graph.js";

package/src/program/metadata.ts

@@ -0,0 +1,68 @@
+/**
+ * .NET metadata file loading
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  DotnetMetadataRegistry,
+  DotnetMetadataFile,
+} from "../dotnet-metadata.js";
+
+/**
+ * Recursively scan a directory for .d.ts files
+ */
+const scanForDeclarationFiles = (dir: string): readonly string[] => {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+
+  const results: string[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...scanForDeclarationFiles(fullPath));
+    } else if (entry.name.endsWith(".d.ts")) {
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+};
+
+/**
+ * Load .NET metadata files from configured type roots
+ * Looks for *.metadata.json files alongside .d.ts files
+ */
+export const loadDotnetMetadata = (
+  typeRoots: readonly string[]
+): DotnetMetadataRegistry => {
+  const registry = new DotnetMetadataRegistry();
+
+  // Scan all type roots for .d.ts files
+  for (const typeRoot of typeRoots) {
+    const absoluteRoot = path.resolve(typeRoot);
+    const declFiles = scanForDeclarationFiles(absoluteRoot);
+
+    for (const declPath of declFiles) {
+      // Look for corresponding .metadata.json file
+      const metadataPath = declPath.replace(/\.d\.ts$/, ".metadata.json");
+
+      try {
+        if (fs.existsSync(metadataPath)) {
+          const content = fs.readFileSync(metadataPath, "utf-8");
+          const metadataFile = JSON.parse(content) as DotnetMetadataFile;
+          registry.loadMetadataFile(metadataPath, metadataFile);
+        }
+      } catch (err) {
+        // Silently skip files that can't be read or parsed
+        // In production, we might want to emit a warning diagnostic
+        console.warn(`Failed to load metadata from ${metadataPath}:`, err);
+      }
+    }
+  }
+
+  return registry;
+};

package/src/program/queries.ts

@@ -0,0 +1,18 @@
+/**
+ * Program query functions
+ */
+
+import * as ts from "typescript";
+import * as path from "node:path";
+import { TsonicProgram } from "./types.js";
+
+/**
+ * Get a source file from the program by file path
+ */
+export const getSourceFile = (
+  program: TsonicProgram,
+  filePath: string
+): ts.SourceFile | null => {
+  const absolutePath = path.resolve(filePath);
+  return program.program.getSourceFile(absolutePath) ?? null;
+};

package/src/program/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Program type definitions
+ */
+
+import * as ts from "typescript";
+import { DotnetMetadataRegistry } from "../dotnet-metadata.js";
+import { BindingRegistry } from "./bindings.js";
+import { DotNetImportResolver } from "../resolver/dotnet-import-resolver.js";
+
+export type RuntimeMode = "js" | "dotnet";
+
+export type CompilerOptions = {
+  readonly sourceRoot: string;
+  readonly rootNamespace: string;
+  readonly strict?: boolean;
+  readonly typeRoots?: readonly string[];
+  readonly verbose?: boolean;
+  /** Use TypeScript standard lib (Array, Promise, etc.) instead of noLib mode */
+  readonly useStandardLib?: boolean;
+  /**
+   * Runtime mode:
+   * - "js": JS built-ins available via Tsonic.JSRuntime
+   * - "dotnet": Pure .NET mode, JS built-ins forbidden
+   * Defaults to "js"
+   */
+  readonly runtime?: RuntimeMode;
+};
+
+export type TsonicProgram = {
+  readonly program: ts.Program;
+  readonly checker: ts.TypeChecker;
+  readonly options: CompilerOptions;
+  readonly sourceFiles: readonly ts.SourceFile[];
+  readonly metadata: DotnetMetadataRegistry;
+  readonly bindings: BindingRegistry;
+  /** Resolver for .NET namespace imports (import-driven discovery) */
+  readonly dotnetResolver: DotNetImportResolver;
+};

package/src/program.ts

@@ -0,0 +1,13 @@
+/**
+ * TypeScript program creation and management
+ * Main dispatcher - re-exports from program/ subdirectory
+ */
+
+export type { CompilerOptions, TsonicProgram } from "./program/index.js";
+export type { ModuleDependencyGraphResult } from "./program/dependency-graph.js";
+export {
+  createProgram,
+  getSourceFile,
+  BindingRegistry,
+  buildModuleDependencyGraph,
+} from "./program/index.js";