@intentius/chant 0.0.1

package/src/lint/rules/barrel-import-style.ts

@@ -0,0 +1,59 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR002: barrel-import-style
+ *
+ * Enforce `import * as _` for local `_.ts` barrel imports.
+ *
+ * Triggers on: import { bucketEncryption } from "./_"
+ * OK: import * as _ from "./_"
+ * OK: import type { Config } from "./_"
+ */
+
+const barrelPattern = /^\.\/(_|_\..*)$/;
+
+function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnostic[]): void {
+  if (ts.isImportDeclaration(node)) {
+    const moduleSpecifier = node.moduleSpecifier;
+    if (!ts.isStringLiteral(moduleSpecifier)) return;
+
+    const modulePath = moduleSpecifier.text;
+    if (!barrelPattern.test(modulePath)) return;
+
+    // Skip type-only imports: import type { X } from "..."
+    if (node.importClause?.isTypeOnly) return;
+
+    const importClause = node.importClause;
+    if (!importClause?.namedBindings) return;
+
+    // Flag named imports (not namespace imports)
+    if (ts.isNamedImports(importClause.namedBindings)) {
+      const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+        node.getStart(context.sourceFile)
+      );
+
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR002",
+        severity: "error",
+        message: `Use namespace import for local barrel — replace with: import * as _ from "./_"`,
+      });
+    }
+  }
+
+  ts.forEachChild(node, child => checkNode(child, context, diagnostics));
+}
+
+export const barrelImportStyleRule: LintRule = {
+  id: "COR002",
+  severity: "error",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    checkNode(context.sourceFile, context, diagnostics);
+    return diagnostics;
+  },
+};

package/src/lint/rules/composite-scope.ts

@@ -0,0 +1,55 @@
+import * as ts from "typescript";
+
+/**
+ * Check if a node is inside a Composite() factory callback.
+ *
+ * Composite factories define parameterized resource groups where dynamic
+ * expressions, spreads, and inline objects are expected. Lint rules that
+ * enforce static declarations should skip nodes inside these callbacks.
+ *
+ * Matches: Composite((props) => { ... }) and _.Composite((props) => { ... })
+ */
+export function isInsideCompositeFactory(node: ts.Node): boolean {
+  let current: ts.Node | undefined = node.parent;
+
+  while (current) {
+    if (ts.isArrowFunction(current) || ts.isFunctionExpression(current)) {
+      const parent = current.parent;
+      if (parent && ts.isCallExpression(parent) && parent.arguments[0] === current) {
+        const callee = parent.expression;
+        if (isCompositeCallee(callee)) {
+          return true;
+        }
+      }
+    }
+    current = current.parent;
+  }
+
+  return false;
+}
+
+/**
+ * If the given CallExpression is a Composite() call, return its factory argument.
+ * Returns undefined if not a Composite call or factory is missing.
+ */
+export function getCompositeFactory(
+  call: ts.CallExpression,
+): ts.ArrowFunction | ts.FunctionExpression | undefined {
+  if (!isCompositeCallee(call.expression)) return undefined;
+  const factory = call.arguments[0];
+  if (!factory) return undefined;
+  if (ts.isArrowFunction(factory) || ts.isFunctionExpression(factory)) return factory;
+  return undefined;
+}
+
+export function isCompositeCallee(node: ts.Expression): boolean {
+  // Composite(...)
+  if (ts.isIdentifier(node) && node.text === "Composite") {
+    return true;
+  }
+  // _.Composite(...) or anything.Composite(...)
+  if (ts.isPropertyAccessExpression(node) && node.name.text === "Composite") {
+    return true;
+  }
+  return false;
+}

package/src/lint/rules/cor017-composite-name-match.test.ts

