@tsonic/frontend 0.0.1

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@tsonic/frontend",
+  "version": "0.0.1",
+  "description": "TypeScript parser and IR builder for Tsonic compiler",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types/metadata.js": {
+      "types": "./dist/types/metadata.d.ts",
+      "default": "./dist/types/metadata.js"
+    },
+    "./types/bindings.js": {
+      "types": "./dist/types/bindings.d.ts",
+      "default": "./dist/types/bindings.js"
+    },
+    "./types/nested-types.js": {
+      "types": "./dist/types/nested-types.d.ts",
+      "default": "./dist/types/nested-types.js"
+    },
+    "./types/explicit-views.js": {
+      "types": "./dist/types/explicit-views.d.ts",
+      "default": "./dist/types/explicit-views.js"
+    },
+    "./metadata/index.js": {
+      "types": "./dist/metadata/index.d.ts",
+      "default": "./dist/metadata/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "mocha 'dist/**/*.test.js'",
+    "test:watch": "mocha 'dist/**/*.test.js' --watch"
+  },
+  "dependencies": {
+    "typescript": "5.9.2"
+  },
+  "devDependencies": {
+    "@types/chai": "5.2.2",
+    "@types/mocha": "10.0.10",
+    "@types/node": "20.14.0",
+    "chai": "5.3.3",
+    "mocha": "11.7.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/dependency-graph.ts

@@ -0,0 +1,18 @@
+/**
+ * Module dependency graph builder
+ * Main dispatcher - re-exports from graph/ subdirectory
+ */
+
+export type { DependencyAnalysis } from "./graph/types.js";
+export { buildDependencyGraph } from "./graph/builder.js";
+export {
+  extractModuleInfo,
+  extractImport,
+  extractExport,
+} from "./graph/extraction.js";
+export { checkCircularDependencies } from "./graph/circular.js";
+export {
+  isTopLevelCode,
+  hasExecutableInitializer,
+  hasExportModifier,
+} from "./graph/helpers.js";

package/src/dotnet-metadata.ts

@@ -0,0 +1,121 @@
+/**
+ * .NET Metadata Loader - Reads .metadata.json files to determine override behavior
+ */
+
+/**
+ * Metadata for a single .NET type member (method, property, etc.)
+ */
+export type DotnetMemberMetadata = {
+  readonly kind: "method" | "property" | "field" | "event";
+  readonly virtual?: boolean; // True if method is virtual/abstract
+  readonly sealed?: boolean; // True if method is sealed (cannot override)
+  readonly abstract?: boolean; // True if method is abstract
+};
+
+/**
+ * Metadata for a complete .NET type (class, interface, struct, etc.)
+ */
+export type DotnetTypeMetadata = {
+  readonly kind: "class" | "interface" | "struct" | "enum";
+  readonly members: Readonly<Record<string, DotnetMemberMetadata>>;
+};
+
+/**
+ * Complete metadata file structure
+ */
+export type DotnetMetadataFile = {
+  readonly types: Readonly<Record<string, DotnetTypeMetadata>>;
+};
+
+/**
+ * Registry of all loaded .NET metadata
+ * Maps fully-qualified type names to their metadata
+ */
+export class DotnetMetadataRegistry {
+  private readonly metadata = new Map<string, DotnetTypeMetadata>();
+
+  /**
+   * Load a metadata file and add its types to the registry
+   */
+  loadMetadataFile(_filePath: string, content: DotnetMetadataFile): void {
+    for (const [typeName, typeMetadata] of Object.entries(content.types)) {
+      this.metadata.set(typeName, typeMetadata);
+    }
+  }
+
+  /**
+   * Look up metadata for a .NET type by fully-qualified name
+   */
+  getTypeMetadata(qualifiedName: string): DotnetTypeMetadata | undefined {
+    return this.metadata.get(qualifiedName);
+  }
+
+  /**
+   * Look up metadata for a specific member of a .NET type
+   * @param qualifiedTypeName Fully-qualified type name (e.g., "System.IO.StringWriter")
+   * @param memberSignature Member signature (e.g., "ToString()" or "Write(string)")
+   */
+  getMemberMetadata(
+    qualifiedTypeName: string,
+    memberSignature: string
+  ): DotnetMemberMetadata | undefined {
+    const typeMetadata = this.metadata.get(qualifiedTypeName);
+    if (!typeMetadata) {
+      return undefined;
+    }
+    return typeMetadata.members[memberSignature];
+  }
+
+  /**
+   * Check if a member is virtual (can be overridden)
+   */
+  isVirtualMember(qualifiedTypeName: string, memberSignature: string): boolean {
+    const memberMetadata = this.getMemberMetadata(
+      qualifiedTypeName,
+      memberSignature
+    );
+    return memberMetadata?.virtual === true;
+  }
+
+  /**
+   * Check if a member is sealed (cannot be overridden)
+   */
+  isSealedMember(qualifiedTypeName: string, memberSignature: string): boolean {
+    const memberMetadata = this.getMemberMetadata(
+      qualifiedTypeName,
+      memberSignature
+    );
+    return memberMetadata?.sealed === true;
+  }
+
+  /**
+   * Get all loaded type names
+   */
+  getAllTypeNames(): readonly string[] {
+    return Array.from(this.metadata.keys());
+  }
+
+  /**
+   * Clear all loaded metadata
+   */
+  clear(): void {
+    this.metadata.clear();
+  }
+}
+
+/**
+ * Build a method signature string for metadata lookup
+ * Format: "MethodName(type1,type2,...)"
+ * @param methodName The method name
+ * @param parameterTypes Array of parameter type names (e.g., ["string", "number"])
+ * @returns Signature string for metadata lookup
+ */
+export const buildMethodSignature = (
+  methodName: string,
+  parameterTypes: readonly string[]
+): string => {
+  if (parameterTypes.length === 0) {
+    return `${methodName}()`;
+  }
+  return `${methodName}(${parameterTypes.join(",")})`;
+};

package/src/graph/builder.ts

@@ -0,0 +1,81 @@
+/**
+ * Dependency graph builder - Main orchestrator
+ */
+
+import * as path from "node:path";
+import { TsonicProgram } from "../program.js";
+import { createModuleGraph, Import } from "../types/module.js";
+import {
+  addDiagnostic,
+  createDiagnosticsCollector,
+} from "../types/diagnostic.js";
+import {
+  createSymbolTable,
+  addSymbol,
+  buildSymbolTable,
+} from "../symbol-table.js";
+import { DependencyAnalysis } from "./types.js";
+import { extractModuleInfo } from "./extraction.js";
+import { checkCircularDependencies } from "./circular.js";
+
+/**
+ * Build a complete dependency graph for a Tsonic program
+ */
+export const buildDependencyGraph = (
+  program: TsonicProgram,
+  entryPoints: readonly string[]
+): DependencyAnalysis => {
+  const modules = new Map();
+  const dependencies = new Map();
+  const dependents = new Map();
+  let symbolTable = createSymbolTable();
+  let diagnostics = createDiagnosticsCollector();
+
+  // Process all source files
+  program.sourceFiles.forEach((sourceFile) => {
+    const moduleInfo = extractModuleInfo(sourceFile, program);
+    modules.set(sourceFile.fileName, moduleInfo);
+
+    // Build symbol table
+    const symbols = buildSymbolTable(sourceFile, program.checker);
+    symbols.forEach((symbol) => {
+      symbolTable = addSymbol(symbolTable, symbol);
+    });
+  });
+
+  // Build dependency relationships
+  modules.forEach((module, modulePath) => {
+    const deps: string[] = [];
+
+    module.imports.forEach((imp: Import) => {
+      if (imp.resolvedPath) {
+        deps.push(imp.resolvedPath);
+
+        // Add to dependents map
+        const currentDependents = dependents.get(imp.resolvedPath) ?? [];
+        dependents.set(imp.resolvedPath, [...currentDependents, modulePath]);
+      }
+    });
+
+    dependencies.set(modulePath, deps);
+  });
+
+  // Check for circular dependencies
+  const circularCheck = checkCircularDependencies(dependencies);
+  if (!circularCheck.ok) {
+    diagnostics = addDiagnostic(diagnostics, circularCheck.error);
+  }
+
+  const graph = createModuleGraph(
+    modules,
+    dependencies,
+    dependents,
+    entryPoints.map((ep) => path.resolve(ep))
+  );
+
+  return {
+    graph,
+    symbolTable,
+    diagnostics,
+  };
+};

package/src/graph/circular.ts

@@ -0,0 +1,58 @@
+/**
+ * Circular dependency detection
+ */
+
+import * as path from "node:path";
+import { Diagnostic, createDiagnostic } from "../types/diagnostic.js";
+import { Result, ok, error } from "../types/result.js";
+
+/**
+ * Check for circular dependencies using depth-first search
+ */
+export const checkCircularDependencies = (
+  dependencies: ReadonlyMap<string, readonly string[]>
+): Result<void, Diagnostic> => {
+  const visited = new Set<string>();
+  const stack = new Set<string>();
+
+  const visit = (module: string, path: string[]): string[] | null => {
+    if (stack.has(module)) {
+      return [...path, module]; // Found cycle
+    }
+
+    if (visited.has(module)) {
+      return null; // Already checked
+    }
+
+    visited.add(module);
+    stack.add(module);
+
+    const deps = dependencies.get(module) ?? [];
+    for (const dep of deps) {
+      const cycle = visit(dep, [...path, module]);
+      if (cycle) {
+        return cycle;
+      }
+    }
+
+    stack.delete(module);
+    return null;
+  };
+
+  for (const [module] of dependencies) {
+    const cycle = visit(module, []);
+    if (cycle) {
+      return error(
+        createDiagnostic(
+          "TSN1002",
+          "error",
+          `Circular dependency detected: ${cycle.map((m) => path.basename(m)).join(" → ")}`,
+          undefined,
+          "Break the circular dependency by refactoring shared code"
+        )
+      );
+    }
+  }
+
+  return ok(undefined);
+};

package/src/graph/extraction/exports.ts

@@ -0,0 +1,55 @@
+/**
+ * Export information extraction
+ */
+
+import * as ts from "typescript";
+import { Export } from "../../types/module.js";
+
+/**
+ * Extract export information from an export declaration
+ */
+export const extractExport = (node: ts.ExportDeclaration): Export | null => {
+  if (
+    !node.moduleSpecifier &&
+    node.exportClause &&
+    ts.isNamedExports(node.exportClause)
+  ) {
+    // export { a, b as c } - named exports without re-export
+    const elements = Array.from(node.exportClause.elements);
+    if (elements.length > 0 && elements[0]) {
+      const spec = elements[0];
+      return {
+        kind: "named",
+        name: spec.name.text,
+        localName: (spec.propertyName ?? spec.name).text,
+      };
+    }
+    return null;
+  }
+
+  if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+    // export { ... } from "..." - re-exports
+    const fromModule = node.moduleSpecifier.text;
+    const exportedNames: { readonly name: string; readonly alias?: string }[] =
+      [];
+
+    if (node.exportClause) {
+      if (ts.isNamedExports(node.exportClause)) {
+        Array.from(node.exportClause.elements).forEach((spec) => {
+          exportedNames.push({
+            name: (spec.propertyName ?? spec.name).text,
+            alias: spec.propertyName ? spec.name.text : undefined,
+          });
+        });
+      }
+    }
+
+    return {
+      kind: "reexport",
+      fromModule,
+      exports: exportedNames,
+    };
+  }
+
+  return null;
+};

