@intentius/chant 0.0.1

package/src/lint/engine.ts

@@ -0,0 +1,172 @@
+import type { LintRule, LintDiagnostic, LintContext, LintRunOptions } from "./rule";
+import { parseFile } from "./parser";
+import { readFileSync } from "fs";
+
+/**
+ * Represents a disable directive found in source code comments
+ */
+interface DisableDirective {
+  /** Line number where the directive appears (1-based) */
+  line: number;
+  /** Type of directive */
+  type: "file" | "line" | "next-line";
+  /** Specific rule IDs to disable, or undefined for all rules */
+  ruleIds?: string[];
+}
+
+/**
+ * Parse disable comments from source code
+ * Supports:
+ * - // chant-disable - disable all rules for entire file
+ * - // chant-disable-line - disable all rules for current line
+ * - // chant-disable-next-line - disable all rules for next line
+ * - // chant-disable rule-id1 rule-id2 - disable specific rules for file
+ * - // chant-disable-line rule-id1 - disable specific rules for line
+ * - // chant-disable-next-line rule-id1 - disable specific rules for next line
+ */
+function parseDisableComments(content: string): DisableDirective[] {
+  const directives: DisableDirective[] = [];
+  const lines = content.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNumber = i + 1;
+
+    // Match disable comments
+    const disableFileMatch = line.match(/\/\/\s*chant-disable(?:\s+(.+))?$/);
+    const disableLineMatch = line.match(/\/\/\s*chant-disable-line(?:\s+(.+))?$/);
+    const disableNextLineMatch = line.match(/\/\/\s*chant-disable-next-line(?:\s+(.+))?$/);
+
+    if (disableNextLineMatch) {
+      const ruleIds = disableNextLineMatch[1]?.trim().split(/\s+/).filter(Boolean);
+      directives.push({
+        line: lineNumber + 1, // Next line
+        type: "next-line",
+        ruleIds: ruleIds && ruleIds.length > 0 ? ruleIds : undefined,
+      });
+    } else if (disableLineMatch) {
+      const ruleIds = disableLineMatch[1]?.trim().split(/\s+/).filter(Boolean);
+      directives.push({
+        line: lineNumber,
+        type: "line",
+        ruleIds: ruleIds && ruleIds.length > 0 ? ruleIds : undefined,
+      });
+    } else if (disableFileMatch) {
+      const ruleIds = disableFileMatch[1]?.trim().split(/\s+/).filter(Boolean);
+      directives.push({
+        line: lineNumber,
+        type: "file",
+        ruleIds: ruleIds && ruleIds.length > 0 ? ruleIds : undefined,
+      });
+    }
+  }
+
+  return directives;
+}
+
+/**
+ * Check if a diagnostic should be suppressed based on disable directives
+ */
+function isDiagnosticDisabled(
+  diagnostic: LintDiagnostic,
+  directives: DisableDirective[],
+  allRuleIds: Set<string>
+): boolean {
+  // Check for file-level disables
+  const fileDisables = directives.filter((d) => d.type === "file");
+  for (const directive of fileDisables) {
+    if (!directive.ruleIds) {
+      // Disable all rules
+      return true;
+    }
+    // Check if rule ID exists before checking if it's disabled
+    if (directive.ruleIds.some((id) => allRuleIds.has(id))) {
+      if (directive.ruleIds.includes(diagnostic.ruleId)) {
+        return true;
+      }
+    }
+    // Silently ignore non-existent rule IDs
+  }
+
+  // Check for line-specific disables
+  const lineDisables = directives.filter(
+    (d) => (d.type === "line" || d.type === "next-line") && d.line === diagnostic.line
+  );
+  for (const directive of lineDisables) {
+    if (!directive.ruleIds) {
+      // Disable all rules
+      return true;
+    }
+    // Check if rule ID exists before checking if it's disabled
+    if (directive.ruleIds.some((id) => allRuleIds.has(id))) {
+      if (directive.ruleIds.includes(diagnostic.ruleId)) {
+        return true;
+      }
+    }
+    // Silently ignore non-existent rule IDs
+  }
+
+  return false;
+}
+
+/**
+ * Execute lint rules on a set of files
+ * @param files - Array of file paths to lint
+ * @param rules - Array of lint rules to execute
+ * @param ruleOptions - Optional map of rule ID to options object
+ * @returns Array of diagnostics from all rules and files, with disable comments applied
+ */
+export async function runLint(
+  files: string[],
+  rules: LintRule[],
+  ruleOptions?: Map<string, Record<string, unknown>>,
+  runOptions?: LintRunOptions,
+): Promise<LintDiagnostic[]> {
+  const allDiagnostics: LintDiagnostic[] = [];
+  const allRuleIds = new Set(rules.map((r) => r.id));
+
+  for (const filePath of files) {
+    try {
+      // Parse the file
+      const sourceFile = parseFile(filePath);
+
+      // Read file content for disable comment parsing
+      const content = readFileSync(filePath, "utf-8");
+      const directives = parseDisableComments(content);
+
+      // Create lint context
+      const context: LintContext = {
+        sourceFile,
+        entities: [],
+        filePath,
+        lexicon: undefined,
+        barrelExports: runOptions?.barrelExports,
+        projectExports: runOptions?.projectExports,
+        projectScan: runOptions?.projectScan,
+      };
+
+      // Execute each rule
+      for (const rule of rules) {
+        const options = ruleOptions?.get(rule.id);
+        const diagnostics = rule.check(context, options);
+        allDiagnostics.push(...diagnostics);
+      }
+
+      // Filter out disabled diagnostics for this file
+      const filteredDiagnostics = allDiagnostics.filter(
+        (diagnostic) => diagnostic.file === filePath && !isDiagnosticDisabled(diagnostic, directives, allRuleIds)
+      );
+
+      // Replace file diagnostics with filtered ones
+      const otherFileDiagnostics = allDiagnostics.filter((d) => d.file !== filePath);
+      allDiagnostics.length = 0;
+      allDiagnostics.push(...otherFileDiagnostics, ...filteredDiagnostics);
+    } catch (error) {
+      // If parsing fails, skip this file and continue with others
+      // In a real implementation, you might want to collect these errors
+      continue;
+    }
+  }
+
+  return allDiagnostics;
+}