@@ -0,0 +1,107 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { cor017CompositeNameMatchRule } from "./cor017-composite-name-match";
+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("COR017: composite-name-match", () => {
+  test("rule metadata", () => {
+    expect(cor017CompositeNameMatchRule.id).toBe("COR017");
+    expect(cor017CompositeNameMatchRule.severity).toBe("error");
+    expect(cor017CompositeNameMatchRule.category).toBe("correctness");
+  });
+
+  test("allows matching name", () => {
+    const ctx = createContext(`
+      const LambdaApi = Composite((props) => {
+        return { role: new Role({}) };
+      }, "LambdaApi");
+    `);
+    expect(cor017CompositeNameMatchRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("allows matching name with _.Composite", () => {
+    const ctx = createContext(`
+      const LambdaApi = _.Composite((props) => {
+        return { role: new Role({}) };
+      }, "LambdaApi");
+    `);
+    expect(cor017CompositeNameMatchRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("flags mismatched name", () => {
+    const ctx = createContext(`
+      const LambdaApi = Composite((props) => {
+        return { role: new Role({}) };
+      }, "MyFunction");
+    `);
+    const diags = cor017CompositeNameMatchRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR017");
+    expect(diags[0].message).toContain('"MyFunction"');
+    expect(diags[0].message).toContain('"LambdaApi"');
+    expect(diags[0].fix).toBeDefined();
+    expect(diags[0].fix!.replacement).toBe('"LambdaApi"');
+  });
+
+  test("flags missing name argument", () => {
+    const ctx = createContext(`
+      const LambdaApi = Composite((props) => {
+        return { role: new Role({}) };
+      });
+    `);
+    const diags = cor017CompositeNameMatchRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR017");
+    expect(diags[0].message).toContain("missing a name argument");
+    expect(diags[0].message).toContain('"LambdaApi"');
+    expect(diags[0].fix).toBeDefined();
+    expect(diags[0].fix!.replacement).toBe(', "LambdaApi"');
+  });
+
+  test("flags non-literal name argument", () => {
+    const ctx = createContext(`
+      const LambdaApi = Composite((props) => {
+        return { role: new Role({}) };
+      }, getName());
+    `);
+    const diags = cor017CompositeNameMatchRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("string literal");
+    expect(diags[0].fix).toBeDefined();
+    expect(diags[0].fix!.replacement).toBe('"LambdaApi"');
+  });
+
+  test("does not flag non-Composite calls", () => {
+    const ctx = createContext(`
+      const thing = createThing((props) => {
+        return { role: new Role({}) };
+      }, "wrong");
+    `);
+    expect(cor017CompositeNameMatchRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("handles _.Composite with mismatch", () => {
+    const ctx = createContext(`
+      const SecureStorage = _.Composite((props) => {
+        return { bucket: new Bucket({}) };
+      }, "Storage");
+    `);
+    const diags = cor017CompositeNameMatchRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].fix!.replacement).toBe('"SecureStorage"');
+  });
+
+  test("handles export const pattern", () => {
+    const ctx = createContext(`
+      export const LambdaApi = Composite((props) => {
+        return { role: new Role({}) };
+      }, "LambdaApi");
+    `);
+    expect(cor017CompositeNameMatchRule.check(ctx)).toHaveLength(0);
+  });
+});

package/src/lint/rules/cor017-composite-name-match.ts

@@ -0,0 +1,108 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+import { isCompositeCallee } from "./composite-scope";
+
+/**
+ * COR017: Composite name must match variable name
+ *
+ * The second argument to Composite() (the name string) must match the
+ * const variable it's assigned to. This name is used in resource expansion
+ * (e.g. healthApi_role, healthApi_func) and in error messages.
+ *
+ * Triggers on: const LambdaApi = Composite(fn, "MyFunction")  — mismatch
+ * Triggers on: const LambdaApi = Composite(fn)                — missing name
+ * OK: const LambdaApi = Composite(fn, "LambdaApi")
+ */
+
+function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnostic[]): void {
+  if (ts.isVariableDeclaration(node) && node.initializer && ts.isCallExpression(node.initializer)) {
+    const call = node.initializer;
+    if (!isCompositeCallee(call.expression)) {
+      ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+      return;
+    }
+
+    // Get the variable name
+    if (!ts.isIdentifier(node.name)) {
+      ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+      return;
+    }
+    const variableName = node.name.text;
+
+    // Check second argument
+    const nameArg = call.arguments[1];
+
+    if (!nameArg) {
+      // Missing name argument
+      const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+        call.expression.getStart(context.sourceFile),
+      );
+
+      // Insert fix: add name argument after the factory callback
+      const factoryArg = call.arguments[0];
+      const insertPos = factoryArg.getEnd();
+
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR017",
+        severity: "error",
+        message: `Composite is missing a name argument — add "${variableName}" as the second argument`,
+        fix: {
+          range: [insertPos, insertPos],
+          replacement: `, "${variableName}"`,
+        },
+      });
+    } else if (!ts.isStringLiteral(nameArg)) {
+      // Non-literal name argument
+      const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+        nameArg.getStart(context.sourceFile),
+      );
+
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR017",
+        severity: "error",
+        message: `Composite name must be a string literal`,
+        fix: {
+          range: [nameArg.getStart(context.sourceFile), nameArg.getEnd()],
+          replacement: `"${variableName}"`,
+        },
+      });
+    } else if (nameArg.text !== variableName) {
+      // Name mismatch
+      const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+        nameArg.getStart(context.sourceFile),
+      );
+
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR017",
+        severity: "error",
+        message: `Composite name "${nameArg.text}" does not match variable name "${variableName}"`,
+        fix: {
+          range: [nameArg.getStart(context.sourceFile), nameArg.getEnd()],
+          replacement: `"${variableName}"`,
+        },
+      });
+    }
+  }
+
+  ts.forEachChild(node, (child) => checkNode(child, context, diagnostics));
+}
+
+export const cor017CompositeNameMatchRule: LintRule = {
+  id: "COR017",
+  severity: "error",
+  category: "correctness",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    checkNode(context.sourceFile, context, diagnostics);
+    return diagnostics;
+  },
+};

