@intentius/chant 0.0.1

package/src/project/scan.ts

@@ -0,0 +1,182 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, basename, relative } from "node:path";
+import ts from "typescript";
+
+export interface ProjectExport {
+  name: string;
+  file: string;
+  className: string;
+}
+
+export interface ProjectScan {
+  barrelPath: string;
+  lexiconPackage: string;
+  exports: ProjectExport[];
+}
+
+/**
+ * Extract the lexicon package from export * declarations in the barrel file.
+ * Finds the first `export * from "..."` where the module specifier is not a relative path.
+ */
+function extractLexiconPackage(sourceFile: ts.SourceFile): string {
+  for (const stmt of sourceFile.statements) {
+    if (
+      ts.isExportDeclaration(stmt) &&
+      !stmt.exportClause &&
+      stmt.moduleSpecifier &&
+      ts.isStringLiteral(stmt.moduleSpecifier)
+    ) {
+      const spec = stmt.moduleSpecifier.text;
+      if (!spec.startsWith(".")) {
+        return spec;
+      }
+    }
+  }
+  return "";
+}
+
+/**
+ * Infer class name from a variable declaration's initializer or type annotation.
+ *
+ * Patterns:
+ * - `export const x = new aws.Bucket(...)` → "Bucket"
+ * - `export const x = new _.Bucket(...)` → "Bucket"
+ * - `export const x = new Bucket(...)` → "Bucket"
+ * - `export const x: aws.Code = ...` → "Code"
+ * - `export const x: _.Code = ...` → "Code"
+ */
+function inferClassName(decl: ts.VariableDeclaration): string {
+  // Check initializer: new X.ClassName(...) or new ClassName(...)
+  if (decl.initializer && ts.isNewExpression(decl.initializer)) {
+    const expr = decl.initializer.expression;
+    if (ts.isPropertyAccessExpression(expr)) {
+      return expr.name.text;
+    }
+    if (ts.isIdentifier(expr)) {
+      return expr.text;
+    }
+  }
+
+  // Check type annotation: X.ClassName or ClassName
+  if (decl.type) {
+    if (ts.isTypeReferenceNode(decl.type)) {
+      const typeName = decl.type.typeName;
+      if (ts.isQualifiedName(typeName)) {
+        return typeName.right.text;
+      }
+      if (ts.isIdentifier(typeName)) {
+        return typeName.text;
+      }
+    }
+  }
+
+  return "";
+}
+
+/**
+ * Extract named exports from a source file.
+ */
+function extractExports(
+  sourceFile: ts.SourceFile,
+  filePath: string,
+): ProjectExport[] {
+  const results: ProjectExport[] = [];
+
+  for (const stmt of sourceFile.statements) {
+    // export const x = ...
+    if (
+      ts.isVariableStatement(stmt) &&
+      stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+    ) {
+      for (const decl of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name)) {
+          results.push({
+            name: decl.name.text,
+            file: filePath,
+            className: inferClassName(decl),
+          });
+        }
+      }
+    }
+
+    // export function x() {}
+    if (
+      ts.isFunctionDeclaration(stmt) &&
+      stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) &&
+      stmt.name
+    ) {
+      results.push({
+        name: stmt.name.text,
+        file: filePath,
+        className: "",
+      });
+    }
+
+    // export class X {}
+    if (
+      ts.isClassDeclaration(stmt) &&
+      stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) &&
+      stmt.name
+    ) {
+      results.push({
+        name: stmt.name.text,
+        file: filePath,
+        className: stmt.name.text,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Scan a project directory to identify the barrel file, lexicon package,
+ * and all exports with their inferred types.
+ */
+export function scanProject(dir: string): ProjectScan {
+  const barrelPath = join(dir, "_.ts");
+
+  let barrelContent: string;
+  try {
+    barrelContent = readFileSync(barrelPath, "utf-8");
+  } catch {
+    throw new Error(`No barrel file found at ${barrelPath}`);
+  }
+
+  const barrelSource = ts.createSourceFile(
+    "_.ts",
+    barrelContent,
+    ts.ScriptTarget.Latest,
+    true,
+  );
+
+  const lexiconPackage = extractLexiconPackage(barrelSource);
+
+  // Scan sibling .ts files
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const exports: ProjectExport[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith(".ts")) continue;
+    if (entry.name === "_.ts") continue;
+    if (entry.name.startsWith("_")) continue;
+    if (entry.name.endsWith(".test.ts") || entry.name.endsWith(".spec.ts"))
+      continue;
+    if (entry.name.endsWith(".d.ts")) continue;
+
+    const filePath = "./" + entry.name.replace(/\.ts$/, "");
+    const fullPath = join(dir, entry.name);
+    const content = readFileSync(fullPath, "utf-8");
+    const sourceFile = ts.createSourceFile(
+      entry.name,
+      content,
+      ts.ScriptTarget.Latest,
+      true,
+    );
+
+    exports.push(...extractExports(sourceFile, filePath));
+  }
+
+  return { barrelPath, lexiconPackage, exports };
+}

package/src/project/sync.test.ts

@@ -0,0 +1,87 @@
+import { describe, test, expect } from "bun:test";
+import { generateBarrelTypes, syncProject } from "./sync";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { writeFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ProjectScan } from "./scan";
+
+describe("generateBarrelTypes", () => {
+  test("generates valid .d.ts with import and typed $", () => {
+    const scan: ProjectScan = {
+      barrelPath: "/project/_.ts",
+      lexiconPackage: "@intentius/chant-lexicon-testdom",
+      exports: [
+        { name: "dataBucket", file: "./data-bucket", className: "Bucket" },
+        { name: "logsBucket", file: "./logs-bucket", className: "Bucket" },
+        { name: "functionRole", file: "./iam", className: "Role" },
+      ],
+    };
+
+    const result = generateBarrelTypes(scan);
+    expect(result).toContain(
+      'import type * as _lexicon from "@intentius/chant-lexicon-testdom";',
+    );
+    expect(result).toContain("dataBucket: _lexicon.Bucket;");
+    expect(result).toContain("logsBucket: _lexicon.Bucket;");
+    expect(result).toContain("functionRole: _lexicon.Role;");
+    expect(result).toContain("export declare const $: typeof _barrel;");
+  });
+
+  test("uses unknown for unresolvable types", () => {
+    const scan: ProjectScan = {
+      barrelPath: "/project/_.ts",
+      lexiconPackage: "@intentius/chant-lexicon-testdom",
+      exports: [
+        { name: "dataBucket", file: "./data-bucket", className: "Bucket" },
+        { name: "greeting", file: "./utils", className: "" },
+      ],
+    };
+
+    const result = generateBarrelTypes(scan);
+    expect(result).toContain("dataBucket: _lexicon.Bucket;");
+    expect(result).toContain("greeting: unknown;");
+  });
+
+  test("handles scan with no lexicon package", () => {
+    const scan: ProjectScan = {
+      barrelPath: "/project/_.ts",
+      lexiconPackage: "",
+      exports: [
+        { name: "bucket", file: "./storage", className: "Bucket" },
+      ],
+    };
+
+    const result = generateBarrelTypes(scan);
+    expect(result).not.toContain("import type");
+    expect(result).toContain("bucket: Bucket;");
+  });
+});
+
+describe("syncProject", () => {
+  test("writes _.d.ts to directory", async () => {
+    await withTestDir(async (dir) => {
+      await writeFile(
+        join(dir, "_.ts"),
+        `export * from "@intentius/chant-lexicon-testdom";\n`,
+      );
+      await writeFile(
+        join(dir, "storage.ts"),
+        [
+          `import * as td from "@intentius/chant-lexicon-testdom";`,
+          `export const dataBucket = new td.Bucket({});`,
+          `export const logsBucket = new td.Bucket({});`,
+        ].join("\n"),
+      );
+
+      syncProject(dir);
+
+      const dtsContent = await readFile(join(dir, "_.d.ts"), "utf-8");
+      expect(dtsContent).toContain(
+        'import type * as _lexicon from "@intentius/chant-lexicon-testdom";',
+      );
+      expect(dtsContent).toContain("dataBucket: _lexicon.Bucket;");
+      expect(dtsContent).toContain("logsBucket: _lexicon.Bucket;");
+      expect(dtsContent).toContain("export declare const $: typeof _barrel;");
+    });
+  });
+});

package/src/project/sync.ts

@@ -0,0 +1,46 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { scanProject, type ProjectScan } from "./scan";
+
+/**
+ * Generate a _.d.ts file content from a project scan.
+ * Produces typed declarations for the barrel's $ proxy.
+ */
+export function generateBarrelTypes(scan: ProjectScan): string {
+  const lines: string[] = [];
+
+  lines.push("// _.d.ts (auto-generated by chant lint)");
+
+  if (scan.lexiconPackage) {
+    lines.push(`import type * as _lexicon from "${scan.lexiconPackage}";`);
+  }
+
+  lines.push("declare const _barrel: {");
+
+  for (const exp of scan.exports) {
+    let typeName: string;
+    if (!exp.className) {
+      typeName = "unknown";
+    } else if (scan.lexiconPackage) {
+      typeName = `_lexicon.${exp.className}`;
+    } else {
+      typeName = exp.className;
+    }
+    lines.push(`  ${exp.name}: ${typeName};`);
+  }
+
+  lines.push("};");
+  lines.push("export declare const $: typeof _barrel;");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Scan a project directory and write the _.d.ts file.
+ */
+export function syncProject(dir: string): void {
+  const scan = scanProject(dir);
+  const content = generateBarrelTypes(scan);
+  writeFileSync(join(dir, "_.d.ts"), content, "utf-8");
+}

package/src/project-validation.test.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { validateProjectStructure } from "./project-validation";
+import { mkdirSync, writeFileSync, rmSync } from "fs";
+import { join } from "path";
+
+const TEST_DIR = join(import.meta.dir, "__test_project_validation__");
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe("validateProjectStructure", () => {
+  test("warns on empty directory", () => {
+    const result = validateProjectStructure(TEST_DIR);
+    expect(result.valid).toBe(true); // warnings don't block
+    expect(result.issues.length).toBeGreaterThan(0);
+    expect(result.issues.some((i) => i.message.includes("config"))).toBe(true);
+    expect(result.issues.some((i) => i.message.includes("src/"))).toBe(true);
+  });
+
+  test("no config warning when chant.config.ts exists", () => {
+    writeFileSync(join(TEST_DIR, "chant.config.ts"), "export default {};");
+    mkdirSync(join(TEST_DIR, "src"));
+    const result = validateProjectStructure(TEST_DIR);
+    expect(result.issues.some((i) => i.message.includes("config"))).toBe(false);
+  });
+
+  test("no config warning when chant.config.json exists", () => {
+    writeFileSync(join(TEST_DIR, "chant.config.json"), "{}");
+    mkdirSync(join(TEST_DIR, "src"));
+    const result = validateProjectStructure(TEST_DIR);
+    expect(result.issues.some((i) => i.message.includes("config"))).toBe(false);
+  });
+
+  test("warns on missing core types", () => {
+    writeFileSync(join(TEST_DIR, "chant.config.ts"), "export default {};");
+    mkdirSync(join(TEST_DIR, "src"));
+    const result = validateProjectStructure(TEST_DIR);
+    expect(result.issues.some((i) => i.message.includes("core"))).toBe(true);
+  });
+
+  test("warns on missing lexicon types", () => {
+    writeFileSync(join(TEST_DIR, "chant.config.ts"), "export default {};");
+    mkdirSync(join(TEST_DIR, "src"));
+    const result = validateProjectStructure(TEST_DIR, ["testdom"]);
+    expect(result.issues.some((i) => i.message.includes('"testdom"'))).toBe(true);
+  });
+
+  test("passes with complete structure", () => {
+    writeFileSync(join(TEST_DIR, "chant.config.ts"), "export default {};");
+    mkdirSync(join(TEST_DIR, "src"));
+    mkdirSync(join(TEST_DIR, ".chant", "types", "core"), { recursive: true });
+    writeFileSync(join(TEST_DIR, ".chant", "types", "core", "index.d.ts"), "export {};");
+    mkdirSync(join(TEST_DIR, ".chant", "types", "lexicon-testdom"), { recursive: true });
+
+    const result = validateProjectStructure(TEST_DIR, ["testdom"]);
+    expect(result.valid).toBe(true);
+    expect(result.issues).toHaveLength(0);
+  });
+});

package/src/project-validation.ts

@@ -0,0 +1,79 @@
+import { existsSync } from "fs";
+import { join } from "path";
+
+/**
+ * Issue found during project structure check
+ */
+export interface ProjectIssue {
+  /** Severity: "error" blocks commands, "warning" is advisory */
+  severity: "error" | "warning";
+  /** Human-readable message */
+  message: string;
+}
+
+/**
+ * Result of project structure validation
+ */
+export interface ProjectValidation {
+  /** Whether the project structure is valid (no errors, warnings OK) */
+  valid: boolean;
+  /** Issues found */
+  issues: ProjectIssue[];
+}
+
+/**
+ * Validate project structure.
+ *
+ * Checks that required files and directories exist for a chant project.
+ *
+ * @param projectDir - Root directory of the chant project
+ * @param lexicons - Lexicon names from config (e.g. ["aws"])
+ */
+export function validateProjectStructure(
+  projectDir: string,
+  lexicons: string[] = [],
+): ProjectValidation {
+  const issues: ProjectIssue[] = [];
+
+  // Check for config file
+  const hasTsConfig = existsSync(join(projectDir, "chant.config.ts"));
+  const hasJsonConfig = existsSync(join(projectDir, "chant.config.json"));
+  if (!hasTsConfig && !hasJsonConfig) {
+    issues.push({
+      severity: "warning",
+      message: "No chant config found. Run \"chant init\" to create one.",
+    });
+  }
+
+  // Check for src directory
+  if (!existsSync(join(projectDir, "src"))) {
+    issues.push({
+      severity: "warning",
+      message: "No src/ directory found.",
+    });
+  }
+
+  // Check for .chant/types/core/
+  if (!existsSync(join(projectDir, ".chant", "types", "core", "index.d.ts"))) {
+    issues.push({
+      severity: "warning",
+      message: "Core types not installed in .chant/types/core/. Run \"chant update\" to sync.",
+    });
+  }
+
+  // Check for lexicon type stubs
+  for (const lexicon of lexicons) {
+    const lexiconDir = join(projectDir, ".chant", "types", `lexicon-${lexicon}`);
+    if (!existsSync(lexiconDir)) {
+      issues.push({
+        severity: "warning",
+        message: `Lexicon types not installed for "${lexicon}". Run "chant update" to sync.`,
+      });
+    }
+  }
+
+  return {
+    valid: issues.every((i) => i.severity !== "error"),
+    issues,
+  };
+}

package/src/pseudo-parameter.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import { PseudoParameter, createPseudoParameters } from "./pseudo-parameter";
+import { INTRINSIC_MARKER } from "./intrinsic";
+
+describe("PseudoParameter", () => {
+  test("toJSON returns Ref object", () => {
+    const p = new PseudoParameter("AWS::StackName");
+    expect(p.toJSON()).toEqual({ Ref: "AWS::StackName" });
+  });
+
+  test("toString returns interpolation syntax", () => {
+    const p = new PseudoParameter("AWS::Region");
+    expect(p.toString()).toBe("${AWS::Region}");
+  });
+
+  test("has INTRINSIC_MARKER", () => {
+    const p = new PseudoParameter("AWS::AccountId");
+    expect(p[INTRINSIC_MARKER]).toBe(true);
+  });
+});
+
+describe("createPseudoParameters", () => {
+  test("creates typed namespace from name map", () => {
+    const params = createPseudoParameters({
+      Region: "AWS::Region",
+      StackName: "AWS::StackName",
+    });
+
+    expect(params.Region).toBeInstanceOf(PseudoParameter);
+    expect(params.StackName).toBeInstanceOf(PseudoParameter);
+    expect(params.Region.toJSON()).toEqual({ Ref: "AWS::Region" });
+    expect(params.StackName.toJSON()).toEqual({ Ref: "AWS::StackName" });
+  });
+
+  test("works with empty map", () => {
+    const params = createPseudoParameters({});
+    expect(Object.keys(params)).toHaveLength(0);
+  });
+});

package/src/pseudo-parameter.ts

@@ -0,0 +1,47 @@
+/**
+ * Generic pseudo-parameter class for lexicon-provided global named references.
+ *
+ * AWS uses "AWS::StackName", Terraform has "path.module", Azure has
+ * "subscription().id" — every format needs the same class that serializes
+ * to a Ref-like structure and has the INTRINSIC_MARKER.
+ */
+
+import { INTRINSIC_MARKER, type Intrinsic } from "./intrinsic";
+
+export class PseudoParameter implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private refName: string;
+
+  constructor(refName: string) {
+    this.refName = refName;
+  }
+
+  toJSON(): { Ref: string } {
+    return { Ref: this.refName };
+  }
+
+  toString(): string {
+    return `\${${this.refName}}`;
+  }
+}
+
+/**
+ * Create a namespace of pseudo-parameters from a name map.
+ *
+ * @example
+ * ```ts
+ * export const { StackName, Region } = createPseudoParameters({
+ *   StackName: "AWS::StackName",
+ *   Region: "AWS::Region",
+ * });
+ * ```
+ */
+export function createPseudoParameters<T extends Record<string, string>>(
+  nameMap: T,
+): { [K in keyof T]: PseudoParameter } {
+  const result = {} as Record<string, PseudoParameter>;
+  for (const [key, refName] of Object.entries(nameMap)) {
+    result[key] = new PseudoParameter(refName);
+  }
+  return result as { [K in keyof T]: PseudoParameter };
+}

package/src/runtime.ts

@@ -0,0 +1,68 @@
+/**
+ * Runtime factory constructors for generated resource and property classes.
+ *
+ * Creates classes that implement the Declarable interface with DECLARABLE_MARKER,
+ * lexicon, entityType, kind, and attribute references.
+ */
+
+import { DECLARABLE_MARKER } from "./declarable";
+import { AttrRef } from "./attrref";
+
+/**
+ * Create a resource class for a given type.
+ * The returned constructor creates Declarable objects with:
+ * - DECLARABLE_MARKER for type identification
+ * - lexicon identifier
+ * - entityType set to the resource type
+ * - kind "resource"
+ * - props stored from constructor argument
+ * - AttrRef instances for each attribute
+ */
+export function createResource(
+  type: string,
+  lexicon: string,
+  attrMap: Record<string, string>,
+): new (props: Record<string, unknown>) => Record<string, unknown> {
+  const ResourceClass = function (this: Record<string, unknown>, props: Record<string, unknown>) {
+    Object.defineProperty(this, DECLARABLE_MARKER, { value: true, enumerable: false });
+    Object.defineProperty(this, "lexicon", { value: lexicon, enumerable: false });
+    Object.defineProperty(this, "entityType", { value: type, enumerable: false });
+    Object.defineProperty(this, "kind", { value: "resource", enumerable: false });
+    Object.defineProperty(this, "props", { value: props ?? {}, enumerable: false, configurable: true });
+
+    // Create AttrRef instances for each attribute
+    // Must be enumerable so getAttributes() can discover them for resolveAttrRefs()
+    for (const [camelName, attrName] of Object.entries(attrMap)) {
+      Object.defineProperty(this, camelName, {
+        value: new AttrRef(this, attrName),
+        enumerable: true,
+        writable: false,
+      });
+    }
+  } as unknown as new (props: Record<string, unknown>) => Record<string, unknown>;
+
+  // Set the constructor name for debugging
+  Object.defineProperty(ResourceClass, "name", { value: type.split("::").pop() ?? type });
+
+  return ResourceClass;
+}
+
+/**
+ * Create a property-kind class for a given property type.
+ */
+export function createProperty(
+  type: string,
+  lexicon: string,
+): new (props: Record<string, unknown>) => Record<string, unknown> {
+  const PropertyClass = function (this: Record<string, unknown>, props: Record<string, unknown>) {
+    Object.defineProperty(this, DECLARABLE_MARKER, { value: true, enumerable: false });
+    Object.defineProperty(this, "lexicon", { value: lexicon, enumerable: false });
+    Object.defineProperty(this, "entityType", { value: type, enumerable: false });
+    Object.defineProperty(this, "kind", { value: "property", enumerable: false });
+    Object.defineProperty(this, "props", { value: props ?? {}, enumerable: false, configurable: true });
+  } as unknown as new (props: Record<string, unknown>) => Record<string, unknown>;
+
+  Object.defineProperty(PropertyClass, "name", { value: type.split(".").pop() ?? type });
+
+  return PropertyClass;
+}