@intentius/chant 0.0.1

package/src/lint/rule-loader.test.ts

@@ -0,0 +1,67 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { mkdirSync, writeFileSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { loadLocalRules } from "./rule-loader";
+
+const TEST_DIR = join(import.meta.dir, "__test_rules_fixture__");
+const RULES_DIR = join(TEST_DIR, ".chant", "rules");
+
+beforeAll(() => {
+  mkdirSync(RULES_DIR, { recursive: true });
+
+  // Write a valid rule file
+  writeFileSync(
+    join(RULES_DIR, "my-rule.ts"),
+    `
+import type { LintRule, LintContext, LintDiagnostic } from "../../../rule";
+
+export const myCustomRule: LintRule = {
+  id: "LOCAL001",
+  severity: "warning",
+  category: "style",
+  check(context: LintContext): LintDiagnostic[] {
+    return [];
+  },
+};
+
+// Non-rule export should be ignored
+export const notARule = "just a string";
+`,
+  );
+});
+
+afterAll(() => {
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true });
+  }
+});
+
+describe("rule-loader", () => {
+  test("loads rules from .chant/rules/ directory", async () => {
+    const rules = await loadLocalRules(TEST_DIR);
+    expect(rules).toHaveLength(1);
+    expect(rules[0].id).toBe("LOCAL001");
+    expect(rules[0].severity).toBe("warning");
+    expect(rules[0].category).toBe("style");
+  });
+
+  test("returns empty array when .chant/rules/ does not exist", async () => {
+    const rules = await loadLocalRules("/tmp/nonexistent-project-dir");
+    expect(rules).toHaveLength(0);
+  });
+
+  test("ignores test files in .chant/rules/", async () => {
+    // Write a test file that should be ignored
+    writeFileSync(
+      join(RULES_DIR, "my-rule.test.ts"),
+      `export const testRule = { id: "SKIP", severity: "error", category: "style", check() { return []; } };`,
+    );
+
+    const rules = await loadLocalRules(TEST_DIR);
+    expect(rules).toHaveLength(1);
+    expect(rules[0].id).toBe("LOCAL001");
+
+    // Clean up
+    rmSync(join(RULES_DIR, "my-rule.test.ts"));
+  });
+});

package/src/lint/rule-loader.ts