package/src/lint/named-checks.test.ts

@@ -0,0 +1,37 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { registerCheck, getNamedCheck, listChecks } from "./named-checks";
+import type { LintContext } from "./rule";
+
+describe("named-checks", () => {
+  test("registerCheck and getNamedCheck", () => {
+    registerCheck("is-string-literal", (node) => ts.isStringLiteral(node));
+    const check = getNamedCheck("is-string-literal");
+    expect(check).toBeDefined();
+
+    const sf = ts.createSourceFile("test.ts", `const a = "hello";`, ts.ScriptTarget.Latest, true);
+    const ctx: LintContext = { sourceFile: sf, entities: [], filePath: "test.ts" };
+
+    // Test with a string literal node
+    let found = false;
+    ts.forEachChild(sf, function visit(node) {
+      if (ts.isStringLiteral(node)) {
+        found = check!(node, ctx);
+      }
+      ts.forEachChild(node, visit);
+    });
+    expect(found).toBe(true);
+  });
+
+  test("getNamedCheck returns undefined for unknown check", () => {
+    expect(getNamedCheck("nonexistent-check")).toBeUndefined();
+  });
+
+  test("listChecks returns registered check names", () => {
+    registerCheck("test-check-a", () => true);
+    registerCheck("test-check-b", () => false);
+    const checks = listChecks();
+    expect(checks).toContain("test-check-a");
+    expect(checks).toContain("test-check-b");
+  });
+});

package/src/lint/named-checks.ts

@@ -0,0 +1,33 @@
+import type * as ts from "typescript";
+import type { LintContext } from "./rule";
+
+/**
+ * A named check function that evaluates a condition on a node.
+ */
+export type NamedCheckFn = (node: ts.Node, context: LintContext) => boolean;
+
+/**
+ * Registry of named check functions.
+ */
+const checkRegistry = new Map<string, NamedCheckFn>();
+
+/**
+ * Register a named check function.
+ */
+export function registerCheck(name: string, fn: NamedCheckFn): void {
+  checkRegistry.set(name, fn);
+}
+
+/**
+ * Get a named check by name. Returns undefined if not found.
+ */
+export function getNamedCheck(name: string): NamedCheckFn | undefined {
+  return checkRegistry.get(name);
+}
+
+/**
+ * List all registered check names.
+ */
+export function listChecks(): string[] {
+  return Array.from(checkRegistry.keys());
+}

