@intentius/chant 0.0.1

package/src/lint/rules/no-redundant-value-cast.ts

@@ -0,0 +1,46 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR015: no-redundant-value-cast
+ *
+ * Flag `as Value<...>` type assertions — AttrRef already implements Intrinsic,
+ * so it satisfies Value<T> without a cast.
+ *
+ * Triggers on: role.arn as Value<string>
+ * OK: role.arn (used directly)
+ */
+
+function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnostic[]): void {
+  if (ts.isAsExpression(node)) {
+    const typeNode = node.type;
+    if (ts.isTypeReferenceNode(typeNode)) {
+      const typeName = typeNode.typeName;
+      if (ts.isIdentifier(typeName) && typeName.text === "Value") {
+        const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+          node.getStart(context.sourceFile)
+        );
+        diagnostics.push({
+          file: context.filePath,
+          line: line + 1,
+          column: character + 1,
+          ruleId: "COR015",
+          severity: "warning",
+          message: `Redundant 'as Value<...>' cast — AttrRef and other Intrinsic types already satisfy Value<T>.`,
+        });
+      }
+    }
+  }
+  ts.forEachChild(node, child => checkNode(child, context, diagnostics));
+}
+
+export const noRedundantValueCastRule: LintRule = {
+  id: "COR015",
+  severity: "warning",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    checkNode(context.sourceFile, context, diagnostics);
+    return diagnostics;
+  },
+};

package/src/lint/rules/no-string-ref.test.ts

