@tsonic/frontend 0.0.1

package/src/resolver/dotnet-import-resolver.ts

@@ -0,0 +1,226 @@
+/**
+ * Import-driven .NET namespace resolution
+ *
+ * Determines if an import specifier refers to a CLR namespace by checking
+ * if bindings.json exists in the package's namespace directory.
+ *
+ * This is the ONLY mechanism for detecting .NET imports - no heuristics,
+ * no special-casing for @tsonic/dotnet or any other package.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+
+/**
+ * Result of resolving a .NET import
+ */
+export type ResolvedDotNetImport =
+  | {
+      readonly isDotNet: true;
+      readonly packageName: string;
+      readonly resolvedNamespace: string;
+      readonly bindingsPath: string;
+      readonly metadataPath: string | undefined;
+    }
+  | {
+      readonly isDotNet: false;
+    };
+
+/**
+ * Parsed module specifier
+ */
+type ParsedSpecifier = {
+  readonly packageName: string;
+  readonly subpath: string;
+};
+
+/**
+ * Resolver for .NET namespace imports
+ *
+ * An import is a CLR namespace import iff:
+ * - It's a package import with a subpath (e.g., @scope/pkg/Namespace)
+ * - The package contains bindings.json in that subpath directory
+ *
+ * This works for any bindings provider package, not just @tsonic/dotnet.
+ */
+export class DotNetImportResolver {
+  // Cache: packageName -> packageRoot (or null if not found)
+  private readonly pkgRootCache = new Map<string, string | null>();
+
+  // Cache: absolute bindingsPath -> exists
+  private readonly bindingsExistsCache = new Map<string, boolean>();
+
+  // require function for Node resolution from the base directory
+  private readonly require: NodeRequire;
+
+  constructor(baseDir: string) {
+    // Create a require function that resolves relative to baseDir
+    this.require = createRequire(join(baseDir, "package.json"));
+  }
+
+  /**
+   * Resolve an import specifier to determine if it's a CLR namespace import
+   */
+  resolve(moduleSpecifier: string): ResolvedDotNetImport {
+    // Skip local imports
+    if (moduleSpecifier.startsWith(".") || moduleSpecifier.startsWith("/")) {
+      return { isDotNet: false };
+    }
+
+    // Parse the specifier into package name and subpath
+    const parsed = this.parseModuleSpecifier(moduleSpecifier);
+    if (!parsed) {
+      return { isDotNet: false };
+    }
+
+    const { packageName, subpath } = parsed;
+
+    // No subpath means it's not a namespace import (e.g., just "@tsonic/dotnet")
+    if (!subpath) {
+      return { isDotNet: false };
+    }
+
+    // Resolve package root using Node resolution
+    const pkgRoot = this.resolvePkgRoot(packageName);
+    if (!pkgRoot) {
+      return { isDotNet: false };
+    }
+
+    // Check if bindings.json exists in the namespace directory
+    const bindingsPath = join(pkgRoot, subpath, "bindings.json");
+    if (!this.hasBindings(bindingsPath)) {
+      return { isDotNet: false };
+    }
+
+    // Check for optional metadata.json
+    const metadataPath = join(pkgRoot, subpath, "internal", "metadata.json");
+    const hasMetadata = this.fileExists(metadataPath);
+
+    return {
+      isDotNet: true,
+      packageName,
+      resolvedNamespace: subpath,
+      bindingsPath,
+      metadataPath: hasMetadata ? metadataPath : undefined,
+    };
+  }
+
+  /**
+   * Parse a module specifier into package name and subpath
+   *
+   * Examples:
+   * - "@tsonic/dotnet/System.IO" -> { packageName: "@tsonic/dotnet", subpath: "System.IO" }
+   * - "lodash/fp" -> { packageName: "lodash", subpath: "fp" }
+   * - "@tsonic/dotnet" -> null (no subpath)
+   * - "lodash" -> null (no subpath)
+   */
+  private parseModuleSpecifier(spec: string): ParsedSpecifier | null {
+    if (spec.startsWith("@")) {
+      // Scoped package: @scope/pkg/subpath
+      const match = spec.match(/^(@[^/]+\/[^/]+)(?:\/(.+))?$/);
+      if (!match) return null;
+      const packageName = match[1];
+      const subpath = match[2];
+      if (!packageName || !subpath) return null;
+      return { packageName, subpath };
+    } else {
+      // Regular package: pkg/subpath
+      const slashIdx = spec.indexOf("/");
+      if (slashIdx === -1) return null;
+      return {
+        packageName: spec.slice(0, slashIdx),
+        subpath: spec.slice(slashIdx + 1),
+      };
+    }
+  }
+
+  /**
+   * Resolve package root directory using Node resolution
+   *
+   * Uses require.resolve to find the package's package.json,
+   * then returns the directory containing it.
+   */
+  private resolvePkgRoot(packageName: string): string | null {
+    const cached = this.pkgRootCache.get(packageName);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    try {
+      // Try to resolve the package's package.json directly
+      const pkgJsonPath = this.require.resolve(`${packageName}/package.json`);
+      const pkgRoot = dirname(pkgJsonPath);
+      this.pkgRootCache.set(packageName, pkgRoot);
+      return pkgRoot;
+    } catch {
+      // package.json might not be exported - try finding package root via node_modules path
+      // This works by looking for node_modules/<package-name> in the require paths
+      try {
+        const paths = this.require.resolve.paths(packageName);
+        if (paths) {
+          for (const searchPath of paths) {
+            // For scoped packages, the path structure is node_modules/@scope/name
+            const pkgDir = packageName.startsWith("@")
+              ? join(searchPath, packageName)
+              : join(searchPath, packageName);
+
+            // Check if package.json exists at this location
+            if (existsSync(join(pkgDir, "package.json"))) {
+              this.pkgRootCache.set(packageName, pkgDir);
+              return pkgDir;
+            }
+          }
+        }
+      } catch {
+        // Fallback failed
+      }
+
+      this.pkgRootCache.set(packageName, null);
+      return null;
+    }
+  }
+
+  /**
+   * Check if bindings.json exists at the given path (cached)
+   */
+  private hasBindings(bindingsPath: string): boolean {
+    const cached = this.bindingsExistsCache.get(bindingsPath);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const exists = existsSync(bindingsPath);
+    this.bindingsExistsCache.set(bindingsPath, exists);
+    return exists;
+  }
+
+  /**
+   * Check if a file exists (not cached - used for optional files)
+   */
+  private fileExists(filePath: string): boolean {
+    return existsSync(filePath);
+  }
+
+  /**
+   * Get all discovered binding paths (for loading)
+   */
+  getDiscoveredBindingPaths(): ReadonlySet<string> {
+    const paths = new Set<string>();
+    for (const [path, exists] of this.bindingsExistsCache) {
+      if (exists) {
+        paths.add(path);
+      }
+    }
+    return paths;
+  }
+}
+
+/**
+ * Create a resolver instance for a given source root
+ */
+export const createDotNetImportResolver = (
+  sourceRoot: string
+): DotNetImportResolver => {
+  return new DotNetImportResolver(sourceRoot);
+};