package/src/graph/extraction/imports.ts

@@ -0,0 +1,81 @@
+/**
+ * Import information extraction
+ */
+
+import * as ts from "typescript";
+import { TsonicProgram } from "../../program.js";
+import { Import } from "../../types/module.js";
+import { resolveImport } from "../../resolver.js";
+
+/**
+ * Extract import information from an import declaration
+ */
+export const extractImport = (
+  node: ts.ImportDeclaration,
+  sourceFile: ts.SourceFile,
+  program: TsonicProgram
+): Import | null => {
+  if (!ts.isStringLiteral(node.moduleSpecifier)) {
+    return null;
+  }
+
+  const specifier = node.moduleSpecifier.text;
+  const result = resolveImport(
+    specifier,
+    sourceFile.fileName,
+    program.options.sourceRoot,
+    program.dotnetResolver
+  );
+
+  const importedNames: { readonly name: string; readonly alias?: string }[] =
+    [];
+
+  if (node.importClause) {
+    // Default import
+    if (node.importClause.name) {
+      importedNames.push({
+        name: "default",
+        alias: node.importClause.name.text,
+      });
+    }
+
+    // Named imports
+    if (node.importClause.namedBindings) {
+      if (ts.isNamespaceImport(node.importClause.namedBindings)) {
+        // import * as ns from "..."
+        importedNames.push({
+          name: "*",
+          alias: node.importClause.namedBindings.name.text,
+        });
+      } else if (ts.isNamedImports(node.importClause.namedBindings)) {
+        // import { a, b as c } from "..."
+        node.importClause.namedBindings.elements.forEach((spec) => {
+          importedNames.push({
+            name: (spec.propertyName ?? spec.name).text,
+            alias: spec.propertyName ? spec.name.text : undefined,
+          });
+        });
+      }
+    }
+  }
+
+  if (result.ok) {
+    return {
+      kind: result.value.isLocal
+        ? "local"
+        : result.value.isDotNet
+          ? "dotnet"
+          : "node_module",
+      specifier,
+      resolvedPath: result.value.resolvedPath || undefined,
+      namespace: result.value.resolvedNamespace,
+      importedNames,
+    };
+  }
+
+  return {
+    kind: "local",
+    specifier,
+    importedNames,
+  };
+};

