@intentius/chant 0.0.15 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.0.15",
+  "version": "0.0.18",
   "license": "Apache-2.0",
   "type": "module",
   "files": [

package/src/codegen/docs.ts

@@ -46,6 +46,8 @@ export interface DocsConfig {
   basePath?: string;
   /** Root directory for resolving {{file:...}} markers in extra page content */
   examplesDir?: string;
+  /** Extra sidebar entries appended after extraPages (supports Starlight groups) */
+  sidebarExtra?: Array<Record<string, unknown>>;
 }
 
 export interface DocsResult {
@@ -285,8 +287,12 @@ export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
   const outDir = config.outDir;
   const contentDir = join(outDir, "src", "content", "docs");
 
-  // Clear stale content and Astro caches so changes are picked up on next build
-  rmSync(contentDir, { recursive: true, force: true });
+  // Clear stale generated content and Astro caches so changes are picked up on next build.
+  // Only remove files that will be regenerated — preserve hand-written pages.
+  for (const filename of result.pages.keys()) {
+    const filePath = join(contentDir, filename);
+    rmSync(filePath, { force: true });
+  }
   rmSync(join(outDir, ".astro"), { recursive: true, force: true });
   rmSync(join(outDir, "node_modules", ".astro"), { recursive: true, force: true });
 
@@ -411,6 +417,11 @@ function buildSidebar(
     items.push({ label: "Serialization", slug: "serialization" });
   }
 
+  // Append raw sidebar entries (supports groups and nested items)
+  if (config.sidebarExtra) {
+    items.push(...config.sidebarExtra);
+  }
+
   return items;
 }
 

package/src/codegen/generate.test.ts

@@ -0,0 +1,111 @@
+import { describe, test, expect } from "bun:test";
+import { generatePipeline, type GeneratePipelineConfig, type ParsedResult } from "./generate";
+import { NamingStrategy } from "./naming";
+
+interface TestResult extends ParsedResult {
+  name: string;
+}
+
+function makeConfig(
+  schemas: Map<string, Buffer>,
+  parseOverride?: (name: string, data: Buffer) => TestResult | TestResult[] | null,
+): GeneratePipelineConfig<TestResult> {
+  return {
+    fetchSchemas: async () => schemas,
+    parseSchema: parseOverride ?? ((name, _data) => ({
+      name,
+      propertyTypes: [],
+      enums: [],
+    })),
+    createNaming: (results) => new NamingStrategy(
+      results.map((r) => ({ typeName: r.name, propertyTypes: r.propertyTypes })),
+      {
+        priorityNames: {},
+        priorityAliases: {},
+        priorityPropertyAliases: {},
+        serviceAbbreviations: {},
+        shortName: (t) => t,
+        serviceName: () => "",
+      },
+    ),
+    generateRegistry: () => "{}",
+    generateTypes: () => "// types",
+    generateRuntimeIndex: () => "// index",
+  };
+}
+
+describe("generatePipeline", () => {
+  test("processes single-result parseSchema", async () => {
+    const schemas = new Map([
+      ["TypeA", Buffer.from("a")],
+      ["TypeB", Buffer.from("b")],
+    ]);
+    const result = await generatePipeline(makeConfig(schemas));
+    expect(result.resources).toBe(2);
+    expect(result.warnings).toHaveLength(0);
+  });
+
+  test("supports parseSchema returning arrays", async () => {
+    const schemas = new Map([
+      ["combined", Buffer.from("data")],
+    ]);
+
+    const config = makeConfig(schemas, (_name, _data) => [
+      { name: "TypeA", propertyTypes: [{ name: "PropA" }], enums: [] },
+      { name: "TypeB", propertyTypes: [{ name: "PropB" }], enums: [] },
+      { name: "TypeC", propertyTypes: [], enums: [{}] },
+    ]);
+
+    const result = await generatePipeline(config);
+    expect(result.resources).toBe(3);
+    expect(result.properties).toBe(2);
+    expect(result.enums).toBe(1);
+  });
+
+  test("handles parseSchema returning null (skip)", async () => {
+    const schemas = new Map([
+      ["skip-me", Buffer.from("x")],
+      ["keep-me", Buffer.from("y")],
+    ]);
+    const config = makeConfig(schemas, (name, _data) => {
+      if (name === "skip-me") return null;
+      return { name, propertyTypes: [], enums: [] };
+    });
+
+    const result = await generatePipeline(config);
+    expect(result.resources).toBe(1);
+  });
+
+  test("handles mixed single and array returns", async () => {
+    const schemas = new Map([
+      ["single", Buffer.from("s")],
+      ["multi", Buffer.from("m")],
+    ]);
+    const config = makeConfig(schemas, (name, _data) => {
+      if (name === "multi") {
+        return [
+          { name: "MultiA", propertyTypes: [], enums: [] },
+          { name: "MultiB", propertyTypes: [], enums: [] },
+        ];
+      }
+      return { name, propertyTypes: [], enums: [] };
+    });
+
+    const result = await generatePipeline(config);
+    expect(result.resources).toBe(3);
+  });
+
+  test("collects parse errors as warnings", async () => {
+    const schemas = new Map([
+      ["bad", Buffer.from("x")],
+    ]);
+    const config = makeConfig(schemas, () => {
+      throw new Error("parse failed");
+    });
+
+    const result = await generatePipeline(config);
+    expect(result.resources).toBe(0);
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0].error).toContain("parse failed");
+  });
+});

