@intentius/chant 0.0.5 → 0.0.9

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})`);
     }
   }

package/src/codegen/generate-registry.test.ts

@@ -51,7 +51,7 @@ describe("buildRegistry", () => {
     const entries = buildRegistry(resources, naming, testConfig);
 
     expect(entries["Bucket"]).toBeDefined();
-    expect(entries["Bucket"].attrs).toEqual({ arn: "Arn", domainName: "DomainName" });
+    expect(entries["Bucket"].attrs).toEqual({ Arn: "Arn", DomainName: "DomainName" });
   });
 
   test("omits attrs when empty", () => {

package/src/codegen/generate-registry.ts

@@ -8,7 +8,6 @@
 
 import type { NamingStrategy } from "./naming";
 import { propertyTypeName, extractDefName } from "./naming";
-import { toCamelCase } from "./case";
 import { constraintsIsEmpty, type PropertyConstraints } from "./json-schema";
 
 export interface RegistryResource {
@@ -47,12 +46,12 @@ export function buildRegistry<E>(
     const tsName = naming.resolve(typeName);
     if (!tsName) continue;
 
-    // Build attrs map: camelCase → raw name
+    // Build attrs map: name → raw name (identity mapping)
     let attrs: Record<string, string> | undefined;
     if (r.attributes.length > 0) {
       attrs = {};
       for (const a of r.attributes) {
-        attrs[toCamelCase(a.name)] = a.name;
+        attrs[a.name] = a.name;
       }
     }
 

package/src/codegen/generate-typescript.test.ts

@@ -18,8 +18,8 @@ describe("writeResourceClass", () => {
     );
     const output = lines.join("\n");
     expect(output).toContain("export declare class Bucket {");
-    expect(output).toContain("bucketName: string;");
-    expect(output).toContain("readonly arn: string;");
+    expect(output).toContain("BucketName: string;");
+    expect(output).toContain("readonly Arn: string;");
     expect(output).toContain("}");
   });
 
@@ -34,7 +34,7 @@ describe("writeResourceClass", () => {
       remap,
     );
     const output = lines.join("\n");
-    expect(output).toContain("readonly config: BucketConfig;");
+    expect(output).toContain("readonly Config: BucketConfig;");
   });
 });
 
@@ -48,7 +48,7 @@ describe("writePropertyClass", () => {
     );
     const output = lines.join("\n");
     expect(output).toContain("export declare class BucketConfig {");
-    expect(output).toContain("enabled?: boolean;");
+    expect(output).toContain("Enabled?: boolean;");
     expect(output).toContain("}");
   });
 });
@@ -71,8 +71,8 @@ describe("writeConstructor", () => {
       undefined,
     );
     const output = lines.join("\n");
-    const reqIdx = output.indexOf("required:");
-    const optIdx = output.indexOf("optional?:");
+    const reqIdx = output.indexOf("Required:");
+    const optIdx = output.indexOf("Optional?:");
     expect(reqIdx).toBeLessThan(optIdx);
   });
 
@@ -88,6 +88,70 @@ describe("writeConstructor", () => {
   });
 });
 
+describe("writeConstructor with resourceAttributesType", () => {
+  test("empty props with attributes type emits both params", () => {
+    const lines: string[] = [];
+    writeConstructor(lines, [], undefined, "CFResourceAttributes");
+    expect(lines.join("\n")).toContain(
+      "constructor(props: Record<string, unknown>, attributes?: CFResourceAttributes);",
+    );
+  });
+
+  test("props with attributes type emits second param after closing brace", () => {
+    const lines: string[] = [];
+    writeConstructor(
+      lines,
+      [{ name: "BucketName", type: "string", required: true }],
+      undefined,
+      "CFResourceAttributes",
+    );
+    const output = lines.join("\n");
+    expect(output).toContain("constructor(props: {");
+    expect(output).toContain("BucketName: string;");
+    expect(output).toContain("}, attributes?: CFResourceAttributes);");
+  });
+
+  test("without attributes type, closing brace has no second param", () => {
+    const lines: string[] = [];
+    writeConstructor(
+      lines,
+      [{ name: "Name", type: "string", required: true }],
+      undefined,
+    );
+    const output = lines.join("\n");
+    expect(output).toContain("  });");
+    expect(output).not.toContain("attributes?");
+  });
+});
+
+describe("writeResourceClass with resourceAttributesType", () => {
+  test("resource class constructor includes attributes param", () => {
+    const lines: string[] = [];
+    writeResourceClass(
+      lines,
+      "Bucket",
+      [{ name: "BucketName", type: "string", required: false }],
+      [{ name: "Arn", type: "string" }],
+      undefined,
+      "CFResourceAttributes",
+    );
+    const output = lines.join("\n");
+    expect(output).toContain("}, attributes?: CFResourceAttributes);");
+    expect(output).toContain("readonly Arn: string;");
+  });
+
+  test("property class does not get attributes param", () => {
+    const lines: string[] = [];
+    writePropertyClass(
+      lines,
+      "BucketConfig",
+      [{ name: "Enabled", type: "boolean", required: false }],
+    );
+    const output = lines.join("\n");
+    expect(output).not.toContain("attributes?");
+  });
+});
+
 describe("writeEnumType", () => {
   test("writes single-line for short enum", () => {
     const lines: string[] = [];

package/src/codegen/generate-typescript.ts

@@ -42,16 +42,17 @@ export function writeResourceClass(
   properties: DtsProperty[],
   attributes: DtsAttribute[],
   remap?: Map<string, string>,
+  resourceAttributesType?: string,
 ): void {
   lines.push("");
   lines.push(`export declare class ${tsName} {`);
-  writeConstructor(lines, properties, remap);
+  writeConstructor(lines, properties, remap, resourceAttributesType);
 
   // Attributes as readonly properties (sorted)
   const attrs = [...attributes].sort((a, b) => a.name.localeCompare(b.name));
   for (const a of attrs) {
     const attrType = resolveConstructorType(a.type, remap);
-    lines.push(`  readonly ${toCamelCase(a.name)}: ${attrType};`);
+    lines.push(`  readonly ${a.name}: ${attrType};`);
   }
 
   lines.push("}");
@@ -79,9 +80,14 @@ export function writeConstructor(
   lines: string[],
   props: DtsProperty[],
   remap: Map<string, string> | undefined,
+  resourceAttributesType?: string,
 ): void {
   if (props.length === 0) {
-    lines.push("  constructor(props: Record<string, unknown>);");
+    if (resourceAttributesType) {
+      lines.push(`  constructor(props: Record<string, unknown>, attributes?: ${resourceAttributesType});`);
+    } else {
+      lines.push("  constructor(props: Record<string, unknown>);");
+    }
     return;
   }
 
@@ -98,9 +104,13 @@ export function writeConstructor(
     if (p.description) {
       lines.push(`    /** ${p.description} */`);
     }
-    lines.push(`    ${toCamelCase(p.name)}${optional}: ${tsType};`);
+    lines.push(`    ${p.name}${optional}: ${tsType};`);
+  }
+  if (resourceAttributesType) {
+    lines.push(`  }, attributes?: ${resourceAttributesType});`);
+  } else {
+    lines.push("  });");
   }
-  lines.push("  });");
 }
 
 /**
@@ -155,7 +165,3 @@ export function resolveConstructorType(tsType: string, remap: Map<string, string
 
   return tsType;
 }
-
-function toCamelCase(name: string): string {
-  return name.charAt(0).toLowerCase() + name.slice(1);
-}

package/src/codegen/generate.ts

@@ -180,26 +180,15 @@ export interface WriteConfig {
   generatedSubdir?: string;
   /** Map of filename → content to write. */
   files: Record<string, string>;
-  /** Optional snapshot function called before overwriting. */
-  snapshot?: (generatedDir: string) => void;
 }
 
 /**
- * Write generated artifacts to disk with optional auto-snapshot.
+ * Write generated artifacts to disk.
  */
 export function writeGeneratedArtifacts(config: WriteConfig): void {
   const generatedDir = join(config.baseDir, config.generatedSubdir ?? "src/generated");
   mkdirSync(generatedDir, { recursive: true });
 
-  // Auto-snapshot before overwriting
-  if (config.snapshot) {
-    try {
-      config.snapshot(generatedDir);
-    } catch {
-      // Best effort — don't fail generation if snapshot fails
-    }
-  }
-
   for (const [filename, content] of Object.entries(config.files)) {
     writeFileSync(join(generatedDir, filename), content);
   }

package/src/codegen/package.ts

@@ -113,7 +113,7 @@ export async function packagePipeline(
 /**
  * Collect lint rule source files from a lexicon package.
  * Auto-discovers .ts files in the specified directories,
- * skipping test files, barrel files (index.ts), and non-.ts files.
+ * skipping test files, re-export files (index.ts), and non-.ts files.
  */
 export function collectRules(
   srcDir: string,

package/src/codegen/typecheck.ts

@@ -4,6 +4,7 @@
 import { writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
+import { getRuntime } from "../runtime-adapter";
 
 export interface TypeCheckResult {
   ok: boolean;
@@ -39,17 +40,11 @@ export async function typecheckDTS(content: string): Promise<TypeCheckResult> {
     writeFileSync(join(dir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2));
 
     // Run tsc
-    const proc = Bun.spawn(["bunx", "tsc", "--noEmit", "--project", "tsconfig.json"], {
-      cwd: dir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-
-    const [stdout, stderr] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-    ]);
-    const exitCode = await proc.exited;
+    const rt = getRuntime();
+    const { stdout, stderr, exitCode } = await rt.spawn(
+      [rt.commands.exec, "tsc", "--noEmit", "--project", "tsconfig.json"],
+      { cwd: dir },
+    );
 
     // Parse diagnostics from stdout (tsc writes errors to stdout)
     const output = stdout + stderr;