@tsonic/frontend 0.0.1

package/src/metadata/library-loader.ts

@@ -0,0 +1,153 @@
+/**
+ * Library Loader - Load metadata and bindings from external library directories.
+ *
+ * External libraries (specified via --lib flag) contain both metadata and bindings:
+ *   lib-path/
+ *     .metadata/
+ *       Namespace.metadata.json
+ *     .bindings/
+ *       Namespace.bindings.json
+ *
+ * This module provides helpers to load both from a single library root path.
+ */
+
+import { join } from "path";
+import { existsSync, statSync } from "fs";
+import type { Result } from "../types/result.js";
+import type { Diagnostic } from "../types/diagnostic.js";
+import { loadMetadataDirectory } from "./loader.js";
+import { loadBindingsDirectory } from "./bindings-loader.js";
+import type { MetadataFile } from "../types/metadata.js";
+import type { BindingsFile } from "../types/bindings.js";
+
+/**
+ * Loaded library data (metadata + bindings).
+ */
+export type LibraryData = {
+  readonly metadata: ReadonlyArray<MetadataFile>;
+  readonly bindings: ReadonlyArray<BindingsFile>;
+};
+
+/**
+ * Load metadata and bindings from a library directory.
+ *
+ * Looks for:
+ * - ${libraryPath}/.metadata/ directory
+ * - ${libraryPath}/.bindings/ directory
+ *
+ * @param libraryPath - Path to external library root
+ * @returns Result with library data or diagnostics
+ */
+export const loadLibrary = (
+  libraryPath: string
+): Result<LibraryData, Diagnostic[]> => {
+  const diagnostics: Diagnostic[] = [];
+
+  // Validate library path exists
+  if (!existsSync(libraryPath)) {
+    return {
+      ok: false,
+      error: [
+        {
+          code: "TSN9016",
+          severity: "error",
+          message: `Library directory not found: ${libraryPath}`,
+        },
+      ],
+    };
+  }
+
+  // Validate it's a directory
+  if (!statSync(libraryPath).isDirectory()) {
+    return {
+      ok: false,
+      error: [
+        {
+          code: "TSN9017",
+          severity: "error",
+          message: `Library path is not a directory: ${libraryPath}`,
+        },
+      ],
+    };
+  }
+
+  // Load metadata from .metadata/ subdirectory
+  const metadataPath = join(libraryPath, ".metadata");
+  let metadata: ReadonlyArray<MetadataFile> = [];
+
+  if (existsSync(metadataPath)) {
+    const metadataResult = loadMetadataDirectory(metadataPath);
+    if (metadataResult.ok) {
+      metadata = metadataResult.value;
+    } else {
+      diagnostics.push(...metadataResult.error);
+    }
+  }
+
+  // Load bindings from .bindings/ subdirectory
+  const bindingsPath = join(libraryPath, ".bindings");
+  let bindings: ReadonlyArray<BindingsFile> = [];
+
+  if (existsSync(bindingsPath)) {
+    const bindingsResult = loadBindingsDirectory(bindingsPath);
+    if (bindingsResult.ok) {
+      bindings = bindingsResult.value;
+    } else {
+      diagnostics.push(...bindingsResult.error);
+    }
+  }
+
+  // Return success even if one or both are missing (library might be incomplete)
+  return {
+    ok: true,
+    value: {
+      metadata,
+      bindings,
+    },
+  };
+};
+
+/**
+ * Load metadata and bindings from multiple library directories.
+ *
+ * @param libraryPaths - Array of library root paths
+ * @returns Result with merged library data or diagnostics
+ */
+export const loadLibraries = (
+  libraryPaths: readonly string[]
+): Result<LibraryData, Diagnostic[]> => {
+  const allMetadata: MetadataFile[] = [];
+  const allBindings: BindingsFile[] = [];
+  const allDiagnostics: Diagnostic[] = [];
+
+  for (const libPath of libraryPaths) {
+    const result = loadLibrary(libPath);
+    if (result.ok) {
+      allMetadata.push(...result.value.metadata);
+      allBindings.push(...result.value.bindings);
+    } else {
+      allDiagnostics.push(...result.error);
+    }
+  }
+
+  // If we have any diagnostics but also loaded some data, still succeed
+  // (allows partial library loading)
+  if (
+    allDiagnostics.length > 0 &&
+    allMetadata.length === 0 &&
+    allBindings.length === 0
+  ) {
+    return {
+      ok: false,
+      error: allDiagnostics,
+    };
+  }
+
+  return {
+    ok: true,
+    value: {
+      metadata: allMetadata,
+      bindings: allBindings,
+    },
+  };
+};