package/src/lint/parser.test.ts

@@ -0,0 +1,129 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { parseFile } from "./parser";
+import { writeFileSync, unlinkSync, mkdirSync } from "fs";
+import { join } from "path";
+import * as ts from "typescript";
+
+const TEST_DIR = join(import.meta.dir, "__test_parser__");
+const VALID_FILE = join(TEST_DIR, "valid.ts");
+const INVALID_FILE = join(TEST_DIR, "invalid.ts");
+const NONEXISTENT_FILE = join(TEST_DIR, "nonexistent.ts");
+
+beforeAll(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+
+  // Create a valid TypeScript file
+  writeFileSync(
+    VALID_FILE,
+    `export interface User {
+  name: string;
+  age: number;
+}
+
+export function greet(user: User): string {
+  return \`Hello, \${user.name}!\`;
+}
+`
+  );
+
+  // Create an invalid TypeScript file (syntax error)
+  writeFileSync(
+    INVALID_FILE,
+    `export interface User {
+  name: string
+  age: number // missing semicolon is ok, but let's make a real syntax error
+}
+
+export function broken( {
+  return "missing closing paren and body";
+`
+  );
+});
+
+afterAll(() => {
+  try {
+    unlinkSync(VALID_FILE);
+  } catch {}
+  try {
+    unlinkSync(INVALID_FILE);
+  } catch {}
+  try {
+    unlinkSync(NONEXISTENT_FILE);
+  } catch {}
+});
+
+describe("parseFile", () => {
+  test("parses valid TypeScript file and returns SourceFile", () => {
+    const sourceFile = parseFile(VALID_FILE);
+
+    expect(sourceFile).toBeDefined();
+    expect(sourceFile.fileName).toBe(VALID_FILE);
+    expect(sourceFile.kind).toBe(ts.SyntaxKind.SourceFile);
+  });
+
+  test("returns SourceFile with expected structure", () => {
+    const sourceFile = parseFile(VALID_FILE);
+
+    // Should have statements (interface and function declarations)
+    expect(sourceFile.statements.length).toBeGreaterThan(0);
+
+    // First statement should be interface declaration
+    const firstStatement = sourceFile.statements[0];
+    expect(firstStatement.kind).toBe(ts.SyntaxKind.InterfaceDeclaration);
+
+    // Second statement should be function declaration
+    const secondStatement = sourceFile.statements[1];
+    expect(secondStatement.kind).toBe(ts.SyntaxKind.FunctionDeclaration);
+  });
+
+  test("sets parent nodes correctly", () => {
+    const sourceFile = parseFile(VALID_FILE);
+
+    // Check that parent nodes are set
+    const firstStatement = sourceFile.statements[0];
+    expect(firstStatement.parent).toBe(sourceFile);
+  });
+
+  test("throws clear error for invalid TypeScript", () => {
+    expect(() => parseFile(INVALID_FILE)).toThrow("TypeScript parsing failed");
+  });
+
+  test("throws error with file location for syntax errors", () => {
+    try {
+      parseFile(INVALID_FILE);
+      expect.unreachable("Should have thrown an error");
+    } catch (err) {
+      expect(err).toBeInstanceOf(Error);
+      const error = err as Error;
+      expect(error.message).toContain(INVALID_FILE);
+      expect(error.message).toContain("TypeScript parsing failed");
+    }
+  });
+
+  test("throws clear error when file does not exist", () => {
+    expect(() => parseFile(NONEXISTENT_FILE)).toThrow("Failed to read file");
+    expect(() => parseFile(NONEXISTENT_FILE)).toThrow(NONEXISTENT_FILE);
+  });
+
+  test("handles empty file", () => {
+    const emptyFile = join(TEST_DIR, "empty.ts");
+    writeFileSync(emptyFile, "");
+
+    const sourceFile = parseFile(emptyFile);
+    expect(sourceFile).toBeDefined();
+    expect(sourceFile.statements.length).toBe(0);
+
+    unlinkSync(emptyFile);
+  });
+
+  test("handles file with only comments", () => {
+    const commentsFile = join(TEST_DIR, "comments.ts");
+    writeFileSync(commentsFile, "// Just a comment\n/* Another comment */");
+
+    const sourceFile = parseFile(commentsFile);
+    expect(sourceFile).toBeDefined();
+    expect(sourceFile.statements.length).toBe(0);
+
+    unlinkSync(commentsFile);
+  });
+});

