@intentius/chant 0.0.1

package/src/config.test.ts

@@ -0,0 +1,91 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { loadChantConfig, DEFAULT_CHANT_CONFIG } from "./config";
+import { writeFileSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+
+const TEST_DIR = join(import.meta.dir, "__test_chant_config__");
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe("loadChantConfig", () => {
+  test("returns default config when no config file exists", async () => {
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config).toEqual(DEFAULT_CHANT_CONFIG);
+    expect(result.configPath).toBeUndefined();
+  });
+
+  test("loads chant.config.ts with default export", async () => {
+    const tsPath = join(TEST_DIR, "chant.config.ts");
+    writeFileSync(
+      tsPath,
+      `export default { lexicons: ["testdom"], lint: { rules: { COR001: "error" } } };`,
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.lexicons).toEqual(["testdom"]);
+    expect(result.config.lint?.rules?.COR001).toBe("error");
+    expect(result.configPath).toBe(tsPath);
+  });
+
+  test("loads chant.config.ts with named config export", async () => {
+    const tsPath = join(TEST_DIR, "chant.config.ts");
+    writeFileSync(
+      tsPath,
+      `export const config = { lexicons: ["testdom"] };`,
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.lexicons).toEqual(["testdom"]);
+  });
+
+  test("loads chant.config.json", async () => {
+    const jsonPath = join(TEST_DIR, "chant.config.json");
+    writeFileSync(
+      jsonPath,
+      JSON.stringify({ lexicons: ["testdom"] }),
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.lexicons).toEqual(["testdom"]);
+    expect(result.configPath).toBe(jsonPath);
+  });
+
+  test("prefers .ts over .json when both exist", async () => {
+    // .ts takes priority — verify by checking configPath ends with .ts
+    writeFileSync(
+      join(TEST_DIR, "chant.config.ts"),
+      `export default { lexicons: ["testdom"] };`,
+    );
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ lexicons: ["from-json"] }),
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.configPath).toEndWith("chant.config.ts");
+  });
+
+  test("handles empty config", async () => {
+    writeFileSync(join(TEST_DIR, "chant.config.json"), "{}");
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config).toEqual({});
+  });
+
+  test("handles config with only lexicons", async () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ lexicons: ["testdom"] }),
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.lexicons).toEqual(["testdom"]);
+    expect(result.config.lint).toBeUndefined();
+  });
+});

package/src/config.ts

@@ -0,0 +1,87 @@
+import { existsSync } from "fs";
+import { join } from "path";
+import { z } from "zod";
+import type { LintConfig } from "./lint/config";
+
+/**
+ * Zod schema for ChantConfig validation.
+ */
+export const ChantConfigSchema = z.object({
+  lexicons: z.array(z.string().min(1)).optional(),
+  lint: z.record(z.string(), z.unknown()).optional(),
+}).passthrough();
+
+/**
+ * Top-level chant project configuration.
+ *
+ * Loaded from `chant.config.ts` (preferred) or `chant.config.json`.
+ */
+export interface ChantConfig {
+  /** Lexicon package names to load (e.g. ["aws"]) */
+  lexicons?: string[];
+
+  /** Lint configuration (rules, extends, overrides, plugins) */
+  lint?: LintConfig;
+}
+
+/**
+ * Resolved project configuration with metadata about how it was loaded.
+ */
+export interface ResolvedConfig {
+  /** The loaded configuration */
+  config: ChantConfig;
+
+  /** Path to the config file that was loaded, or undefined if defaults */
+  configPath?: string;
+}
+
+/**
+ * Default configuration when no config file exists.
+ */
+export const DEFAULT_CHANT_CONFIG: ChantConfig = {};
+
+/**
+ * Load project configuration from a directory.
+ *
+ * Tries `chant.config.ts` first (via dynamic import), then `chant.config.json`.
+ * Returns default config if neither exists.
+ */
+export async function loadChantConfig(dir: string): Promise<ResolvedConfig> {
+  // Try chant.config.ts first
+  const tsPath = join(dir, "chant.config.ts");
+  if (existsSync(tsPath)) {
+    const mod = await import(tsPath);
+    const config = mod.default ?? mod.config ?? mod;
+    return { config: normalizeConfig(config, tsPath), configPath: tsPath };
+  }
+
+  // Fall back to chant.config.json
+  const jsonPath = join(dir, "chant.config.json");
+  if (existsSync(jsonPath)) {
+    const { readFileSync } = await import("fs");
+    const content = readFileSync(jsonPath, "utf-8");
+    const parsed = JSON.parse(content);
+    return { config: normalizeConfig(parsed, jsonPath), configPath: jsonPath };
+  }
+
+  return { config: DEFAULT_CHANT_CONFIG };
+}
+
+/**
+ * Validate and normalize a raw config object into ChantConfig shape.
+ */
+function normalizeConfig(raw: Record<string, unknown>, source?: string): ChantConfig {
+  if (typeof raw !== "object" || raw === null) {
+    return DEFAULT_CHANT_CONFIG;
+  }
+
+  const result = ChantConfigSchema.safeParse(raw);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const path = issue.path.length > 0 ? issue.path.join(".") : undefined;
+    const loc = source ? ` in ${source}` : "";
+    throw new Error(`Invalid chant config${loc}: ${path ? `${path}: ` : ""}${issue.message}`);
+  }
+
+  return raw as ChantConfig;
+}