@@ -0,0 +1,100 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { noStringRefRule } from "./no-string-ref";
+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("COR003: no-string-ref", () => {
+  test("rule metadata", () => {
+    expect(noStringRefRule.id).toBe("COR003");
+    expect(noStringRefRule.severity).toBe("warning");
+    expect(noStringRefRule.category).toBe("correctness");
+  });
+
+  test("flags td.GetAtt()", () => {
+    const ctx = createContext(`const arn = td.GetAtt("myBucket", "Arn");`);
+    const diags = noStringRefRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR003");
+    expect(diags[0].message).toContain("GetAtt");
+  });
+
+  test("flags td.Ref()", () => {
+    const ctx = createContext(`const id = td.Ref("myBucket");`);
+    const diags = noStringRefRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR003");
+    expect(diags[0].message).toContain("Ref");
+  });
+
+  test("flags bare GetAtt()", () => {
+    const ctx = createContext(`const arn = GetAtt("myBucket", "Arn");`);
+    const diags = noStringRefRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR003");
+    expect(diags[0].message).toContain("GetAtt");
+  });
+
+  test("flags bare Ref()", () => {
+    const ctx = createContext(`const id = Ref("myBucket");`);
+    const diags = noStringRefRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR003");
+    expect(diags[0].message).toContain("Ref");
+  });
+
+  test("allows AttrRef property access", () => {
+    const ctx = createContext(`const arn = bucket.arn;`);
+    const diags = noStringRefRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("allows resource constructor", () => {
+    const ctx = createContext(`const bucket = new td.Bucket({ bucketName: "my-bucket" });`);
+    const diags = noStringRefRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("allows Sub/If/Join intrinsics", () => {
+    const ctx = createContext(
+      [
+        `const a = td.Sub("arn:\${TestDom::AccountId}");`,
+        `const b = td.If("cond", "a", "b");`,
+        `const c = td.Join("-", ["a", "b"]);`,
+      ].join("\n")
+    );
+    const diags = noStringRefRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("multiple violations", () => {
+    const ctx = createContext(
+      [
+        `const a = GetAtt("bucket1", "Arn");`,
+        `const b = td.GetAtt("bucket2", "DomainName");`,
+        `const c = GetAtt("bucket3", "WebsiteURL");`,
+      ].join("\n")
+    );
+    const diags = noStringRefRule.check(ctx);
+    expect(diags).toHaveLength(3);
+    expect(diags.every((d) => d.ruleId === "COR003")).toBe(true);
+  });
+
+  test("correct line and column", () => {
+    const code = [
+      `const x = 1;`,
+      `const arn = GetAtt("myBucket", "Arn");`,
+      `const y = 2;`,
+    ].join("\n");
+    const ctx = createContext(code);
+    const diags = noStringRefRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].line).toBe(2);
+    expect(diags[0].column).toBe(13);
+    expect(diags[0].file).toBe("test.ts");
+  });
+});

package/src/lint/rules/no-string-ref.ts

@@ -0,0 +1,66 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR003: no-string-ref
+ *
+ * Flag string-based `GetAtt("name", "attr")` and `Ref("name")` intrinsic
+ * calls. These bypass type safety — users should import resources and use
+ * typed AttrRef properties like `resource.arn`.
+ */
+
+const TARGET_FUNCTIONS = new Set(["GetAtt", "Ref"]);
+
+export const noStringRefRule: LintRule = {
+  id: "COR003",
+  severity: "warning",
+  category: "correctness",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const sf = context.sourceFile;
+
+    function visit(node: ts.Node): void {
+      if (ts.isCallExpression(node)) {
+        const name = getCalledFunctionName(node);
+        if (name && TARGET_FUNCTIONS.has(name) && hasStringArguments(node)) {
+          const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+          const fnText = name === "GetAtt" ? "GetAtt" : "Ref";
+          diagnostics.push({
+            file: context.filePath,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "COR003",
+            severity: "warning",
+            message: `Avoid string-based ${fnText}() — import the resource and use typed property access instead.`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sf);
+    return diagnostics;
+  },
+};
+
+/**
+ * Extract the function name from a call expression.
+ * Handles both `GetAtt(...)` and `aws.GetAtt(...)` patterns.
+ */
+function getCalledFunctionName(node: ts.CallExpression): string | undefined {
+  const expr = node.expression;
+  if (ts.isIdentifier(expr)) {
+    return expr.text;
+  }
+  if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.name)) {
+    return expr.name.text;
+  }
+  return undefined;
+}
+
+/**
+ * Check if the call has at least one string literal argument.
+ */
+function hasStringArguments(node: ts.CallExpression): boolean {
+  return node.arguments.some((arg) => ts.isStringLiteral(arg));
+}

package/src/lint/rules/no-unused-declarable-import.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { noUnusedDeclarableImportRule } from "./no-unused-declarable-import";
+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("COR010: no-unused-declarable-import", () => {
+  test("rule metadata", () => {
+    expect(noUnusedDeclarableImportRule.id).toBe("COR010");
+    expect(noUnusedDeclarableImportRule.severity).toBe("warning");
+    expect(noUnusedDeclarableImportRule.category).toBe("style");
+  });
+
+  test("triggers on unused namespace import", () => {
+    const ctx = createContext(`import * as td from "@intentius/chant-lexicon-testdom";\nexport const x = 1;`);
+    const diags = noUnusedDeclarableImportRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR010");
+    expect(diags[0].message).toContain("td");
+  });
+
+  test("does not trigger when namespace is used as property access", () => {
+    const ctx = createContext(
+      `import * as td from "@intentius/chant-lexicon-testdom";\nexport const b = new td.Bucket({});`,
+    );
+    const diags = noUnusedDeclarableImportRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not trigger on type-only imports", () => {
+    const ctx = createContext(
+      `import type * as core from "@intentius/chant";\nexport const x = 1;`,
+    );
+    const diags = noUnusedDeclarableImportRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not trigger on non-chant imports", () => {
+    const ctx = createContext(`import * as ts from "typescript";\nexport const x = 1;`);
+    const diags = noUnusedDeclarableImportRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not trigger on named imports (those are COR006)", () => {
+    const ctx = createContext(`import { Bucket } from "@intentius/chant-lexicon-testdom";\nexport const x = 1;`);
+    const diags = noUnusedDeclarableImportRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("handles multiple namespace imports", () => {
+    const ctx = createContext(
+      `import * as td from "@intentius/chant-lexicon-testdom";\n` +
+        `import * as core from "@intentius/chant";\n` +
+        `export const b = new td.Bucket({});`,
+    );
+    const diags = noUnusedDeclarableImportRule.check(ctx);
+    // aws is used, core is not
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("core");
+  });
+
+  test("detects usage in type positions (qualified names)", () => {
+    const ctx = createContext(
+      `import * as core from "@intentius/chant";\n` +
+        `const x: core.Value<string> = "hello";`,
+    );
+    const diags = noUnusedDeclarableImportRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/rules/no-unused-declarable-import.ts

@@ -0,0 +1,103 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR010: no-unused-declarable-import
+ *
+ * Namespace imports from @intentius/chant* must be referenced.
+ *
+ * Triggers on: import * as <name> from "@intentius/chant-lexicon-<name>" (when <name>. never appears)
+ * OK: import * as <name> from "@intentius/chant-lexicon-<name>" (when <name>.Bucket is used)
+ * OK: import type * as core from "@intentius/chant" (type-only)
+ */
+
+interface NamespaceImportInfo {
+  name: string;
+  node: ts.ImportDeclaration;
+}
+
+function collectNamespaceImports(sourceFile: ts.SourceFile): NamespaceImportInfo[] {
+  const imports: NamespaceImportInfo[] = [];
+
+  ts.forEachChild(sourceFile, (node) => {
+    if (!ts.isImportDeclaration(node)) return;
+
+    const moduleSpecifier = node.moduleSpecifier;
+    if (!ts.isStringLiteral(moduleSpecifier)) return;
+    if (!moduleSpecifier.text.startsWith("@intentius/chant") && !moduleSpecifier.text.startsWith("@intentius/chant-lexicon-")) return;
+
+    // Skip type-only imports
+    if (node.importClause?.isTypeOnly) return;
+
+    const importClause = node.importClause;
+    if (!importClause?.namedBindings) return;
+
+    // Only check namespace imports (import * as X)
+    if (ts.isNamespaceImport(importClause.namedBindings)) {
+      imports.push({
+        name: importClause.namedBindings.name.text,
+        node,
+      });
+    }
+  });
+
+  return imports;
+}
+
+function isNamespaceUsed(name: string, sourceFile: ts.SourceFile): boolean {
+  let used = false;
+
+  function visit(node: ts.Node): void {
+    if (used) return;
+
+    // Check for property access: name.something
+    if (ts.isPropertyAccessExpression(node)) {
+      if (ts.isIdentifier(node.expression) && node.expression.text === name) {
+        used = true;
+        return;
+      }
+    }
+
+    // Check for qualified names in types: name.Type
+    if (ts.isQualifiedName(node)) {
+      if (ts.isIdentifier(node.left) && node.left.text === name) {
+        used = true;
+        return;
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return used;
+}
+
+export const noUnusedDeclarableImportRule: LintRule = {
+  id: "COR010",
+  severity: "warning",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const imports = collectNamespaceImports(context.sourceFile);
+
+    for (const imp of imports) {
+      if (!isNamespaceUsed(imp.name, context.sourceFile)) {
+        const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+          imp.node.getStart(context.sourceFile),
+        );
+
+        diagnostics.push({
+          file: context.filePath,
+          line: line + 1,
+          column: character + 1,
+          ruleId: "COR010",
+          severity: "warning",
+          message: `Namespace import '${imp.name}' is never used — remove the import or use ${imp.name}.<resource>.`,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/no-unused-declarable.test.ts

@@ -0,0 +1,134 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { noUnusedDeclarableRule } from "./no-unused-declarable";
+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("COR004: no-unused-declarable", () => {
+  test("rule metadata", () => {
+    expect(noUnusedDeclarableRule.id).toBe("COR004");
+    expect(noUnusedDeclarableRule.severity).toBe("warning");
+    expect(noUnusedDeclarableRule.category).toBe("correctness");
+  });
+
+  test("flags exported declarable that is never referenced", () => {
+    const ctx = createContext(`export const bucket = new Bucket({ bucketName: "x" });`);
+    const diags = noUnusedDeclarableRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR004");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("bucket");
+    expect(diags[0].message).toContain("never referenced");
+  });
+
+  test("does not flag declarable that is referenced by another declarable", () => {
+    const ctx = createContext(
+      `export const bucket = new Bucket({ bucketName: "x" });\n` +
+        `export const fn = new Function({ bucket: bucket.arn });`,
+    );
+    const diags = noUnusedDeclarableRule.check(ctx);
+    // bucket is referenced by fn, but fn itself is unreferenced
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("fn");
+  });
+
+  test("does not flag declarable referenced via namespace import style", () => {
+    const ctx = createContext(
+      `import * as td from "@intentius/chant-lexicon-testdom";\n` +
+        `export const bucket = new td.Bucket({ bucketName: "x" });\n` +
+        `export const fn = new td.Function({ env: { BUCKET: bucket.arn } });`,
+    );
+    const diags = noUnusedDeclarableRule.check(ctx);
+    // bucket is referenced, fn is not
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("fn");
+  });
+
+  test("OK for non-declarable exports (plain objects, functions)", () => {
+    const ctx = createContext(
+      `export const config = { region: "us-east-1" };\n` +
+        `export function helper() { return 1; }`,
+    );
+    const diags = noUnusedDeclarableRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("OK for non-exported declarable (that's COR008's job)", () => {
+    const ctx = createContext(`const bucket = new Bucket({ bucketName: "x" });`);
+    const diags = noUnusedDeclarableRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("OK for new expression with lowercase name (not a declarable)", () => {
+    const ctx = createContext(`export const obj = new someFactory();`);
+    const diags = noUnusedDeclarableRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("flags multiple unused declarables", () => {
+    const ctx = createContext(
+      `export const bucket = new Bucket({ bucketName: "x" });\n` +
+        `export const role = new Role({ roleName: "y" });\n` +
+        `export const fn = new Function({});`,
+    );
+    const diags = noUnusedDeclarableRule.check(ctx);
+    expect(diags).toHaveLength(3);
+    const names = diags.map((d) => d.message);
+    expect(names.some((m) => m.includes("bucket"))).toBe(true);
+    expect(names.some((m) => m.includes("role"))).toBe(true);
+    expect(names.some((m) => m.includes("fn"))).toBe(true);
+  });
+
+  test("flags only unused declarables when some are referenced", () => {
+    const ctx = createContext(
+      `export const bucket = new Bucket({ bucketName: "x" });\n` +
+        `export const role = new Role({ roleName: "y" });\n` +
+        `export const fn = new Function({ bucket: bucket.arn, role: role.arn });`,
+    );
+    const diags = noUnusedDeclarableRule.check(ctx);
+    // bucket and role are referenced by fn, but fn is unreferenced
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("fn");
+  });
+
+  test("reports correct file path", () => {
+    const ctx = createContext(
+      `export const bucket = new Bucket({ bucketName: "x" });`,
+      "infra/storage.ts",
+    );
+    const diags = noUnusedDeclarableRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].file).toBe("infra/storage.ts");
+  });
+
+  test("reports correct line and column", () => {
+    const ctx = createContext(
+      `import * as td from "@intentius/chant-lexicon-testdom";\n` +
+        `export const bucket = new td.Bucket({ bucketName: "x" });`,
+    );
+    const diags = noUnusedDeclarableRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].line).toBe(2);
+    expect(diags[0].column).toBe(1);
+  });
+
+  test("detects reference as function argument", () => {
+    const ctx = createContext(
+      `export const bucket = new Bucket({});\n` + `console.log(bucket);`,
+    );
+    const diags = noUnusedDeclarableRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("detects reference in array literal", () => {
+    const ctx = createContext(
+      `export const bucket = new Bucket({});\n` + `export const list = [bucket];`,
+    );
+    const diags = noUnusedDeclarableRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/rules/no-unused-declarable.ts

@@ -0,0 +1,118 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR004: no-unused-declarable
+ *
+ * Detects exported declarables (export const x = new X(...)) that are never
+ * referenced elsewhere in the same file. This catches orphaned infrastructure
+ * declarations that nothing depends on.
+ *
+ * Triggers on: export const bucket = new Bucket({...}) when bucket is never referenced
+ * OK: export const bucket = new Bucket({...}); export const fn = new Function({ bucket: bucket.arn })
+ */
+
+interface DeclarableInfo {
+  name: string;
+  node: ts.VariableStatement;
+}
+
+function isCapitalized(name: string): boolean {
+  return name.length > 0 && name[0] === name[0].toUpperCase() && name[0] !== name[0].toLowerCase();
+}
+
+function getNewExpressionClassName(expr: ts.NewExpression): string | undefined {
+  if (ts.isIdentifier(expr.expression)) {
+    return expr.expression.text;
+  }
+  if (ts.isPropertyAccessExpression(expr.expression)) {
+    return expr.expression.name.text;
+  }
+  return undefined;
+}
+
+function collectExportedDeclarables(sourceFile: ts.SourceFile): DeclarableInfo[] {
+  const declarables: DeclarableInfo[] = [];
+
+  ts.forEachChild(sourceFile, (node) => {
+    if (!ts.isVariableStatement(node)) return;
+
+    // Must have export modifier
+    const hasExport = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    if (!hasExport) return;
+
+    for (const decl of node.declarationList.declarations) {
+      if (!ts.isIdentifier(decl.name)) continue;
+      if (!decl.initializer) continue;
+
+      // Must be a new expression with a capitalized name
+      if (!ts.isNewExpression(decl.initializer)) continue;
+
+      const className = getNewExpressionClassName(decl.initializer);
+      if (!className || !isCapitalized(className)) continue;
+
+      declarables.push({
+        name: decl.name.text,
+        node,
+      });
+    }
+  });
+
+  return declarables;
+}
+
+function collectReferences(name: string, sourceFile: ts.SourceFile, declarationNode: ts.Node): boolean {
+  let found = false;
+
+  function visit(node: ts.Node): void {
+    if (found) return;
+
+    // Skip the declaration itself
+    if (node === declarationNode) return;
+
+    if (ts.isIdentifier(node) && node.text === name) {
+      // Make sure this isn't the declaration's own name
+      const parent = node.parent;
+      if (parent && ts.isVariableDeclaration(parent) && parent.name === node) {
+        // This is the declaration itself, skip
+      } else {
+        found = true;
+        return;
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return found;
+}
+
+export const noUnusedDeclarableRule: LintRule = {
+  id: "COR004",
+  severity: "warning",
+  category: "correctness",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const declarables = collectExportedDeclarables(context.sourceFile);
+
+    for (const decl of declarables) {
+      if (!collectReferences(decl.name, context.sourceFile, decl.node)) {
+        const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+          decl.node.getStart(context.sourceFile),
+        );
+
+        diagnostics.push({
+          file: context.filePath,
+          line: line + 1,
+          column: character + 1,
+          ruleId: "COR004",
+          severity: "warning",
+          message: `Exported declarable '${decl.name}' is never referenced in this file — it may be dead infrastructure code.`,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};