package/src/lint/parser.ts

@@ -0,0 +1,42 @@
+import * as ts from "typescript";
+import { readFileSync } from "fs";
+
+/**
+ * Parse a TypeScript file into an AST
+ * @param path - Absolute or relative path to the TypeScript file
+ * @returns Parsed TypeScript SourceFile
+ * @throws Error if the file cannot be read or parsed
+ */
+export function parseFile(path: string): ts.SourceFile {
+  let content: string;
+
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch (err) {
+    throw new Error(`Failed to read file ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const sourceFile = ts.createSourceFile(
+    path,
+    content,
+    ts.ScriptTarget.Latest,
+    true // setParentNodes
+  );
+
+  // Check for syntax errors (parseDiagnostics is internal but accessible)
+  const diagnostics = [
+    ...(sourceFile as unknown as { parseDiagnostics: ts.DiagnosticWithLocation[] }).parseDiagnostics,
+  ];
+
+  if (diagnostics.length > 0) {
+    const errors = diagnostics
+      .map((d) => {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(d.start ?? 0);
+        return `${path}:${line + 1}:${character + 1} - ${ts.flattenDiagnosticMessageText(d.messageText, "\n")}`;
+      })
+      .join("\n");
+    throw new Error(`TypeScript parsing failed:\n${errors}`);
+  }
+
+  return sourceFile;
+}

package/src/lint/post-synth.test.ts

@@ -0,0 +1,113 @@
+import { describe, test, expect } from "bun:test";
+import { runPostSynthChecks } from "./post-synth";
+import type { PostSynthCheck, PostSynthContext } from "./post-synth";
+
+function createBuildResult(overrides: Partial<PostSynthContext["buildResult"]> = {}) {
+  return {
+    outputs: new Map<string, string>(),
+    entities: new Map(),
+    warnings: [] as string[],
+    errors: [] as Array<{ message: string; name: string }>,
+    sourceFileCount: 0,
+    ...overrides,
+  };
+}
+
+describe("post-synth checks", () => {
+  test("runs check and collects diagnostics", () => {
+    const check: PostSynthCheck = {
+      id: "PS001",
+      description: "Check for empty outputs",
+      check(ctx) {
+        if (ctx.outputs.size === 0) {
+          return [{ checkId: "PS001", severity: "warning", message: "No outputs produced" }];
+        }
+        return [];
+      },
+    };
+
+    const result = createBuildResult();
+    const diags = runPostSynthChecks([check], result);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("PS001");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toBe("No outputs produced");
+  });
+
+  test("returns empty when no issues found", () => {
+    const check: PostSynthCheck = {
+      id: "PS002",
+      description: "Always passes",
+      check() {
+        return [];
+      },
+    };
+
+    const diags = runPostSynthChecks([check], createBuildResult());
+    expect(diags).toHaveLength(0);
+  });
+
+  test("aggregates diagnostics from multiple checks", () => {
+    const checks: PostSynthCheck[] = [
+      {
+        id: "PS003A",
+        description: "Check A",
+        check() {
+          return [{ checkId: "PS003A", severity: "error", message: "Error A" }];
+        },
+      },
+      {
+        id: "PS003B",
+        description: "Check B",
+        check() {
+          return [
+            { checkId: "PS003B", severity: "warning", message: "Warning B1" },
+            { checkId: "PS003B", severity: "info", message: "Info B2" },
+          ];
+        },
+      },
+    ];
+
+    const diags = runPostSynthChecks(checks, createBuildResult());
+    expect(diags).toHaveLength(3);
+    expect(diags[0].checkId).toBe("PS003A");
+    expect(diags[1].checkId).toBe("PS003B");
+    expect(diags[2].checkId).toBe("PS003B");
+  });
+
+  test("provides entities and outputs in context", () => {
+    const entities = new Map([["myBucket", { kind: "resource" }]]);
+    const outputs = new Map([["aws", '{"AWSTemplateFormatVersion":"2010-09-09"}']]);
+
+    const check: PostSynthCheck = {
+      id: "PS004",
+      description: "Check entities",
+      check(ctx) {
+        const diags = [];
+        for (const [name] of ctx.entities) {
+          diags.push({
+            checkId: "PS004",
+            severity: "info" as const,
+            message: `Found entity: ${name}`,
+            entity: name,
+            lexicon: "aws",
+          });
+        }
+        return diags;
+      },
+    };
+
+    const diags = runPostSynthChecks(
+      [check],
+      createBuildResult({ entities: entities as never, outputs }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("myBucket");
+    expect(diags[0].lexicon).toBe("aws");
+  });
+
+  test("handles empty check list", () => {
+    const diags = runPostSynthChecks([], createBuildResult());
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth.ts

@@ -0,0 +1,76 @@
+import type { Declarable } from "../declarable";
+import type { SerializerResult } from "../serializer";
+import type { Severity } from "./rule";
+
+/**
+ * Context provided to post-synthesis checks.
+ */
+export interface PostSynthContext {
+  /** The build result outputs (lexicon name → serialized output) */
+  outputs: Map<string, string | SerializerResult>;
+  /** Map of entity name to Declarable entity */
+  entities: Map<string, Declarable>;
+  /** Raw build result object */
+  buildResult: {
+    outputs: Map<string, string | SerializerResult>;
+    entities: Map<string, Declarable>;
+    warnings: string[];
+    errors: Array<{ message: string; name: string }>;
+    sourceFileCount: number;
+  };
+}
+
+/**
+ * Extract the primary content string from a serializer output.
+ */
+export function getPrimaryOutput(output: string | SerializerResult): string {
+  return typeof output === "string" ? output : output.primary;
+}
+
+/**
+ * A diagnostic from a post-synthesis check.
+ */
+export interface PostSynthDiagnostic {
+  /** ID of the check that produced this diagnostic */
+  checkId: string;
+  /** Severity level */
+  severity: Severity;
+  /** Human-readable message */
+  message: string;
+  /** Optional entity name related to this diagnostic */
+  entity?: string;
+  /** Optional lexicon related to this diagnostic */
+  lexicon?: string;
+}
+
+/**
+ * A post-synthesis check that validates build output.
+ */
+export interface PostSynthCheck {
+  /** Unique identifier for this check */
+  id: string;
+  /** Human-readable description */
+  description: string;
+  /** Execute the check and return diagnostics */
+  check(ctx: PostSynthContext): PostSynthDiagnostic[];
+}
+
+/**
+ * Run a set of post-synthesis checks against a build result.
+ */
+export function runPostSynthChecks(
+  checks: PostSynthCheck[],
+  buildResult: PostSynthContext["buildResult"],
+): PostSynthDiagnostic[] {
+  const ctx: PostSynthContext = {
+    outputs: buildResult.outputs,
+    entities: buildResult.entities,
+    buildResult,
+  };
+
+  const diagnostics: PostSynthDiagnostic[] = [];
+  for (const check of checks) {
+    diagnostics.push(...check.check(ctx));
+  }
+  return diagnostics;
+}

package/src/lint/presets/relaxed.json

@@ -0,0 +1,19 @@
+{
+  "rules": {
+    "COR001": "warning",
+    "COR002": "off",
+    "COR003": "off",
+    "COR004": "off",
+    "COR005": "off",
+    "COR006": "off",
+    "COR007": "off",
+    "COR008": "warning",
+    "COR009": "off",
+    "COR010": "warning",
+    "COR011": "warning",
+    "COR012": "off",
+    "COR013": "off",
+    "COR014": "off",
+    "COR015": "off"
+  }
+}

package/src/lint/presets/strict.json

@@ -0,0 +1,19 @@
+{
+  "rules": {
+    "COR001": "error",
+    "COR002": "error",
+    "COR003": "warning",
+    "COR004": "warning",
+    "COR005": "warning",
+    "COR006": "error",
+    "COR007": "warning",
+    "COR008": "error",
+    "COR009": "warning",
+    "COR010": "warning",
+    "COR011": "error",
+    "COR012": "warning",
+    "COR013": "info",
+    "COR014": "warning",
+    "COR015": "warning"
+  }
+}