package/src/resolver/import-resolution.ts

@@ -0,0 +1,177 @@
+/**
+ * Import resolution with ESM rules enforcement
+ */
+
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { Result, ok, error } from "../types/result.js";
+import { Diagnostic, createDiagnostic } from "../types/diagnostic.js";
+import { isLocalImport } from "../types/module.js";
+import { ResolvedModule } from "./types.js";
+import { getBindingRegistry } from "../ir/converters/statements/declarations/registry.js";
+import { DotNetImportResolver } from "./dotnet-import-resolver.js";
+
+/**
+ * Resolve import specifier to module
+ */
+export const resolveImport = (
+  importSpecifier: string,
+  containingFile: string,
+  sourceRoot: string,
+  dotnetResolver?: DotNetImportResolver
+): Result<ResolvedModule, Diagnostic> => {
+  if (isLocalImport(importSpecifier)) {
+    return resolveLocalImport(importSpecifier, containingFile, sourceRoot);
+  }
+
+  // Use import-driven resolution for .NET imports (if resolver provided)
+  if (dotnetResolver) {
+    const dotnetResolution = dotnetResolver.resolve(importSpecifier);
+    if (dotnetResolution.isDotNet) {
+      return ok({
+        resolvedPath: "", // No file path for .NET imports
+        isLocal: false,
+        isDotNet: true,
+        originalSpecifier: importSpecifier,
+        resolvedNamespace: dotnetResolution.resolvedNamespace,
+      });
+    }
+  }
+
+  // Check if this is a module binding (e.g., Node.js API)
+  const binding = getBindingRegistry().getBinding(importSpecifier);
+  if (binding && binding.kind === "module") {
+    return ok({
+      resolvedPath: "", // No file path for bound modules
+      isLocal: false,
+      isDotNet: false,
+      originalSpecifier: importSpecifier,
+      resolvedClrType: binding.type,
+      resolvedAssembly: binding.assembly,
+    });
+  }
+
+  // @tsonic/types is a type-only package (phantom types) - no runtime code
+  if (importSpecifier === "@tsonic/types") {
+    return ok({
+      resolvedPath: "", // No file path for type-only packages
+      isLocal: false,
+      isDotNet: false,
+      originalSpecifier: importSpecifier,
+      resolvedClrType: undefined,
+      resolvedAssembly: undefined,
+    });
+  }
+
+  return error(
+    createDiagnostic(
+      "TSN1004",
+      "error",
+      `Unsupported module import: "${importSpecifier}"`,
+      undefined,
+      "Tsonic only supports local imports (with .ts), .NET imports, and registered module bindings"
+    )
+  );
+};
+
+/**
+ * Resolve local import with ESM rules
+ */
+export const resolveLocalImport = (
+  importSpecifier: string,
+  containingFile: string,
+  sourceRoot: string
+): Result<ResolvedModule, Diagnostic> => {
+  // Check for .ts extension
+  if (!importSpecifier.endsWith(".ts")) {
+    return error(
+      createDiagnostic(
+        "TSN1001",
+        "error",
+        `Local import must have .ts extension: "${importSpecifier}"`,
+        undefined,
+        `Change to: "${importSpecifier}.ts"`
+      )
+    );
+  }
+
+  const containingDir = path.dirname(containingFile);
+  const resolvedPath = path.resolve(containingDir, importSpecifier);
+
+  // Check if file exists
+  if (!fs.existsSync(resolvedPath)) {
+    return error(
+      createDiagnostic(
+        "TSN1004",
+        "error",
+        `Cannot find module: "${importSpecifier}"`,
+        undefined,
+        `File not found: ${resolvedPath}`
+      )
+    );
+  }
+
+  // Check case sensitivity
+  const realPath = fs.realpathSync(resolvedPath);
+  if (realPath !== resolvedPath && process.platform !== "win32") {
+    return error(
+      createDiagnostic(
+        "TSN1003",
+        "error",
+        `Case mismatch in import path: "${importSpecifier}"`,
+        undefined,
+        `File exists as: ${realPath}`
+      )
+    );
+  }
+
+  // Ensure it's within the source root
+  if (!resolvedPath.startsWith(sourceRoot)) {
+    return error(
+      createDiagnostic(
+        "TSN1004",
+        "error",
+        `Import outside source root: "${importSpecifier}"`,
+        undefined,
+        `Source root: ${sourceRoot}`
+      )
+    );
+  }
+
+  return ok({
+    resolvedPath,
+    isLocal: true,
+    isDotNet: false,
+    originalSpecifier: importSpecifier,
+  });
+};
+
+/**
+ * Resolve .NET import (namespace validation)
+ */
+export const resolveDotNetImport = (
+  importSpecifier: string
+): Result<ResolvedModule, Diagnostic> => {
+  // For .NET imports, we don't resolve to a file
+  // We just validate the format and return the namespace
+
+  // Check for invalid characters
+  if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(importSpecifier)) {
+    return error(
+      createDiagnostic(
+        "TSN4001",
+        "error",
+        `Invalid .NET namespace: "${importSpecifier}"`,
+        undefined,
+        "Must be a valid .NET namespace identifier"
+      )
+    );
+  }
+
+  return ok({
+    resolvedPath: "", // No file path for .NET imports
+    isLocal: false,
+    isDotNet: true,
+    originalSpecifier: importSpecifier,
+  });
+};

