@intentius/chant 0.0.1

package/src/discovery/cache.test.ts

@@ -0,0 +1,78 @@
+import { describe, test, expect } from "bun:test";
+import { DiscoveryCache } from "./cache";
+import { writeFileSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+describe("DiscoveryCache", () => {
+  test("hasFileChanged returns true for unknown files", () => {
+    const cache = new DiscoveryCache();
+    expect(cache.hasFileChanged("/nonexistent/file.ts")).toBe(true);
+  });
+
+  test("trackFileImport and hasFileChanged detect changes", async () => {
+    const cache = new DiscoveryCache();
+    const dir = join(tmpdir(), `chant-cache-test-${Date.now()}`);
+    mkdirSync(dir, { recursive: true });
+
+    const file = join(dir, "test.ts");
+    writeFileSync(file, "export const a = 1;");
+
+    const { statSync: stat } = require("fs");
+    const { mtimeMs } = stat(file);
+    cache.trackFileImport(file, mtimeMs, ["a"]);
+
+    // File hasn't changed
+    expect(cache.hasFileChanged(file)).toBe(false);
+
+    // Wait briefly to ensure mtime differs, then modify
+    await new Promise((r) => setTimeout(r, 50));
+    writeFileSync(file, "export const a = 2;");
+
+    // File has changed
+    expect(cache.hasFileChanged(file)).toBe(true);
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("invalidate removes entries and returns entity names", () => {
+    const cache = new DiscoveryCache();
+    cache.trackFileImport("/a.ts", 100, ["bucket", "role"]);
+    cache.trackFileImport("/b.ts", 200, ["table"]);
+
+    const invalidated = cache.invalidate(["/a.ts"]);
+    expect(invalidated.has("bucket")).toBe(true);
+    expect(invalidated.has("role")).toBe(true);
+    expect(invalidated.has("table")).toBe(false);
+
+    // a.ts is now unknown
+    expect(cache.hasFileChanged("/a.ts")).toBe(true);
+  });
+
+  test("invalidate with unknown file returns empty set", () => {
+    const cache = new DiscoveryCache();
+    const invalidated = cache.invalidate(["/unknown.ts"]);
+    expect(invalidated.size).toBe(0);
+  });
+
+  test("trackedFiles returns all tracked file paths", () => {
+    const cache = new DiscoveryCache();
+    cache.trackFileImport("/a.ts", 100, ["x"]);
+    cache.trackFileImport("/b.ts", 200, ["y"]);
+    expect(cache.trackedFiles().sort()).toEqual(["/a.ts", "/b.ts"]);
+  });
+
+  test("getFileEntities returns entity names for tracked file", () => {
+    const cache = new DiscoveryCache();
+    cache.trackFileImport("/a.ts", 100, ["bucket", "role"]);
+    expect(cache.getFileEntities("/a.ts")).toEqual(["bucket", "role"]);
+    expect(cache.getFileEntities("/unknown.ts")).toBeUndefined();
+  });
+
+  test("clear removes all entries", () => {
+    const cache = new DiscoveryCache();
+    cache.trackFileImport("/a.ts", 100, ["x"]);
+    cache.clear();
+    expect(cache.trackedFiles()).toEqual([]);
+  });
+});

package/src/discovery/cache.ts

@@ -0,0 +1,86 @@
+import { statSync } from "fs";
+
+/**
+ * Cache entry for a single file
+ */
+interface FileCacheEntry {
+  /** Last modified time in milliseconds */
+  mtime: number;
+  /** Entity names exported by this file */
+  entityNames: string[];
+}
+
+/**
+ * Discovery cache for incremental rebuilds.
+ *
+ * Tracks file mtimes and file→entity mappings so that only changed files
+ * need to be re-imported during watch-mode rebuilds.
+ */
+export class DiscoveryCache {
+  private files = new Map<string, FileCacheEntry>();
+
+  /**
+   * Check if a file has changed since it was last tracked.
+   * Returns true if the file is new or its mtime has changed.
+   */
+  hasFileChanged(filePath: string): boolean {
+    const entry = this.files.get(filePath);
+    if (!entry) return true;
+
+    try {
+      const stat = statSync(filePath);
+      return stat.mtimeMs !== entry.mtime;
+    } catch {
+      // File may have been deleted
+      return true;
+    }
+  }
+
+  /**
+   * Record a successful import, storing the file's mtime and entity names.
+   */
+  trackFileImport(filePath: string, mtime: number, entityNames: string[]): void {
+    this.files.set(filePath, { mtime, entityNames });
+  }
+
+  /**
+   * Invalidate cache entries for the given files.
+   * Returns the set of entity names that were invalidated.
+   */
+  invalidate(changedFiles: string[]): Set<string> {
+    const invalidatedEntities = new Set<string>();
+
+    for (const file of changedFiles) {
+      const entry = this.files.get(file);
+      if (entry) {
+        for (const name of entry.entityNames) {
+          invalidatedEntities.add(name);
+        }
+        this.files.delete(file);
+      }
+    }
+
+    return invalidatedEntities;
+  }
+
+  /**
+   * Get all tracked file paths.
+   */
+  trackedFiles(): string[] {
+    return [...this.files.keys()];
+  }
+
+  /**
+   * Get entity names for a tracked file.
+   */
+  getFileEntities(filePath: string): string[] | undefined {
+    return this.files.get(filePath)?.entityNames;
+  }
+
+  /**
+   * Clear all cached data.
+   */
+  clear(): void {
+    this.files.clear();
+  }
+}

package/src/discovery/collect.test.ts

@@ -0,0 +1,269 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { collectEntities } from "./collect";
+import { DECLARABLE_MARKER } from "../declarable";
+import { DiscoveryError } from "../errors";
+import { Composite, CompositeRegistry } from "../composite";
+import { createMockEntity, expectToThrow } from "@intentius/chant-test-utils";
+
+describe("collectEntities", () => {
+  test("collects declarable entities from single module", () => {
+    const entity1 = createMockEntity("test");
+
+    const modules = [
+      {
+        file: "test.ts",
+        exports: {
+          entity1,
+          notDeclarable: "value",
+        },
+      },
+    ];
+
+    const result = collectEntities(modules);
+    expect(result.size).toBe(1);
+    expect(result.get("entity1")).toBe(entity1);
+  });
+
+  test("collects declarable entities from multiple modules", () => {
+    const entity1 = createMockEntity("type1");
+    const entity2 = createMockEntity("type2");
+    const entity3 = createMockEntity("type3");
+
+    const modules = [
+      {
+        file: "file1.ts",
+        exports: {
+          entity1,
+          helper: "function",
+        },
+      },
+      {
+        file: "file2.ts",
+        exports: {
+          entity2,
+          entity3,
+          util: 42,
+        },
+      },
+    ];
+
+    const result = collectEntities(modules);
+    expect(result.size).toBe(3);
+    expect(result.get("entity1")).toBe(entity1);
+    expect(result.get("entity2")).toBe(entity2);
+    expect(result.get("entity3")).toBe(entity3);
+  });
+
+  test("ignores non-declarable exports", () => {
+    const entity = createMockEntity("test");
+
+    const modules = [
+      {
+        file: "mixed.ts",
+        exports: {
+          entity,
+          string: "value",
+          number: 123,
+          object: { key: "value" },
+          array: [1, 2, 3],
+          func: () => "test",
+          nullValue: null,
+          undefinedValue: undefined,
+          boolValue: true,
+        },
+      },
+    ];
+
+    const result = collectEntities(modules);
+    expect(result.size).toBe(1);
+    expect(result.get("entity")).toBe(entity);
+  });
+
+  test("returns empty map when no declarables found", () => {
+    const modules = [
+      {
+        file: "empty.ts",
+        exports: {
+          value1: "string",
+          value2: 42,
+          value3: { data: "object" },
+        },
+      },
+    ];
+
+    const result = collectEntities(modules);
+    expect(result.size).toBe(0);
+  });
+
+  test("returns empty map when modules array is empty", () => {
+    const result = collectEntities([]);
+    expect(result.size).toBe(0);
+  });
+
+  test("throws DiscoveryError with type 'resolution' on duplicate export names", async () => {
+    const entity1 = createMockEntity("type1");
+    const entity2 = createMockEntity("type2");
+
+    const modules = [
+      {
+        file: "file1.ts",
+        exports: { myEntity: entity1 },
+      },
+      {
+        file: "file2.ts",
+        exports: { myEntity: entity2 },
+      },
+    ];
+
+    await expectToThrow(
+      () => collectEntities(modules),
+      DiscoveryError,
+      (error) => {
+        expect(error.type).toBe("resolution");
+        expect(error.file).toBe("file2.ts");
+        expect(error.message).toContain("Duplicate");
+        expect(error.message).toContain("myEntity");
+      }
+    );
+  });
+
+  test("throws DiscoveryError with detailed message for duplicates", async () => {
+    const entity1 = createMockEntity("test");
+    const entity2 = createMockEntity("test");
+
+    const modules = [
+      {
+        file: "a.ts",
+        exports: { duplicateName: entity1 },
+      },
+      {
+        file: "b.ts",
+        exports: { duplicateName: entity2 },
+      },
+    ];
+
+    await expectToThrow(
+      () => collectEntities(modules),
+      DiscoveryError,
+      (error) => {
+        expect(error.type).toBe("resolution");
+        expect(error.message).toBe('Duplicate export name "duplicateName" found');
+      }
+    );
+  });
+
+  test("allows same export name if not declarable in one module", () => {
+    const entity = createMockEntity("test");
+
+    const modules = [
+      {
+        file: "file1.ts",
+        exports: { name: "not declarable" },
+      },
+      {
+        file: "file2.ts",
+        exports: { name: entity },
+      },
+    ];
+
+    const result = collectEntities(modules);
+    expect(result.size).toBe(1);
+    expect(result.get("name")).toBe(entity);
+  });
+
+  test("preserves entity type information", () => {
+    const entity1 = createMockEntity("parameter");
+    const entity2 = createMockEntity("output");
+
+    const modules = [
+      {
+        file: "test.ts",
+        exports: { entity1, entity2 },
+      },
+    ];
+
+    const result = collectEntities(modules);
+    expect(result.get("entity1")?.entityType).toBe("parameter");
+    expect(result.get("entity2")?.entityType).toBe("output");
+  });
+
+  test("correctly identifies objects without DECLARABLE_MARKER as non-declarable", () => {
+    const fakeDeclarable = {
+      entityType: "fake",
+      // Missing DECLARABLE_MARKER
+    };
+
+    const modules = [
+      {
+        file: "test.ts",
+        exports: { fakeDeclarable },
+      },
+    ];
+
+    const result = collectEntities(modules);
+    expect(result.size).toBe(0);
+  });
+
+  test("correctly identifies objects with wrong marker value as non-declarable", () => {
+    const fakeDeclarable = {
+      entityType: "fake",
+      [DECLARABLE_MARKER]: false, // Wrong value
+    };
+
+    const modules = [
+      {
+        file: "test.ts",
+        exports: { fakeDeclarable },
+      },
+    ];
+
+    const result = collectEntities(modules);
+    expect(result.size).toBe(0);
+  });
+
+  test("error serializes to JSON correctly", async () => {
+    const modules = [
+      {
+        file: "first.ts",
+        exports: { dup: createMockEntity("test") },
+      },
+      {
+        file: "second.ts",
+        exports: { dup: createMockEntity("test") },
+      },
+    ];
+
+    const error = await expectToThrow(
+      () => collectEntities(modules),
+      DiscoveryError
+    );
+
+    const json = error.toJSON();
+    expect(json.name).toBe("DiscoveryError");
+    expect(json.file).toBe("second.ts");
+    expect(json.type).toBe("resolution");
+    expect(json.message).toBeDefined();
+  });
+});
+
+describe("collectEntities with composites", () => {
+  beforeEach(() => {
+    CompositeRegistry.clear();
+  });
+
+  test("composite is expanded into individual entities", () => {
+    const Comp = Composite(() => ({
+      a: createMockEntity("TestA"),
+      b: createMockEntity("TestB"),
+    }));
+    const instance = Comp({});
+
+    const entities = collectEntities([
+      { file: "test.ts", exports: { myComp: instance } },
+    ]);
+
+    expect(entities.has("myComp_a")).toBe(true);
+    expect(entities.has("myComp_b")).toBe(true);
+    expect(entities.has("myComp")).toBe(false);
+  });
+});

package/src/discovery/collect.ts

@@ -0,0 +1,51 @@
+import { isDeclarable, type Declarable } from "../declarable";
+import { isCompositeInstance, expandComposite } from "../composite";
+import { DiscoveryError } from "../errors";
+
+/**
+ * Collects all declarable entities from imported modules.
+ * CompositeInstance exports are expanded into individual entities
+ * with `{exportName}_{memberName}` naming.
+ *
+ * @param modules - Array of module records with their exports
+ * @returns Map of export name to Declarable entity
+ * @throws {DiscoveryError} with type "resolution" if duplicate export names are found
+ */
+export function collectEntities(
+  modules: Array<{ file: string; exports: Record<string, unknown> }>
+): Map<string, Declarable> {
+  const entities = new Map<string, Declarable>();
+
+  for (const { file, exports } of modules) {
+    for (const [name, value] of Object.entries(exports)) {
+      if (isDeclarable(value)) {
+        if (entities.has(name)) {
+          // Same object re-exported from multiple files (e.g. barrel re-exports) is fine
+          if (entities.get(name) !== value) {
+            throw new DiscoveryError(
+              file,
+              `Duplicate export name "${name}" found`,
+              "resolution"
+            );
+          }
+        } else {
+          entities.set(name, value);
+        }
+      } else if (isCompositeInstance(value)) {
+        const expanded = expandComposite(name, value);
+        for (const [expandedName, entity] of expanded) {
+          if (entities.has(expandedName)) {
+            throw new DiscoveryError(
+              file,
+              `Duplicate entity name "${expandedName}" from composite expansion of "${name}"`,
+              "resolution",
+            );
+          }
+          entities.set(expandedName, entity);
+        }
+      }
+    }
+  }
+
+  return entities;
+}