@intentius/chant 0.0.8 → 0.0.9

package/src/cli/reporters/stylish.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { formatStylish, formatSummary, formatJson, formatSarif } from "./stylish";
-import type { LintDiagnostic } from "../../lint/rule";
+import type { LintDiagnostic, LintRule } from "../../lint/rule";
 
 describe("formatStylish", () => {
   const originalNoColor = process.env.NO_COLOR;
@@ -279,4 +279,215 @@ describe("formatSarif", () => {
     // Should have 2 unique rules
     expect(parsed.runs[0].tool.driver.rules).toHaveLength(2);
   });
+
+  test("enriches rules with descriptions when LintRule objects are provided", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Issue",
+      },
+    ];
+
+    const rules: LintRule[] = [
+      {
+        id: "COR001",
+        severity: "warning",
+        category: "style",
+        description: "No inline objects in Declarable constructors",
+        check: () => [],
+      },
+    ];
+
+    const result = formatSarif(diagnostics, rules);
+    const parsed = JSON.parse(result);
+    const sarifRule = parsed.runs[0].tool.driver.rules[0];
+
+    expect(sarifRule.shortDescription.text).toBe("No inline objects in Declarable constructors");
+    expect(sarifRule.fullDescription.text).toBe("No inline objects in Declarable constructors");
+    expect(sarifRule.helpUri).toContain("cor001");
+    expect(sarifRule.defaultConfiguration.level).toBe("warning");
+    expect(sarifRule.properties.category).toBe("style");
+  });
+
+  test("includes fingerprints in results", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 10,
+        column: 5,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Something",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+
+    expect(parsed.runs[0].results[0].fingerprints).toBeDefined();
+    expect(parsed.runs[0].results[0].fingerprints["chant/v1"]).toBe("COR001:test.ts:10:5");
+  });
+
+  test("includes ruleIndex in results", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Issue",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+
+    expect(parsed.runs[0].results[0].ruleIndex).toBe(0);
+  });
+
+  test("includes endLine/endColumn when provided", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 10,
+        column: 5,
+        endLine: 12,
+        endColumn: 20,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Something",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+    const region = parsed.runs[0].results[0].locations[0].physicalLocation.region;
+
+    expect(region.startLine).toBe(10);
+    expect(region.startColumn).toBe(5);
+    expect(region.endLine).toBe(12);
+    expect(region.endColumn).toBe(20);
+  });
+
+  test("omits endLine/endColumn when not provided", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 10,
+        column: 5,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Something",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+    const region = parsed.runs[0].results[0].locations[0].physicalLocation.region;
+
+    expect(region.endLine).toBeUndefined();
+    expect(region.endColumn).toBeUndefined();
+  });
+
+  test("includes suppressed diagnostics with suppressions array", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Active issue",
+      },
+    ];
+
+    const suppressed: Array<LintDiagnostic & { reason?: string }> = [
+      {
+        file: "test.ts",
+        line: 5,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Suppressed issue",
+        reason: "backwards compat",
+      },
+    ];
+
+    const result = formatSarif(diagnostics, undefined, suppressed);
+    const parsed = JSON.parse(result);
+
+    // Should have 2 results total (1 active + 1 suppressed)
+    expect(parsed.runs[0].results).toHaveLength(2);
+
+    // First result: no suppressions
+    expect(parsed.runs[0].results[0].suppressions).toBeUndefined();
+
+    // Second result: has suppressions
+    expect(parsed.runs[0].results[1].suppressions).toHaveLength(1);
+    expect(parsed.runs[0].results[1].suppressions[0].kind).toBe("inSource");
+    expect(parsed.runs[0].results[1].suppressions[0].justification).toBe("backwards compat");
+  });
+
+  test("suppressed diagnostics without reason omit justification", () => {
+    const suppressed: Array<LintDiagnostic & { reason?: string }> = [
+      {
+        file: "test.ts",
+        line: 5,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Suppressed issue",
+      },
+    ];
+
+    const result = formatSarif([], undefined, suppressed);
+    const parsed = JSON.parse(result);
+
+    expect(parsed.runs[0].results[0].suppressions[0].kind).toBe("inSource");
+    expect(parsed.runs[0].results[0].suppressions[0].justification).toBeUndefined();
+  });
+
+  test("falls back to rule ID when no description available", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "UNKNOWN",
+        severity: "warning",
+        message: "Issue",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+    const sarifRule = parsed.runs[0].tool.driver.rules[0];
+
+    expect(sarifRule.shortDescription.text).toBe("UNKNOWN");
+    expect(sarifRule.helpUri).toContain("unknown");
+  });
+
+  test("converts absolute file paths to file:// URIs", () => {
+    const diagnostics: LintDiagnostic[] = [
+      {
+        file: "/Users/test/project/test.ts",
+        line: 1,
+        column: 1,
+        ruleId: "COR001",
+        severity: "warning",
+        message: "Issue",
+      },
+    ];
+
+    const result = formatSarif(diagnostics);
+    const parsed = JSON.parse(result);
+    const uri = parsed.runs[0].results[0].locations[0].physicalLocation.artifactLocation.uri;
+
+    expect(uri).toMatch(/^file:\/\//);
+  });
 });