package/src/metadata/loader.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Tests for metadata JSON loader
+ */
+
+import { describe, it } from "mocha";
+import { strict as assert } from "assert";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { loadMetadataFile, loadMetadataDirectory } from "./loader.js";
+import type { MetadataFile } from "../types/metadata.js";
+
+describe("Metadata Loader", () => {
+  describe("loadMetadataFile", () => {
+    it("should load valid metadata file", () => {
+      // Create temporary metadata file
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tsonic-test-"));
+      const metadataPath = path.join(tmpDir, "test.metadata.json");
+
+      const metadata: MetadataFile = {
+        namespace: "System",
+        contributingAssemblies: ["System.Runtime"],
+        types: [
+          {
+            clrName: "System.String",
+            tsEmitName: "String",
+            kind: "Class",
+            accessibility: "Public",
+            isAbstract: false,
+            isSealed: true,
+            isStatic: false,
+            arity: 0,
+            methods: [],
+            properties: [],
+            fields: [],
+            events: [],
+            constructors: [],
+          },
+        ],
+      };
+
+      fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
+
+      const result = loadMetadataFile(metadataPath);
+
+      // Cleanup
+      fs.unlinkSync(metadataPath);
+      fs.rmdirSync(tmpDir);
+
+      assert.ok(result.ok);
+      if (result.ok) {
+        assert.equal(result.value.namespace, "System");
+        assert.equal(result.value.types.length, 1);
+        assert.equal(result.value.types[0]?.tsEmitName, "String");
+      }
+    });
+
+    it("should return error for non-existent file", () => {
+      const result = loadMetadataFile("/nonexistent/file.metadata.json");
+
+      assert.ok(!result.ok);
+      if (!result.ok) {
+        assert.equal(result.error[0]?.code, "TSN9001");
+      }
+    });
+
+    it("should return error for invalid JSON", () => {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tsonic-test-"));
+      const metadataPath = path.join(tmpDir, "invalid.metadata.json");
+
+      fs.writeFileSync(metadataPath, "{ invalid json }");
+
+      const result = loadMetadataFile(metadataPath);
+
+      // Cleanup
+      fs.unlinkSync(metadataPath);
+      fs.rmdirSync(tmpDir);
+
+      assert.ok(!result.ok);
+      if (!result.ok) {
+        assert.equal(result.error[0]?.code, "TSN9003");
+      }
+    });
+
+    it("should return error for missing required fields", () => {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tsonic-test-"));
+      const metadataPath = path.join(tmpDir, "incomplete.metadata.json");
+
+      // Missing namespace field
+      fs.writeFileSync(
+        metadataPath,
+        JSON.stringify({ contributingAssemblies: [], types: [] })
+      );
+
+      const result = loadMetadataFile(metadataPath);
+
+      // Cleanup
+      fs.unlinkSync(metadataPath);
+      fs.rmdirSync(tmpDir);
+
+      assert.ok(!result.ok);
+      if (!result.ok) {
+        assert.equal(result.error[0]?.code, "TSN9005");
+      }
+    });
+  });
+
+  describe("loadMetadataDirectory", () => {
+    it("should load all metadata files from directory", () => {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tsonic-test-"));
+
+      // Create two metadata files
+      const metadata1: MetadataFile = {
+        namespace: "System",
+        contributingAssemblies: ["System.Runtime"],
+        types: [],
+      };
+
+      const metadata2: MetadataFile = {
+        namespace: "System.Collections",
+        contributingAssemblies: ["System.Collections"],
+        types: [],
+      };
+
+      fs.writeFileSync(
+        path.join(tmpDir, "System.metadata.json"),
+        JSON.stringify(metadata1)
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, "System.Collections.metadata.json"),
+        JSON.stringify(metadata2)
+      );
+
+      const result = loadMetadataDirectory(tmpDir);
+
+      // Cleanup
+      fs.unlinkSync(path.join(tmpDir, "System.metadata.json"));
+      fs.unlinkSync(path.join(tmpDir, "System.Collections.metadata.json"));
+      fs.rmdirSync(tmpDir);
+
+      assert.ok(result.ok);
+      if (result.ok) {
+        assert.equal(result.value.length, 2);
+      }
+    });
+
+    it("should return error for non-existent directory", () => {
+      const result = loadMetadataDirectory("/nonexistent/directory");
+
+      assert.ok(!result.ok);
+      if (!result.ok) {
+        assert.equal(result.error[0]?.code, "TSN9016");
+      }
+    });
+  });
+});

package/src/metadata/loader.ts

