@intentius/chant 0.0.1

package/src/discovery/import.test.ts

@@ -0,0 +1,199 @@
+import { describe, test, expect } from "bun:test";
+import { importModule } from "./import";
+import { DiscoveryError } from "../errors";
+import { withTestDir, expectToThrow } from "@intentius/chant-test-utils";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+describe("importModule", () => {
+
+  test("imports a valid module and returns exports", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "module.ts");
+      await writeFile(
+        filePath,
+        'export const greeting = "hello";\nexport const count = 42;'
+      );
+
+      const module = await importModule(filePath);
+      expect(module.greeting).toBe("hello");
+      expect(module.count).toBe(42);
+    });
+  });
+
+  test("imports module with default export", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "default.ts");
+      await writeFile(filePath, "export default { name: 'test', value: 123 };");
+
+      const module = await importModule(filePath);
+      expect(module.default).toBeDefined();
+      expect(module.default.name).toBe("test");
+      expect(module.default.value).toBe(123);
+    });
+  });
+
+  test("imports module with mixed exports", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "mixed.ts");
+      await writeFile(
+        filePath,
+        'export default "main";\nexport const helper = "utils";\nexport const version = 1;'
+      );
+
+      const module = await importModule(filePath);
+      expect(module.default).toBe("main");
+      expect(module.helper).toBe("utils");
+      expect(module.version).toBe(1);
+    });
+  });
+
+  test("imports module with no exports", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "empty.ts");
+      await writeFile(filePath, "const internal = 42;");
+
+      const module = await importModule(filePath);
+      expect(module).toBeDefined();
+      expect(Object.keys(module)).not.toContain("internal");
+    });
+  });
+
+  test("throws DiscoveryError with type 'import' for non-existent file", async () => {
+    await withTestDir(async (testDir) => {
+      const nonExistentPath = join(testDir, "does-not-exist.ts");
+
+      const error = await expectToThrow(
+        () => importModule(nonExistentPath),
+        DiscoveryError,
+        (err) => {
+          expect(err.type).toBe("import");
+          expect(err.file).toBe(nonExistentPath);
+          expect(err.message).toBeDefined();
+        }
+      );
+    });
+  });
+
+  test("throws DiscoveryError with type 'import' for invalid syntax", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "invalid.ts");
+      await writeFile(filePath, "export const broken = {");
+
+      await expectToThrow(
+        () => importModule(filePath),
+        DiscoveryError,
+        (error) => {
+          expect(error.type).toBe("import");
+          expect(error.file).toBe(filePath);
+          expect(error.message).toBeDefined();
+        }
+      );
+    });
+  });
+
+  test("throws DiscoveryError with type 'import' for runtime error", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "runtime-error.ts");
+      await writeFile(
+        filePath,
+        'throw new Error("Module initialization failed");'
+      );
+
+      await expectToThrow(
+        () => importModule(filePath),
+        DiscoveryError,
+        (error) => {
+          expect(error.type).toBe("import");
+          expect(error.file).toBe(filePath);
+          expect(error.message).toContain("Module initialization failed");
+        }
+      );
+    });
+  });
+
+  test("imports module with class exports", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "class.ts");
+      await writeFile(
+        filePath,
+        `export class MyClass {
+        constructor(public value: number) {}
+        getValue() { return this.value; }
+      }`
+      );
+
+      const module = await importModule(filePath);
+      expect(module.MyClass).toBeDefined();
+      const instance = new module.MyClass(100);
+      expect(instance.getValue()).toBe(100);
+    });
+  });
+
+  test("imports module with function exports", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "functions.ts");
+      await writeFile(
+        filePath,
+        `export function add(a: number, b: number) { return a + b; }
+       export const multiply = (a: number, b: number) => a * b;`
+      );
+
+      const module = await importModule(filePath);
+      expect(module.add).toBeInstanceOf(Function);
+      expect(module.multiply).toBeInstanceOf(Function);
+      expect(module.add(2, 3)).toBe(5);
+      expect(module.multiply(4, 5)).toBe(20);
+    });
+  });
+
+  test("imports module with re-exports", async () => {
+    await withTestDir(async (testDir) => {
+      const utilsPath = join(testDir, "utils.ts");
+      const indexPath = join(testDir, "index.ts");
+
+      await writeFile(utilsPath, 'export const util = "helper";');
+      await writeFile(indexPath, 'export { util } from "./utils.ts";');
+
+      const module = await importModule(indexPath);
+      expect(module.util).toBe("helper");
+    });
+  });
+
+  test("preserves error message from underlying import failure", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "missing-dep.ts");
+      await writeFile(
+        filePath,
+        'import { nonExistent } from "./does-not-exist.ts";\nexport const value = nonExistent;'
+      );
+
+      await expectToThrow(
+        () => importModule(filePath),
+        DiscoveryError,
+        (error) => {
+          expect(error.type).toBe("import");
+          expect(error.file).toBe(filePath);
+          expect(error.message.length).toBeGreaterThan(0);
+        }
+      );
+    });
+  });
+
+  test("error serializes to JSON correctly", async () => {
+    await withTestDir(async (testDir) => {
+      const filePath = join(testDir, "bad.ts");
+
+      const error = await expectToThrow(
+        () => importModule(filePath),
+        DiscoveryError
+      );
+
+      const json = error.toJSON();
+      expect(json.name).toBe("DiscoveryError");
+      expect(json.file).toBe(filePath);
+      expect(json.type).toBe("import");
+      expect(json.message).toBeDefined();
+    });
+  });
+});