package/src/cli/reporters/stylish.ts

@@ -1,4 +1,5 @@
-import type { LintDiagnostic } from "../../lint/rule";
+import type { LintDiagnostic, LintRule, Severity } from "../../lint/rule";
+import { pathToFileURL } from "node:url";
 
 /**
  * ANSI color codes
@@ -121,10 +122,90 @@ export function formatJson(diagnostics: LintDiagnostic[]): string {
   return JSON.stringify(diagnostics, null, 2);
 }
 
+/**
+ * Map lint severity to SARIF level
+ */
+function mapSeverity(severity: Severity): "error" | "warning" | "note" {
+  if (severity === "error") return "error";
+  if (severity === "warning") return "warning";
+  return "note";
+}
+
+/**
+ * Build a SARIF region object, only including endLine/endColumn when available
+ */
+function buildRegion(diag: LintDiagnostic): Record<string, number> {
+  const region: Record<string, number> = {
+    startLine: diag.line,
+    startColumn: diag.column,
+  };
+  if (diag.endLine !== undefined) region.endLine = diag.endLine;
+  if (diag.endColumn !== undefined) region.endColumn = diag.endColumn;
+  return region;
+}
+
+/**
+ * Build a SARIF result from a diagnostic
+ */
+function buildSarifResult(diag: LintDiagnostic, ruleIndex: Map<string, number>) {
+  const result: Record<string, unknown> = {
+    ruleId: diag.ruleId,
+    ruleIndex: ruleIndex.get(diag.ruleId),
+    level: mapSeverity(diag.severity),
+    message: { text: diag.message },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: {
+            uri: diag.file.startsWith("/") ? pathToFileURL(diag.file).href : diag.file,
+          },
+          region: buildRegion(diag),
+        },
+      },
+    ],
+    fingerprints: {
+      "chant/v1": `${diag.ruleId}:${diag.file}:${diag.line}:${diag.column}`,
+    },
+  };
+  return result;
+}
+
 /**
  * Format diagnostics as SARIF (Static Analysis Results Interchange Format)
+ *
+ * @param diagnostics - Active (non-suppressed) diagnostics
+ * @param rules - Full list of loaded LintRules for rich metadata (optional)
+ * @param suppressed - Suppressed diagnostics with optional reason (optional)
+ * @param version - Tool version string (optional, defaults to "0.1.0")
  */