package/src/codegen/generate.ts

@@ -48,8 +48,13 @@ export interface GeneratePipelineConfig<T extends ParsedResult> {
   /** Fetch or provide raw schema data. */
   fetchSchemas: (opts: { force?: boolean }) => Promise<Map<string, Buffer>>;
 
-  /** Parse a single schema buffer into a result. Returns null to skip. */
-  parseSchema: (typeName: string, data: Buffer) => T | null;
+  /**
+   * Parse a single schema buffer into results. Returns null to skip.
+   *
+   * May return an array when a single schema file produces multiple results
+   * (e.g. K8s OpenAPI spec, GitLab CI schema).
+   */
+  parseSchema: (typeName: string, data: Buffer) => T | T[] | null;
 
   /** Create a naming strategy from the parsed results. */
   createNaming: (results: T[]) => NamingStrategy;
@@ -119,7 +124,13 @@ export async function generatePipeline<T extends ParsedResult>(
   for (const [typeName, data] of schemas) {
     try {
       const result = config.parseSchema(typeName, data);
-      if (result) results.push(result);
+      if (result) {
+        if (Array.isArray(result)) {
+          results.push(...result);
+        } else {
+          results.push(result);
+        }
+      }
     } catch (err) {
       warnings.push({
         file: typeName,

package/src/index.ts

@@ -33,6 +33,7 @@ export * from "./lint/selectors";
 export * from "./lint/named-checks";
 export * from "./lint/post-synth";
 export * from "./lint/rule-loader";
+export * from "./lint/discover";
 export * from "./import/parser";
 export * from "./import/generator";
 export * from "./lexicon";

package/src/lint/discover.test.ts

@@ -0,0 +1,69 @@
+import { describe, test, expect } from "bun:test";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { discoverLintRules, discoverPostSynthChecks } from "./discover";
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+
+describe("discoverLintRules", () => {
+  test("returns empty array for non-existent directory", () => {
+    const rules = discoverLintRules("/nonexistent/path", import.meta.url);
+    expect(rules).toEqual([]);
+  });
+
+  test("discovers rules from a real lexicon", () => {
+    // Use the Helm lexicon's rules directory as a real test case
+    const helmRulesDir = join(thisDir, "../../../../lexicons/helm/src/lint/rules");
+    const rules = discoverLintRules(helmRulesDir, import.meta.url);
+    expect(rules.length).toBeGreaterThan(0);
+    // Each discovered rule should have the expected shape
+    for (const rule of rules) {
+      expect(typeof rule.id).toBe("string");
+      expect(typeof rule.severity).toBe("string");
+      expect(typeof rule.category).toBe("string");
+      expect(typeof rule.check).toBe("function");
+    }
+  });
+
+  test("sorts rules by id", () => {
+    const helmRulesDir = join(thisDir, "../../../../lexicons/helm/src/lint/rules");
+    const rules = discoverLintRules(helmRulesDir, import.meta.url);
+    for (let i = 1; i < rules.length; i++) {
+      expect(rules[i].id.localeCompare(rules[i - 1].id)).toBeGreaterThanOrEqual(0);
+    }
+  });
+});
+
+describe("discoverPostSynthChecks", () => {
+  test("returns empty array for non-existent directory", () => {
+    const checks = discoverPostSynthChecks("/nonexistent/path", import.meta.url);
+    expect(checks).toEqual([]);
+  });
+
+  test("discovers checks from a real lexicon", () => {
+    const helmPostSynthDir = join(thisDir, "../../../../lexicons/helm/src/lint/post-synth");
+    const checks = discoverPostSynthChecks(helmPostSynthDir, import.meta.url);
+    expect(checks.length).toBeGreaterThan(0);
+    for (const check of checks) {
+      expect(typeof check.id).toBe("string");
+      expect(typeof check.description).toBe("string");
+      expect(typeof check.check).toBe("function");
+    }
+  });
+
+  test("sorts checks by id", () => {
+    const helmPostSynthDir = join(thisDir, "../../../../lexicons/helm/src/lint/post-synth");
+    const checks = discoverPostSynthChecks(helmPostSynthDir, import.meta.url);
+    for (let i = 1; i < checks.length; i++) {
+      expect(checks[i].id.localeCompare(checks[i - 1].id)).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  test("does not include lint rules", () => {
+    // Post-synth checks should not pick up lint rules (which also have check())
+    const helmRulesDir = join(thisDir, "../../../../lexicons/helm/src/lint/rules");
+    const checks = discoverPostSynthChecks(helmRulesDir, import.meta.url);
+    // Lint rules have severity, post-synth checks don't — so this should be empty
+    expect(checks.length).toBe(0);
+  });
+});

package/src/lint/discover.ts

@@ -0,0 +1,112 @@
+/**
+ * Auto-discovery for lint rules and post-synth checks.
+ *
+ * Scans directories for .ts files and loads exported rules/checks,
+ * eliminating the need to manually list every rule in plugin.ts.
+ */
+
+import { readdirSync } from "fs";
+import { join } from "path";
+import { createRequire } from "module";
+import type { LintRule } from "./rule";
+import type { PostSynthCheck } from "./post-synth";
+
+/**
+ * Discover lint rules from a directory.
+ *
+ * Scans the directory for .ts files (excluding tests, helpers, and index files),
+ * loads each module, and collects any exported objects that look like a LintRule
+ * (has `id`, `severity`, `category`, and `check` function).
+ *
+ * @param dir - Absolute path to the rules directory
+ * @param importMetaUrl - The caller's import.meta.url (for createRequire)
+ */
+export function discoverLintRules(dir: string, importMetaUrl: string): LintRule[] {
+  const require = createRequire(importMetaUrl);
+  const rules: LintRule[] = [];
+
+  for (const file of listRuleFiles(dir)) {
+    try {
+      // Strip .ts extension — require() resolves without it
+      const modPath = join(dir, file.replace(/\.ts$/, ""));
+      const mod = require(modPath);
+      for (const exp of Object.values(mod)) {
+        if (isLintRule(exp)) rules.push(exp);
+      }
+    } catch {
+      // Skip files that fail to load
+    }
+  }
+
+  return rules.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Discover post-synth checks from a directory.
+ *
+ * Scans the directory for .ts files (excluding tests, helpers, and index files),
+ * loads each module, and collects any exported objects that look like a PostSynthCheck
+ * (has `id`, `description`, and `check` function).
+ *
+ * @param dir - Absolute path to the post-synth rules directory
+ * @param importMetaUrl - The caller's import.meta.url (for createRequire)
+ */
+export function discoverPostSynthChecks(dir: string, importMetaUrl: string): PostSynthCheck[] {
+  const require = createRequire(importMetaUrl);
+  const checks: PostSynthCheck[] = [];
+
+  for (const file of listRuleFiles(dir)) {
+    try {
+      // Strip .ts extension — require() resolves without it
+      const modPath = join(dir, file.replace(/\.ts$/, ""));
+      const mod = require(modPath);
+      for (const exp of Object.values(mod)) {
+        if (isPostSynthCheck(exp)) checks.push(exp);
+      }
+    } catch {
+      // Skip files that fail to load
+    }
+  }
+
+  return checks.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * List rule files in a directory (excluding tests, helpers, index).
+ */
+function listRuleFiles(dir: string): string[] {
+  try {
+    return readdirSync(dir).filter((f) => {
+      if (!f.endsWith(".ts")) return false;
+      if (f.endsWith(".test.ts")) return false;
+      if (f === "index.ts") return false;
+      if (f.includes("helper")) return false;
+      return true;
+    });
+  } catch {
+    return [];
+  }
+}
+
+function isLintRule(obj: unknown): obj is LintRule {
+  if (typeof obj !== "object" || obj === null) return false;
+  const o = obj as Record<string, unknown>;
+  return (
+    typeof o.id === "string" &&
+    typeof o.severity === "string" &&
+    typeof o.category === "string" &&
+    typeof o.check === "function"
+  );
+}
+
+function isPostSynthCheck(obj: unknown): obj is PostSynthCheck {
+  if (typeof obj !== "object" || obj === null) return false;
+  const o = obj as Record<string, unknown>;
+  return (
+    typeof o.id === "string" &&
+    typeof o.description === "string" &&
+    typeof o.check === "function" &&
+    // Exclude LintRules (which also have check) by checking for PostSynthCheck-specific fields
+    typeof o.severity !== "string"
+  );
+}

package/src/lint/rules/index.ts

@@ -25,6 +25,7 @@ export { evl009CompositeNoConstantRule } from "./evl009-composite-no-constant";
 export { evl010CompositeNoTransformRule } from "./evl010-composite-no-transform";
 export { cor017CompositeNameMatchRule } from "./cor017-composite-name-match";
 export { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-lexicon-type";
+export { isInsideCompositeFactory } from "./composite-scope";
 
 import { flatDeclarationsRule } from "./flat-declarations";
 import { exportRequiredRule } from "./export-required";