@intentius/chant 0.0.1

package/src/lint/declarative.ts

@@ -0,0 +1,187 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic, LintFix, Severity, Category } from "./rule";
+import { resolveSelector } from "./selectors";
+import { getNamedCheck } from "./named-checks";
+
+/**
+ * Condition for matching nodes within a selector result.
+ */
+export interface MatchCondition {
+  /** RegExp pattern to match the node's text */
+  pattern?: RegExp;
+  /** Selector name — only match if node is within a parent matching this selector */
+  within?: string;
+  /** Require specific child selector(s) to be present */
+  require?: string | string[];
+  /** Named check to evaluate */
+  check?: string;
+}
+
+/**
+ * Declarative fix description.
+ */
+export interface DeclarativeFix {
+  /** Kind of fix operation */
+  kind: "replace" | "insert-before" | "insert-after" | "delete";
+  /** Static replacement text */
+  text?: string;
+  /** Dynamic resolve function for the replacement text */
+  resolve?: (node: ts.Node, sf: ts.SourceFile) => string;
+}
+
+/**
+ * Specification for a declarative lint rule.
+ */
+export interface RuleSpec {
+  /** Unique rule ID */
+  id: string;
+  /** Severity level */
+  severity: Severity;
+  /** Category for grouping */
+  category: Category;
+  /** Selector name (or compound) to find target nodes */
+  selector: string;
+  /** Optional match condition to further filter nodes */
+  match?: MatchCondition;
+  /** Message template. `{node}` is replaced with the node's text. */
+  message: string;
+  /** Optional fix to apply */
+  fix?: DeclarativeFix;
+  /** Optional custom validation function */
+  validate?: (node: ts.Node, context: LintContext) => boolean;
+}
+
+/**
+ * Build a standard LintRule from a declarative RuleSpec.
+ */
+export function rule(spec: RuleSpec): LintRule {
+  const selectorFn = resolveSelector(spec.selector);
+
+  return {
+    id: spec.id,
+    severity: spec.severity,
+    category: spec.category,
+    check(context: LintContext): LintDiagnostic[] {
+      const diagnostics: LintDiagnostic[] = [];
+      const sf = context.sourceFile;
+      let nodes = selectorFn(sf);
+
+      // Apply match conditions
+      if (spec.match) {
+        nodes = nodes.filter((node) => matchNode(node, spec.match!, sf, context));
+      }
+
+      // Apply custom validation
+      if (spec.validate) {
+        nodes = nodes.filter((node) => spec.validate!(node, context));
+      }
+
+      for (const node of nodes) {
+        const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+        const nodeText = node.getText(sf);
+        const message = spec.message.replace(/\{node\}/g, nodeText);
+
+        const diagnostic: LintDiagnostic = {
+          file: context.filePath,
+          line: line + 1,
+          column: character + 1,
+          ruleId: spec.id,
+          severity: spec.severity,
+          message,
+        };
+
+        if (spec.fix) {
+          diagnostic.fix = buildFix(node, spec.fix, sf);
+        }
+
+        diagnostics.push(diagnostic);
+      }
+
+      return diagnostics;
+    },
+  };
+}
+
+/**
+ * Check if a node matches the given condition.
+ */
+function matchNode(
+  node: ts.Node,
+  condition: MatchCondition,
+  sf: ts.SourceFile,
+  context: LintContext,
+): boolean {
+  // Pattern match
+  if (condition.pattern) {
+    const text = node.getText(sf);
+    if (!condition.pattern.test(text)) return false;
+  }
+
+  // Within match — node must be inside a parent matching the selector
+  if (condition.within) {
+    const parentSelector = resolveSelector(condition.within);
+    const parents = parentSelector(sf);
+    const isWithin = parents.some((parent) => isAncestorOf(parent, node));
+    if (!isWithin) return false;
+  }
+
+  // Require match — node must contain children matching the selector(s)
+  if (condition.require) {
+    const reqs = Array.isArray(condition.require) ? condition.require : [condition.require];
+    for (const req of reqs) {
+      const childSelector = resolveSelector(req);
+      const children = childSelector(sf);
+      const hasChild = children.some((child) => isAncestorOf(node, child));
+      if (!hasChild) return false;
+    }
+  }
+
+  // Named check
+  if (condition.check) {
+    const checkFn = getNamedCheck(condition.check);
+    if (!checkFn) {
+      throw new Error(`Unknown named check: "${condition.check}"`);
+    }
+    if (!checkFn(node, context)) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check if `ancestor` is an ancestor of `node`.
+ */
+function isAncestorOf(ancestor: ts.Node, node: ts.Node): boolean {
+  let current = node.parent;
+  while (current) {
+    if (current === ancestor) return true;
+    current = current.parent;
+  }
+  return false;
+}
+
+/**
+ * Build a LintFix from a declarative fix spec.
+ */
+function buildFix(node: ts.Node, fix: DeclarativeFix, sf: ts.SourceFile): LintFix {
+  const start = node.getStart(sf);
+  const end = node.getEnd();
+
+  switch (fix.kind) {
+    case "replace": {
+      const text = fix.resolve ? fix.resolve(node, sf) : (fix.text ?? "");
+      return { range: [start, end], replacement: text, kind: "replace" };
+    }
+    case "insert-before": {
+      const text = fix.resolve ? fix.resolve(node, sf) : (fix.text ?? "");
+      return { range: [start, start], replacement: text, kind: "insert-before" };
+    }
+    case "insert-after": {
+      const text = fix.resolve ? fix.resolve(node, sf) : (fix.text ?? "");
+      return { range: [end, end], replacement: text, kind: "insert-after" };
+    }
+    case "delete": {
+      return { range: [start, end], replacement: "", kind: "delete" };
+    }
+  }
+}

package/src/lint/engine.test.ts

@@ -0,0 +1,465 @@
+import { describe, test, expect } from "bun:test";
+import { runLint } from "./engine";
+import type { LintRule, LintContext, LintDiagnostic } from "./rule";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+describe("runLint", () => {
+  test("executes rules and returns diagnostics", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(testFile, "const x = 1;");
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 1,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const diagnostics = await runLint([testFile], [mockRule]);
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].ruleId).toBe("test-rule");
+      expect(diagnostics[0].message).toBe("Test error");
+    });
+  });
+
+  test("supports file-level disable comment for all rules", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable
+const x = 1;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const diagnostics = await runLint([testFile], [mockRule]);
+
+      expect(diagnostics).toHaveLength(0);
+    });
+  });
+
+  test("supports file-level disable comment for specific rules", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable test-rule-1
+const x = 1;`
+      );
+
+      const mockRule1: LintRule = {
+        id: "test-rule-1",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule-1",
+              severity: "error",
+              message: "Test error 1",
+            },
+          ];
+        },
+      };
+
+      const mockRule2: LintRule = {
+        id: "test-rule-2",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule-2",
+              severity: "error",
+              message: "Test error 2",
+            },
+          ];
+        },
+      };
+
+      const diagnostics = await runLint([testFile], [mockRule1, mockRule2]);
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].ruleId).toBe("test-rule-2");
+    });
+  });
+
+  test("supports disable-line comment", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `const x = 1; // chant-disable-line
+const y = 2;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 1,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error line 1",
+            },
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error line 2",
+            },
+          ];
+        },
+      };
+
+      const diagnostics = await runLint([testFile], [mockRule]);
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].line).toBe(2);
+    });
+  });
+
+  test("supports disable-next-line comment", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable-next-line
+const x = 1;
+const y = 2;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error line 2",
+            },
+            {
+              file: context.filePath,
+              line: 3,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error line 3",
+            },
+          ];
+        },
+      };
+
+      const diagnostics = await runLint([testFile], [mockRule]);
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].line).toBe(3);
+    });
+  });
+
+  test("supports disable-line with specific rule", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(testFile, `const x = 1; // chant-disable-line test-rule-1`);
+
+      const mockRule1: LintRule = {
+        id: "test-rule-1",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 1,
+              column: 1,
+              ruleId: "test-rule-1",
+              severity: "error",
+              message: "Test error 1",
+            },
+          ];
+        },
+      };
+
+      const mockRule2: LintRule = {
+        id: "test-rule-2",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 1,
+              column: 1,
+              ruleId: "test-rule-2",
+              severity: "error",
+              message: "Test error 2",
+            },
+          ];
+        },
+      };
+
+      const diagnostics = await runLint([testFile], [mockRule1, mockRule2]);
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].ruleId).toBe("test-rule-2");
+    });
+  });
+
+  test("ignores non-existent rule IDs in disable comments", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable non-existent-rule
+const x = 1;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const diagnostics = await runLint([testFile], [mockRule]);
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].ruleId).toBe("test-rule");
+    });
+  });
+
+  test("supports multiple disable comments for same rule", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable-next-line test-rule
+const x = 1;
+// chant-disable-next-line test-rule
+const y = 2;
+const z = 3;`
+      );
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error line 2",
+            },
+            {
+              file: context.filePath,
+              line: 4,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error line 4",
+            },
+            {
+              file: context.filePath,
+              line: 5,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error line 5",
+            },
+          ];
+        },
+      };
+
+      const diagnostics = await runLint([testFile], [mockRule]);
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].line).toBe(5);
+    });
+  });
+
+  test("processes multiple files", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile1 = join(testDir, "test1.ts");
+      const testFile2 = join(testDir, "test2.ts");
+      await writeFile(testFile1, "const x = 1;");
+      await writeFile(testFile2, "const y = 2;");
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 1,
+              column: 1,
+              ruleId: "test-rule",
+              severity: "error",
+              message: "Test error",
+            },
+          ];
+        },
+      };
+
+      const diagnostics = await runLint([testFile1, testFile2], [mockRule]);
+
+      expect(diagnostics).toHaveLength(2);
+      expect(diagnostics.map((d) => d.file).sort()).toEqual([testFile1, testFile2].sort());
+    });
+  });
+
+  test("handles parsing errors gracefully", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "invalid.ts");
+      await writeFile(testFile, "const x = ;");
+
+      const mockRule: LintRule = {
+        id: "test-rule",
+        severity: "error",
+        category: "correctness",
+        check: (): LintDiagnostic[] => {
+          return [];
+        },
+      };
+
+      const diagnostics = await runLint([testFile], [mockRule]);
+      expect(diagnostics).toHaveLength(0);
+    });
+  });
+
+  test("supports multiple rules with disable comment", async () => {
+    await withTestDir(async (testDir) => {
+      const testFile = join(testDir, "test.ts");
+      await writeFile(
+        testFile,
+        `// chant-disable test-rule-1 test-rule-2
+const x = 1;`
+      );
+
+      const mockRule1: LintRule = {
+        id: "test-rule-1",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule-1",
+              severity: "error",
+              message: "Test error 1",
+            },
+          ];
+        },
+      };
+
+      const mockRule2: LintRule = {
+        id: "test-rule-2",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule-2",
+              severity: "error",
+              message: "Test error 2",
+            },
+          ];
+        },
+      };
+
+      const mockRule3: LintRule = {
+        id: "test-rule-3",
+        severity: "error",
+        category: "correctness",
+        check: (context: LintContext): LintDiagnostic[] => {
+          return [
+            {
+              file: context.filePath,
+              line: 2,
+              column: 1,
+              ruleId: "test-rule-3",
+              severity: "error",
+              message: "Test error 3",
+            },
+          ];
+        },
+      };
+
+      const diagnostics = await runLint([testFile], [mockRule1, mockRule2, mockRule3]);
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].ruleId).toBe("test-rule-3");
+    });
+  });
+});