@intentius/chant 0.0.1

package/src/lint/rules/declarable-naming-convention.test.ts

@@ -0,0 +1,69 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { declarableNamingConventionRule } from "./declarable-naming-convention";
+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("COR005: declarable-naming-convention", () => {
+  test("rule metadata", () => {
+    expect(declarableNamingConventionRule.id).toBe("COR005");
+    expect(declarableNamingConventionRule.severity).toBe("warning");
+    expect(declarableNamingConventionRule.category).toBe("style");
+  });
+
+  test("triggers on PascalCase declarable name", () => {
+    const ctx = createContext(`export const DataBucket = new Bucket({ bucketName: "x" });`);
+    const diags = declarableNamingConventionRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR005");
+    expect(diags[0].message).toContain("dataBucket");
+  });
+
+  test("triggers on UPPER_SNAKE_CASE declarable name", () => {
+    const ctx = createContext(`export const DATA_BUCKET = new Bucket({ bucketName: "x" });`);
+    const diags = declarableNamingConventionRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR005");
+  });
+
+  test("does not trigger on camelCase declarable name", () => {
+    const ctx = createContext(`export const dataBucket = new Bucket({ bucketName: "x" });`);
+    const diags = declarableNamingConventionRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not trigger on function calls (not new expressions)", () => {
+    const ctx = createContext(`export const DataBucket = createBucket({ bucketName: "x" });`);
+    const diags = declarableNamingConventionRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not trigger on non-exported declarations", () => {
+    const ctx = createContext(`const DataBucket = new Bucket({ bucketName: "x" });`);
+    const diags = declarableNamingConventionRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("reports correct line and column", () => {
+    const ctx = createContext(`export const DataBucket = new Bucket({});`);
+    const diags = declarableNamingConventionRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].line).toBe(1);
+    expect(diags[0].column).toBeGreaterThan(0);
+  });
+});

package/src/lint/rules/declarable-naming-convention.ts

@@ -0,0 +1,70 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR005: declarable-naming-convention
+ *
+ * Exported declarable instances (i.e. `export const x = new SomeClass(...)`)
+ * must use camelCase names. Flags PascalCase and UPPER_SNAKE_CASE names.
+ *
+ * Triggers on: export const DataBucket = new Bucket({ ... })
+ * Triggers on: export const DATA_BUCKET = new Bucket({ ... })
+ * OK: export const dataBucket = new Bucket({ ... })
+ * OK: export const DataBucket = createBucket({ ... })  (not a new expression)
+ * OK: const DataBucket = new Bucket({ ... })  (not exported)
+ */
+
+function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnostic[]): void {
+  if (ts.isVariableStatement(node)) {
+    const hasExport = node.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
+    if (!hasExport) {
+      ts.forEachChild(node, child => checkNode(child, context, diagnostics));
+      return;
+    }
+
+    for (const decl of node.declarationList.declarations) {
+      if (!ts.isIdentifier(decl.name)) continue;
+      if (!decl.initializer || !ts.isNewExpression(decl.initializer)) continue;
+
+      const name = decl.name.text;
+      // camelCase starts with lowercase — that's fine
+      if (/^[a-z]/.test(name)) continue;
+
+      const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+        decl.name.getStart(context.sourceFile),
+      );
+
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR005",
+        severity: "warning",
+        message: `Declarable '${name}' should use camelCase naming — rename to '${toCamelCase(name)}'.`,
+      });
+    }
+  }
+
+  ts.forEachChild(node, child => checkNode(child, context, diagnostics));
+}
+
+/** Suggest a camelCase version of a PascalCase or UPPER_SNAKE_CASE name */
+function toCamelCase(name: string): string {
+  // PascalCase -> camelCase: lowercase first char
+  if (/^[A-Z][a-z]/.test(name)) {
+    return name[0].toLowerCase() + name.slice(1);
+  }
+  // UPPER_SNAKE -> camelCase
+  return name.toLowerCase().replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export const declarableNamingConventionRule: LintRule = {
+  id: "COR005",
+  severity: "warning",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    checkNode(context.sourceFile, context, diagnostics);
+    return diagnostics;
+  },
+};