package/src/resolver/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Module resolver - Public API
+ */
+
+export type { ResolvedModule } from "./types.js";
+export {
+  resolveImport,
+  resolveLocalImport,
+  resolveDotNetImport,
+} from "./import-resolution.js";
+export { resolveModulePath } from "./path-resolution.js";
+export { getNamespaceFromPath } from "./namespace.js";
+export { getClassNameFromPath } from "./naming.js";
+export {
+  DotNetImportResolver,
+  createDotNetImportResolver,
+  type ResolvedDotNetImport,
+} from "./dotnet-import-resolver.js";

package/src/resolver/namespace.test.ts

@@ -0,0 +1,86 @@
+import { describe, it } from "mocha";
+import { expect } from "chai";
+import { getNamespaceFromPath } from "./namespace.js";
+
+describe("getNamespaceFromPath", () => {
+  it("should return root namespace for files directly in source root", () => {
+    const result = getNamespaceFromPath(
+      "/project/src/index.ts",
+      "/project/src",
+      "MyApp"
+    );
+    expect(result).to.equal("MyApp");
+  });
+
+  it("should return root namespace for files in source root without src directory", () => {
+    const result = getNamespaceFromPath(
+      "/project/index.ts",
+      "/project",
+      "MyApp"
+    );
+    expect(result).to.equal("MyApp");
+  });
+
+  it("should compute namespace from single subdirectory", () => {
+    const result = getNamespaceFromPath(
+      "/project/src/models/user.ts",
+      "/project/src",
+      "MyApp"
+    );
+    expect(result).to.equal("MyApp.models");
+  });
+
+  it("should compute namespace from nested subdirectories", () => {
+    const result = getNamespaceFromPath(
+      "/project/src/models/entities/user.ts",
+      "/project/src",
+      "MyApp"
+    );
+    expect(result).to.equal("MyApp.models.entities");
+  });
+
+  it("should filter out 'src' from path components", () => {
+    const result = getNamespaceFromPath(
+      "/project/src/models/src/user.ts",
+      "/project/src",
+      "MyApp"
+    );
+    expect(result).to.equal("MyApp.models");
+  });
+
+  it("should handle case-preserved directory names", () => {
+    const result = getNamespaceFromPath(
+      "/project/src/MyModels/UserEntity.ts",
+      "/project/src",
+      "MyApp"
+    );
+    expect(result).to.equal("MyApp.MyModels");
+  });
+
+  it("should handle deep nesting", () => {
+    const result = getNamespaceFromPath(
+      "/project/src/a/b/c/d/e/file.ts",
+      "/project/src",
+      "MyApp"
+    );
+    expect(result).to.equal("MyApp.a.b.c.d.e");
+  });
+
+  it("should handle source root without trailing slash", () => {
+    const result = getNamespaceFromPath(
+      "/project/src/models/user.ts",
+      "/project/src",
+      "MyApp"
+    );
+    expect(result).to.equal("MyApp.models");
+  });
+
+  it("should handle source root with trailing slash", () => {
+    const result = getNamespaceFromPath(
+      "/project/src/models/user.ts",
+      "/project/src/",
+      "MyApp"
+    );
+    expect(result).to.equal("MyApp.models");
+  });
+});