@@ -0,0 +1,67 @@
+import { readdirSync, existsSync } from "fs";
+import { join, resolve } from "path";
+import type { LintRule } from "./rule";
+
+/**
+ * Type guard to check if a value conforms to the LintRule interface.
+ */
+function isLintRule(value: unknown): value is LintRule {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "id" in value &&
+    typeof (value as Record<string, unknown>).id === "string" &&
+    "severity" in value &&
+    "category" in value &&
+    "check" in value &&
+    typeof (value as Record<string, unknown>).check === "function"
+  );
+}
+
+/**
+ * Load local lint rules from `.chant/rules/` directory.
+ *
+ * Scans for `.ts` files, dynamically imports each, and collects
+ * all exports that conform to the LintRule interface.
+ *
+ * @param projectDir - Root directory of the project
+ * @returns Array of LintRule objects found in `.chant/rules/`
+ */
+export async function loadLocalRules(projectDir: string): Promise<LintRule[]> {
+  const rulesDir = join(projectDir, ".chant", "rules");
+
+  if (!existsSync(rulesDir)) {
+    return [];
+  }
+
+  const rules: LintRule[] = [];
+  let entries: string[];
+
+  try {
+    entries = readdirSync(rulesDir);
+  } catch {
+    return [];
+  }
+
+  const tsFiles = entries.filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts") && !f.endsWith(".spec.ts"));
+
+  for (const file of tsFiles) {
+    const filePath = resolve(rulesDir, file);
+    let mod: Record<string, unknown>;
+    try {
+      mod = await import(filePath);
+    } catch (err) {
+      throw new Error(
+        `Failed to load rule file "${file}": ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    for (const value of Object.values(mod)) {
+      if (isLintRule(value)) {
+        rules.push(value);
+      }
+    }
+  }
+
+  return rules;
+}

package/src/lint/rule-options.test.ts

@@ -0,0 +1,141 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { parseRuleConfig, loadConfig } from "./config";
+import { fileDeclarableLimitRule } from "./rules/file-declarable-limit";
+import * as ts from "typescript";
+import type { LintContext } from "./rule";
+import { writeFileSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+
+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");
+}
+
+const TEST_DIR = join(import.meta.dir, "__test_rule_options__");
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe("parseRuleConfig", () => {
+  test("parses string severity", () => {
+    const result = parseRuleConfig("warning");
+    expect(result).toEqual({ severity: "warning" });
+  });
+
+  test("parses 'off' string", () => {
+    const result = parseRuleConfig("off");
+    expect(result).toEqual({ severity: "off" });
+  });
+
+  test("parses [severity, options] tuple", () => {
+    const result = parseRuleConfig(["warning", { max: 12 }]);
+    expect(result).toEqual({ severity: "warning", options: { max: 12 } });
+  });
+
+  test("throws for invalid tuple length", () => {
+    expect(() => parseRuleConfig([] as unknown as [string, Record<string, unknown>])).toThrow(
+      /expected a severity string or \[severity, options\] tuple/
+    );
+  });
+
+  test("throws for invalid severity in tuple", () => {
+    expect(() => parseRuleConfig(["invalid" as "error", { max: 1 }])).toThrow(
+      /severity "invalid" must be/
+    );
+  });
+
+  test("throws when options is not a plain object", () => {
+    expect(() => parseRuleConfig(["warning", [1, 2] as unknown as Record<string, unknown>])).toThrow(
+      /options must be a plain object/
+    );
+  });
+
+  test("throws when options is null", () => {
+    expect(() => parseRuleConfig(["warning", null as unknown as Record<string, unknown>])).toThrow(
+      /options must be a plain object/
+    );
+  });
+});
+
+describe("COR009 with options", () => {
+  test("uses default limit (8) when no options", () => {
+    const code = makeNewExprs(["A", "B", "C", "D", "E", "F", "G", "H", "I"]);
+    const context = createContext(code);
+    const diagnostics = fileDeclarableLimitRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain("limit: 8");
+  });
+
+  test("respects custom max from options", () => {
+    const code = makeNewExprs(["A", "B", "C", "D", "E", "F", "G", "H", "I"]);
+    const context = createContext(code);
+
+    // With max: 12, 9 instances should not trigger
+    const diagnostics = fileDeclarableLimitRule.check(context, { max: 12 });
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("custom max triggers when exceeded", () => {
+    const code = makeNewExprs(["A", "B", "C", "D", "E"]);
+    const context = createContext(code);
+
+    // With max: 4, 5 instances should trigger
+    const diagnostics = fileDeclarableLimitRule.check(context, { max: 4 });
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain("limit: 4");
+  });
+});
+
+describe("config loading with tuple format", () => {
+  test("loads config with string severity", () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ rules: { COR009: "error" } })
+    );
+    const config = loadConfig(TEST_DIR);
+    expect(config.rules?.["COR009"]).toBe("error");
+  });
+
+  test("loads config with [severity, options] tuple", () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ rules: { COR009: ["warning", { max: 12 }] } })
+    );
+    const config = loadConfig(TEST_DIR);
+    expect(config.rules?.["COR009"]).toEqual(["warning", { max: 12 }]);
+  });
+
+  test("rejects invalid tuple format in config", () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ rules: { COR009: ["warning"] } })
+    );
+    expect(() => loadConfig(TEST_DIR)).toThrow(/must be a severity string or \[severity, options\] tuple/);
+  });
+
+  test("rejects non-object options in config tuple", () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ rules: { COR009: ["warning", "not-an-object"] } })
+    );
+    expect(() => loadConfig(TEST_DIR)).toThrow(/must be a severity string or \[severity, options\] tuple/);
+  });
+
+  test("rejects non-string/non-tuple rule values", () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ rules: { COR009: 42 } })
+    );
+    expect(() => loadConfig(TEST_DIR)).toThrow(/must be a severity string or \[severity, options\] tuple/);
+  });
+});

package/src/lint/rule.test.ts

@@ -0,0 +1,196 @@
+import { describe, test, expect } from "bun:test";
+import type {
+  LintRule,
+  LintContext,
+  LintDiagnostic,
+  LintFix,
+  Severity,
+  Category,
+} from "./rule";
+import * as ts from "typescript";
+
+describe("LintRule interfaces", () => {
+  test("creates mock LintRule with all required methods", () => {
+    const mockRule: LintRule = {
+      id: "test-rule",
+      severity: "warning" as Severity,
+      category: "correctness" as Category,
+      check: (context: LintContext) => [],
+      fix: (context: LintContext) => [],
+    };
+
+    expect(mockRule.id).toBe("test-rule");
+    expect(mockRule.severity).toBe("warning");
+    expect(mockRule.category).toBe("correctness");
+    expect(typeof mockRule.check).toBe("function");
+    expect(typeof mockRule.fix).toBe("function");
+  });
+
+  test("creates LintContext with undefined lexicon for core rules", () => {
+    const sourceFile = ts.createSourceFile(
+      "test.ts",
+      "const x = 1;",
+      ts.ScriptTarget.Latest,
+      true
+    );
+
+    const context: LintContext = {
+      sourceFile,
+      entities: [],
+      filePath: "test.ts",
+      lexicon: undefined,
+    };
+
+    expect(context.sourceFile).toBe(sourceFile);
+    expect(context.entities).toEqual([]);
+    expect(context.filePath).toBe("test.ts");
+    expect(context.lexicon).toBeUndefined();
+  });
+
+  test("creates LintContext with lexicon for lexicon-specific rules", () => {
+    const sourceFile = ts.createSourceFile(
+      "test.ts",
+      "const x = 1;",
+      ts.ScriptTarget.Latest,
+      true
+    );
+
+    const context: LintContext = {
+      sourceFile,
+      entities: [{ name: "TestEntity" }],
+      filePath: "test.ts",
+      lexicon: "my-domain",
+    };
+
+    expect(context.lexicon).toBe("my-domain");
+  });
+
+  test("creates LintDiagnostic without fix", () => {
+    const diagnostic: LintDiagnostic = {
+      file: "/src/test.ts",
+      line: 10,
+      column: 5,
+      ruleId: "no-unused-vars",
+      severity: "error",
+      message: "Variable 'x' is declared but never used",
+    };
+
+    expect(diagnostic.file).toBe("/src/test.ts");
+    expect(diagnostic.line).toBe(10);
+    expect(diagnostic.column).toBe(5);
+    expect(diagnostic.ruleId).toBe("no-unused-vars");
+    expect(diagnostic.severity).toBe("error");
+    expect(diagnostic.message).toBe("Variable 'x' is declared but never used");
+    expect(diagnostic.fix).toBeUndefined();
+  });
+
+  test("creates LintDiagnostic with fix", () => {
+    const fix: LintFix = {
+      range: [100, 110],
+      replacement: "const y = 1;",
+    };
+
+    const diagnostic: LintDiagnostic = {
+      file: "/src/test.ts",
+      line: 10,
+      column: 5,
+      ruleId: "prefer-const",
+      severity: "warning",
+      message: "Use 'const' instead of 'let'",
+      fix,
+    };
+
+    expect(diagnostic.fix).toBe(fix);
+    expect(diagnostic.fix?.range).toEqual([100, 110]);
+    expect(diagnostic.fix?.replacement).toBe("const y = 1;");
+  });
+
+  test("LintDiagnostic serializes to JSON correctly", () => {
+    const diagnostic: LintDiagnostic = {
+      file: "/src/app.ts",
+      line: 42,
+      column: 15,
+      ruleId: "no-console",
+      severity: "info",
+      message: "Unexpected console statement",
+      fix: {
+        range: [500, 520],
+        replacement: "",
+      },
+    };
+
+    const json = JSON.parse(JSON.stringify(diagnostic));
+
+    expect(json).toEqual({
+      file: "/src/app.ts",
+      line: 42,
+      column: 15,
+      ruleId: "no-console",
+      severity: "info",
+      message: "Unexpected console statement",
+      fix: {
+        range: [500, 520],
+        replacement: "",
+      },
+    });
+  });
+
+  test("LintFix has valid source positions", () => {
+    const fix: LintFix = {
+      range: [0, 10],
+      replacement: "new code",
+    };
+
+    expect(fix.range[0]).toBeGreaterThanOrEqual(0);
+    expect(fix.range[1]).toBeGreaterThan(fix.range[0]);
+    expect(typeof fix.replacement).toBe("string");
+  });
+
+  test("LintRule can be implemented without fix method", () => {
+    const ruleWithoutFix: LintRule = {
+      id: "no-fix-rule",
+      severity: "error",
+      category: "style",
+      check: () => [],
+    };
+
+    expect(ruleWithoutFix.fix).toBeUndefined();
+  });
+
+  test("all severity levels are valid", () => {
+    const severities: Severity[] = ["error", "warning", "info"];
+
+    severities.forEach((severity) => {
+      const diagnostic: LintDiagnostic = {
+        file: "test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "test",
+        severity,
+        message: "test",
+      };
+
+      expect(diagnostic.severity).toBe(severity);
+    });
+  });
+
+  test("all categories are valid", () => {
+    const categories: Category[] = [
+      "correctness",
+      "style",
+      "performance",
+      "security",
+    ];
+
+    categories.forEach((category) => {
+      const rule: LintRule = {
+        id: "test",
+        severity: "error",
+        category,
+        check: () => [],
+      };
+
+      expect(rule.category).toBe(category);
+    });
+  });
+});

package/src/lint/rule.ts

@@ -0,0 +1,98 @@
+import type * as ts from "typescript";
+
+/**
+ * Severity level for lint diagnostics
+ */
+export type Severity = "error" | "warning" | "info";
+
+/**
+ * Category for grouping related lint rules
+ */
+export type Category = "correctness" | "style" | "performance" | "security";
+
+/**
+ * A fix that can be applied to source code
+ */
+export interface LintFix {
+  /** [start, end] positions in the source file */
+  range: [number, number];
+  /** Text to replace the range with */
+  replacement: string;
+  /** Kind of fix operation */
+  kind?: "replace" | "insert-before" | "insert-after" | "delete" | "write-file";
+  /** Additional parameters for the fix */
+  params?: Record<string, unknown>;
+}
+
+/**
+ * A diagnostic message from a lint rule
+ */
+export interface LintDiagnostic {
+  /** File path where the issue was found */
+  file: string;
+  /** Line number (1-based) */
+  line: number;
+  /** Column number (1-based) */
+  column: number;
+  /** ID of the rule that produced this diagnostic */
+  ruleId: string;
+  /** Severity level */
+  severity: Severity;
+  /** Human-readable message */
+  message: string;
+  /** Optional fix that can be applied */
+  fix?: LintFix;
+}
+
+/**
+ * Context provided to lint rules during checking
+ */
+export interface LintContext {
+  /** Parsed TypeScript source file */
+  sourceFile: ts.SourceFile;
+  /** Discovered entities in the file */
+  entities: unknown[];
+  /** Path to the file being linted */
+  filePath: string;
+  /** Optional lexicon context (undefined for core rules) */
+  lexicon?: string;
+  /** Export names from the barrel file (for EVL008) */
+  barrelExports?: Set<string>;
+  /** All project exports keyed by name (for EVL008) */
+  projectExports?: Map<string, { file: string; className: string }>;
+  /** Project scan result (for COR016) */
+  projectScan?: import("../project/scan").ProjectScan;
+}
+
+/**
+ * Options for extending the lint context with project-level information
+ */
+export interface LintRunOptions {
+  /** Export names from the barrel file */
+  barrelExports?: Set<string>;
+  /** All project exports keyed by name */
+  projectExports?: Map<string, { file: string; className: string }>;
+  /** Project scan result (for COR016) */
+  projectScan?: import("../project/scan").ProjectScan;
+}
+
+/**
+ * Configuration value for a rule: either a severity string or a [severity, options] tuple
+ */
+export type RuleConfig = Severity | "off" | [Severity | "off", Record<string, unknown>];
+
+/**
+ * A lint rule that can check code and optionally provide fixes
+ */
+export interface LintRule {
+  /** Unique identifier for this rule */
+  id: string;
+  /** Severity level for diagnostics from this rule */
+  severity: Severity;
+  /** Category for grouping */
+  category: Category;
+  /** Check the code and return diagnostics */
+  check(context: LintContext, options?: Record<string, unknown>): LintDiagnostic[];
+  /** Optionally provide fixes for issues found */
+  fix?(context: LintContext): LintFix[];
+}

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

@@ -0,0 +1,80 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { barrelImportStyleRule } from "./barrel-import-style";
+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("COR002: barrel-import-style", () => {
+  test("rule metadata", () => {
+    expect(barrelImportStyleRule.id).toBe("COR002");
+    expect(barrelImportStyleRule.severity).toBe("error");
+    expect(barrelImportStyleRule.category).toBe("style");
+  });
+
+  test("flags named import from ./_", () => {
+    const code = `import { bucketEncryption } from "./_";`;
+    const context = createContext(code);
+    const diagnostics = barrelImportStyleRule.check(context);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR002");
+    expect(diagnostics[0].severity).toBe("error");
+    expect(diagnostics[0].message).toBe(
+      `Use namespace import for local barrel — replace with: import * as _ from "./_"`
+    );
+  });
+
+  test("allows namespace import from ./_", () => {
+    const code = `import * as _ from "./_";`;
+    const context = createContext(code);
+    const diagnostics = barrelImportStyleRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("allows type-only import from ./_", () => {
+    const code = `import type { Config } from "./_";`;
+    const context = createContext(code);
+    const diagnostics = barrelImportStyleRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not flag imports from other relative paths", () => {
+    const code = `import { helper } from "./utils";`;
+    const context = createContext(code);
+    const diagnostics = barrelImportStyleRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("does not flag imports from packages", () => {
+    const code = `import { useState } from "react";`;
+    const context = createContext(code);
+    const diagnostics = barrelImportStyleRule.check(context);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test("reports correct line and column numbers", () => {
+    const code = `import { foo } from "./_";`;
+    const context = createContext(code);
+    const diagnostics = barrelImportStyleRule.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");
+  });
+});