package/src/graph/extraction/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Module extraction - Public API
+ */
+
+export { extractModuleInfo } from "./orchestrator.js";
+export { extractImport } from "./imports.js";
+export { extractExport } from "./exports.js";

package/src/graph/extraction/orchestrator.ts

@@ -0,0 +1,99 @@
+/**
+ * Module information extraction orchestrator
+ */
+
+import * as ts from "typescript";
+import { TsonicProgram } from "../../program.js";
+import { ModuleInfo, Import, Export } from "../../types/module.js";
+import { getNamespaceFromPath, getClassNameFromPath } from "../../resolver.js";
+import { hasExportModifier, isTopLevelCode } from "../helpers.js";
+import { extractImport } from "./imports.js";
+import { extractExport } from "./exports.js";
+
+/**
+ * Extract module information from a TypeScript source file
+ */
+export const extractModuleInfo = (
+  sourceFile: ts.SourceFile,
+  program: TsonicProgram
+): ModuleInfo => {
+  const imports: Import[] = [];
+  const exports: Export[] = [];
+  let hasTopLevelCode = false;
+
+  const visitor = (node: ts.Node): void => {
+    // Extract imports
+    if (ts.isImportDeclaration(node)) {
+      const imp = extractImport(node, sourceFile, program);
+      if (imp) {
+        imports.push(imp);
+      }
+    }
+
+    // Extract exports
+    if (ts.isExportDeclaration(node)) {
+      const exp = extractExport(node);
+      if (exp) {
+        exports.push(exp);
+      }
+    }
+
+    if (ts.isExportAssignment(node)) {
+      exports.push({
+        kind: "default",
+        localName: node.expression.getText(),
+      });
+    }
+
+    // Check for exported declarations
+    if (hasExportModifier(node)) {
+      if (ts.isVariableStatement(node)) {
+        node.declarationList.declarations.forEach((decl) => {
+          if (ts.isIdentifier(decl.name)) {
+            exports.push({
+              kind: "named",
+              name: decl.name.text,
+              localName: decl.name.text,
+            });
+          }
+        });
+      } else if (
+        (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) &&
+        node.name
+      ) {
+        exports.push({
+          kind: "named",
+          name: node.name.text,
+          localName: node.name.text,
+        });
+      }
+    }
+
+    // Check for top-level code (non-declaration statements)
+    if (isTopLevelCode(node)) {
+      hasTopLevelCode = true;
+    }
+
+    ts.forEachChild(node, visitor);
+  };
+
+  visitor(sourceFile);
+
+  const namespace = getNamespaceFromPath(
+    sourceFile.fileName,
+    program.options.sourceRoot,
+    program.options.rootNamespace
+  );
+
+  const className = getClassNameFromPath(sourceFile.fileName);
+
+  return {
+    filePath: sourceFile.fileName,
+    sourceText: sourceFile.getFullText(),
+    imports,
+    exports,
+    hasTopLevelCode,
+    namespace,
+    className,
+  };
+};