package/src/resolver/namespace.ts

@@ -0,0 +1,42 @@
+import { dirname, relative } from "path";
+
+/**
+ * Compute namespace from file path relative to source root.
+ *
+ * Rules:
+ * - Namespace = rootNamespace + path components (excluding "src")
+ * - Path normalized with "/" separators after relative() call
+ * - Empty path maps to root namespace
+ *
+ * Examples:
+ * - /project/src/models/user.ts → RootNamespace.models
+ * - /project/src/index.ts → RootNamespace
+ * - /project/models/user.ts → RootNamespace.models
+ *
+ * @param filePath - Absolute path to the TypeScript file
+ * @param sourceRoot - Absolute path to source root directory
+ * @param rootNamespace - Root namespace for the project
+ * @returns Computed namespace string
+ */
+export const getNamespaceFromPath = (
+  filePath: string,
+  sourceRoot: string,
+  rootNamespace: string
+): string => {
+  const fileDir = dirname(filePath);
+
+  // Make relative to source root, then normalize to forward slashes
+  // IMPORTANT: Normalize AFTER relative() call, not before (cross-platform)
+  let relativePath = relative(sourceRoot, fileDir).replace(/\\/g, "/");
+
+  // Split by "/" and filter out empty, ".", and "src" components
+  const parts = relativePath
+    .split("/")
+    .filter((p) => p !== "" && p !== "." && p !== "src");
+
+  // If no path components, return root namespace
+  // Otherwise, join with "."
+  return parts.length === 0
+    ? rootNamespace
+    : `${rootNamespace}.${parts.join(".")}`;
+};