package/src/discovery/import.ts

@@ -0,0 +1,20 @@
+import { DiscoveryError } from "../errors";
+
+/**
+ * Dynamically import a module and return its exports.
+ *
+ * @param path - The file path to import
+ * @returns The module exports
+ * @throws {DiscoveryError} with type "import" if the import fails
+ */
+export async function importModule(
+  path: string
+): Promise<Record<string, unknown>> {
+  try {
+    return require(path);
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Unknown import error";
+    throw new DiscoveryError(path, message, "import");
+  }
+}

package/src/discovery/index.test.ts

@@ -0,0 +1,272 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { discover } from "./index";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { DECLARABLE_MARKER } from "../declarable";
+
+describe("discover", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-discover-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("returns empty result for empty directory", async () => {
+    const result = await discover(testDir);
+
+    expect(result.entities.size).toBe(0);
+    expect(result.dependencies.size).toBe(0);
+    expect(result.sourceFiles).toEqual([]);
+    expect(result.errors).toEqual([]);
+  });
+
+  test("discovers entities from a single file", async () => {
+    await writeFile(
+      join(testDir, "app.ts"),
+      `
+        export const myEntity = {
+          entityType: "TestEntity",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    const result = await discover(testDir);
+
+    expect(result.entities.size).toBe(1);
+    expect(result.entities.has("myEntity")).toBe(true);
+    expect(result.sourceFiles).toHaveLength(1);
+    expect(result.sourceFiles[0]).toMatch(/app\.ts$/);
+    expect(result.errors).toEqual([]);
+  });
+
+  test("discovers entities from multiple files", async () => {
+    await writeFile(
+      join(testDir, "app.ts"),
+      `
+        export const entity1 = {
+          entityType: "Entity1",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    await writeFile(
+      join(testDir, "config.ts"),
+      `
+        export const entity2 = {
+          entityType: "Entity2",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    const result = await discover(testDir);
+
+    expect(result.entities.size).toBe(2);
+    expect(result.entities.has("entity1")).toBe(true);
+    expect(result.entities.has("entity2")).toBe(true);
+    expect(result.sourceFiles).toHaveLength(2);
+    expect(result.errors).toEqual([]);
+  });
+
+  test("builds dependency graph for entities with references", async () => {
+    await writeFile(
+      join(testDir, "entities.ts"),
+      `
+        export const parent = {
+          entityType: "Parent",
+          [Symbol.for("chant.declarable")]: true,
+        };
+
+        export const child = {
+          entityType: "Child",
+          [Symbol.for("chant.declarable")]: true,
+          parentRef: parent,
+        };
+      `
+    );
+
+    const result = await discover(testDir);
+
+    expect(result.entities.size).toBe(2);
+    expect(result.dependencies.size).toBe(2);
+
+    const childDeps = result.dependencies.get("child");
+    expect(childDeps).toBeDefined();
+    expect(childDeps?.has("parent")).toBe(true);
+
+    const parentDeps = result.dependencies.get("parent");
+    expect(parentDeps).toBeDefined();
+    expect(parentDeps?.size).toBe(0);
+
+    expect(result.errors).toEqual([]);
+  });
+
+  test("collects import errors and continues processing", async () => {
+    await writeFile(
+      join(testDir, "good.ts"),
+      `
+        export const goodEntity = {
+          entityType: "Good",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    await writeFile(
+      join(testDir, "bad.ts"),
+      `
+        // This will cause a syntax error
+        export const badEntity = {
+          entityType: "Bad"
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    const result = await discover(testDir);
+
+    // Should still process the good file
+    expect(result.entities.has("goodEntity")).toBe(true);
+    expect(result.sourceFiles).toHaveLength(2);
+
+    // Should have collected the import error
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors.some(e => e.type === "import")).toBe(true);
+  });
+
+  test("returns source files even when no entities found", async () => {
+    await writeFile(
+      join(testDir, "empty.ts"),
+      `
+        export const notAnEntity = { foo: "bar" };
+      `
+    );
+
+    const result = await discover(testDir);
+
+    expect(result.entities.size).toBe(0);
+    expect(result.sourceFiles).toHaveLength(1);
+    expect(result.sourceFiles[0]).toMatch(/empty\.ts$/);
+    expect(result.errors).toEqual([]);
+  });
+
+  test("handles nested directory structures", async () => {
+    const subDir = join(testDir, "src", "entities");
+    await mkdir(subDir, { recursive: true });
+
+    await writeFile(
+      join(testDir, "root.ts"),
+      `
+        export const rootEntity = {
+          entityType: "Root",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    await writeFile(
+      join(subDir, "nested.ts"),
+      `
+        export const nestedEntity = {
+          entityType: "Nested",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    const result = await discover(testDir);
+
+    expect(result.entities.size).toBe(2);
+    expect(result.entities.has("rootEntity")).toBe(true);
+    expect(result.entities.has("nestedEntity")).toBe(true);
+    expect(result.sourceFiles).toHaveLength(2);
+    expect(result.errors).toEqual([]);
+  });
+
+  test("excludes test files from discovery", async () => {
+    await writeFile(
+      join(testDir, "app.ts"),
+      `
+        export const appEntity = {
+          entityType: "App",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    await writeFile(
+      join(testDir, "app.test.ts"),
+      `
+        export const testEntity = {
+          entityType: "Test",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    const result = await discover(testDir);
+
+    expect(result.entities.size).toBe(1);
+    expect(result.entities.has("appEntity")).toBe(true);
+    expect(result.entities.has("testEntity")).toBe(false);
+    expect(result.sourceFiles).toHaveLength(1);
+  });
+
+  test("filters non-declarable exports", async () => {
+    await writeFile(
+      join(testDir, "mixed.ts"),
+      `
+        export const entity = {
+          entityType: "Entity",
+          [Symbol.for("chant.declarable")]: true,
+        };
+
+        export const nonEntity = { foo: "bar" };
+        export const anotherNonEntity = 42;
+      `
+    );
+
+    const result = await discover(testDir);
+
+    expect(result.entities.size).toBe(1);
+    expect(result.entities.has("entity")).toBe(true);
+    expect(result.entities.has("nonEntity")).toBe(false);
+    expect(result.entities.has("anotherNonEntity")).toBe(false);
+  });
+
+  test("returns empty dependencies map for entities without references", async () => {
+    await writeFile(
+      join(testDir, "standalone.ts"),
+      `
+        export const standalone1 = {
+          entityType: "Standalone1",
+          [Symbol.for("chant.declarable")]: true,
+        };
+
+        export const standalone2 = {
+          entityType: "Standalone2",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `
+    );
+
+    const result = await discover(testDir);
+
+    expect(result.entities.size).toBe(2);
+    expect(result.dependencies.size).toBe(2);
+
+    const deps1 = result.dependencies.get("standalone1");
+    expect(deps1?.size).toBe(0);
+
+    const deps2 = result.dependencies.get("standalone2");
+    expect(deps2?.size).toBe(0);
+  });
+});

package/src/discovery/index.ts

@@ -0,0 +1,132 @@
+import type { Declarable } from "../declarable";
+import type { DiscoveryError } from "../errors";
+import { findInfraFiles } from "./files";
+import { importModule } from "./import";
+import { collectEntities } from "./collect";
+import { resolveAttrRefs } from "./resolve";
+import { buildDependencyGraph } from "./graph";
+
+/**
+ * Result of the discovery process
+ */
+export interface DiscoveryResult {
+  /** Map of entity name to Declarable entity */
+  entities: Map<string, Declarable>;
+  /** Map of entity name to set of entity names it depends on */
+  dependencies: Map<string, Set<string>>;
+  /** Array of source file paths that were processed */
+  sourceFiles: string[];
+  /** Array of errors encountered during discovery */
+  errors: DiscoveryError[];
+}
+
+/**
+ * Discovers all declarable entities in a directory by scanning files,
+ * importing modules, collecting entities, resolving references, and building
+ * a dependency graph.
+ *
+ * @param path - The directory path to discover entities in
+ * @returns DiscoveryResult with entities, dependencies, sourceFiles, and errors
+ */
+export async function discover(path: string): Promise<DiscoveryResult> {
+  const errors: DiscoveryError[] = [];
+  const sourceFiles: string[] = [];
+
+  // Step 1: Scan for TypeScript files
+  const files = await findInfraFiles(path);
+  sourceFiles.push(...files);
+
+  // Step 2: Import all modules
+  const modules: Array<{ file: string; exports: Record<string, unknown> }> = [];
+
+  for (const file of files) {
+    try {
+      const exports = await importModule(file);
+      modules.push({ file, exports });
+    } catch (error) {
+      // Collect import errors but continue processing other files
+      if (error instanceof Error && error.name === "DiscoveryError") {
+        errors.push(error as DiscoveryError);
+      } else {
+        // Convert unexpected errors to DiscoveryError
+        const { DiscoveryError: DiscoveryErrorClass } = await import(
+          "../errors"
+        );
+        errors.push(
+          new DiscoveryErrorClass(
+            file,
+            error instanceof Error ? error.message : String(error),
+            "import"
+          )
+        );
+      }
+    }
+  }
+
+  // Step 3: Collect entities from imported modules
+  let entities = new Map<string, Declarable>();
+
+  try {
+    entities = collectEntities(modules);
+  } catch (error) {
+    // Collect resolution errors
+    if (error instanceof Error && error.name === "DiscoveryError") {
+      errors.push(error as DiscoveryError);
+    } else {
+      const { DiscoveryError: DiscoveryErrorClass } = await import("../errors");
+      errors.push(
+        new DiscoveryErrorClass(
+          "",
+          error instanceof Error ? error.message : String(error),
+          "resolution"
+        )
+      );
+    }
+    // If collection fails, return early with empty results
+    return {
+      entities: new Map(),
+      dependencies: new Map(),
+      sourceFiles,
+      errors,
+    };
+  }
+
+  // Step 4: Resolve AttrRefs
+  try {
+    resolveAttrRefs(entities);
+  } catch (error) {
+    // Collect resolution errors but continue
+    const { DiscoveryError: DiscoveryErrorClass } = await import("../errors");
+    errors.push(
+      new DiscoveryErrorClass(
+        "",
+        error instanceof Error ? error.message : String(error),
+        "resolution"
+      )
+    );
+  }
+
+  // Step 5: Build dependency graph
+  let dependencies = new Map<string, Set<string>>();
+
+  try {
+    dependencies = buildDependencyGraph(entities);
+  } catch (error) {
+    // Collect graph building errors
+    const { DiscoveryError: DiscoveryErrorClass } = await import("../errors");
+    errors.push(
+      new DiscoveryErrorClass(
+        "",
+        error instanceof Error ? error.message : String(error),
+        "resolution"
+      )
+    );
+  }
+
+  return {
+    entities,
+    dependencies,
+    sourceFiles,
+    errors,
+  };
+}