@intentius/chant 0.7.0 → 0.8.0

package/src/codegen/generate-post-synth-barrel.test.ts

@@ -0,0 +1,37 @@
+import { describe, test, expect } from "vitest";
+import { generatePostSynthBarrel, type BarrelEntry } from "./generate-post-synth-barrel";
+
+describe("generatePostSynthBarrel", () => {
+  test("emits a DO NOT EDIT banner, static imports, and an id-sorted array", () => {
+    const entries: BarrelEntry[] = [
+      { module: "./gha021", exportName: "gha021", id: "GHA021" },
+      { module: "./apt-no-recommends", exportName: "dkrd010", id: "DKRD010" },
+      { module: "./gha006", exportName: "gha006", id: "GHA006" },
+    ];
+    const out = generatePostSynthBarrel(entries);
+
+    expect(out).toContain("// Code generated by chant generate. DO NOT EDIT.");
+    expect(out).toContain('import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";');
+    // Export name may differ from the module name (docker/helm/temporal).
+    expect(out).toContain('import { dkrd010 } from "./apt-no-recommends";');
+    // Array is ordered by id, not insertion order.
+    const arrayBody = out.slice(out.indexOf("postSynthChecks: PostSynthCheck[] = ["));
+    expect(arrayBody.indexOf("dkrd010")).toBeLessThan(arrayBody.indexOf("gha006"));
+    expect(arrayBody.indexOf("gha006")).toBeLessThan(arrayBody.indexOf("gha021"));
+  });
+
+  test("is deterministic regardless of input order", () => {
+    const a: BarrelEntry[] = [
+      { module: "./b", exportName: "b", id: "X2" },
+      { module: "./a", exportName: "a", id: "X1" },
+    ];
+    const b = [...a].reverse();
+    expect(generatePostSynthBarrel(a)).toBe(generatePostSynthBarrel(b));
+  });
+
+  test("empty input yields an empty array, still valid", () => {
+    const out = generatePostSynthBarrel([]);
+    expect(out).toContain("export const postSynthChecks: PostSynthCheck[] = [");
+    expect(out).toContain("];");
+  });
+});

package/src/codegen/generate-post-synth-barrel.ts

@@ -0,0 +1,75 @@
+/**
+ * Generate a static, importable barrel of a lexicon's post-synth checks.
+ *
+ * The runtime loader (`discoverPostSynthChecks`) readdir-globs the directory and
+ * `require()`s each file via tsx — fs- and tsx-coupled, so it can't run in a
+ * bundle or on an edge runtime (Cloudflare Workers). This generator produces a
+ * committed `lint/post-synth/index.ts` with explicit static imports + an exported
+ * `postSynthChecks` array, which bundlers can follow with no fs/tsx/require. See #409.
+ *
+ * Detection reuses the runtime's own `isPostSynthCheck`, so the barrel contains
+ * exactly the checks discovery would — including files whose export name differs
+ * from the filename (docker/helm/temporal) and excluding helper modules
+ * (cf-refs, arm-refs, …) that export no check.
+ */
+
+import { createRequire } from "module";
+import { listRuleFiles } from "../lint/discover";
+import { isPostSynthCheck } from "../lint/post-synth";
+
+export interface BarrelEntry {
+  /** Module specifier relative to the barrel, e.g. "./gha021" or "./apt-no-recommends". */
+  module: string;
+  /** Exported binding holding the check, e.g. "gha021" or "dkrd010". */
+  exportName: string;
+  /** The check's id (e.g. "GHA021"), used for stable ordering. */
+  id: string;
+}
+
+/**
+ * Scan a post-synth directory and return one entry per exported check.
+ * Runs at codegen time on Node (tsx-powered require), never in the shipped path.
+ */
+export function scanPostSynthChecks(dir: string, importMetaUrl: string): BarrelEntry[] {
+  const require = createRequire(importMetaUrl);
+  const entries: BarrelEntry[] = [];
+  for (const file of listRuleFiles(dir)) {
+    const base = file.replace(/\.ts$/, "");
+    let mod: Record<string, unknown>;
+    try {
+      mod = require(`${dir}/${base}`) as Record<string, unknown>;
+    } catch {
+      continue; // a file that fails to load contributes nothing
+    }
+    for (const [exportName, value] of Object.entries(mod)) {
+      if (isPostSynthCheck(value)) {
+        entries.push({ module: `./${base}`, exportName, id: value.id });
+      }
+    }
+  }
+  return entries;
+}
+
+/** Render the barrel file content from scanned entries (pure — easy to unit test). */
+export function generatePostSynthBarrel(entries: BarrelEntry[]): string {
+  const sorted = [...entries].sort((a, b) => a.id.localeCompare(b.id));
+  const lines: string[] = [];
+  lines.push("// Code generated by chant generate. DO NOT EDIT.");
+  lines.push('import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";');
+  for (const e of sorted) {
+    lines.push(`import { ${e.exportName} } from ${JSON.stringify(e.module)};`);
+  }
+  lines.push("");
+  lines.push("export const postSynthChecks: PostSynthCheck[] = [");
+  for (const e of sorted) {
+    lines.push(`  ${e.exportName},`);
+  }
+  lines.push("];");
+  lines.push("");
+  return lines.join("\n");
+}
+
+/** Scan a directory and render its barrel in one step. */
+export function renderPostSynthBarrelForDir(dir: string, importMetaUrl: string): string {
+  return generatePostSynthBarrel(scanPostSynthChecks(dir, importMetaUrl));
+}