package/src/graph/extraction.ts

@@ -0,0 +1,10 @@
+/**
+ * Module information extraction from TypeScript source files
+ * Main dispatcher - re-exports from extraction/ subdirectory
+ */
+
+export {
+  extractModuleInfo,
+  extractImport,
+  extractExport,
+} from "./extraction/index.js";

package/src/graph/helpers.ts

@@ -0,0 +1,51 @@
+/**
+ * Helper functions for dependency graph analysis
+ */
+
+import * as ts from "typescript";
+
+/**
+ * Check if a node is top-level executable code (not just declarations)
+ */
+export const isTopLevelCode = (node: ts.Node): boolean => {
+  // Check if this is a top-level statement that's not a declaration
+  if (node.parent && ts.isSourceFile(node.parent)) {
+    return (
+      !ts.isModuleDeclaration(node) &&
+      !ts.isImportDeclaration(node) &&
+      !ts.isExportDeclaration(node) &&
+      !ts.isExportAssignment(node) &&
+      !ts.isTypeAliasDeclaration(node) &&
+      !ts.isInterfaceDeclaration(node) &&
+      !(ts.isVariableStatement(node) && !hasExecutableInitializer(node)) &&
+      !ts.isFunctionDeclaration(node) &&
+      !ts.isClassDeclaration(node) &&
+      !ts.isEnumDeclaration(node)
+    );
+  }
+  return false;
+};
+
+/**
+ * Check if a variable statement has an initializer that executes code
+ */
+export const hasExecutableInitializer = (
+  node: ts.VariableStatement
+): boolean => {
+  return node.declarationList.declarations.some(
+    (decl) => decl.initializer && !ts.isLiteralExpression(decl.initializer)
+  );
+};
+
+/**
+ * Check if a node has the export modifier
+ */
+export const hasExportModifier = (node: ts.Node): boolean => {
+  if (!ts.canHaveModifiers(node)) {
+    return false;
+  }
+  const modifiers = ts.getModifiers(node);
+  return (
+    modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false
+  );
+};

package/src/graph/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Dependency graph builder - Public API
+ */
+
+export type { DependencyAnalysis } from "./types.js";
+export { buildDependencyGraph } from "./builder.js";
+export {
+  extractModuleInfo,
+  extractImport,
+  extractExport,
+} from "./extraction.js";
+export { checkCircularDependencies } from "./circular.js";
+export {
+  isTopLevelCode,
+  hasExecutableInitializer,
+  hasExportModifier,
+} from "./helpers.js";

package/src/graph/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Dependency graph type definitions
+ */
+
+import { ModuleGraph } from "../types/module.js";
+import { DiagnosticsCollector } from "../types/diagnostic.js";
+import { SymbolTable } from "../symbol-table.js";
+
+export type DependencyAnalysis = {
+  readonly graph: ModuleGraph;
+  readonly symbolTable: SymbolTable;
+  readonly diagnostics: DiagnosticsCollector;
+};