@intentius/chant 0.44.14 → 0.45.0

package/src/cli/commands/check-lexicon-examples.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, beforeAll, afterAll } from "vitest";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, symlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { checkExamplesBuild } from "./check-lexicon-examples";
@@ -15,7 +15,10 @@ import { checkExamplesBuild } from "./check-lexicon-examples";
  * exactly what each example's own `npm run build` does.
  *
  * These fixtures import the real, already-installed `@intentius/chant-lexicon-aws`
- * package (workspace-linked), so no lexicon plugin needs to be faked.
+ * package (workspace-linked), so no lexicon plugin needs to be faked. The
+ * temp lexicon dir gets the repo's node_modules linked in so that bare
+ * specifier resolves from the fixture the way it does from a real lexicon
+ * (Vitest 4's module runner resolves from the importing file, not the root).
  */
 
 function writeLexiconDirWithExample(
@@ -35,18 +38,43 @@ describe("checkExamplesBuild", () => {
 
   beforeAll(() => {
     dir = mkdtempSync(join(tmpdir(), "chant-check-lexicon-examples-"));
+    symlinkSync(join(__dirname, "..", "..", "..", "..", "..", "node_modules"), join(dir, "node_modules"), "dir");
   });
   afterAll(() => rmSync(dir, { recursive: true, force: true }));
 
-  test("a clean example builds", async () => {
-    writeLexiconDirWithExample(dir, "clean", {
-      "bucket.ts": `import { Bucket } from "@intentius/chant-lexicon-aws";
+  // A bucket that satisfies the aws lexicon's error-severity checks (#1400):
+  // public access blocked (WAW018) and a TLS-only bucket policy (WAW042).
+  const cleanBucketSource = `import { Bucket, PublicAccessBlockConfiguration, S3BucketPolicy, Ref } from "@intentius/chant-lexicon-aws";
 
 export const appBucket = new Bucket({
   BucketName: "my-app-bucket",
+  PublicAccessBlockConfiguration: new PublicAccessBlockConfiguration({
+    BlockPublicAcls: true,
+    BlockPublicPolicy: true,
+    IgnorePublicAcls: true,
+    RestrictPublicBuckets: true,
+  }),
 });
-`,
-    });
+
+export const appBucketPolicy = new S3BucketPolicy({
+  Bucket: Ref(appBucket),
+  PolicyDocument: {
+    Version: "2012-10-17",
+    Statement: [
+      {
+        Effect: "Deny",
+        Principal: "*",
+        Action: "s3:*",
+        Resource: [appBucket.Arn],
+        Condition: { Bool: { "aws:SecureTransport": "false" } },
+      },
+    ],
+  },
+});
+`;
+
+  test("a clean example builds", async () => {
+    writeLexiconDirWithExample(dir, "clean", { "bucket.ts": cleanBucketSource });
 
     const results = await checkExamplesBuild(dir);
     const clean = results.find((r) => r.example === "clean");
@@ -75,6 +103,44 @@ export const dataBucket = new Bucket({
     expect(broken?.detail).toMatch(/Duplicate export name "dataBucket" found/);
   });
 
+  // chant #1400 — a bare bucket serializes fine, which is all #1067 asked,
+  // but fails the aws lexicon's own WAW018/WAW042 at error severity. This is
+  // the exact shape lambda-api and lambda-s3 shipped in.
+  test("an example that fails its own lexicon's post-synth checks at error severity fails (#1400)", async () => {
+    writeLexiconDirWithExample(dir, "insecure", {
+      "bucket.ts": `import { Bucket } from "@intentius/chant-lexicon-aws";
+
+export const plainBucket = new Bucket({
+  BucketName: "plain-bucket",
+});
+`,
+    });
+
+    const results = await checkExamplesBuild(dir);
+    const insecure = results.find((r) => r.example === "insecure");
+    expect(insecure?.ok).toBe(false);
+    expect(insecure?.detail).toMatch(/post-synth error\(s\) from the lexicon's own checks/);
+    expect(insecure?.detail).toMatch(/WAW042: \[plainBucket\]/);
+  });
+
+  test("an example's own lint.rules severity config applies to post-synth checks (#1400)", async () => {
+    writeLexiconDirWithExample(dir, "suppressed", {
+      "bucket.ts": `import { Bucket } from "@intentius/chant-lexicon-aws";
+
+export const plainBucket = new Bucket({
+  BucketName: "plain-bucket",
+});
+`,
+    });
+    writeFileSync(
+      join(dir, "examples", "suppressed", "chant.config.json"),
+      JSON.stringify({ lint: { rules: { WAW018: "warning", WAW042: "off" } } }),
+    );
+
+    const results = await checkExamplesBuild(dir);
+    expect(results.find((r) => r.example === "suppressed")).toMatchObject({ ok: true });
+  });
+
   test("an empty src/ directory is skipped, not reported as a failure", async () => {
     writeLexiconDirWithExample(dir, "empty", {});
     const results = await checkExamplesBuild(dir);

package/src/cli/commands/check-lexicon-examples.ts

@@ -1,5 +1,6 @@
 /**
- * "Every shipped example builds" (chant #1067).
+ * "Every shipped example builds" (chant #1067) and "every shipped example
+ * passes its own lexicon's post-synth checks" (chant #1400).
  *
  * `check-lexicon.ts`'s existing example checks only count directories
  * ("At least 1 example", "At least 3 examples", "At least 5 examples with
@@ -12,28 +13,29 @@
  * pipeline `chant build` runs and report whether it produced output with no
  * structural error.
  *
- * Scope, deliberately: "builds" here means discovery + serialization
- * succeed (no `DiscoveryError`/`BuildError`, real output produced) — the
- * same thing a `Duplicate export name` failure blocks. It does not
- * additionally require the output to pass every post-synth/lint check
- * (WAW0xx and friends). Those are a separate, already-gated contract
- * (`chant lint`, the post-synth pipeline) with their own severity model and
- * their own CI step; several existing AWS examples (docs-snippets,
- * lambda-api, lambda-s3, shared-alb) currently fail one or more post-synth
- * checks for reasons unrelated to this issue (e.g. WAW042, a TLS-only
- * bucket policy check added after those examples were written). Folding
- * that axis into "does it build" would fail this new check for all of them
- * on its very first run, for defects this issue never set out to fix.
- * Tracked separately; not silently absorbed here.
+ * #1067 scoped "builds" to discovery + serialization on purpose, and said
+ * so here: three aws examples (lambda-api, lambda-s3, shared-alb) failed
+ * WAW042/WAW054 at error severity at the time, for defects that issue never
+ * set out to fix. #1400 fixed those three and added the second axis: after
+ * serialization, the post-synth checks each loaded plugin ships run against
+ * that plugin's own output, exactly as `chant build` runs them (scoped per
+ * plugin, `lint.rules` from the example's chant.config applied), and any
+ * diagnostic left at `error` severity fails the example. Warnings do not.
+ * An example is what a user copies wholesale; it must not teach a pattern
+ * the lexicon it demonstrates flags as an error.
  */
 
 import { existsSync, readdirSync } from "fs";
 import { join } from "path";
-import { build } from "../../build";
+import { build, type BuildResult } from "../../build";
 import { findInfraFiles } from "../../discovery/files";
 import { detectLexicons } from "../../detectLexicon";
 import { loadChantConfig } from "../../config";
 import { loadPlugins } from "../plugins";
+import { runPostSynthChecks, type PostSynthDiagnostic } from "../../lint/post-synth";
+import { applyConfiguredSeverity } from "../../lint/config";
+import type { LexiconPlugin } from "../../lexicon";
+import type { SerializerResult } from "../../serializer";
 
 export interface ExampleBuildResult {
   example: string;
@@ -41,6 +43,43 @@ export interface ExampleBuildResult {
   detail?: string;
 }
 
+/**
+ * Run each plugin's own post-synth checks against that plugin's output —
+ * the same per-plugin scoping and `lint.rules` severity resolution
+ * `cli/commands/build.ts` applies — and return what is left at `error`
+ * severity. Project `lint.policies` are not run here: those are the
+ * example author's organizational policy, not the lexicon's contract.
+ */
+export function postSynthErrors(
+  plugins: LexiconPlugin[],
+  result: BuildResult,
+  lintRules: Parameters<typeof applyConfiguredSeverity>[1],
+): PostSynthDiagnostic[] {
+  const errors: PostSynthDiagnostic[] = [];
+  for (const plugin of plugins) {
+    if (!plugin.postSynthChecks) continue;
+    const checks = plugin.postSynthChecks();
+    if (checks.length === 0) continue;
+
+    const outputKey = plugin.serializer.name;
+    const scopedOutputs = new Map<string, string | SerializerResult>();
+    const pluginOutput = result.outputs.get(outputKey);
+    if (pluginOutput !== undefined) scopedOutputs.set(outputKey, pluginOutput);
+
+    const diags = runPostSynthChecks(checks, { ...result, outputs: scopedOutputs });
+    const { diagnostics } = applyConfiguredSeverity(diags, lintRules);
+    for (const diag of diagnostics) {
+      if (diag.severity === "error") errors.push(diag);
+    }
+  }
+  return errors;
+}
+
+function formatPostSynthError(diag: PostSynthDiagnostic): string {
+  const prefix = diag.entity ? `[${diag.entity}] ` : "";
+  return `${diag.checkId}: ${prefix}${diag.message}`;
+}
+
 /**
  * Build every non-empty example under `<lexiconDir>/examples/*\/src` and
  * report per-example pass/fail. Returns `[]` when the lexicon has no
@@ -94,7 +133,15 @@ export async function checkExamplesBuild(lexiconDir: string): Promise<ExampleBui
 
       const structuralErrors = result.errors.map((e) => e.message);
       const producedOutput = result.outputs.size > 0;
-      const ok = structuralErrors.length === 0 && producedOutput;
+      const structurallyOk = structuralErrors.length === 0 && producedOutput;
+
+      // #1400 — only once the build is structurally sound. A discovery error
+      // already explains the failure, and partial output is not the output
+      // the checks are meant to see.
+      const postSynth = structurallyOk
+        ? postSynthErrors(plugins, result, exampleConfig.lint?.rules)
+        : [];
+      const ok = structurallyOk && postSynth.length === 0;
 
       results.push({
         example: entry.name,
@@ -103,7 +150,9 @@ export async function checkExamplesBuild(lexiconDir: string): Promise<ExampleBui
           ? undefined
           : structuralErrors.length > 0
             ? structuralErrors.join("; ")
-            : "discovered source but produced no output",
+            : !producedOutput
+              ? "discovered source but produced no output"
+              : `post-synth error(s) from the lexicon's own checks: ${postSynth.map(formatPostSynthError).join("; ")}`,
       });
     } catch (err) {
       results.push({

package/src/cli/commands/check-lexicon.test.ts

@@ -17,7 +17,7 @@ describe("checkLexicon", () => {
   test("includes the new #1067 tier-1 checks by name", async () => {
     const result = await checkLexicon(gitlabDir);
     const names = result.items.map((i) => i.name);
-    expect(names).toContain("Every shipped example builds");
+    expect(names).toContain("Every shipped example builds and passes its own post-synth checks");
     expect(names).toContain("Registered intrinsics are exported by the package");
     expect(names).toContain("Registered intrinsics' isTag matches how they're authored");
     expect(names).toContain("dist/manifest.json declares a chantVersion");

package/src/cli/commands/check-lexicon.ts

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "fs";
 import { join, basename } from "path";
 import { auditIntrinsics } from "./check-lexicon-intrinsics";
 import { checkExamplesBuild } from "./check-lexicon-examples";
-import { auditDocsReachability } from "./check-lexicon-docs";
+import { auditDocsClassification, auditDocsReachability } from "./check-lexicon-docs";
 import { auditMcpNames, lexiconNameFor } from "./check-lexicon-mcp";
 import { loadLexiconFromDir, registers, safeList } from "./check-lexicon-plugin";
 import { RULE_CATALOG } from "../../audit/catalog";
@@ -254,12 +254,14 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
   // checks only ever counted example directories; none tried to build one,
   // so `lexicons/aws/examples/core-concepts` shipped with a discovery-time
   // "Duplicate export name" error while this tool reported "All tier-1
-  // checks passed." See ./check-lexicon-examples.ts for exactly what
-  // "builds" means here (discovery + serialization, not post-synth/lint).
+  // checks passed." chant #1400 — and the built output must pass the
+  // lexicon's own post-synth checks at error severity; three aws examples
+  // taught patterns (no TLS-only bucket policy, mutable ECR tags) the
+  // lexicon flags as errors. See ./check-lexicon-examples.ts.
   const exampleBuilds = await checkExamplesBuild(dir);
   const brokenExamples = exampleBuilds.filter((e) => !e.ok);
   items.push({
-    name: "Every shipped example builds",
+    name: "Every shipped example builds and passes its own post-synth checks",
     tier: 1,
     pass: brokenExamples.length === 0,
     detail:
@@ -374,6 +376,19 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
         : undefined,
   });
 
+  // Authored pages name their Diátaxis quadrant; the sidebar is built from
+  // it, so an untagged page cannot be placed (#1731).
+  const docsClass = auditDocsClassification(dir);
+  items.push({
+    name: "Every authored doc page has a diataxis quadrant",
+    tier: 1,
+    pass: !docsClass.hasPages || docsClass.unclassified.length === 0,
+    detail:
+      docsClass.unclassified.length > 0
+        ? `${docsClass.unclassified.length} unclassified: ${docsClass.unclassified.join(", ")}`
+        : undefined,
+  });
+
   // ── Tier 2: Recommended ────────────────────────────────────────
 
   const pluginContent = readOr(join(dir, "src/plugin.ts"));

package/src/cli/commands/init-lexicon/templates/codegen.ts

@@ -67,7 +67,8 @@ export async function generate(options?: { verbose?: boolean; force?: boolean })
  * Write generated files to the package directory.
  */
 export function writeGeneratedFiles(result: GenerateResult, pkgDir?: string): void {
-  const dir = pkgDir ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  // This file lives in src/codegen/, so the package root is three levels up.
+  const dir = pkgDir ?? dirname(dirname(dirname(fileURLToPath(import.meta.url))));
   writeGeneratedArtifacts({
     baseDir: dir,
     files: {
@@ -86,7 +87,9 @@ import { generate, writeGeneratedFiles } from "./generate";
 import { dirname } from "path";
 import { fileURLToPath } from "url";
 
-const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+// src/codegen/generate-cli.ts -> src/codegen -> src -> package root.
+// Two dirnames land in src/ and the first generate writes src/src/generated/ (#1614).
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 const result = await generate({ verbose: true });
 writeGeneratedFiles(result, pkgDir);
 `;

package/src/cli/commands/init-lexicon/templates/docs.ts

@@ -57,16 +57,49 @@ export default defineConfig({
 }
 
 export function generateDocsContentConfig(): string {
-  return `import { defineCollection } from 'astro:content';
+  return `import { defineCollection, z } from 'astro:content';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
 
 export const collections = {
-  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+  docs: defineCollection({
+    loader: docsLoader(),
+    schema: docsSchema({
+      extend: z.object({
+        // Diátaxis quadrant (https://diataxis.fr), chant #1731.
+        diataxis: z.enum(['tutorial', 'how-to', 'reference', 'explanation']).optional(),
+      }),
+    }),
+  }),
 };
 `;
 }
 
+/**
+ * First authored page. Lives under docs/pages/; the docs pipeline copies it
+ * into src/content/docs/ and builds the sidebar from its `diataxis` field.
+ */
+export function generateDocsGettingStartedMdx(name: string): string {
+  const displayName = name.charAt(0).toUpperCase() + name.slice(1);
+  return `---
+title: Getting Started
+description: First project with the ${displayName} lexicon
+diataxis: tutorial
+---
+
+Install the lexicon, declare one resource, and build it.
+
+\`\`\`bash
+npm install --save-dev @intentius/chant-lexicon-${name}
+chant build
+\`\`\`
+
+Replace this with a walkthrough a new user can follow start to finish. Other
+pages go beside this file in \`docs/pages/\`, each with a \`diataxis\` field
+(\`tutorial\`, \`how-to\`, \`reference\` or \`explanation\`).
+`;
+}
+
 export function generateDocsIndexMdx(name: string): string {
   const displayName = name.charAt(0).toUpperCase() + name.slice(1);
   return `---

package/src/cli/commands/init-lexicon.test.ts

@@ -1,5 +1,6 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
-import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync, readdirSync } from "fs";
+import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync, readdirSync, realpathSync } from "fs";
+import { execFileSync } from "child_process";
 import { join, dirname } from "path";
 import { tmpdir } from "os";
 import { fileURLToPath } from "url";
@@ -63,6 +64,7 @@ describe("initLexiconCommand", () => {
       "docs/astro.config.mjs",
       "docs/src/content.config.ts",
       "docs/src/content/docs/index.mdx",
+      "docs/pages/getting-started.mdx",
       "examples/getting-started/package.json",
       "examples/getting-started/src/infra.ts",
       "src/generated/.gitkeep",
@@ -265,6 +267,45 @@ describe("scaffold content validation", () => {
     const content = readFileSync(join(targetDir, "src/lint/rules/index.ts"), "utf-8");
     expect(content).toContain("export const rules");
   });
+
+  // #1614: generate-cli.ts lives in src/codegen/, so the package root is three
+  // dirnames up. Two dirnames is src/, and the first `npm run generate` then
+  // writes src/src/generated/. Run the scaffolded CLI for real with generate.ts
+  // replaced by a stub that reports where it was told to write.
+  test("generate-cli.ts resolves pkgDir to the package root, so generate writes src/generated (#1614)", () => {
+    const cliPath = join(targetDir, "src/codegen/generate-cli.ts");
+    expect(readFileSync(cliPath, "utf-8")).toContain(
+      "dirname(dirname(dirname(fileURLToPath(import.meta.url))))",
+    );
+
+    writeFileSync(
+      join(targetDir, "src/codegen/generate.ts"),
+      [
+        'import { mkdirSync, writeFileSync } from "fs";',
+        'import { join } from "path";',
+        "export async function generate() { return {}; }",
+        "export function writeGeneratedFiles(_result: unknown, pkgDir: string) {",
+        '  const dir = join(pkgDir, "src/generated");',
+        "  mkdirSync(dir, { recursive: true });",
+        '  writeFileSync(join(dir, "lexicon.json"), "{}");',
+        "  process.stdout.write(pkgDir);",
+        "}",
+        "",
+      ].join("\n"),
+    );
+
+    const tsx = join(__dirname, "../../../../../node_modules/.bin/tsx");
+    const out = execFileSync(tsx, [cliPath], { cwd: targetDir, encoding: "utf-8" });
+
+    expect(realpathSync(out.trim())).toBe(realpathSync(targetDir));
+    expect(existsSync(join(targetDir, "src/generated/lexicon.json"))).toBe(true);
+    expect(existsSync(join(targetDir, "src/src"))).toBe(false);
+  });
+
+  test("generate.ts default pkgDir is also the package root (#1614)", () => {
+    const content = readFileSync(join(targetDir, "src/codegen/generate.ts"), "utf-8");
+    expect(content).toContain("pkgDir ?? dirname(dirname(dirname(fileURLToPath(import.meta.url))))");
+  });
 });
 
 // ── Fixture snapshot tests ──────────────────────────────────────────

package/src/cli/commands/init-lexicon.ts

@@ -10,7 +10,7 @@ import { generateSampleRuleTs, generateLintRulesIndexTs } from "./init-lexicon/t
 import { generateLspCompletionsTs, generateLspHoverTs } from "./init-lexicon/templates/lsp";
 import { generatePackageJson, generateTsConfig, generateTsConfigBuild, generateJustfile, generateGitignore, generateReadme, generateSerializerTs, generateValidateTs, generateValidateCliTs } from "./init-lexicon/templates/project";
 import { generatePluginTestTs, generateSerializerTestTs, generateCompletionsTestTs, generateHoverTestTs } from "./init-lexicon/templates/tests";
-import { generateDocsPackageJson, generateDocsTsConfig, generateDocsAstroConfig, generateDocsContentConfig, generateDocsIndexMdx } from "./init-lexicon/templates/docs";
+import { generateDocsPackageJson, generateDocsTsConfig, generateDocsAstroConfig, generateDocsContentConfig, generateDocsIndexMdx, generateDocsGettingStartedMdx } from "./init-lexicon/templates/docs";
 import { generateExamplePackageJson, generateExampleInfraTs } from "./init-lexicon/templates/examples";
 
 /**
@@ -115,6 +115,7 @@ export async function initLexiconCommand(options: InitLexiconOptions): Promise<I
     "docs/src",
     "docs/src/content",
     "docs/src/content/docs",
+    "docs/pages",
     "examples/getting-started",
     "examples/getting-started/src",
   ];
@@ -159,6 +160,7 @@ export async function initLexiconCommand(options: InitLexiconOptions): Promise<I
     "docs/astro.config.mjs": generateDocsAstroConfig(name),
     "docs/src/content.config.ts": generateDocsContentConfig(),
     "docs/src/content/docs/index.mdx": generateDocsIndexMdx(name),
+    "docs/pages/getting-started.mdx": generateDocsGettingStartedMdx(name),
     "examples/getting-started/package.json": generateExamplePackageJson(name),
     "examples/getting-started/src/infra.ts": generateExampleInfraTs(name, names),
   };

package/src/cli/commands/lexicon-rolling-upgrade.ts

@@ -46,7 +46,7 @@ export async function runRollingUpgrade(
       lexicon: "aws",
       hasUpgrade: false,
       severity: "none",
-      delta: { added: [], changed: [], removed: [], severity: "none" },
+      delta: { added: [], changed: [], removed: [], renamed: [], severity: "none" },
       deltaText: "",
       validationOk: false,
       failures: [{ step: "setup", output: `Lexicon directory not found: ${dir}` }],

package/src/cli/commands/lexicon-surface-diff.test.ts

@@ -21,7 +21,7 @@ function result(over: Partial<RegenResult>): RegenResult {
     ok: true,
     changed: true,
     severity: "additive",
-    delta: { added: [], changed: [], removed: [], severity: "additive" },
+    delta: { added: [], changed: [], removed: [], renamed: [], severity: "additive" },
     deltaText: "",
     failures: [],
     freshSnapshot: { surface: "x" } as unknown as RegenResult["freshSnapshot"],

package/src/cli/commands/lexicon-surface-diff.ts

@@ -62,7 +62,7 @@ export async function runSurfaceDiff(opts: SurfaceDiffOptions): Promise<RegenRes
       ok: false,
       changed: false,
       severity: "none",
-      delta: { added: [], changed: [], removed: [], severity: "none" },
+      delta: { added: [], changed: [], removed: [], renamed: [], severity: "none" },
       deltaText: "",
       failures: [failure],
       freshSnapshot: null,