package/src/declarable.test.ts

@@ -0,0 +1,160 @@
+import { describe, test, expect } from "bun:test";
+import {
+  DECLARABLE_MARKER,
+  type Declarable,
+  isDeclarable,
+  isPropertyDeclarable,
+} from "./declarable";
+
+describe("DECLARABLE_MARKER", () => {
+  test("is a symbol", () => {
+    expect(typeof DECLARABLE_MARKER).toBe("symbol");
+  });
+
+  test("uses Symbol.for for global registry", () => {
+    expect(DECLARABLE_MARKER).toBe(Symbol.for("chant.declarable"));
+  });
+});
+
+describe("isDeclarable", () => {
+  test("returns true for object with DECLARABLE_MARKER", () => {
+    const obj: Declarable = {
+      lexicon: "test",
+      entityType: "Test",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    expect(isDeclarable(obj)).toBe(true);
+  });
+
+  test("returns true for object with kind field", () => {
+    const resourceObj: Declarable = {
+      lexicon: "test",
+      entityType: "Resource",
+      kind: "resource",
+      [DECLARABLE_MARKER]: true,
+    };
+    const propertyObj: Declarable = {
+      lexicon: "test",
+      entityType: "Property",
+      kind: "property",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    expect(isDeclarable(resourceObj)).toBe(true);
+    expect(isDeclarable(propertyObj)).toBe(true);
+  });
+
+  test("returns false for object without DECLARABLE_MARKER", () => {
+    const obj = {
+      entityType: "Test",
+    };
+
+    expect(isDeclarable(obj)).toBe(false);
+  });
+
+  test("returns false for null", () => {
+    expect(isDeclarable(null)).toBe(false);
+  });
+
+  test("returns false for undefined", () => {
+    expect(isDeclarable(undefined)).toBe(false);
+  });
+
+  test("returns false for primitive values", () => {
+    expect(isDeclarable("string")).toBe(false);
+    expect(isDeclarable(123)).toBe(false);
+    expect(isDeclarable(true)).toBe(false);
+  });
+
+  test("returns false for object with DECLARABLE_MARKER but wrong value", () => {
+    const obj = {
+      entityType: "Test",
+      [DECLARABLE_MARKER]: false,
+    };
+
+    expect(isDeclarable(obj)).toBe(false);
+  });
+});
+
+describe("isPropertyDeclarable", () => {
+  test("returns true for Declarable with kind property", () => {
+    const obj: Declarable = {
+      lexicon: "test",
+      entityType: "Property",
+      kind: "property",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    expect(isPropertyDeclarable(obj)).toBe(true);
+  });
+
+  test("returns false for Declarable with kind resource", () => {
+    const obj: Declarable = {
+      lexicon: "test",
+      entityType: "Resource",
+      kind: "resource",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    expect(isPropertyDeclarable(obj)).toBe(false);
+  });
+
+  test("returns false for Declarable without kind field", () => {
+    const obj: Declarable = {
+      lexicon: "test",
+      entityType: "Test",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    expect(isPropertyDeclarable(obj)).toBe(false);
+  });
+
+  test("returns false for Declarable with undefined kind", () => {
+    const obj: Declarable = {
+      lexicon: "test",
+      entityType: "Test",
+      kind: undefined,
+      [DECLARABLE_MARKER]: true,
+    };
+
+    expect(isPropertyDeclarable(obj)).toBe(false);
+  });
+});
+
+describe("Declarable interface", () => {
+  test("allows creating objects without kind field (backward compatibility)", () => {
+    const obj: Declarable = {
+      lexicon: "test",
+      entityType: "Test",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    expect(obj.entityType).toBe("Test");
+    expect(obj.kind).toBeUndefined();
+  });
+
+  test("allows creating objects with kind resource", () => {
+    const obj: Declarable = {
+      lexicon: "test",
+      entityType: "Bucket",
+      kind: "resource",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    expect(obj.entityType).toBe("Bucket");
+    expect(obj.kind).toBe("resource");
+  });
+
+  test("allows creating objects with kind property", () => {
+    const obj: Declarable = {
+      lexicon: "test",
+      entityType: "BucketEncryption",
+      kind: "property",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    expect(obj.entityType).toBe("BucketEncryption");
+    expect(obj.kind).toBe("property");
+  });
+});

package/src/declarable.ts

@@ -0,0 +1,47 @@
+/**
+ * Marker symbol for Declarable type identification
+ */
+export const DECLARABLE_MARKER = Symbol.for("chant.declarable");
+
+/**
+ * Base interface for all declarable entities
+ */
+export interface Declarable {
+  readonly lexicon: string;
+  readonly entityType: string;
+  readonly kind?: "resource" | "property";
+  readonly [DECLARABLE_MARKER]: true;
+}
+
+/**
+ * Core parameter type for lexicon-agnostic parameters
+ */
+export interface CoreParameter extends Declarable {
+  readonly parameterType: string;
+}
+
+/**
+ * Core output type for lexicon-agnostic outputs
+ */
+export interface CoreOutput extends Declarable {
+  readonly value: unknown;
+}
+
+/**
+ * Type guard to check if a value is a Declarable
+ */
+export function isDeclarable(value: unknown): value is Declarable {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    DECLARABLE_MARKER in value &&
+    (value as Record<symbol, unknown>)[DECLARABLE_MARKER] === true
+  );
+}
+
+/**
+ * Type guard to check if a Declarable is a property-level type
+ */
+export function isPropertyDeclarable(value: Declarable): boolean {
+  return value.kind === "property";
+}

package/src/detectLexicon.test.ts

@@ -0,0 +1,236 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { detectLexicons } from "./detectLexicon";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+describe("detectLexicons", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    // Create a unique temp directory for each test
+    testDir = join(tmpdir(), `chant-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    // Clean up temp directory
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test.each([
+    {
+      lexicon: "testdom",
+      code: 'import * as td from "@intentius/chant-lexicon-testdom";\n\nexport const bucket = new td.storage.Bucket({});',
+    },
+  ])("detects $lexicon lexicon from import statement", async ({ lexicon, code }) => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(file, code);
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual([lexicon]);
+  });
+
+  test("detects lexicon from destructured import", async () => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(
+      file,
+      'import { Bucket, Interpolate } from "@intentius/chant-lexicon-testdom";\n\nexport const bucket = new Bucket({});'
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("detects lexicon across multiple files", async () => {
+    const file1 = join(testDir, "storage.ts");
+    const file2 = join(testDir, "compute.ts");
+    await writeFile(
+      file1,
+      'import * as td from "@intentius/chant-lexicon-testdom";\n\nexport const bucket = new td.storage.Bucket({});'
+    );
+    await writeFile(
+      file2,
+      'import * as td from "@intentius/chant-lexicon-testdom";\n\nexport const fn = new td.compute.Function({});'
+    );
+
+    const result = await detectLexicons([file1, file2]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("throws error when no lexicon is detected", async () => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(
+      file,
+      'import { readFile } from "node:fs/promises";\n\nexport const data = {};'
+    );
+
+    await expect(detectLexicons([file])).rejects.toThrow(
+      "No lexicon detected in infrastructure files"
+    );
+  });
+
+  test("returns multiple lexicons when multiple files use same lexicon", async () => {
+    const file1 = join(testDir, "storage.ts");
+    const file2 = join(testDir, "compute.ts");
+    await writeFile(
+      file1,
+      'import * as td from "@intentius/chant-lexicon-testdom";\n\nexport const bucket = new td.storage.Bucket({});'
+    );
+    await writeFile(
+      file2,
+      'import * as td from "@intentius/chant-lexicon-testdom";\n\nexport const fn = new td.compute.Function({});'
+    );
+
+    const result = await detectLexicons([file1, file2]);
+    expect(result).toContain("testdom");
+    expect(result).toHaveLength(1);
+  });
+
+  test("handles file with no imports gracefully", async () => {
+    const file = join(testDir, "empty.ts");
+    await writeFile(file, "export const value = 42;");
+
+    await expect(detectLexicons([file])).rejects.toThrow(
+      "No lexicon detected in infrastructure files"
+    );
+  });
+
+  test("handles mixed chant and non-chant imports", async () => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(
+      file,
+      'import { readFile } from "node:fs/promises";\nimport * as td from "@intentius/chant-lexicon-testdom";\nimport React from "react";\n\nexport const bucket = new td.storage.Bucket({});'
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("ignores comments containing lexicon names", async () => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(
+      file,
+      '// This could be for any lexicon\nimport * as td from "@intentius/chant-lexicon-testdom";\n\nexport const bucket = new td.storage.Bucket({});'
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("handles single-quoted imports", async () => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(
+      file,
+      "import * as aws from '@intentius/chant-lexicon-testdom';\n\nexport const bucket = new td.storage.Bucket({});"
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("handles double-quoted imports", async () => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(
+      file,
+      'import * as td from "@intentius/chant-lexicon-testdom";\n\nexport const bucket = new td.storage.Bucket({});'
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("handles file that cannot be read", async () => {
+    const file = join(testDir, "nonexistent.ts");
+
+    await expect(detectLexicons([file])).rejects.toThrow(
+      "No lexicon detected in infrastructure files"
+    );
+  });
+
+  test("detects lexicon when some files are unreadable", async () => {
+    const file1 = join(testDir, "valid.ts");
+    const file2 = join(testDir, "nonexistent.ts");
+    await writeFile(
+      file1,
+      'import * as td from "@intentius/chant-lexicon-testdom";\n\nexport const bucket = new td.storage.Bucket({});'
+    );
+
+    const result = await detectLexicons([file1, file2]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("handles multiple imports from same lexicon", async () => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(
+      file,
+      'import * as td from "@intentius/chant-lexicon-testdom";\nimport { Bucket } from "@intentius/chant-lexicon-testdom";\nimport type { BucketProps } from "@intentius/chant-lexicon-testdom";\nexport const bucket = new Bucket({});'
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("deduplicates lexicon across multiple files", async () => {
+    const file1 = join(testDir, "storage.ts");
+    const file2 = join(testDir, "compute.ts");
+    const file3 = join(testDir, "networking.ts");
+    await writeFile(file1, 'import * as td from "@intentius/chant-lexicon-testdom";');
+    await writeFile(file2, 'import * as td from "@intentius/chant-lexicon-testdom";');
+    await writeFile(file3, 'import * as td from "@intentius/chant-lexicon-testdom";');
+
+    const result = await detectLexicons([file1, file2, file3]);
+    expect(result).toContain("testdom");
+    expect(result).toHaveLength(1);
+  });
+
+  test("handles empty file array", async () => {
+    await expect(detectLexicons([])).rejects.toThrow(
+      "No lexicon detected in infrastructure files"
+    );
+  });
+
+  test("detects lexicon with whitespace variations in import", async () => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(
+      file,
+      'import   *   as   td   from   "@intentius/chant-lexicon-testdom"  ;\n\nexport const bucket = new td.storage.Bucket({});'
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("handles import with type modifier", async () => {
+    const file = join(testDir, "infra.ts");
+    await writeFile(
+      file,
+      'import type { BucketProps } from "@intentius/chant-lexicon-testdom";\nimport * as td from "@intentius/chant-lexicon-testdom";\nexport const bucket: BucketProps = {};'
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("detects lexicon from export statement", async () => {
+    const file = join(testDir, "barrel.ts");
+    await writeFile(
+      file,
+      'export * from "@intentius/chant-lexicon-testdom";\nimport * as core from "@intentius/chant";'
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual(["testdom"]);
+  });
+
+  test("detects lexicon from export with curly braces", async () => {
+    const file = join(testDir, "barrel.ts");
+    await writeFile(
+      file,
+      'export { Bucket, Interpolate } from "@intentius/chant-lexicon-testdom";'
+    );
+
+    const result = await detectLexicons([file]);
+    expect(result).toEqual(["testdom"]);
+  });
+});

package/src/detectLexicon.ts

@@ -0,0 +1,37 @@
+import { readFile } from "node:fs/promises";
+
+/**
+ * Detects which lexicons are being used by analyzing import statements
+ * in the provided infrastructure files. Matches any `@intentius/chant-lexicon-*` package.
+ *
+ * @param files - Array of file paths to analyze
+ * @returns Array of detected lexicon names
+ * @throws Error if no lexicon is detected
+ */
+export async function detectLexicons(files: string[]): Promise<string[]> {
+  const detectedLexicons = new Set<string>();
+
+  for (const file of files) {
+    let content: string;
+    try {
+      content = await readFile(file, "utf-8");
+    } catch (error) {
+      // Skip files that can't be read
+      continue;
+    }
+
+    // Match @intentius/chant-lexicon-<name> in import/export statements
+    const regex = /(?:import|export)\s+.*\s+from\s+['"]@intentius\/chant-lexicon-([a-z][\w-]*)['"]/g;
+
+    for (const match of content.matchAll(regex)) {
+      detectedLexicons.add(match[1]);
+    }
+  }
+
+  // Validate results
+  if (detectedLexicons.size === 0) {
+    throw new Error("No lexicon detected in infrastructure files");
+  }
+
+  return Array.from(detectedLexicons);
+}