package/src/lint/rules/enforce-barrel-import.test.ts

@@ -0,0 +1,169 @@
+import { describe, test, expect, mock, beforeEach, afterEach } from "bun:test";
+import * as ts from "typescript";
+import { enforceBarrelImportRule } from "./enforce-barrel-import";
+import type { LintContext } from "../rule";
+import { writeFileSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+
+const TEST_DIR = join(import.meta.dir, "__test_barrel_import__");
+
+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("COR014: enforce-barrel-import", () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  });
+
+  test("rule metadata", () => {
+    expect(enforceBarrelImportRule.id).toBe("COR014");
+    expect(enforceBarrelImportRule.severity).toBe("warning");
+    expect(enforceBarrelImportRule.category).toBe("style");
+  });
+
+  test("flags lexicon import in non-barrel file", () => {
+    const code = `import * as td from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code, join(TEST_DIR, "my-stack.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR014");
+    expect(diagnostics[0].severity).toBe("warning");
+  });
+
+  test("skips barrel file named _.ts", () => {
+    const code = `import * as td from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code, join(TEST_DIR, "_.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("skips barrel file with path prefix", () => {
+    const code = `import * as td from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code, join(TEST_DIR, "infra", "_.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("allows barrel import", () => {
+    const code = `import * as _ from "./_";`;
+    const context = createContext(code, join(TEST_DIR, "my-stack.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("allows non-chant imports", () => {
+    const code = `import * as ts from "typescript";`;
+    const context = createContext(code, join(TEST_DIR, "my-stack.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("message includes barrel content when barrel missing", () => {
+    const code = `import * as td from "@intentius/chant-lexicon-testdom";`;
+    const filePath = join(TEST_DIR, "my-stack.ts");
+    const context = createContext(code, filePath);
+    const diagnostics = enforceBarrelImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain("Create _.ts");
+    expect(diagnostics[0].message).toContain(`export * from "@intentius/chant-lexicon-testdom"`);
+    expect(diagnostics[0].message).toContain("barrel");
+  });
+
+  test("message is shorter when barrel exists", () => {
+    // Create a barrel file in TEST_DIR
+    writeFileSync(join(TEST_DIR, "_.ts"), `export * from "@intentius/chant-lexicon-testdom";`);
+
+    const code = `import * as td from "@intentius/chant-lexicon-testdom";`;
+    const filePath = join(TEST_DIR, "my-stack.ts");
+    const context = createContext(code, filePath);
+    const diagnostics = enforceBarrelImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).not.toContain("Create _.ts");
+    expect(diagnostics[0].message).toContain("use the barrel");
+  });
+
+  test("provides auto-fix when barrel exists", () => {
+    writeFileSync(join(TEST_DIR, "_.ts"), `export * from "@intentius/chant-lexicon-testdom";`);
+
+    const code = `import * as td from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code, join(TEST_DIR, "my-stack.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].fix).toBeDefined();
+    expect(diagnostics[0].fix!.replacement).toBe(`import * as _ from "./_"`);
+  });
+
+  test("does not provide auto-fix when barrel is missing", () => {
+    const code = `import * as td from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code, join(TEST_DIR, "my-stack.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].fix).toBeUndefined();
+  });
+
+  test("flags type-only lexicon import", () => {
+    const code = `import type { Code } from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code, join(TEST_DIR, "my-stack.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR014");
+  });
+
+  test("skips subpath imports from core", () => {
+    const code = `import type { LintRule } from "@intentius/chant/lint/rule";`;
+    const context = createContext(code, join(TEST_DIR, "my-rule.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("skips deep subpath imports from lexicon", () => {
+    const code = `import { helper } from "@intentius/chant-lexicon-aws/internal/util";`;
+    const context = createContext(code, join(TEST_DIR, "my-stack.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("flags multiple lexicon imports", () => {
+    const code = `import * as td from "@intentius/chant-lexicon-testdom";
+import * as core from "@intentius/chant";`;
+    const context = createContext(code, join(TEST_DIR, "my-stack.ts"));
+    const diagnostics = enforceBarrelImportRule.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 * as td from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code, join(TEST_DIR, "my-stack.ts"));
+    const diagnostics = enforceBarrelImportRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].line).toBe(1);
+    expect(diagnostics[0].column).toBe(1);
+  });
+});

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

@@ -0,0 +1,81 @@
+import * as ts from "typescript";
+import { existsSync } from "fs";
+import { dirname, join, basename } from "path";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR014: enforce-barrel-import
+ *
+ * Flags direct lexicon imports (`import * as <name> from "@intentius/chant-lexicon-<name>"`)
+ * in non-barrel files. Use the barrel (`import * as _ from "./_"`) instead.
+ *
+ * Triggers on: import * as <name> from "@intentius/chant-lexicon-<name>" (in non-barrel files)
+ * OK: import * as _ from "./_"
+ * OK: import * as <name> from "@intentius/chant-lexicon-<name>" (in _.ts barrel files)
+ */
+
+export const enforceBarrelImportRule: LintRule = {
+  id: "COR014",
+  severity: "warning",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const sf = context.sourceFile;
+
+    // Skip barrel files
+    if (basename(context.filePath).startsWith("_")) return diagnostics;
+
+    // Check if barrel exists
+    const dir = dirname(context.filePath);
+    const barrelExists = existsSync(join(dir, "_.ts"));
+
+    for (const stmt of sf.statements) {
+      if (!ts.isImportDeclaration(stmt)) continue;
+      if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+
+      const modulePath = stmt.moduleSpecifier.text;
+      if (!modulePath.startsWith("@intentius/chant") && !modulePath.startsWith("@intentius/chant-lexicon-")) continue;
+
+      // Skip subpath imports (e.g., @intentius/chant/lint/rule) — these are
+      // framework internals not available through the barrel
+      const parts = modulePath.split("/");
+      if (parts.length > 2) continue;
+
+      const { line, character } = sf.getLineAndCharacterOfPosition(stmt.getStart(sf));
+      const importText = stmt.getText(sf);
+
+      let message: string;
+      if (barrelExists) {
+        message = `Direct lexicon import — use the barrel.\n    - ${importText}\n    + import * as _ from "./_";`;
+      } else {
+        const lexiconPkg = modulePath;
+        message =
+          `Direct lexicon import — use a barrel file.\n\n` +
+          `  Create _.ts:\n\n` +
+          `    export * from "${lexiconPkg}";\n` +
+          `    import { barrel } from "@intentius/chant";\n` +
+          `    export const $ = barrel(import.meta.dir);\n\n` +
+          `  Then replace this file's import:\n` +
+          `    - ${importText}\n` +
+          `    + import * as _ from "./_";`;
+      }
+
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR014",
+        severity: "warning",
+        message,
+        // Only provide auto-fix when barrel exists — replacing the import
+        // when no barrel is present corrupts the file
+        fix: barrelExists ? {
+          range: [stmt.getStart(sf), stmt.getEnd()],
+          replacement: `import * as _ from "./_"`,
+        } : undefined,
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/enforce-barrel-ref.test.ts

@@ -0,0 +1,114 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { enforceBarrelRefRule } from "./enforce-barrel-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("COR007: enforce-barrel-ref", () => {
+  test("rule metadata", () => {
+    expect(enforceBarrelRefRule.id).toBe("COR007");
+    expect(enforceBarrelRefRule.severity).toBe("warning");
+    expect(enforceBarrelRefRule.category).toBe("style");
+  });
+
+  test("flags named import from sibling", () => {
+    const code = `import { dataBucket } from "./data-bucket";`;
+    const context = createContext(code);
+    const diagnostics = enforceBarrelRefRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR007");
+    expect(diagnostics[0].severity).toBe("warning");
+  });
+
+  test("flags namespace import from sibling", () => {
+    const code = `import * as db from "./data-bucket";`;
+    const context = createContext(code);
+    const diagnostics = enforceBarrelRefRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR007");
+  });
+
+  test("skips barrel import", () => {
+    const code = `import * as _ from "./_";`;
+    const context = createContext(code);
+    const diagnostics = enforceBarrelRefRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("skips lexicon imports", () => {
+    const code = `import * as td from "@intentius/chant-lexicon-testdom";`;
+    const context = createContext(code);
+    const diagnostics = enforceBarrelRefRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("skips barrel file", () => {
+    const code = `import { dataBucket } from "./data-bucket";`;
+    const context = createContext(code, "_.ts");
+    const diagnostics = enforceBarrelRefRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("message includes suggestion with _.$ prefix", () => {
+    const code = `import { dataBucket } from "./data-bucket";`;
+    const context = createContext(code);
+    const diagnostics = enforceBarrelRefRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain("_.$.dataBucket");
+  });
+
+  test("flags multiple sibling imports", () => {
+    const code = `import { dataBucket } from "./data-bucket";
+import { logGroup } from "./log-group";`;
+    const context = createContext(code);
+    const diagnostics = enforceBarrelRefRule.check(context);
+
+    expect(diagnostics).toHaveLength(2);
+  });
+
+  test("flags parent relative imports", () => {
+    const code = `import { x } from "../other";`;
+    const context = createContext(code);
+    const diagnostics = enforceBarrelRefRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR007");
+  });
+
+  test("does not provide auto-fix", () => {
+    const code = `import { dataBucket } from "./data-bucket";`;
+    const context = createContext(code);
+    const diagnostics = enforceBarrelRefRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].fix).toBeUndefined();
+  });
+
+  test("reports correct line and column numbers", () => {
+    const code = `import { dataBucket } from "./data-bucket";`;
+    const context = createContext(code);
+    const diagnostics = enforceBarrelRefRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].line).toBe(1);
+    expect(diagnostics[0].column).toBe(1);
+  });
+});

package/src/lint/rules/enforce-barrel-ref.ts

@@ -0,0 +1,75 @@
+import * as ts from "typescript";
+import { basename } from "path";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+
+/**
+ * COR007: enforce-barrel-ref
+ *
+ * Flags direct sibling imports (`import { dataBucket } from "./data-bucket"`)
+ * in non-barrel files. Use `_.$` instead.
+ *
+ * Triggers on: import { dataBucket } from "./data-bucket"
+ * OK: import * as _ from "./_"
+ * OK: import { dataBucket } from "./data-bucket" (in _.ts barrel files)
+ */
+
+const barrelPattern = /^\.\/(_|_\..*)$/;
+
+export const enforceBarrelRefRule: LintRule = {
+  id: "COR007",
+  severity: "warning",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const sf = context.sourceFile;
+
+    // Skip barrel files
+    if (basename(context.filePath).startsWith("_")) return diagnostics;
+
+    for (const stmt of sf.statements) {
+      if (!ts.isImportDeclaration(stmt)) continue;
+      if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+
+      const modulePath = stmt.moduleSpecifier.text;
+
+      // Skip non-relative imports
+      if (!modulePath.startsWith("./") && !modulePath.startsWith("../")) continue;
+
+      // Skip barrel imports
+      if (barrelPattern.test(modulePath)) continue;
+
+      // This is a direct sibling import — flag it
+      const { line, character } = sf.getLineAndCharacterOfPosition(stmt.getStart(sf));
+      const importText = stmt.getText(sf);
+
+      // Extract imported names for the suggestion
+      const importedNames: string[] = [];
+      const clause = stmt.importClause;
+      if (clause?.namedBindings) {
+        if (ts.isNamedImports(clause.namedBindings)) {
+          for (const el of clause.namedBindings.elements) {
+            importedNames.push(el.name.text);
+          }
+        } else if (ts.isNamespaceImport(clause.namedBindings)) {
+          importedNames.push(clause.namedBindings.name.text + ".*");
+        }
+      }
+
+      const refSuggestion =
+        importedNames.length > 0
+          ? `\n  Access via: ${importedNames.map((n) => `_.$.${n}`).join(", ")}`
+          : "";
+
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR007",
+        severity: "warning",
+        message: `Direct sibling import — use _.$ instead.\n    - ${importText}${refSuggestion}`,
+      });
+    }
+
+    return diagnostics;
+  },
+};