@intentius/chant 0.0.1

package/src/lint/config.ts

@@ -0,0 +1,375 @@
+import { readFileSync, existsSync } from "fs";
+import { join, dirname, resolve } from "path";
+import { z } from "zod";
+import type { Severity, RuleConfig } from "./rule";
+import strictPreset from "./presets/strict.json";
+
+/** Mapping of built-in preset names to their file paths */
+const BUILTIN_PRESETS: Record<string, string> = {
+  "@intentius/chant/lint/presets/strict": resolve(import.meta.dir, "presets/strict.json"),
+  "@intentius/chant/lint/presets/relaxed": resolve(import.meta.dir, "presets/relaxed.json"),
+};
+
+// ── Zod schemas for lint config validation ─────────────────────────
+
+const SeveritySchema = z.enum(["off", "error", "warning", "info"]);
+
+const RuleConfigSchema = z.union([
+  SeveritySchema,
+  z.tuple([SeveritySchema, z.record(z.string(), z.unknown())]),
+]);
+
+export const LintConfigSchema = z.object({
+  rules: z.record(z.string(), RuleConfigSchema).optional(),
+  extends: z.array(z.string()).optional(),
+  overrides: z.array(z.object({
+    files: z.array(z.string()),
+    rules: z.record(z.string(), RuleConfigSchema),
+  })).optional(),
+  plugins: z.array(z.string()).optional(),
+});
+
+/**
+ * Check if a Zod union error is specifically about an invalid severity string
+ * (as opposed to a completely wrong type like a number).
+ */
+function isBadSeverityError(issue: z.ZodIssue, config: unknown, path: readonly (string | number)[]): string | null {
+  if (issue.code !== "invalid_union") return null;
+
+  // Navigate to the value in the config to see what was actually provided
+  let value: unknown = config;
+  for (const key of path) {
+    if (value == null || typeof value !== "object") return null;
+    value = (value as any)[key];
+  }
+
+  // If the value is a string, the user meant it as a severity — show the specific severity error
+  if (typeof value === "string") {
+    return value;
+  }
+  return null;
+}
+
+/**
+ * Format a Zod error into a human-readable message matching existing error patterns.
+ */
+function formatLintConfigError(configPath: string, error: z.ZodError, rawConfig: unknown): string {
+  const issue = error.issues[0];
+  const path = issue.path;
+
+  // Cast path to (string | number)[] — Zod's path is PropertyKey[] but only uses string | number
+  const p = path as (string | number)[];
+
+  // rules.{ruleId} — invalid severity or structure
+  if (p[0] === "rules" && p.length >= 2) {
+    const ruleId = p[1];
+    const badValue = isBadSeverityError(issue, rawConfig, p);
+    if (badValue !== null) {
+      return `Invalid config file ${configPath}: rule "${ruleId}" has invalid severity "${badValue}". Must be "off", "error", "warning", or "info"`;
+    }
+    return `Invalid config file ${configPath}: rule "${ruleId}" must be a severity string or [severity, options] tuple`;
+  }
+
+  // rules — wrong type
+  if (p[0] === "rules" && p.length === 1) {
+    return `Invalid config file ${configPath}: rules must be an object`;
+  }
+
+  // extends — wrong type or element type
+  if (p[0] === "extends") {
+    if (p.length === 1) {
+      return `Invalid config file ${configPath}: extends must be an array`;
+    }
+    return `Invalid config file ${configPath}: extends must be an array of strings`;
+  }
+
+  // overrides[i].* errors
+  if (p[0] === "overrides") {
+    if (p.length === 1) {
+      return `Invalid config file ${configPath}: overrides must be an array`;
+    }
+    const i = p[1];
+    if (p.length === 2) {
+      return `Invalid config file ${configPath}: overrides[${i}] must be an object`;
+    }
+    if (p[2] === "files") {
+      if (p.length === 3) {
+        return `Invalid config file ${configPath}: overrides[${i}].files must be an array`;
+      }
+      return `Invalid config file ${configPath}: overrides[${i}].files must be an array of strings`;
+    }
+    if (p[2] === "rules") {
+      if (p.length === 3) {
+        return `Invalid config file ${configPath}: overrides[${i}].rules must be an object`;
+      }
+      if (p.length >= 4) {
+        const ruleId = p[3];
+        const badValue = isBadSeverityError(issue, rawConfig, p);
+        if (badValue !== null) {
+          return `Invalid config file ${configPath}: overrides[${i}] rule "${ruleId}" has invalid severity "${badValue}". Must be "off", "error", "warning", or "info"`;
+        }
+        return `Invalid config file ${configPath}: overrides[${i}] rule "${ruleId}" must be a severity string or [severity, options] tuple`;
+      }
+    }
+  }
+
+  // plugins — wrong type or element type
+  if (p[0] === "plugins") {
+    if (p.length === 1) {
+      return `Invalid config file ${configPath}: plugins must be an array`;
+    }
+    return `Invalid config file ${configPath}: plugins must be an array of strings`;
+  }
+
+  // Fallback
+  return `Invalid config file ${configPath}: ${issue.message}`;
+}
+
+/**
+ * Per-file rule override
+ */
+export interface LintOverride {
+  /** Glob patterns to match file paths */
+  files: string[];
+  /** Rule overrides for matched files */
+  rules: Record<string, RuleConfig>;
+}
+
+/**
+ * Lint configuration
+ */
+export interface LintConfig {
+  /** Rule configurations: rule ID -> severity string or [severity, options] tuple */
+  rules?: Record<string, RuleConfig>;
+  /** Array of config file paths to extend from */
+  extends?: string[];
+  /** Per-file rule overrides via glob patterns */
+  overrides?: LintOverride[];
+  /** Array of plugin file paths to load custom rules from (project-local, not inherited) */
+  plugins?: string[];
+}
+
+/**
+ * Parsed rule configuration with severity and optional options
+ */
+export interface ParsedRuleConfig {
+  severity: "off" | Severity;
+  options?: Record<string, unknown>;
+}
+
+/**
+ * Parse a rule config value into severity and options
+ */
+export function parseRuleConfig(value: RuleConfig): ParsedRuleConfig {
+  if (typeof value === "string") {
+    return { severity: value as "off" | Severity };
+  }
+
+  if (!Array.isArray(value) || value.length !== 2) {
+    throw new Error(`Invalid rule config: expected a severity string or [severity, options] tuple`);
+  }
+
+  const [severity, options] = value;
+
+  if (typeof severity !== "string" || !isValidSeverity(severity)) {
+    throw new Error(
+      `Invalid rule config: severity "${severity}" must be "off", "error", "warning", or "info"`
+    );
+  }
+
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    throw new Error(`Invalid rule config: options must be a plain object`);
+  }
+
+  return { severity, options };
+}
+
+/**
+ * Default configuration with all rules enabled at strict preset severities
+ */
+export const DEFAULT_CONFIG: LintConfig = {
+  rules: { ...strictPreset.rules } as Record<string, RuleConfig>,
+  extends: [],
+};
+
+/**
+ * Validate that a severity string is valid
+ */
+function isValidSeverity(value: string): value is "off" | Severity {
+  return value === "off" || value === "error" || value === "warning" || value === "info";
+}
+
+/**
+ * Load and merge a single config file
+ */
+function loadConfigFile(configPath: string, visited: Set<string> = new Set()): LintConfig {
+  // Check for circular extends
+  if (visited.has(configPath)) {
+    throw new Error(`Circular extends detected: ${configPath}`);
+  }
+  visited.add(configPath);
+
+  // Read and parse config file
+  if (!existsSync(configPath)) {
+    throw new Error(`Config file not found: ${configPath}`);
+  }
+
+  let content: string;
+  try {
+    content = readFileSync(configPath, "utf-8");
+  } catch (err) {
+    throw new Error(`Failed to read config file ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  let config: LintConfig;
+  try {
+    config = JSON.parse(content);
+  } catch (err) {
+    throw new Error(`Failed to parse config file ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  // Validate config structure
+  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+    throw new Error(`Invalid config file ${configPath}: must be an object`);
+  }
+
+  // Validate with Zod schema
+  const parseResult = LintConfigSchema.safeParse(config);
+  if (!parseResult.success) {
+    throw new Error(formatLintConfigError(configPath, parseResult.error, config));
+  }
+
+  // Process extends
+  let mergedConfig: LintConfig = { rules: {}, extends: [] };
+
+  if (config.extends && config.extends.length > 0) {
+    const baseDir = dirname(configPath);
+
+    for (const extendPath of config.extends) {
+      // Resolve paths: relative, built-in preset, or absolute
+      let resolvedPath: string;
+      if (extendPath.startsWith(".")) {
+        resolvedPath = join(baseDir, extendPath);
+      } else if (extendPath.startsWith("@intentius/chant")) {
+        const builtinPath = BUILTIN_PRESETS[extendPath];
+        if (builtinPath) {
+          resolvedPath = builtinPath;
+        } else {
+          throw new Error(`Unknown preset: ${extendPath} (extended from ${configPath})`);
+        }
+      } else {
+        resolvedPath = extendPath;
+      }
+
+      // Check if extended config exists
+      if (!existsSync(resolvedPath)) {
+        throw new Error(`Extended config file not found: ${resolvedPath} (extended from ${configPath})`);
+      }
+
+      // Load extended config recursively
+      const extendedConfig = loadConfigFile(resolvedPath, visited);
+
+      // Merge rules (later configs override earlier ones)
+      mergedConfig.rules = {
+        ...mergedConfig.rules,
+        ...extendedConfig.rules,
+      };
+    }
+  }
+
+  // Merge current config rules on top
+  mergedConfig.rules = {
+    ...mergedConfig.rules,
+    ...config.rules,
+  };
+
+  // Preserve overrides from the current config
+  if (config.overrides) {
+    mergedConfig.overrides = config.overrides;
+  }
+
+  // Preserve plugins from the current config only (not inherited from extends)
+  if (config.plugins) {
+    mergedConfig.plugins = config.plugins;
+  }
+
+  return mergedConfig;
+}
+
+/**
+ * Load lint configuration from a directory.
+ *
+ * Tries `chant.config.ts` first (extracts `lint` property from ChantConfig),
+ * then falls back to `chant.config.json` (legacy LintConfig format).
+ * Returns default configuration if neither exists.
+ *
+ * @param dir - Directory path to search for config file
+ * @returns Loaded and merged configuration, or default config if not found
+ */
+export function loadConfig(dir: string): LintConfig {
+  // Try chant.config.ts first — Bun supports synchronous require() for .ts
+  const tsConfigPath = join(dir, "chant.config.ts");
+  if (existsSync(tsConfigPath)) {
+    try {
+      const mod = require(tsConfigPath);
+      const config = mod.default ?? mod.config ?? mod;
+      if (typeof config === "object" && config !== null) {
+        // ChantConfig format: extract lint property
+        if ("lint" in config && typeof config.lint === "object") {
+          return config.lint as LintConfig;
+        }
+        // Bare rules at top level
+        if ("rules" in config) {
+          return config as LintConfig;
+        }
+        // Config exists but has no lint section — use defaults
+        return DEFAULT_CONFIG;
+      }
+    } catch {
+      // Fall through to JSON
+    }
+  }
+
+  // Fall back to chant.config.json
+  const jsonConfigPath = join(dir, "chant.config.json");
+  if (!existsSync(jsonConfigPath)) {
+    return DEFAULT_CONFIG;
+  }
+
+  try {
+    return loadConfigFile(jsonConfigPath);
+  } catch (error) {
+    throw error;
+  }
+}
+
+/**
+ * Resolve the effective rules for a specific file path by applying overrides.
+ *
+ * Starts with the base config rules, then iterates through overrides in order.
+ * For each override whose file globs match the given path, merges override rules on top.
+ *
+ * @param config - The loaded lint configuration
+ * @param filePath - The file path to resolve rules for (relative to project root)
+ * @returns Merged rule configuration with overrides applied
+ */
+export function resolveRulesForFile(config: LintConfig, filePath: string): Record<string, RuleConfig> {
+  const rules: Record<string, RuleConfig> = { ...config.rules };
+
+  if (!config.overrides) {
+    return rules;
+  }
+
+  for (const override of config.overrides) {
+    const matches = override.files.some((pattern) => {
+      const glob = new Bun.Glob(pattern);
+      return glob.match(filePath);
+    });
+
+    if (matches) {
+      Object.assign(rules, override.rules);
+    }
+  }
+
+  return rules;
+}

package/src/lint/declarative.test.ts

@@ -0,0 +1,256 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { rule } from "./declarative";
+import type { RuleSpec } from "./declarative";
+import type { LintContext } from "./rule";
+import { registerCheck } from "./named-checks";
+
+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("declarative rule()", () => {
+  test("creates a rule with correct metadata", () => {
+    const spec: RuleSpec = {
+      id: "TEST001",
+      severity: "warning",
+      category: "style",
+      selector: "string-literal",
+      message: "Found a string literal",
+    };
+    const r = rule(spec);
+    expect(r.id).toBe("TEST001");
+    expect(r.severity).toBe("warning");
+    expect(r.category).toBe("style");
+  });
+
+  test("reports diagnostics for matching nodes", () => {
+    const spec: RuleSpec = {
+      id: "TEST002",
+      severity: "error",
+      category: "correctness",
+      selector: "string-literal",
+      message: "No string literals allowed",
+    };
+    const r = rule(spec);
+    const ctx = createContext(`const a = "hello"; const b = "world";`);
+    const diags = r.check(ctx);
+    expect(diags).toHaveLength(2);
+    expect(diags[0].ruleId).toBe("TEST002");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toBe("No string literals allowed");
+  });
+
+  test("returns no diagnostics when nothing matches", () => {
+    const spec: RuleSpec = {
+      id: "TEST003",
+      severity: "warning",
+      category: "style",
+      selector: "resource",
+      message: "Found a resource",
+    };
+    const r = rule(spec);
+    const ctx = createContext(`const a = 42;`);
+    expect(r.check(ctx)).toHaveLength(0);
+  });
+
+  test("message template replaces {node}", () => {
+    const spec: RuleSpec = {
+      id: "TEST004",
+      severity: "info",
+      category: "style",
+      selector: "string-literal",
+      message: "Found: {node}",
+    };
+    const r = rule(spec);
+    const ctx = createContext(`const a = "hello";`);
+    const diags = r.check(ctx);
+    expect(diags[0].message).toBe('Found: "hello"');
+  });
+
+  test("match.pattern filters by regex", () => {
+    const spec: RuleSpec = {
+      id: "TEST005",
+      severity: "warning",
+      category: "style",
+      selector: "string-literal",
+      match: { pattern: /world/ },
+      message: "Found world",
+    };
+    const r = rule(spec);
+    const ctx = createContext(`const a = "hello"; const b = "world";`);
+    const diags = r.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toBe("Found world");
+  });
+
+  test("match.check uses named check", () => {
+    registerCheck("always-true", () => true);
+    registerCheck("always-false", () => false);
+
+    const specTrue: RuleSpec = {
+      id: "TEST006A",
+      severity: "warning",
+      category: "style",
+      selector: "string-literal",
+      match: { check: "always-true" },
+      message: "matches",
+    };
+    const specFalse: RuleSpec = {
+      id: "TEST006B",
+      severity: "warning",
+      category: "style",
+      selector: "string-literal",
+      match: { check: "always-false" },
+      message: "no match",
+    };
+
+    const ctx = createContext(`const a = "hello";`);
+    expect(rule(specTrue).check(ctx)).toHaveLength(1);
+    expect(rule(specFalse).check(ctx)).toHaveLength(0);
+  });
+
+  test("validate function filters nodes", () => {
+    const spec: RuleSpec = {
+      id: "TEST007",
+      severity: "warning",
+      category: "style",
+      selector: "string-literal",
+      message: "Found string",
+      validate: (node, _ctx) => {
+        return ts.isStringLiteral(node) && node.text === "keep";
+      },
+    };
+    const r = rule(spec);
+    const ctx = createContext(`const a = "keep"; const b = "skip";`);
+    const diags = r.check(ctx);
+    expect(diags).toHaveLength(1);
+  });
+
+  test("fix with replace kind", () => {
+    const spec: RuleSpec = {
+      id: "TEST008",
+      severity: "warning",
+      category: "style",
+      selector: "string-literal",
+      message: "Replace string",
+      fix: { kind: "replace", text: '"replaced"' },
+    };
+    const r = rule(spec);
+    const ctx = createContext(`const a = "hello";`);
+    const diags = r.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].fix).toBeDefined();
+    expect(diags[0].fix!.replacement).toBe('"replaced"');
+    expect(diags[0].fix!.kind).toBe("replace");
+  });
+
+  test("fix with delete kind", () => {
+    const spec: RuleSpec = {
+      id: "TEST009",
+      severity: "warning",
+      category: "style",
+      selector: "string-literal",
+      message: "Delete string",
+      fix: { kind: "delete" },
+    };
+    const r = rule(spec);
+    const ctx = createContext(`const a = "hello";`);
+    const diags = r.check(ctx);
+    expect(diags[0].fix!.replacement).toBe("");
+    expect(diags[0].fix!.kind).toBe("delete");
+  });
+
+  test("fix with resolve function", () => {
+    const spec: RuleSpec = {
+      id: "TEST010",
+      severity: "warning",
+      category: "style",
+      selector: "string-literal",
+      message: "Transform string",
+      fix: {
+        kind: "replace",
+        resolve: (node, sf) => `"${(node as ts.StringLiteral).text.toUpperCase()}"`,
+      },
+    };
+    const r = rule(spec);
+    const ctx = createContext(`const a = "hello";`);
+    const diags = r.check(ctx);
+    expect(diags[0].fix!.replacement).toBe('"HELLO"');
+  });
+
+  test("correct line and column positions", () => {
+    const code = [
+      `const x = 1;`,
+      `const a = "target";`,
+      `const y = 2;`,
+    ].join("\n");
+    const spec: RuleSpec = {
+      id: "TEST011",
+      severity: "warning",
+      category: "style",
+      selector: "string-literal",
+      message: "Found",
+    };
+    const r = rule(spec);
+    const ctx = createContext(code);
+    const diags = r.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].line).toBe(2);
+    expect(diags[0].file).toBe("test.ts");
+  });
+
+  test("produces same diagnostics as equivalent imperative rule", () => {
+    // Declarative version
+    const declarativeRule = rule({
+      id: "CMP001",
+      severity: "warning",
+      category: "correctness",
+      selector: "resource",
+      message: "Found resource instantiation: {node}",
+    });
+
+    // Imperative equivalent
+    const imperativeRule = {
+      id: "CMP001",
+      severity: "warning" as const,
+      category: "correctness" as const,
+      check(context: LintContext) {
+        const diagnostics: { file: string; line: number; column: number; ruleId: string; severity: "warning"; message: string }[] = [];
+        const sf = context.sourceFile;
+        function visit(node: ts.Node) {
+          if (ts.isNewExpression(node)) {
+            const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+            diagnostics.push({
+              file: context.filePath,
+              line: line + 1,
+              column: character + 1,
+              ruleId: "CMP001",
+              severity: "warning",
+              message: `Found resource instantiation: ${node.getText(sf)}`,
+            });
+          }
+          ts.forEachChild(node, visit);
+        }
+        visit(sf);
+        return diagnostics;
+      },
+    };
+
+    const code = `const b = new Bucket({ name: "test" });\nconst t = new Table({});`;
+    const ctx = createContext(code);
+
+    const declDiags = declarativeRule.check(ctx);
+    const impDiags = imperativeRule.check(ctx);
+
+    expect(declDiags).toHaveLength(impDiags.length);
+    for (let i = 0; i < declDiags.length; i++) {
+      expect(declDiags[i].ruleId).toBe(impDiags[i].ruleId);
+      expect(declDiags[i].severity).toBe(impDiags[i].severity);
+      expect(declDiags[i].line).toBe(impDiags[i].line);
+      expect(declDiags[i].column).toBe(impDiags[i].column);
+      expect(declDiags[i].message).toBe(impDiags[i].message);
+    }
+  });
+});