@intentius/chant 0.0.1

package/src/lint/rules/prefer-namespace-import.test.ts

@@ -0,0 +1,102 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { preferNamespaceImportRule } from "./prefer-namespace-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("COR006: prefer-namespace-import", () => {
+  test("rule metadata", () => {
+    expect(preferNamespaceImportRule.id).toBe("COR006");
+    expect(preferNamespaceImportRule.severity).toBe("error");
+    expect(preferNamespaceImportRule.category).toBe("style");
+  });
+
+  test("flags named import from @intentius/chant* package", () => {
+    const code = `import { Bucket } from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code);
+    const diagnostics = preferNamespaceImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR006");
+    expect(diagnostics[0].severity).toBe("error");
+    expect(diagnostics[0].message).toBe(
+      `Use namespace import for @intentius/chant-lexicon-testdom — replace with: import * as testdom from "@intentius/chant-lexicon-testdom"`
+    );
+  });
+
+  test("allows namespace import from @intentius/chant* package", () => {
+    const code = `import * as testdom from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code);
+    const diagnostics = preferNamespaceImportRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("allows type-only import from @intentius/chant* package", () => {
+    const code = `import type { Declarable } from "@intentius/chant";`;
+    const context = createContext(code);
+    const diagnostics = preferNamespaceImportRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not flag imports from non-@intentius/chant packages", () => {
+    const code = `import { useState } from "react";`;
+    const context = createContext(code);
+    const diagnostics = preferNamespaceImportRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not flag imports from relative paths", () => {
+    const code = `import { helper } from "./utils";`;
+    const context = createContext(code);
+    const diagnostics = preferNamespaceImportRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("derives alias from package name", () => {
+    const code = `import { Config } from "@intentius/chant";`;
+    const context = createContext(code);
+    const diagnostics = preferNamespaceImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain("import * as core");
+  });
+
+  test("flags multiple named imports from different @intentius/chant packages", () => {
+    const code = `
+import { Bucket } from "@intentius/chant-lexicon-testdom";
+import { Config } from "@intentius/chant";
+`;
+    const context = createContext(code);
+    const diagnostics = preferNamespaceImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(2);
+    expect(diagnostics[0].message).toContain("@intentius/chant-lexicon-testdom");
+    expect(diagnostics[1].message).toContain("@intentius/chant");
+  });
+
+  test("reports correct line and column numbers", () => {
+    const code = `import { Bucket } from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code);
+    const diagnostics = preferNamespaceImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].line).toBe(1);
+    expect(diagnostics[0].column).toBe(1);
+    expect(diagnostics[0].file).toBe("test.ts");
+  });
+});

package/src/lint/rules/prefer-namespace-import.ts

@@ -0,0 +1,63 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR006: prefer-namespace-import
+ *
+ * Enforce `import * as pkg` for `@intentius/chant*` package imports.
+ *
+ * Triggers on: import { Bucket } from "@intentius/chant-lexicon-<name>"
+ * OK: import * as <name> from "@intentius/chant-lexicon-<name>"
+ * OK: import type { Declarable } from "@intentius/chant"
+ */
+
+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 (!modulePath.startsWith("@intentius/chant") && !modulePath.startsWith("@intentius/chant-lexicon-")) 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)
+      );
+
+      const pkgName = modulePath === "@intentius/chant"
+        ? "core"
+        : modulePath.startsWith("@intentius/chant-lexicon-")
+          ? modulePath.replace("@intentius/chant-lexicon-", "")
+          : modulePath.replace("@intentius/chant-", "");
+
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR006",
+        severity: "error",
+        message: `Use namespace import for ${modulePath} — replace with: import * as ${pkgName} from "${modulePath}"`,
+      });
+    }
+  }
+
+  ts.forEachChild(node, child => checkNode(child, context, diagnostics));
+}
+
+export const preferNamespaceImportRule: LintRule = {
+  id: "COR006",
+  severity: "error",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    checkNode(context.sourceFile, context, diagnostics);
+    return diagnostics;
+  },
+};

package/src/lint/rules/single-concern-file.test.ts

@@ -0,0 +1,156 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { singleConcernFileRule } from "./single-concern-file";
+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("COR013: single-concern-file", () => {
+  test("rule metadata", () => {
+    expect(singleConcernFileRule.id).toBe("COR013");
+    expect(singleConcernFileRule.severity).toBe("info");
+    expect(singleConcernFileRule.category).toBe("style");
+  });
+
+  test("does not trigger on resource-only file", () => {
+    const code = `
+      export const bucket = new Bucket({ bucketName: "data" });
+      export const table = new Table({ tableName: "users" });
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not trigger on config-only file", () => {
+    const code = `
+      export const encryption = new BucketEncryption({ type: "AES256" });
+      export const versioning = new VersioningConfiguration({ status: "Enabled" });
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("triggers on file mixing resource and config declarables", () => {
+    const code = `
+      export const bucket = new Bucket({ bucketName: "data" });
+      export const encryption = new BucketEncryption({ type: "AES256" });
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR013");
+    expect(diagnostics[0].severity).toBe("info");
+    expect(diagnostics[0].message).toContain("mixes resource Declarables with configuration Declarables");
+  });
+
+  test("triggers with qualified class names (e.g. aws.Bucket)", () => {
+    const code = `
+      export const bucket = new aws.Bucket({ bucketName: "data" });
+      export const encryption = new aws.BucketEncryption({ type: "AES256" });
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR013");
+  });
+
+  test("does not trigger on file with no new expressions", () => {
+    const code = `
+      export const name = "hello";
+      export function greet() { return name; }
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not trigger on file with only lowercase constructors", () => {
+    const code = `
+      const x = new something();
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("triggers with multiple property-kind patterns", () => {
+    const code = `
+      export const role = new Role({ roleName: "admin" });
+      export const policy = new AccessPolicy({ effect: "Allow" });
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR013");
+  });
+
+  test("does not trigger with single new expression", () => {
+    const code = `
+      export const bucket = new Bucket({ bucketName: "data" });
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("reports correct file path", () => {
+    const code = `
+      export const bucket = new Bucket({});
+      export const enc = new BucketEncryption({});
+    `;
+    const context = createContext(code, "src/my-file.ts");
+    const diagnostics = singleConcernFileRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].file).toBe("src/my-file.ts");
+  });
+
+  test("handles Configuration suffix", () => {
+    const code = `
+      export const bucket = new Bucket({});
+      export const config = new VersioningConfiguration({});
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+    expect(diagnostics).toHaveLength(1);
+  });
+
+  test("handles Block suffix", () => {
+    const code = `
+      export const bucket = new Bucket({});
+      export const block = new PublicAccessBlock({});
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+    expect(diagnostics).toHaveLength(1);
+  });
+
+  test("handles Specification suffix", () => {
+    const code = `
+      export const bucket = new Bucket({});
+      export const spec = new ServerSideEncryptionSpecification({});
+    `;
+    const context = createContext(code);
+    const diagnostics = singleConcernFileRule.check(context);
+    expect(diagnostics).toHaveLength(1);
+  });
+});

package/src/lint/rules/single-concern-file.ts

@@ -0,0 +1,98 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR013: Single-concern file
+ *
+ * Advisory rule that flags files mixing resource Declarables (e.g. Bucket,
+ * Function, Role) with property/config Declarables (e.g. BucketEncryption,
+ * VersioningConfiguration) as `new` expressions.
+ *
+ * Heuristic: class names containing "Configuration", "Encryption", "Policy",
+ * "Rule", "Setting", "Block", "Specification" are considered property-kind.
+ * All other capitalized `new` expressions are considered resource-kind.
+ *
+ * Triggers when a single file has `new` expressions for both kinds.
+ */
+
+const PROPERTY_KIND_PATTERNS = [
+  "Configuration",
+  "Encryption",
+  "Policy",
+  "Rule",
+  "Setting",
+  "Block",
+  "Specification",
+];
+
+function isPropertyKindClass(className: string): boolean {
+  return PROPERTY_KIND_PATTERNS.some(pattern => className.includes(pattern));
+}
+
+function isResourceKindClass(className: string): boolean {
+  return /^[A-Z]/.test(className) && !isPropertyKindClass(className);
+}
+
+interface NewExpressionInfo {
+  className: string;
+  node: ts.NewExpression;
+}
+
+function collectNewExpressions(
+  node: ts.Node,
+  sourceFile: ts.SourceFile,
+  results: NewExpressionInfo[],
+): void {
+  if (ts.isNewExpression(node)) {
+    const className = node.expression.getText(sourceFile);
+    // Only consider capitalized class names (likely Declarable constructors)
+    if (/^[A-Z]/.test(className) || /\.[A-Z]/.test(className)) {
+      // Extract the simple class name (after any dot for qualified access like aws.Bucket)
+      const simpleName = className.includes(".")
+        ? className.split(".").pop()!
+        : className;
+      results.push({ className: simpleName, node });
+    }
+  }
+
+  ts.forEachChild(node, child =>
+    collectNewExpressions(child, sourceFile, results),
+  );
+}
+
+export const singleConcernFileRule: LintRule = {
+  id: "COR013",
+  severity: "info",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    const newExpressions: NewExpressionInfo[] = [];
+    collectNewExpressions(context.sourceFile, context.sourceFile, newExpressions);
+
+    const resourceExpressions = newExpressions.filter(e =>
+      isResourceKindClass(e.className),
+    );
+    const propertyExpressions = newExpressions.filter(e =>
+      isPropertyKindClass(e.className),
+    );
+
+    // Only flag if the file has both kinds
+    if (resourceExpressions.length === 0 || propertyExpressions.length === 0) {
+      return [];
+    }
+
+    // Report a single diagnostic at the file level (first line)
+    const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(0);
+
+    return [
+      {
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR013",
+        severity: "info",
+        message:
+          "COR013: File mixes resource Declarables with configuration Declarables — consider splitting into separate files",
+      },
+    ];
+  },
+};

package/src/lint/rules/stale-barrel-types.ts

@@ -0,0 +1,60 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+import { generateBarrelTypes } from "../../project/sync";
+
+/**
+ * COR016: stale-barrel-types
+ *
+ * Checks that `_.d.ts` barrel type declarations are up-to-date with
+ * the current project scan. Fires only on `_.ts` barrel files.
+ *
+ * When --fix is used, the fix writes the expected content to `_.d.ts`.
+ */
+export const staleBarrelTypesRule: LintRule = {
+  id: "COR016",
+  severity: "warning",
+  category: "correctness",
+  check(context: LintContext): LintDiagnostic[] {
+    // Only fire on _.ts barrel files
+    if (!context.filePath.endsWith("/_.ts") && context.filePath !== "_.ts") {
+      return [];
+    }
+
+    // Requires projectScan
+    if (!context.projectScan) return [];
+
+    const expected = generateBarrelTypes(context.projectScan);
+    const dtsPath = join(dirname(context.filePath), "_.d.ts");
+
+    let existing: string | undefined;
+    try {
+      existing = readFileSync(dtsPath, "utf-8");
+    } catch {
+      // File doesn't exist
+    }
+
+    if (existing === expected) return [];
+
+    const message = existing === undefined
+      ? "Missing _.d.ts barrel type declarations. Run 'chant lint --fix' to generate."
+      : "Stale _.d.ts barrel type declarations. Run 'chant lint --fix' to regenerate.";
+
+    return [
+      {
+        file: context.filePath,
+        line: 1,
+        column: 1,
+        ruleId: "COR016",
+        severity: "warning",
+        message,
+        fix: {
+          range: [0, 0],
+          replacement: "",
+          kind: "write-file",
+          params: { path: dtsPath, content: expected },
+        },
+      },
+    ];
+  },
+};

package/src/lint/selectors.test.ts

@@ -0,0 +1,113 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { resolveSelector, registerSelector, collectNodes } from "./selectors";
+
+function parse(code: string): ts.SourceFile {
+  return ts.createSourceFile("test.ts", code, ts.ScriptTarget.Latest, true);
+}
+
+describe("selectors", () => {
+  describe("collectNodes", () => {
+    test("collects matching nodes recursively", () => {
+      const sf = parse(`const a = "hello"; const b = "world";`);
+      const strings = collectNodes(sf, (node) => ts.isStringLiteral(node));
+      expect(strings).toHaveLength(2);
+    });
+
+    test("returns empty for no matches", () => {
+      const sf = parse(`const a = 1;`);
+      const strings = collectNodes(sf, (node) => ts.isStringLiteral(node));
+      expect(strings).toHaveLength(0);
+    });
+  });
+
+  describe("built-in selectors", () => {
+    test("resource selector matches new expressions", () => {
+      const sf = parse(`const b = new Bucket({ name: "test" });`);
+      const sel = resolveSelector("resource");
+      const nodes = sel(sf);
+      expect(nodes).toHaveLength(1);
+      expect(ts.isNewExpression(nodes[0])).toBe(true);
+    });
+
+    test("any-resource is alias for resource", () => {
+      const sf = parse(`const b = new Bucket({}); const c = new Table({});`);
+      const sel = resolveSelector("any-resource");
+      expect(sel(sf)).toHaveLength(2);
+    });
+
+    test("string-literal matches string literals", () => {
+      const sf = parse(`const a = "hello"; const b = 42;`);
+      const sel = resolveSelector("string-literal");
+      const nodes = sel(sf);
+      expect(nodes).toHaveLength(1);
+      expect(ts.isStringLiteral(nodes[0])).toBe(true);
+    });
+
+    test("export-name matches exported declarations", () => {
+      const sf = parse(`export const a = 1; const b = 2; export function foo() {}`);
+      const sel = resolveSelector("export-name");
+      const nodes = sel(sf);
+      expect(nodes).toHaveLength(2);
+    });
+
+    test("import-source matches import declarations", () => {
+      const sf = parse(`import { Bucket } from "@aws/s3"; import * as iam from "@aws/iam";`);
+      const sel = resolveSelector("import-source");
+      const nodes = sel(sf);
+      expect(nodes).toHaveLength(2);
+    });
+
+    test("property matches property assignments", () => {
+      const sf = parse(`const x = { a: 1, b: 2 };`);
+      const sel = resolveSelector("property");
+      const nodes = sel(sf);
+      expect(nodes).toHaveLength(2);
+    });
+
+    test("resource-type matches new expressions with type arguments", () => {
+      const sf = parse(`const b = new Bucket<MyType>({}); const c = new Table({});`);
+      const sel = resolveSelector("resource-type");
+      const nodes = sel(sf);
+      expect(nodes).toHaveLength(1);
+    });
+
+    test("exported-const matches exported const declarations", () => {
+      const sf = parse(`export const a = 1; export let b = 2; const c = 3;`);
+      const sel = resolveSelector("exported-const");
+      const nodes = sel(sf);
+      expect(nodes).toHaveLength(1);
+    });
+  });
+
+  describe("compound selectors", () => {
+    test("resource > property scopes to children", () => {
+      const sf = parse(`const b = new Bucket({ name: "test", region: "us" }); const other = { x: 1 };`);
+      const sel = resolveSelector("resource > property");
+      const nodes = sel(sf);
+      expect(nodes).toHaveLength(2);
+    });
+  });
+
+  describe("registerSelector", () => {
+    test("registers and resolves custom selector", () => {
+      registerSelector("number-literal", (sf) =>
+        collectNodes(sf, (node) => ts.isNumericLiteral(node))
+      );
+      const sf = parse(`const a = 42; const b = "hello";`);
+      const sel = resolveSelector("number-literal");
+      const nodes = sel(sf);
+      expect(nodes).toHaveLength(1);
+    });
+  });
+
+  describe("error handling", () => {
+    test("throws for unknown selector", () => {
+      expect(() => resolveSelector("nonexistent")).toThrow('Unknown selector: "nonexistent"');
+    });
+
+    test("throws for unknown compound part", () => {
+      expect(() => resolveSelector("resource > nonexistent")).toThrow('Unknown selector: "nonexistent"');
+    });
+  });
+});