@intentius/chant 0.0.1

package/src/lint/rules/export-required.ts

@@ -0,0 +1,158 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR008: Export required
+ *
+ * Detects declarable instances that are not exported.
+ * All declarable instances should be exported to be tracked by chant.
+ *
+ * Triggers on: new Bucket({...}) without export
+ * OK: export const bucket = new Bucket({...})
+ */
+
+interface ExportInfo {
+  exportedNames: Set<string>;
+  localVariableNames: Set<string>;
+}
+
+function isDeclarableClass(node: ts.Node, sourceFile: ts.SourceFile): boolean {
+  // Check if it's a class with Declarable interface implementation
+  if (ts.isClassDeclaration(node) && node.heritageClauses) {
+    for (const clause of node.heritageClauses) {
+      for (const type of clause.types) {
+        const typeName = type.expression.getText(sourceFile);
+        if (typeName === "Declarable") {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+function collectExportInfo(sourceFile: ts.SourceFile): ExportInfo {
+  const exportedNames = new Set<string>();
+  const localVariableNames = new Set<string>();
+
+  function visit(node: ts.Node): void {
+    // Handle exported variable declarations
+    if (ts.isVariableStatement(node)) {
+      const hasExportModifier = node.modifiers?.some(
+        m => m.kind === ts.SyntaxKind.ExportKeyword
+      );
+
+      for (const declaration of node.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name)) {
+          const name = declaration.name.text;
+          if (hasExportModifier) {
+            exportedNames.add(name);
+          } else {
+            localVariableNames.add(name);
+          }
+        }
+      }
+    }
+
+    // Handle export assignments: export = something
+    if (ts.isExportAssignment(node)) {
+      if (ts.isIdentifier(node.expression)) {
+        exportedNames.add(node.expression.text);
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return { exportedNames, localVariableNames };
+}
+
+function isDeclarableNewExpression(node: ts.NewExpression, context: LintContext): boolean {
+  // Check if the class being instantiated implements Declarable
+  // We look for the class declaration in the source file or imports
+  const className = node.expression.getText(context.sourceFile);
+
+  // Check local class declarations
+  let isDeclarable = false;
+
+  function checkClassDeclarations(n: ts.Node): void {
+    if (ts.isClassDeclaration(n) && n.name?.text === className) {
+      if (isDeclarableClass(n, context.sourceFile)) {
+        isDeclarable = true;
+      }
+    }
+    ts.forEachChild(n, checkClassDeclarations);
+  }
+
+  checkClassDeclarations(context.sourceFile);
+
+  // For imported classes, we use a heuristic: check if the class name is capitalized
+  // and follows common declarable patterns (like Bucket, Parameter, etc.)
+  if (!isDeclarable && /^[A-Z]/.test(className)) {
+    // Additional check: see if it's imported from a declarable-looking module
+    // For now, we'll be conservative and only flag classes that are clearly local
+    return isDeclarable;
+  }
+
+  return isDeclarable;
+}
+
+function checkNode(
+  node: ts.Node,
+  context: LintContext,
+  exportInfo: ExportInfo,
+  diagnostics: LintDiagnostic[]
+): void {
+  // Check for new expressions that are not exported
+  if (ts.isNewExpression(node)) {
+    // Skip if this is part of a variable initializer that's exported
+    let parent = node.parent;
+    let isPartOfExportedVariable = false;
+    let variableName: string | undefined;
+
+    while (parent) {
+      if (ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+        variableName = parent.name.text;
+        if (exportInfo.exportedNames.has(variableName)) {
+          isPartOfExportedVariable = true;
+          break;
+        }
+      }
+      parent = parent.parent;
+    }
+
+    if (!isPartOfExportedVariable && isDeclarableNewExpression(node, context)) {
+      const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+        node.getStart(context.sourceFile)
+      );
+
+      const className = node.expression.getText(context.sourceFile);
+      const label = variableName ? `'${variableName}' (${className})` : `'${className}'`;
+
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR008",
+        severity: "warning",
+        message: `Declarable ${label} is not exported — add 'export' so chant can discover it during synthesis.`,
+      });
+    }
+  }
+
+  // Recursively check child nodes
+  ts.forEachChild(node, child => checkNode(child, context, exportInfo, diagnostics));
+}
+
+export const exportRequiredRule: LintRule = {
+  id: "COR008",
+  severity: "warning",
+  category: "correctness",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const exportInfo = collectExportInfo(context.sourceFile);
+    checkNode(context.sourceFile, context, exportInfo, diagnostics);
+    return diagnostics;
+  },
+};

package/src/lint/rules/file-declarable-limit.test.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { fileDeclarableLimitRule } from "./file-declarable-limit";
+import type { LintContext } from "../rule";
+
+function createContext(code: string, filePath = "test.ts"): LintContext {
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+  );
+
+  return {
+    sourceFile,
+    entities: [],
+    filePath,
+    lexicon: undefined,
+  };
+}
+
+function makeNewExprs(names: string[]): string {
+  return names.map((n) => `const x = new ${n}({ name: "a" });`).join("\n");
+}
+
+describe("COR009: file-declarable-limit", () => {
+  test("rule metadata", () => {
+    expect(fileDeclarableLimitRule.id).toBe("COR009");
+    expect(fileDeclarableLimitRule.severity).toBe("warning");
+    expect(fileDeclarableLimitRule.category).toBe("style");
+  });
+
+  test("does not warn with 3 Declarable instances", () => {
+    const code = makeNewExprs(["Bucket", "Table", "Queue"]);
+    const context = createContext(code);
+    const diagnostics = fileDeclarableLimitRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not warn with exactly 8 Declarable instances", () => {
+    const code = makeNewExprs([
+      "Bucket",
+      "Table",
+      "Queue",
+      "Topic",
+      "Function",
+      "Role",
+      "Policy",
+      "Stack",
+    ]);
+    const context = createContext(code);
+    const diagnostics = fileDeclarableLimitRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("warns with 9 Declarable instances", () => {
+    const code = makeNewExprs([
+      "Bucket",
+      "Table",
+      "Queue",
+      "Topic",
+      "Function",
+      "Role",
+      "Policy",
+      "Stack",
+      "Alarm",
+    ]);
+    const context = createContext(code);
+    const diagnostics = fileDeclarableLimitRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR009");
+    expect(diagnostics[0].severity).toBe("warning");
+    expect(diagnostics[0].line).toBe(1);
+    expect(diagnostics[0].column).toBe(1);
+    expect(diagnostics[0].message).toBe(
+      "File contains 9 Declarable instances (limit: 8) — consider splitting into separate files by concern",
+    );
+  });
+
+  test("does not count non-Declarable new expressions", () => {
+    const code = [
+      `const d = new Date();`,
+      `const m = new Map();`,
+      `const s = new Set();`,
+      `const e = new Error("oops");`,
+      `const r = new RegExp("abc");`,
+      `const a = new Array(10);`,
+      `const w = new WeakMap();`,
+      `const p = new Promise(() => {});`,
+      `const u = new URL("https://example.com");`,
+    ].join("\n");
+    const context = createContext(code);
+    const diagnostics = fileDeclarableLimitRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("only counts capitalized constructors as Declarable", () => {
+    // Mix of lowercase (non-Declarable) and uppercase (Declarable)
+    const code = [
+      ...Array.from({ length: 10 }, () => `new foo();`),
+      `new Bucket({ name: "a" });`,
+    ].join("\n");
+    const context = createContext(code);
+    const diagnostics = fileDeclarableLimitRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("reports correct file path", () => {
+    const code = makeNewExprs([
+      "A",
+      "B",
+      "C",
+      "D",
+      "E",
+      "F",
+      "G",
+      "H",
+      "I",
+    ]);
+    const context = createContext(code, "infra/my-stack.ts");
+    const diagnostics = fileDeclarableLimitRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].file).toBe("infra/my-stack.ts");
+  });
+
+  test("message includes actual count", () => {
+    const code = makeNewExprs([
+      "A",
+      "B",
+      "C",
+      "D",
+      "E",
+      "F",
+      "G",
+      "H",
+      "I",
+      "J",
+      "K",
+    ]);
+    const context = createContext(code);
+    const diagnostics = fileDeclarableLimitRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain("11 Declarable instances");
+  });
+});

package/src/lint/rules/file-declarable-limit.ts

@@ -0,0 +1,96 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+const DECLARABLE_LIMIT = 8;
+
+const BUILTIN_CONSTRUCTORS = new Set([
+  "Array",
+  "ArrayBuffer",
+  "BigInt64Array",
+  "BigUint64Array",
+  "Boolean",
+  "DataView",
+  "Date",
+  "Error",
+  "EvalError",
+  "Float32Array",
+  "Float64Array",
+  "Int8Array",
+  "Int16Array",
+  "Int32Array",
+  "Map",
+  "Number",
+  "Object",
+  "Promise",
+  "Proxy",
+  "RangeError",
+  "ReferenceError",
+  "RegExp",
+  "Set",
+  "SharedArrayBuffer",
+  "String",
+  "SyntaxError",
+  "TypeError",
+  "URIError",
+  "URL",
+  "URLSearchParams",
+  "Uint8Array",
+  "Uint8ClampedArray",
+  "Uint16Array",
+  "Uint32Array",
+  "WeakMap",
+  "WeakRef",
+  "WeakSet",
+]);
+
+function isDeclarableConstructor(node: ts.NewExpression): boolean {
+  const expr = node.expression;
+  if (ts.isIdentifier(expr)) {
+    const name = expr.text;
+    return (
+      name.length > 0 &&
+      name[0] >= "A" &&
+      name[0] <= "Z" &&
+      !BUILTIN_CONSTRUCTORS.has(name)
+    );
+  }
+  return false;
+}
+
+function collectDeclarableNewExpressions(
+  node: ts.Node,
+  results: ts.NewExpression[],
+): void {
+  if (ts.isNewExpression(node) && isDeclarableConstructor(node)) {
+    results.push(node);
+  }
+  ts.forEachChild(node, (child) =>
+    collectDeclarableNewExpressions(child, results),
+  );
+}
+
+export const fileDeclarableLimitRule: LintRule = {
+  id: "COR009",
+  severity: "warning",
+  category: "style",
+  check(context: LintContext, options?: Record<string, unknown>): LintDiagnostic[] {
+    const limit = (typeof options?.max === "number" ? options.max : null) ?? DECLARABLE_LIMIT;
+    const instances: ts.NewExpression[] = [];
+    collectDeclarableNewExpressions(context.sourceFile, instances);
+
+    if (instances.length > limit) {
+      return [
+        {
+          file: context.filePath,
+          line: 1,
+          column: 1,
+          ruleId: "COR009",
+          severity: "warning",
+          message: `File contains ${instances.length} Declarable instances (limit: ${limit}) — consider splitting into separate files by concern`,
+        },
+      ];
+    }
+
+    return [];
+  },
+};

package/src/lint/rules/flat-declarations.test.ts

@@ -0,0 +1,210 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { flatDeclarationsRule } from "./flat-declarations";
+import type { LintContext } from "../rule";
+
+function createContext(code: string, filePath = "test.ts"): LintContext {
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    code,
+    ts.ScriptTarget.Latest,
+    true
+  );
+
+  return {
+    sourceFile,
+    entities: [],
+    filePath,
+    lexicon: undefined,
+  };
+}
+
+describe("COR001: flat-declarations", () => {
+  test("rule metadata", () => {
+    expect(flatDeclarationsRule.id).toBe("COR001");
+    expect(flatDeclarationsRule.severity).toBe("warning");
+    expect(flatDeclarationsRule.category).toBe("style");
+  });
+
+  test("triggers on inline object literal in constructor", () => {
+    const code = `new Bucket({ bucketEncryption: { serverSideEncryptionConfiguration: [] } });`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR001");
+    expect(diagnostics[0].severity).toBe("warning");
+    expect(diagnostics[0].message).toBe("Inline object in Declarable constructor — extract to a named 'const' with 'export'. Each config value should be its own Declarable.");
+  });
+
+  test("triggers on inline array literal in constructor", () => {
+    const code = `new Bucket({ tags: [{ key: "env", value: "prod" }] });`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR001");
+    expect(diagnostics[0].message).toBe("Inline object in Declarable constructor — extract to a named 'const' with 'export'. Each config value should be its own Declarable.");
+  });
+
+  test("does not trigger on primitive values in constructor", () => {
+    const code = `new Bucket({ bucketName: "my-bucket", accessControl: "Private" });`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not trigger on identifier references in constructor", () => {
+    const code = `new Bucket({ encryption: dataEncryption, publicAccessBlock: dataAccessBlock });`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not trigger on intrinsic calls in constructor", () => {
+    const code = `new Bucket({ bucketName: Sub\`\${AWS.StackName}-data\` });`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not trigger on function/method calls in constructor", () => {
+    const code = `new Bucket({ encryption: getEncryption() });`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("triggers on multiple inline objects in same constructor", () => {
+    const code = `new Bucket({
+      encryption: { type: "AES256" },
+      tags: [{ key: "env" }]
+    });`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+
+    expect(diagnostics).toHaveLength(2);
+    expect(diagnostics[0].ruleId).toBe("COR001");
+    expect(diagnostics[1].ruleId).toBe("COR001");
+  });
+
+  test("triggers on multiple constructor calls with violations", () => {
+    const code = `
+      new Bucket({ encryption: { type: "AES256" } });
+      new Table({ schema: { fields: [] } });
+    `;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+
+    expect(diagnostics).toHaveLength(2);
+    expect(diagnostics[0].ruleId).toBe("COR001");
+    expect(diagnostics[1].ruleId).toBe("COR001");
+  });
+
+  test("does not trigger on empty object in constructor", () => {
+    const code = `new Bucket({});`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not trigger on constructor with no arguments", () => {
+    const code = `new Bucket();`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not trigger on constructor with non-object argument", () => {
+    const code = `new SomeClass("string-arg");`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("reports correct line and column numbers", () => {
+    const code = `new Bucket({ encryption: { type: "AES256" } });`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].line).toBe(1);
+    expect(diagnostics[0].column).toBeGreaterThan(0);
+    expect(diagnostics[0].file).toBe("test.ts");
+  });
+
+  test("handles mixed primitive and object properties in constructor", () => {
+    const code = `new Bucket({
+      bucketName: "my-bucket",
+      encryption: { type: "AES256" },
+      accessControl: "Private"
+    });`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toBe("Inline object in Declarable constructor — extract to a named 'const' with 'export'. Each config value should be its own Declarable.");
+  });
+
+  test("does not trigger on non-constructor object literals", () => {
+    const code = `export const x = { a: { b: 1 } };`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("handles nested constructors", () => {
+    const code = `new Outer({ inner: new Inner({ config: { value: 1 } }) });`;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+
+    // Should flag the inline object in the Inner constructor
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR001");
+  });
+
+  test("does not trigger inside Composite() factory callback", () => {
+    const code = `
+      const MyComposite = Composite((props) => {
+        const role = new Role({
+          assumeRolePolicyDocument: {
+            Version: "2012-10-17",
+            Statement: [{ Effect: "Allow" }],
+          },
+        });
+        return { role };
+      });
+    `;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not trigger inside _.Composite() factory callback", () => {
+    const code = `
+      const MyComposite = _.Composite((props) => {
+        const role = new _.Role({
+          policies: [{ policyName: "CustomPolicy" }],
+        });
+        return { role };
+      });
+    `;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("still triggers outside Composite() in same file", () => {
+    const code = `
+      const MyComposite = Composite((props) => {
+        const role = new Role({ config: { value: 1 } });
+        return { role };
+      });
+      const bucket = new Bucket({ encryption: { type: "AES256" } });
+    `;
+    const context = createContext(code);
+    const diagnostics = flatDeclarationsRule.check(context);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain("Inline object");
+  });
+});

package/src/lint/rules/flat-declarations.ts

@@ -0,0 +1,70 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+import { isInsideCompositeFactory } from "./composite-scope";
+
+/**
+ * COR001: No inline objects in Declarable constructors
+ *
+ * Detects inline object literals or array literals as property values
+ * in Declarable constructor arguments. All structure should be expressed
+ * through typed Declarable declarations, never inline object literals.
+ *
+ * Triggers on: new Bucket({ bucketEncryption: { serverSideEncryptionConfiguration: [...] } })
+ * Triggers on: new Bucket({ tags: [{ key: "env", value: "prod" }] })
+ * OK: new Bucket({ bucketName: "my-bucket", accessControl: "Private" })
+ * OK: new Bucket({ encryption: dataEncryption })
+ */
+
+function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnostic[]): void {
+  // Check for NewExpression nodes (constructor calls)
+  // Skip resource constructors inside Composite() factory callbacks
+  if (ts.isNewExpression(node) && !isInsideCompositeFactory(node)) {
+    // Check if the first argument is an object literal
+    if (node.arguments && node.arguments.length > 0) {
+      const firstArg = node.arguments[0];
+
+      if (ts.isObjectLiteralExpression(firstArg)) {
+        // Check each property in the constructor argument
+        for (const property of firstArg.properties) {
+          if (ts.isPropertyAssignment(property)) {
+            const initializer = property.initializer;
+
+            // Flag inline object literals
+            // Flag array literals only if they contain inline objects/arrays
+            if (ts.isObjectLiteralExpression(initializer) ||
+                (ts.isArrayLiteralExpression(initializer) && initializer.elements.some(
+                  el => ts.isObjectLiteralExpression(el) || ts.isArrayLiteralExpression(el)
+                ))) {
+              const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+                initializer.getStart(context.sourceFile)
+              );
+
+              diagnostics.push({
+                file: context.filePath,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "COR001",
+                severity: "warning",
+                message: "Inline object in Declarable constructor — extract to a named 'const' with 'export'. Each config value should be its own Declarable.",
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Recursively check child nodes
+  ts.forEachChild(node, child => checkNode(child, context, diagnostics));
+}
+
+export const flatDeclarationsRule: LintRule = {
+  id: "COR001",
+  severity: "warning",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    checkNode(context.sourceFile, context, diagnostics);
+    return diagnostics;
+  },
+};