-export function formatSarif(diagnostics: LintDiagnostic[]): string {
+export function formatSarif(
+  diagnostics: LintDiagnostic[],
+  rules?: LintRule[],
+  suppressed?: Array<LintDiagnostic & { reason?: string }>,
+  version?: string,
+): string {
+  // Build rule metadata from LintRule objects when available, otherwise from diagnostics
+  const { sarifRules, ruleIndex } = buildRuleMetadata(diagnostics, suppressed ?? [], rules);
+
+  // Build active results
+  const results: Record<string, unknown>[] = diagnostics.map((diag) =>
+    buildSarifResult(diag, ruleIndex),
+  );
+
+  // Append suppressed results with SARIF suppressions
+  if (suppressed) {
+    for (const diag of suppressed) {
+      const result = buildSarifResult(diag, ruleIndex);
+      result.suppressions = [
+        {
+          kind: "inSource",
+          ...(diag.reason ? { justification: diag.reason } : {}),
+        },
+      ];
+      results.push(result);
+    }
+  }
+
   const sarif = {
     $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
     version: "2.1.0",
@@ -133,31 +214,12 @@ export function formatSarif(diagnostics: LintDiagnostic[]): string {
         tool: {
           driver: {
             name: "chant",
-            version: "0.1.0",
+            version: version ?? "0.1.0",
             informationUri: "https://chant.dev",
-            rules: getUniqueRules(diagnostics),
+            rules: sarifRules,
           },
         },
-        results: diagnostics.map((diag) => ({
-          ruleId: diag.ruleId,
-          level: diag.severity === "error" ? "error" : diag.severity === "warning" ? "warning" : "note",
-          message: {
-            text: diag.message,
-          },
-          locations: [
-            {
-              physicalLocation: {
-                artifactLocation: {
-                  uri: diag.file,
-                },
-                region: {
-                  startLine: diag.line,
-                  startColumn: diag.column,
-                },
-              },
-            },
-          ],
-        })),
+        results,
       },
     ],
   };
@@ -166,21 +228,56 @@ export function formatSarif(diagnostics: LintDiagnostic[]): string {
 }
 
 /**
- * Extract unique rules from diagnostics for SARIF
+ * Build SARIF rule metadata from loaded LintRules and/or diagnostics.
+ * Returns both the rules array and a ruleId→index map for result references.
  */
-function getUniqueRules(diagnostics: LintDiagnostic[]): Array<{ id: string; shortDescription: { text: string } }> {
-  const ruleIds = new Set<string>();
-  const rules: Array<{ id: string; shortDescription: { text: string } }> = [];
+function buildRuleMetadata(
+  diagnostics: LintDiagnostic[],
+  suppressed: LintDiagnostic[],
+  rules?: LintRule[],
+): {
+  sarifRules: Record<string, unknown>[];
+  ruleIndex: Map<string, number>;
+} {
+  // Build a lookup from rule objects
+  const ruleMap = new Map<string, LintRule>();
+  if (rules) {
+    for (const r of rules) {
+      ruleMap.set(r.id, r);
+    }
+  }
 
-  for (const diag of diagnostics) {
-    if (!ruleIds.has(diag.ruleId)) {
-      ruleIds.add(diag.ruleId);
-      rules.push({
-        id: diag.ruleId,
-        shortDescription: { text: diag.ruleId },
-      });
+  // Collect all unique rule IDs from diagnostics + suppressed
+  const seen = new Set<string>();
+  const orderedIds: string[] = [];
+  for (const diag of [...diagnostics, ...suppressed]) {
+    if (!seen.has(diag.ruleId)) {
+      seen.add(diag.ruleId);
+      orderedIds.push(diag.ruleId);
+    }
+  }
+
+  const sarifRules: Record<string, unknown>[] = [];
+  const ruleIndex = new Map<string, number>();
+
+  for (const id of orderedIds) {
+    const rule = ruleMap.get(id);
+    const descText = rule?.description || id;
+    const entry: Record<string, unknown> = {
+      id,
+      shortDescription: { text: descText },
+      fullDescription: { text: descText },
+      helpUri: rule?.helpUri || `https://chant.dev/lint-rules/${id.toLowerCase()}`,
+      defaultConfiguration: {
+        level: mapSeverity(rule?.severity ?? "warning"),
+      },
+    };
+    if (rule?.category) {
+      entry.properties = { category: rule.category };
     }
+    ruleIndex.set(id, sarifRules.length);
+    sarifRules.push(entry);
   }
 
-  return rules;
+  return { sarifRules, ruleIndex };
 }

package/src/codegen/docs-rules.test.ts

@@ -0,0 +1,112 @@
+import { describe, test, expect } from "bun:test";
+import { generateRuleCatalog, generateRuleDetailPage } from "./docs-rules";
+import type { RuleEntry } from "../lint/rule-registry";
+
+const mockEntries: RuleEntry[] = [
+  {
+    id: "COR001",
+    description: "No inline objects in Declarable constructors",
+    category: "style",
+    defaultSeverity: "warning",
+    source: "core",
+    phase: "pre-synth",
+    hasAutoFix: false,
+  },
+  {
+    id: "WAW018",
+    description: "S3 bucket missing public access block",
+    category: "security",
+    defaultSeverity: "error",
+    source: "aws",
+    phase: "post-synth",
+    hasAutoFix: false,
+    helpUri: "https://chant.dev/lint-rules/waw018",
+  },
+  {
+    id: "COR008",
+    description: "Export required for declarable instances",
+    category: "correctness",
+    defaultSeverity: "warning",
+    source: "core",
+    phase: "pre-synth",
+    hasAutoFix: true,
+  },
+];
+
+describe("generateRuleCatalog", () => {
+  test("generates valid MDX with frontmatter", () => {
+    const mdx = generateRuleCatalog(mockEntries);
+
+    expect(mdx).toContain("---");
+    expect(mdx).toContain('title: "Rule Reference"');
+    expect(mdx).toContain("**3** rules");
+  });
+
+  test("groups rules by category", () => {
+    const mdx = generateRuleCatalog(mockEntries);
+
+    expect(mdx).toContain("## Correctness");
+    expect(mdx).toContain("## Security");
+    expect(mdx).toContain("## Style");
+  });
+
+  test("includes table headers", () => {
+    const mdx = generateRuleCatalog(mockEntries);
+
+    expect(mdx).toContain("| ID | Description | Severity | Phase | Fix |");
+  });
+
+  test("renders rule entries with correct data", () => {
+    const mdx = generateRuleCatalog(mockEntries);
+
+    expect(mdx).toContain("COR001");
+    expect(mdx).toContain("No inline objects");
+    expect(mdx).toContain("WAW018");
+    expect(mdx).toContain("public access");
+  });
+
+  test("marks auto-fix rules", () => {
+    const mdx = generateRuleCatalog(mockEntries);
+    const lines = mdx.split("\n");
+    const cor008Line = lines.find((l) => l.includes("COR008"));
+    expect(cor008Line).toContain("Yes");
+  });
+
+  test("renders helpUri as link", () => {
+    const mdx = generateRuleCatalog(mockEntries);
+    expect(mdx).toContain("[`WAW018`](https://chant.dev/lint-rules/waw018)");
+  });
+});
+
+describe("generateRuleDetailPage", () => {
+  test("generates valid MDX with frontmatter", () => {
+    const mdx = generateRuleDetailPage(mockEntries[0]);
+
+    expect(mdx).toContain("---");
+    expect(mdx).toContain("COR001");
+    expect(mdx).toContain("No inline objects");
+  });
+
+  test("includes metadata table", () => {
+    const mdx = generateRuleDetailPage(mockEntries[0]);
+
+    expect(mdx).toContain("| **Severity** | warning |");
+    expect(mdx).toContain("| **Category** | style |");
+    expect(mdx).toContain("| **Phase** | pre-synth |");
+  });
+
+  test("includes configuration example", () => {
+    const mdx = generateRuleDetailPage(mockEntries[0]);
+
+    expect(mdx).toContain("## Configuration");
+    expect(mdx).toContain('"COR001"');
+  });
+
+  test("includes disable syntax", () => {
+    const mdx = generateRuleDetailPage(mockEntries[0]);
+
+    expect(mdx).toContain("## Disabling");
+    expect(mdx).toContain("chant-disable COR001");
+    expect(mdx).toContain("chant-disable-next-line COR001 -- reason");
+  });
+});

package/src/codegen/docs-rules.ts

@@ -0,0 +1,129 @@
+/**
+ * Rule documentation auto-generation.
+ *
+ * Generates MDX pages from a RuleEntry registry:
+ * - A catalog page with all rules grouped by category
+ * - Per-rule detail pages with configuration examples and disable syntax
+ */
+
+import type { RuleEntry } from "../lint/rule-registry";
+
+/**
+ * Generate a rule catalog MDX page with all rules grouped by category.
+ */
+export function generateRuleCatalog(
+  entries: RuleEntry[],
+  displayName = "chant",
+): string {
+  const lines: string[] = [
+    "---",
+    `title: "Rule Reference"`,
+    `description: "Complete reference of all lint rules and post-synth checks"`,
+    "---",
+    "",
+    `This page lists all **${entries.length}** rules available in ${displayName}.`,
+    "",
+  ];
+
+  // Group by category
+  const byCategory = new Map<string, RuleEntry[]>();
+  for (const entry of entries) {
+    const cat = entry.category;
+    const existing = byCategory.get(cat) ?? [];
+    existing.push(entry);
+    byCategory.set(cat, existing);
+  }
+
+  // Render each category
+  const categoryOrder = ["correctness", "security", "style", "performance"];
+  const sortedCategories = [...byCategory.keys()].sort(
+    (a, b) => (categoryOrder.indexOf(a) ?? 99) - (categoryOrder.indexOf(b) ?? 99),
+  );
+
+  for (const cat of sortedCategories) {
+    const catEntries = byCategory.get(cat)!;
+    const title = cat.charAt(0).toUpperCase() + cat.slice(1);
+
+    lines.push(
+      `## ${title}`,
+      "",
+      "| ID | Description | Severity | Phase | Fix |",
+      "|----|-------------|----------|-------|-----|",
+    );
+
+    for (const entry of catEntries.sort((a, b) => a.id.localeCompare(b.id))) {
+      const fix = entry.hasAutoFix ? "Yes" : "";
+      const link = entry.helpUri
+        ? `[\`${entry.id}\`](${entry.helpUri})`
+        : `\`${entry.id}\``;
+      lines.push(
+        `| ${link} | ${entry.description} | ${entry.defaultSeverity} | ${entry.phase} | ${fix} |`,
+      );
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate a per-rule detail MDX page.
+ */
+export function generateRuleDetailPage(entry: RuleEntry): string {
+  const lines: string[] = [
+    "---",
+    `title: "${entry.id}: ${entry.description}"`,
+    `description: "${entry.description}"`,
+    "---",
+    "",
+    `# ${entry.id}`,
+    "",
+    entry.description,
+    "",
+    "| Property | Value |",
+    "|----------|-------|",
+    `| **ID** | \`${entry.id}\` |`,
+    `| **Severity** | ${entry.defaultSeverity} |`,
+    `| **Category** | ${entry.category} |`,
+    `| **Phase** | ${entry.phase} |`,
+    `| **Source** | ${entry.source} |`,
+    `| **Auto-fix** | ${entry.hasAutoFix ? "Yes" : "No"} |`,
+    "",
+  ];
+
+  // Configuration example
+  lines.push(
+    "## Configuration",
+    "",
+    "Override severity in your `chant.config.ts`:",
+    "",
+    "```ts",
+    "// chant.config.ts",
+    `rules: {`,
+    `  "${entry.id}": "warning",  // or "error", "info", "off"`,
+    `}`,
+    "```",
+    "",
+  );
+
+  // Disable syntax
+  lines.push(
+    "## Disabling",
+    "",
+    "Suppress this rule with inline comments:",
+    "",
+    "```ts",
+    `// chant-disable ${entry.id}`,
+    `// ... entire file suppressed for ${entry.id}`,
+    "",
+    `const x = 1; // chant-disable-line ${entry.id}`,
+    "",
+    `// chant-disable-next-line ${entry.id} -- reason for suppression`,
+    `const y = 2;`,
+    "```",
+    "",
+  );
+
+  return lines.join("\n");
+}

package/src/codegen/docs.ts

@@ -32,7 +32,7 @@ export interface DocsConfig {
   /** Custom sections to append to overview page */
   extraSections?: Array<{ title: string; content: string }>;
   /** Standalone pages added to the sidebar after Overview */
-  extraPages?: Array<{ slug: string; title: string; description?: string; content: string }>;
+  extraPages?: Array<{ slug: string; title: string; description?: string; content: string; sidebar?: boolean }>;
   /** Slugs of auto-generated pages to suppress (e.g. "pseudo-parameters") */
   suppressPages?: string[];
   /** Source directory for scanning rule files (defaults to srcDir sibling of distDir) */
@@ -385,6 +385,7 @@ function buildSidebar(
   // Extra pages from lexicon config (appear after Overview)
   if (config.extraPages) {
     for (const page of config.extraPages) {
+      if (page.sidebar === false) continue;
       items.push({ label: page.title, slug: page.slug });
     }
   }
@@ -447,6 +448,7 @@ function generateOverview(
   // Extra pages listed first in reference links
   if (config.extraPages && config.extraPages.length > 0) {
     for (const page of config.extraPages) {
+      if (page.sidebar === false) continue;
       lines.push(`- [${page.title}](./${page.slug})`);
     }
   }