package/src/lint/rules/cor018-composite-prefer-lexicon-type.test.ts

@@ -0,0 +1,172 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-lexicon-type";
+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("COR018: composite-prefer-lexicon-type", () => {
+  test("rule metadata", () => {
+    expect(cor018CompositePreferLexiconTypeRule.id).toBe("COR018");
+    expect(cor018CompositePreferLexiconTypeRule.severity).toBe("info");
+    expect(cor018CompositePreferLexiconTypeRule.category).toBe("style");
+  });
+
+  test("flags local interface used in Composite props", () => {
+    const ctx = createContext(`
+      interface PolicyStatement {
+        effect: string;
+        action: string[];
+        resource: string[];
+      }
+
+      interface LambdaApiProps {
+        name: string;
+        policies?: PolicyStatement[];
+      }
+
+      const LambdaApi = Composite<LambdaApiProps>((props) => {
+        const role = new Role({ policies: props.policies });
+        return { role };
+      }, "LambdaApi");
+    `);
+    const diags = cor018CompositePreferLexiconTypeRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR018");
+    expect(diags[0].message).toContain("PolicyStatement");
+    expect(diags[0].message).toContain("policies");
+    expect(diags[0].message).toContain("lexicon property type");
+  });
+
+  test("does not flag when no local types are used", () => {
+    const ctx = createContext(`
+      interface LambdaApiProps {
+        name: string;
+        timeout?: number;
+        policies?: InstanceType<typeof Role_Policy>[];
+      }
+
+      const LambdaApi = Composite<LambdaApiProps>((props) => {
+        const role = new Role({ policies: props.policies });
+        return { role };
+      }, "LambdaApi");
+    `);
+    expect(cor018CompositePreferLexiconTypeRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("does not flag files without Composite", () => {
+    const ctx = createContext(`
+      interface MyType {
+        name: string;
+      }
+
+      interface MyProps {
+        item: MyType;
+      }
+    `);
+    expect(cor018CompositePreferLexiconTypeRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("flags local type alias used in Composite props", () => {
+    const ctx = createContext(`
+      type EncryptionConfig = {
+        algorithm: string;
+        keyId: string;
+      };
+
+      interface StorageProps {
+        encryption: EncryptionConfig;
+      }
+
+      const Storage = Composite<StorageProps>((props) => {
+        const bucket = new Bucket({ encryption: props.encryption });
+        return { bucket };
+      }, "Storage");
+    `);
+    const diags = cor018CompositePreferLexiconTypeRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("EncryptionConfig");
+    expect(diags[0].message).toContain("encryption");
+  });
+
+  test("flags with _.Composite", () => {
+    const ctx = createContext(`
+      interface CustomPolicy {
+        name: string;
+      }
+
+      interface MyProps {
+        policy: CustomPolicy;
+      }
+
+      const MyComp = _.Composite<MyProps>((props) => {
+        return { role: new Role({}) };
+      }, "MyComp");
+    `);
+    const diags = cor018CompositePreferLexiconTypeRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("CustomPolicy");
+  });
+
+  test("flags multiple local types in props", () => {
+    const ctx = createContext(`
+      interface PolicyDoc {
+        version: string;
+      }
+
+      interface TagConfig {
+        key: string;
+        value: string;
+      }
+
+      interface MyProps {
+        policy: PolicyDoc;
+        tags: TagConfig[];
+      }
+
+      const MyComp = Composite<MyProps>((props) => {
+        return { role: new Role({}) };
+      }, "MyComp");
+    `);
+    const diags = cor018CompositePreferLexiconTypeRule.check(ctx);
+    expect(diags).toHaveLength(2);
+  });
+
+  test("does not flag primitives in props", () => {
+    const ctx = createContext(`
+      interface MyProps {
+        name: string;
+        count: number;
+        enabled: boolean;
+        tags: string[];
+      }
+
+      const MyComp = Composite<MyProps>((props) => {
+        return { bucket: new Bucket({}) };
+      }, "MyComp");
+    `);
+    expect(cor018CompositePreferLexiconTypeRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("handles union types with local type", () => {
+    const ctx = createContext(`
+      interface CustomCode {
+        zipFile: string;
+      }
+
+      interface MyProps {
+        code: CustomCode | string;
+      }
+
+      const MyComp = Composite<MyProps>((props) => {
+        return { func: new Function({}) };
+      }, "MyComp");
+    `);
+    const diags = cor018CompositePreferLexiconTypeRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("CustomCode");
+  });
+});

package/src/lint/rules/cor018-composite-prefer-lexicon-type.ts

@@ -0,0 +1,167 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+import { isCompositeCallee } from "./composite-scope";
+
+/**
+ * COR018: Prefer lexicon property types in Composite props
+ *
+ * Composite prop interfaces should use lexicon property types (via the barrel)
+ * instead of locally-declared interfaces or type aliases. Local types next to
+ * a Composite definition often duplicate existing lexicon property types.
+ *
+ * Triggers on: interface with fields used as a Composite prop type, declared
+ *              in the same file as the Composite (excluding the props interface itself)
+ * OK: InstanceType<typeof _.Role_Policy>
+ * OK: primitives (string, number, boolean)
+ * OK: barrel-imported types
+ */
+
+/**
+ * Find all Composite() calls and extract their props type names.
+ */
+function findCompositePropsTypes(sourceFile: ts.SourceFile): Set<string> {
+  const propsTypes = new Set<string>();
+
+  function walk(node: ts.Node): void {
+    if (ts.isCallExpression(node) && isCompositeCallee(node.expression)) {
+      // Composite<PropsType>(...) — extract from type arguments
+      if (node.typeArguments && node.typeArguments.length > 0) {
+        const typeArg = node.typeArguments[0];
+        if (ts.isTypeReferenceNode(typeArg) && ts.isIdentifier(typeArg.typeName)) {
+          propsTypes.add(typeArg.typeName.text);
+        }
+      }
+    }
+    ts.forEachChild(node, walk);
+  }
+
+  walk(sourceFile);
+  return propsTypes;
+}
+
+/**
+ * Find all locally-declared interface and type alias names.
+ */
+function findLocalTypeDeclarations(sourceFile: ts.SourceFile): Map<string, ts.Node> {
+  const types = new Map<string, ts.Node>();
+
+  function walk(node: ts.Node): void {
+    if (ts.isInterfaceDeclaration(node)) {
+      types.set(node.name.text, node);
+    } else if (ts.isTypeAliasDeclaration(node)) {
+      types.set(node.name.text, node);
+    }
+    ts.forEachChild(node, walk);
+  }
+
+  walk(sourceFile);
+  return types;
+}
+
+/**
+ * Collect type references used in a props interface's field types.
+ * Returns names of locally-referenced types (not primitives, not from barrel).
+ */
+function collectFieldTypeRefs(
+  propsDecl: ts.Node,
+  localTypes: Map<string, ts.Node>,
+): Map<string, { fieldName: string; typeNode: ts.Node }> {
+  const refs = new Map<string, { fieldName: string; typeNode: ts.Node }>();
+
+  if (!ts.isInterfaceDeclaration(propsDecl)) return refs;
+
+  for (const member of propsDecl.members) {
+    if (!ts.isPropertySignature(member) || !member.type) continue;
+
+    const fieldName = ts.isIdentifier(member.name!) ? member.name!.text : "<computed>";
+    collectTypeRefsFromNode(member.type, localTypes, fieldName, refs);
+  }
+
+  return refs;
+}
+
+function collectTypeRefsFromNode(
+  node: ts.TypeNode,
+  localTypes: Map<string, ts.Node>,
+  fieldName: string,
+  refs: Map<string, { fieldName: string; typeNode: ts.Node }>,
+): void {
+  if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+    const name = node.typeName.text;
+    if (localTypes.has(name) && !refs.has(name)) {
+      refs.set(name, { fieldName, typeNode: node });
+    }
+  }
+
+  // Recurse into array types: CustomType[] → CustomType
+  if (ts.isArrayTypeNode(node)) {
+    collectTypeRefsFromNode(node.elementType, localTypes, fieldName, refs);
+  }
+
+  // Recurse into union/intersection types
+  if (ts.isUnionTypeNode(node) || ts.isIntersectionTypeNode(node)) {
+    for (const member of node.types) {
+      collectTypeRefsFromNode(member, localTypes, fieldName, refs);
+    }
+  }
+
+  // Recurse into generic type arguments
+  if (ts.isTypeReferenceNode(node) && node.typeArguments) {
+    for (const arg of node.typeArguments) {
+      collectTypeRefsFromNode(arg, localTypes, fieldName, refs);
+    }
+  }
+}
+
+function checkFile(context: LintContext): LintDiagnostic[] {
+  const diagnostics: LintDiagnostic[] = [];
+  const { sourceFile } = context;
+
+  // Find Composite calls and their props types
+  const propsTypeNames = findCompositePropsTypes(sourceFile);
+  if (propsTypeNames.size === 0) return diagnostics;
+
+  // Find all local type declarations
+  const localTypes = findLocalTypeDeclarations(sourceFile);
+
+  for (const propsTypeName of propsTypeNames) {
+    const propsDecl = localTypes.get(propsTypeName);
+    if (!propsDecl) continue;
+
+    // Find local types referenced in the props fields
+    // Exclude the props interface itself
+    const otherLocalTypes = new Map(localTypes);
+    otherLocalTypes.delete(propsTypeName);
+
+    if (otherLocalTypes.size === 0) continue;
+
+    const fieldRefs = collectFieldTypeRefs(propsDecl, otherLocalTypes);
+
+    for (const [typeName, { fieldName, typeNode }] of fieldRefs) {
+      const typeDecl = localTypes.get(typeName)!;
+      const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+        typeDecl.getStart(context.sourceFile),
+      );
+
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR018",
+        severity: "info",
+        message: `Local type "${typeName}" is used in Composite prop "${fieldName}" — consider using a lexicon property type instead (e.g., InstanceType<typeof _.PropertyType>)`,
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export const cor018CompositePreferLexiconTypeRule: LintRule = {
+  id: "COR018",
+  severity: "info",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    return checkFile(context);
+  },
+};