package/src/codegen/post-synth-barrel-guards.test.ts

@@ -0,0 +1,63 @@
+import { describe, test, expect } from "vitest";
+import { build } from "esbuild";
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { join } from "path";
+import { renderPostSynthBarrelForDir } from "./generate-post-synth-barrel";
+
+const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
+const lexiconsDir = join(repoRoot, "lexicons");
+const lexiconDirs = readdirSync(lexiconsDir).filter((name) =>
+  existsSync(join(lexiconsDir, name, "src", "lint", "post-synth", "index.ts")),
+);
+
+describe("post-synth barrel freshness", () => {
+  test.each(lexiconDirs)("%s barrel is up to date (run npm run generate)", (lexicon) => {
+    const dir = join(lexiconsDir, lexicon, "src", "lint", "post-synth");
+    const committed = readFileSync(join(dir, "index.ts"), "utf-8");
+    const regenerated = renderPostSynthBarrelForDir(dir, import.meta.url);
+    expect(committed, `${lexicon} barrel is stale — run \`npm run generate\``).toBe(regenerated);
+  });
+});
+
+describe("post-synth barrel is exported", () => {
+  // A lexicon that ships a barrel must export it so consumers can import
+  // `@intentius/chant-lexicon-<lex>/lint/post-synth` without `/index` (#417).
+  test.each(lexiconDirs)("%s exports ./lint/post-synth", (lexicon) => {
+    const pkg = JSON.parse(readFileSync(join(lexiconsDir, lexicon, "package.json"), "utf-8"));
+    const entry = pkg.exports?.["./lint/post-synth"];
+    // Lexicons shipping .d.ts use a conditional export — `types` resolves to the
+    // emitted declaration for external consumers; `development`/`default` keep
+    // runtime resolution on source (in-repo and published alike). Lexicons not
+    // yet building dist keep the plain source string.
+    if (typeof entry === "string") {
+      expect(entry).toBe("./src/lint/post-synth/index.ts");
+    } else {
+      expect(entry?.development).toBe("./src/lint/post-synth/index.ts");
+      expect(entry?.types).toBe("./dist/lint/post-synth/index.d.ts");
+      expect(entry?.default).toBe("./src/lint/post-synth/index.ts");
+    }
+  });
+});
+
+describe("post-synth barrel is edge-bundle clean", () => {
+  // The barrel is the entry an edge/bundled deployment imports. It must not drag
+  // in the TypeScript compiler or the fs/tsx runtime loader (#409).
+  test("github barrel bundles without typescript or the fs loader", async () => {
+    const entry = join(lexiconsDir, "github", "src", "lint", "post-synth", "index.ts");
+    const result = await build({
+      entryPoints: [entry],
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      metafile: true,
+      write: false,
+      outfile: "out.js",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    expect(inputs.some((p) => p.includes("node_modules/typescript"))).toBe(false);
+    // The runtime fs+tsx loader must not be in the graph.
+    expect(inputs.some((p) => p.includes("lint/discover"))).toBe(false);
+  }, 30_000);
+});

package/src/codegen/validate.ts

@@ -25,6 +25,14 @@ export interface LexiconValidationConfig {
   lexiconJsonFilename: string;
   /** Required backward-compatible export names to check in lexicon JSON */
   requiredNames: string[];
+  /**
+   * When true, a required name is satisfied if it appears as a substring of any
+   * lexicon JSON key (not only as an exact key). Lexicons that bound their
+   * generated type expansion (e.g. azure, #438) emit shared types under
+   * resource-prefixed/variant names, so the bare curated name is present only
+   * as a substring. Defaults to false (exact-key match).
+   */
+  requiredNamesMatchSubstring?: boolean;
   /** Base path of the lexicon package */
   basePath: string;
   /** Path to the generated directory (defaults to basePath/src/generated) */
@@ -70,7 +78,11 @@ export async function validateLexiconArtifacts(config: LexiconValidationConfig):
 
   // Check 3: Required backward-compatible names present in lexicon JSON
   if (lexiconData && config.requiredNames.length > 0) {
-    const missing = config.requiredNames.filter((name) => !(name in lexiconData!));
+    const keys = Object.keys(lexiconData);
+    const present = config.requiredNamesMatchSubstring
+      ? (name: string) => keys.some((k) => k.includes(name))
+      : (name: string) => name in lexiconData!;
+    const missing = config.requiredNames.filter((name) => !present(name));
     if (missing.length > 0) {
       checks.push({
         name: "required-names",

package/src/lint/discover.ts

@@ -84,7 +84,7 @@ export function discoverPostSynthChecks(dir: string, importMetaUrl: string): Pos
 /**
  * List rule files in a directory (excluding tests, helpers, index).
  */
-function listRuleFiles(dir: string): string[] {
+export function listRuleFiles(dir: string): string[] {
   try {
     return readdirSync(dir).filter((f) => {
       if (!f.endsWith(".ts")) return false;

package/src/meta/peer-deps.test.ts

@@ -0,0 +1,29 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { join } from "path";
+
+/**
+ * The lexicon packages are published in lockstep with core, so their
+ * `@intentius/*` peerDependencies must track the current core version. They were
+ * once frozen at `^0.1.0` while shipping at 0.7.0, which made a clean
+ * `npm install` fail (#411). This locks the invariant so it can't drift again.
+ */
+const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
+const coreVersion = JSON.parse(readFileSync(join(repoRoot, "packages/core/package.json"), "utf-8")).version as string;
+const expected = `^${coreVersion}`;
+
+const lexiconsDir = join(repoRoot, "lexicons");
+const lexicons = readdirSync(lexiconsDir).filter((name) => existsSync(join(lexiconsDir, name, "package.json")));
+
+describe("lexicon peerDependencies track the core version", () => {
+  test.each(lexicons)("%s pins @intentius/* peers to the current version", (lexicon) => {
+    const pkg = JSON.parse(readFileSync(join(lexiconsDir, lexicon, "package.json"), "utf-8"));
+    const peers: Record<string, string> = pkg.peerDependencies ?? {};
+    for (const [dep, range] of Object.entries(peers)) {
+      if (dep.startsWith("@intentius/")) {
+        expect(range, `${lexicon}: peer ${dep} should be ${expected}`).toBe(expected);
+      }
+    }
+  });
+});