@intentius/chant 0.44.14 → 0.46.0

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

@@ -9,6 +9,12 @@
  *
  * The snapshot file is written to `<lexicon-dir>/surface.snapshot.json`.
  * Pass `--update-snapshot` to commit the fresh snapshot after a successful run.
+ *
+ * An update run is exempt from the `surface-matches-snapshot` validate check
+ * and from nothing else (#1825): that check fails on the stale baseline the
+ * run exists to replace, and with an `"always"` gate (#1475) the documented
+ * re-baseline flow would deadlock. Any other failing step still refuses the
+ * write, so a broken generate cannot be baselined.
  */
 
 import { existsSync, readFileSync } from "fs";
@@ -62,7 +68,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,
@@ -78,6 +84,9 @@ export async function runSurfaceDiff(opts: SurfaceDiffOptions): Promise<RegenRes
     skipLint: opts.skipLint,
     skipExamples: !opts.runExamples,
     pinnedDigestPath: opts.pinnedDigestPath,
+    // The update run skips only the surface-matches-snapshot validate check —
+    // the staleness it is about to fix (#1825).
+    updatingSnapshot: opts.updateSnapshot,
   });
 
   // Update snapshot when requested and the run succeeded

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

@@ -0,0 +1,112 @@
+/**
+ * `--update-snapshot` against a failing snapshot gate (#1825).
+ *
+ * Since #1475 the k8s/azure gates run in "always" mode, so a stale baseline
+ * fails validate on every run — including the update run whose whole purpose
+ * is to replace that baseline. These tests run the real pipeline (no mocks)
+ * against a fixture lexicon whose validate script behaves like an "always"
+ * gate: it fails while the committed snapshot is stale, unless the run is
+ * exempted via CHANT_SNAPSHOT_UPDATE.
+ */
+
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { runSurfaceDiff } from "./lexicon-surface-diff";
+import { SNAPSHOT_FILENAME } from "../../codegen/lexicon-regen";
+import { parseSnapshot } from "../../codegen/surface-snapshot";
+
+const STALE_SNAPSHOT = JSON.stringify({
+  schemaVersion: 1,
+  generatedAt: "2026-01-01T00:00:00.000Z",
+  entries: { Queue: { kind: "resource", resourceType: "X::Y::Queue", attrs: [], props: [] } },
+});
+
+const GENERATE_SCRIPT = `node -e "
+const fs = require('fs');
+const path = require('path');
+const dir = path.join(process.cwd(), 'src', 'generated');
+fs.mkdirSync(dir, { recursive: true });
+fs.writeFileSync(path.join(dir, 'lexicon-test.json'), JSON.stringify({Widget:{kind:'resource',resourceType:'X::Y::Widget',attrs:{Id:'Id'}}}));
+fs.writeFileSync(path.join(dir, 'index.d.ts'), 'export declare class Widget { constructor(props: { Name?: string; }); readonly Id: string; }');
+"`;
+
+// Emulates a checkSurfaceSnapshot: "always" gate: fail while the committed
+// snapshot does not describe the generated surface, unless the run carries the
+// update exemption.
+const GATED_VALIDATE_SCRIPT = `node -e "
+if (process.env.CHANT_SNAPSHOT_UPDATE === '1') process.exit(0);
+const fs = require('fs');
+const path = require('path');
+const snap = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'surface.snapshot.json'), 'utf-8'));
+process.exit(snap.entries && snap.entries.Widget ? 0 : 1);
+"`;
+
+function makeLexiconDir(validateScript: string): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-sd-update-"));
+  const pkg = {
+    name: "@intentius/chant-lexicon-test",
+    version: "0.1.0",
+    type: "module",
+    scripts: {
+      generate: GENERATE_SCRIPT,
+      validate: validateScript,
+    },
+  };
+  writeFileSync(join(dir, "package.json"), JSON.stringify(pkg, null, 2));
+  writeFileSync(join(dir, SNAPSHOT_FILENAME), STALE_SNAPSHOT);
+  return dir;
+}
+
+const baseOpts = { skipBundle: true, skipBuild: true, skipLint: true };
+
+describe("surface-diff --update-snapshot vs. an \"always\" snapshot gate (#1825)", () => {
+  test("without --update-snapshot the stale snapshot still fails validate", async () => {
+    const dir = makeLexiconDir(GATED_VALIDATE_SCRIPT);
+    try {
+      const result = await runSurfaceDiff({ lexiconDir: dir, ...baseOpts });
+      expect(result.ok).toBe(false);
+      expect(result.failures.some((f) => f.step === "validate")).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("stale snapshot + healthy codegen: the update succeeds and the snapshot matches after", async () => {
+    const dir = makeLexiconDir(GATED_VALIDATE_SCRIPT);
+    try {
+      const result = await runSurfaceDiff({ lexiconDir: dir, ...baseOpts, updateSnapshot: true });
+      expect(result.ok).toBe(true);
+      expect(result.failures).toEqual([]);
+
+      // The baseline now describes the generated surface, not the stale one.
+      const written = parseSnapshot(readFileSync(join(dir, SNAPSHOT_FILENAME), "utf-8"));
+      expect(written.entries.Widget).toBeDefined();
+      expect(written.entries.Queue).toBeUndefined();
+
+      // A second run against the fresh baseline is green with no exemption.
+      const rerun = await runSurfaceDiff({ lexiconDir: dir, ...baseOpts });
+      expect(rerun.ok).toBe(true);
+      expect(rerun.changed).toBe(false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("stale snapshot + another failing validate check: the update refuses", async () => {
+    // A validate that fails even with the exemption stands in for any check
+    // other than surface-matches-snapshot. The exemption covers only the
+    // staleness check, so a broken generate cannot be baselined.
+    const dir = makeLexiconDir("node -e \"process.exit(1)\"");
+    try {
+      const result = await runSurfaceDiff({ lexiconDir: dir, ...baseOpts, updateSnapshot: true });
+      expect(result.ok).toBe(false);
+      expect(result.failures.some((f) => f.step === "validate")).toBe(true);
+      // The stale baseline is untouched.
+      expect(readFileSync(join(dir, SNAPSHOT_FILENAME), "utf-8")).toBe(STALE_SNAPSHOT);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/cli/commands/lint.ts

@@ -20,6 +20,8 @@ import { GENERATED_MARKER } from "../../discovery/files";
 
 // Import config loader
 import { loadConfig, resolveRulesForFile, resolveConfiguredSeverity, findProjectRoot } from "../../lint/config";
+import { loadChantConfig } from "../../config";
+import type { LintProjectConfig } from "../../lint/rule";
 
 /**
  * Type guard to check if a value conforms to the LintRule interface.
@@ -447,6 +449,17 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   const config = loadConfig(projectRoot);
   const hasOverrides = config.overrides && config.overrides.length > 0;
 
+  // chant #1221 — the project's chant.config slice for config-aware rules
+  // (COR021 reads `environments` + `ownership`), threaded into every
+  // runLint() call below via LintContext.projectConfig. Best-effort: a
+  // directory with no project config lints with those rules silent.
+  let projectConfig: LintProjectConfig | undefined;
+  try {
+    projectConfig = (await loadChantConfig(projectRoot)).config as LintProjectConfig;
+  } catch {
+    projectConfig = undefined;
+  }
+
   // Load all rules from lexicon plugins (core "chant" + lexicon-specific)
   const loaded = await loadAllPluginRules(projectRoot);
   let allRules = loaded.rules;
@@ -470,7 +483,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   let diagnostics: LintDiagnostic[];
   let suppressed: Array<LintDiagnostic & { reason?: string }> = [];
   if (options.rules) {
-    const result = await runLint(files, options.rules, undefined, intrinsics);
+    const result = await runLint(files, options.rules, undefined, intrinsics, projectConfig);
     diagnostics = result.diagnostics;
     suppressed = result.suppressed;
   } else if (hasOverrides) {
@@ -478,13 +491,13 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     for (const file of files) {
       const relativePath = relative(projectRoot, file);
       const { rules: fileRules, ruleOptions } = getDefaultRules(projectRoot, relativePath, allRules);
-      const result = await runLint([file], fileRules, ruleOptions, intrinsics);
+      const result = await runLint([file], fileRules, ruleOptions, intrinsics, projectConfig);
       diagnostics.push(...result.diagnostics);
       suppressed.push(...result.suppressed);
     }
   } else {
     const { rules, ruleOptions } = getDefaultRules(projectRoot, undefined, allRules);
-    const result = await runLint(files, rules, ruleOptions, intrinsics);
+    const result = await runLint(files, rules, ruleOptions, intrinsics, projectConfig);
     diagnostics = result.diagnostics;
     suppressed = result.suppressed;
   }
@@ -518,7 +531,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
 
     // Re-lint after fixes to get updated diagnostics
     if (options.rules) {
-      const postResult = await runLint(files, options.rules, undefined, intrinsics);
+      const postResult = await runLint(files, options.rules, undefined, intrinsics, projectConfig);
       diagnostics = postResult.diagnostics;
       suppressed = postResult.suppressed;
     } else if (hasOverrides) {
@@ -527,13 +540,13 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
       for (const file of files) {
         const relativePath = relative(projectRoot, file);
         const { rules: fileRules, ruleOptions } = getDefaultRules(projectRoot, relativePath, allRules);
-        const postResult = await runLint([file], fileRules, ruleOptions, intrinsics);
+        const postResult = await runLint([file], fileRules, ruleOptions, intrinsics, projectConfig);
         diagnostics.push(...postResult.diagnostics);
         suppressed.push(...postResult.suppressed);
       }
     } else {
       const { rules, ruleOptions } = getDefaultRules(projectRoot, undefined, allRules);
-      const postResult = await runLint(files, rules, ruleOptions, intrinsics);
+      const postResult = await runLint(files, rules, ruleOptions, intrinsics, projectConfig);
       diagnostics = postResult.diagnostics;
       suppressed = postResult.suppressed;
     }