@@ -0,0 +1,382 @@
+/**
+ * Metadata JSON loader - Reads and validates .metadata.json files from tsbindgen.
+ *
+ * This module provides pure functions to load CLR metadata files and validate
+ * their structure against the expected schema.
+ *
+ * @see spec/metadata.md for complete schema documentation
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { Result } from "../types/result.ts";
+import type { Diagnostic } from "../types/diagnostic.ts";
+import type {
+  MetadataFile,
+  TypeMetadata,
+  TypeKind,
+  Accessibility,
+} from "../types/metadata.ts";
+
+/**
+ * Load and parse a metadata.json file.
+ *
+ * @param filePath - Absolute path to the .metadata.json file
+ * @returns Result containing parsed metadata or diagnostics
+ */
+export const loadMetadataFile = (
+  filePath: string
+): Result<MetadataFile, Diagnostic[]> => {
+  // Check file exists
+  if (!fs.existsSync(filePath)) {
+    return {
+      ok: false,
+      error: [
+        {
+          code: "TSN9001",
+          message: `Metadata file not found: ${filePath}`,
+          severity: "error",
+          location: undefined,
+        },
+      ],
+    };
+  }
+
+  // Read file contents
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch (error) {
+    return {
+      ok: false,
+      error: [
+        {
+          code: "TSN9002",
+          message: `Failed to read metadata file: ${error}`,
+          severity: "error",
+          location: undefined,
+        },
+      ],
+    };
+  }
+
+  // Parse JSON
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    return {
+      ok: false,
+      error: [
+        {
+          code: "TSN9003",
+          message: `Invalid JSON in metadata file: ${error}`,
+          severity: "error",
+          location: undefined,
+        },
+      ],
+    };
+  }
+
+  // Validate structure
+  const validation = validateMetadataFile(parsed, filePath);
+  if (!validation.ok) {
+    return validation;
+  }
+
+  return { ok: true, value: validation.value };
+};
+
+/**
+ * Validate that parsed JSON matches MetadataFile schema.
+ *
+ * @param data - Parsed JSON data
+ * @param filePath - File path for error messages
+ * @returns Result containing validated metadata or diagnostics
+ */
+const validateMetadataFile = (
+  data: unknown,
+  filePath: string
+): Result<MetadataFile, Diagnostic[]> => {
+  const diagnostics: Diagnostic[] = [];
+
+  if (typeof data !== "object" || data === null) {
+    return {
+      ok: false,
+      error: [
+        {
+          code: "TSN9004",
+          message: `Metadata file must be an object, got ${typeof data}`,
+          severity: "error",
+          location: undefined,
+        },
+      ],
+    };
+  }
+
+  const obj = data as Record<string, unknown>;
+
+  // Validate namespace
+  if (typeof obj.namespace !== "string") {
+    diagnostics.push({
+      code: "TSN9005",
+      message: `Missing or invalid 'namespace' field in ${path.basename(filePath)}`,
+      severity: "error",
+      location: undefined,
+    });
+  }
+
+  // Validate contributingAssemblies
+  if (!Array.isArray(obj.contributingAssemblies)) {
+    diagnostics.push({
+      code: "TSN9006",
+      message: `Missing or invalid 'contributingAssemblies' field in ${path.basename(filePath)}`,
+      severity: "error",
+      location: undefined,
+    });
+  } else if (
+    !obj.contributingAssemblies.every((item) => typeof item === "string")
+  ) {
+    diagnostics.push({
+      code: "TSN9007",
+      message: `All 'contributingAssemblies' must be strings in ${path.basename(filePath)}`,
+      severity: "error",
+      location: undefined,
+    });
+  }
+
+  // Validate types array
+  if (!Array.isArray(obj.types)) {
+    diagnostics.push({
+      code: "TSN9008",
+      message: `Missing or invalid 'types' field in ${path.basename(filePath)}`,
+      severity: "error",
+      location: undefined,
+    });
+  } else {
+    // Validate each type
+    for (let i = 0; i < obj.types.length; i++) {
+      const typeValidation = validateTypeMetadata(obj.types[i], filePath, i);
+      if (!typeValidation.ok) {
+        diagnostics.push(...typeValidation.error);
+      }
+    }
+  }
+
+  if (diagnostics.length > 0) {
+    return { ok: false, error: diagnostics };
+  }
+
+  return { ok: true, value: obj as MetadataFile };
+};
+
+/**
+ * Validate a single TypeMetadata object.
+ *
+ * @param data - Type metadata to validate
+ * @param filePath - File path for error messages
+ * @param index - Type index in array
+ * @returns Result indicating validation success or errors
+ */
+const validateTypeMetadata = (
+  data: unknown,
+  filePath: string,
+  index: number
+): Result<TypeMetadata, Diagnostic[]> => {
+  const diagnostics: Diagnostic[] = [];
+  const context = `type ${index} in ${path.basename(filePath)}`;
+
+  if (typeof data !== "object" || data === null) {
+    return {
+      ok: false,
+      error: [
+        {
+          code: "TSN9009",
+          message: `Invalid ${context}: must be an object`,
+          severity: "error",
+          location: undefined,
+        },
+      ],
+    };
+  }
+
+  const type = data as Record<string, unknown>;
+
+  // Validate required string fields
+  const requiredStringFields = ["clrName", "tsEmitName"];
+  for (const field of requiredStringFields) {
+    if (typeof type[field] !== "string") {
+      diagnostics.push({
+        code: "TSN9010",
+        message: `Invalid ${context}: missing or invalid '${field}'`,
+        severity: "error",
+        location: undefined,
+      });
+    }
+  }
+
+  // Validate kind
+  const validKinds: TypeKind[] = [
+    "Class",
+    "Interface",
+    "Struct",
+    "Enum",
+    "Delegate",
+  ];
+  if (!validKinds.includes(type.kind as TypeKind)) {
+    diagnostics.push({
+      code: "TSN9011",
+      message: `Invalid ${context}: 'kind' must be one of ${validKinds.join(", ")}`,
+      severity: "error",
+      location: undefined,
+    });
+  }
+
+  // Validate accessibility
+  const validAccessibility: Accessibility[] = [
+    "Public",
+    "Internal",
+    "Protected",
+    "ProtectedInternal",
+    "PrivateProtected",
+    "Private",
+  ];
+  if (!validAccessibility.includes(type.accessibility as Accessibility)) {
+    diagnostics.push({
+      code: "TSN9012",
+      message: `Invalid ${context}: 'accessibility' must be one of ${validAccessibility.join(", ")}`,
+      severity: "error",
+      location: undefined,
+    });
+  }
+
+  // Validate required boolean fields
+  const requiredBooleanFields = ["isAbstract", "isSealed", "isStatic"];
+  for (const field of requiredBooleanFields) {
+    if (typeof type[field] !== "boolean") {
+      diagnostics.push({
+        code: "TSN9013",
+        message: `Invalid ${context}: '${field}' must be a boolean`,
+        severity: "error",
+        location: undefined,
+      });
+    }
+  }
+
+  // Validate arity
+  if (typeof type.arity !== "number" || type.arity < 0) {
+    diagnostics.push({
+      code: "TSN9014",
+      message: `Invalid ${context}: 'arity' must be a non-negative number`,
+      severity: "error",
+      location: undefined,
+    });
+  }
+
+  // Validate required array fields
+  const requiredArrayFields = [
+    "methods",
+    "properties",
+    "fields",
+    "events",
+    "constructors",
+  ];
+  for (const field of requiredArrayFields) {
+    if (!Array.isArray(type[field])) {
+      diagnostics.push({
+        code: "TSN9015",
+        message: `Invalid ${context}: '${field}' must be an array`,
+        severity: "error",
+        location: undefined,
+      });
+    }
+  }
+
+  // Note: We're doing basic structural validation here
+  // More detailed validation of nested objects (methods, properties, etc.)
+  // can be added in future iterations if needed
+
+  if (diagnostics.length > 0) {
+    return { ok: false, error: diagnostics };
+  }
+
+  return { ok: true, value: type as TypeMetadata };
+};
+
+/**
+ * Load metadata from a directory containing .metadata.json files.
+ *
+ * @param directoryPath - Path to directory containing metadata files
+ * @returns Result containing array of loaded metadata files or diagnostics
+ */
+export const loadMetadataDirectory = (
+  directoryPath: string
+): Result<MetadataFile[], Diagnostic[]> => {
+  if (!fs.existsSync(directoryPath)) {
+    return {
+      ok: false,
+      error: [
+        {
+          code: "TSN9016",
+          message: `Metadata directory not found: ${directoryPath}`,
+          severity: "error",
+          location: undefined,
+        },
+      ],
+    };
+  }
+
+  const stats = fs.statSync(directoryPath);
+  if (!stats.isDirectory()) {
+    return {
+      ok: false,
+      error: [
+        {
+          code: "TSN9017",
+          message: `Not a directory: ${directoryPath}`,
+          severity: "error",
+          location: undefined,
+        },
+      ],
+    };
+  }
+
+  // Find all .metadata.json files
+  const files = fs
+    .readdirSync(directoryPath)
+    .filter((file) => file.endsWith(".metadata.json"))
+    .map((file) => path.join(directoryPath, file));
+
+  if (files.length === 0) {
+    return {
+      ok: false,
+      error: [
+        {
+          code: "TSN9018",
+          message: `No .metadata.json files found in ${directoryPath}`,
+          severity: "warning",
+          location: undefined,
+        },
+      ],
+    };
+  }
+
+  // Load each file
+  const metadataFiles: MetadataFile[] = [];
+  const diagnostics: Diagnostic[] = [];
+
+  for (const file of files) {
+    const result = loadMetadataFile(file);
+    if (result.ok) {
+      metadataFiles.push(result.value);
+    } else {
+      diagnostics.push(...result.error);
+    }
+  }
+
+  if (diagnostics.length > 0) {
+    return { ok: false, error: diagnostics };
+  }
+
+  return { ok: true, value: metadataFiles };
+};