package/src/resolver/naming.ts

@@ -0,0 +1,38 @@
+/**
+ * Namespace and class name generation from file paths
+ */
+
+import * as path from "node:path";
+import { resolveModulePath } from "./path-resolution.js";
+
+/**
+ * Generate namespace from file path
+ */
+export const getNamespaceFromPath = (
+  filePath: string,
+  sourceRoot: string,
+  rootNamespace: string
+): string => {
+  const relativePath = resolveModulePath(filePath, sourceRoot);
+  const dirPath = path.dirname(relativePath);
+
+  if (dirPath === ".") {
+    return rootNamespace;
+  }
+
+  // Strip hyphens from directory names (per spec: hyphens are ignored)
+  const parts = dirPath
+    .split(path.sep)
+    .filter((p) => p !== ".")
+    .map((p) => p.replace(/-/g, ""));
+  return [rootNamespace, ...parts].join(".");
+};
+
+/**
+ * Generate class name from file path
+ */
+export const getClassNameFromPath = (filePath: string): string => {
+  const basename = path.basename(filePath, ".ts");
+  // Strip hyphens from file names (per spec: hyphens are ignored)
+  return basename.replace(/-/g, "");
+};

package/src/resolver/path-resolution.ts

@@ -0,0 +1,22 @@
+/**
+ * Path resolution utilities
+ */
+
+import * as path from "node:path";
+
+/**
+ * Resolve module path relative to source root
+ */
+export const resolveModulePath = (
+  filePath: string,
+  sourceRoot: string
+): string => {
+  const absolutePath = path.resolve(filePath);
+  const absoluteRoot = path.resolve(sourceRoot);
+
+  if (!absolutePath.startsWith(absoluteRoot)) {
+    throw new Error(`File ${filePath} is outside source root ${sourceRoot}`);
+  }
+
+  return path.relative(absoluteRoot, absolutePath);
+};

package/src/resolver/types.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolver type definitions
+ */
+
+export type ResolvedModule = {
+  readonly resolvedPath: string;
+  readonly isLocal: boolean;
+  readonly isDotNet: boolean;
+  readonly originalSpecifier: string;
+  // For .NET imports: the CLR namespace (e.g., "System" from "@tsonic/dotnet/System")
+  readonly resolvedNamespace?: string;
+  // For module bindings (Node.js APIs mapped to CLR types)
+  readonly resolvedClrType?: string; // e.g., "Tsonic.NodeApi.fs"
+  readonly resolvedAssembly?: string; // e.g., "Tsonic.NodeApi"
+};