@intentius/chant 0.124.13 → 0.124.15

package/dist/codegen/testdata/postgres-tags.json

@@ -0,0 +1,242 @@
+[
+ {
+  "name": "REL_19_BETA4",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_19_BETA3",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_19_BETA2",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_19_BETA1",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_6",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_5",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_4",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_3",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_2",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_1",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_0",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_RC1",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_BETA3",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_BETA2",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_BETA1",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_17_11",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_17_10",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_17_9",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_17_0",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_17_RC1",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_17_BETA1",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_16_15",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_16_9",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_16_0",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_15_19",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_15_2",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_14_24",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_14_9",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_13_23",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_12_22",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_11_22",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_10_23",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL9_6_24",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL9_5_25",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL8_4_22",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL8_0_26",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL7_4_30",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "Release_2_0",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "Release_1_0",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ },
+ {
+  "name": "REL_18_STABLE",
+  "commit": {
+   "sha": "0000000000000000000000000000000000000000"
+  }
+ }
+]

package/dist/codegen/topo-sort.js

@@ -0,0 +1,36 @@
+/**
+ * Generic DFS-based topological sort.
+ */
+/**
+ * Sort nodes in topological order (dependencies first).
+ *
+ * @param nodes - The items to sort.
+ * @param getId - Extract a unique identifier from a node.
+ * @param getEdges - Return the IDs of nodes that `node` depends on.
+ * @returns Sorted array where dependencies appear before dependents.
+ */
+export function topoSort(nodes, getId, getEdges) {
+    const result = [];
+    const added = new Set();
+    const nodeMap = new Map();
+    for (const node of nodes) {
+        nodeMap.set(getId(node), node);
+    }
+    function visit(node) {
+        const id = getId(node);
+        if (added.has(id))
+            return;
+        for (const dep of getEdges(node)) {
+            const depNode = nodeMap.get(dep);
+            if (depNode && !added.has(dep)) {
+                visit(depNode);
+            }
+        }
+        result.push(node);
+        added.add(id);
+    }
+    for (const node of nodes) {
+        visit(node);
+    }
+    return result;
+}

package/dist/codegen/typecheck.js

@@ -0,0 +1,115 @@
+/**
+ * Type-check generated .d.ts files by spawning tsc.
+ */
+import { writeFileSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { createRequire } from "module";
+import { getRuntime } from "../runtime-adapter.js";
+// Resolve tsc binary path — works regardless of cwd when spawning.
+function resolveTsc() {
+    try {
+        const req = createRequire(import.meta.url);
+        const tscPkg = req.resolve("typescript/bin/tsc");
+        return tscPkg;
+    }
+    catch {
+        return "tsc";
+    }
+}
+/**
+ * Minimal TypeScript lib stub — declares just enough built-in types for
+ * validating generated .d.ts files without needing the full standard library.
+ * This avoids transient failures from corrupted bunx TypeScript caches.
+ */
+const MINIMAL_LIB = `
+interface Array<T> { length: number; [n: number]: T; }
+interface ReadonlyArray<T> { length: number; readonly [n: number]: T; }
+interface String { length: number; }
+interface Boolean {}
+interface Number {}
+interface Function {}
+interface CallableFunction extends Function {}
+interface NewableFunction extends Function {}
+interface Object {}
+interface RegExp {}
+interface IArguments {}
+interface Symbol {}
+type Record<K extends string | number | symbol, V> = { [P in K]: V; };
+type Partial<T> = { [P in keyof T]?: T[P]; };
+type Required<T> = { [P in keyof T]-?: T[P]; };
+type Readonly<T> = { readonly [P in keyof T]: T[P]; };
+type Pick<T, K extends keyof T> = { [P in K]: T[P]; };
+type Omit<T, K extends string | number | symbol> = Pick<T, Exclude<keyof T, K>>;
+type Exclude<T, U> = T extends U ? never : T;
+type Extract<T, U> = T extends U ? T : never;
+type NonNullable<T> = T extends null | undefined ? never : T;
+type ReturnType<T extends (...args: any) => any> = T extends (...args: any) => infer R ? R : any;
+type InstanceType<T extends abstract new (...args: any) => any> = T extends abstract new (...args: any) => infer R ? R : any;
+type Promise<T> = { then<TResult>(onfulfilled?: (value: T) => TResult): Promise<TResult>; };
+interface TemplateStringsArray extends ReadonlyArray<string> { readonly raw: readonly string[]; }
+`;
+/**
+ * Type-check a .d.ts content string by writing to a temp file and running tsc.
+ */
+export async function typecheckDTS(content) {
+    // Create temp directory
+    const dir = join(tmpdir(), `chant-typecheck-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(dir, { recursive: true });
+    try {
+        // Write the .d.ts file
+        const dtsPath = join(dir, "index.d.ts");
+        writeFileSync(dtsPath, content);
+        // Write a minimal lib stub so tsc doesn't depend on a full TypeScript
+        // standard library installation (avoids bunx cache corruption issues).
+        writeFileSync(join(dir, "lib.d.ts"), MINIMAL_LIB);
+        // Write stubs for @intentius/chant sub-path imports used in generated .d.ts files.
+        // tsc runs in a temp dir with no node_modules, so these must be declared manually.
+        const chantDeclarableDir = join(dir, "node_modules", "@intentius", "chant", "declarable");
+        mkdirSync(chantDeclarableDir, { recursive: true });
+        writeFileSync(join(chantDeclarableDir, "index.d.ts"), `export interface Declarable<TProps = Record<string, unknown>> { props: TProps; }\n`);
+        writeFileSync(join(chantDeclarableDir, "package.json"), JSON.stringify({ name: "@intentius/chant/declarable", main: "index.d.ts", types: "index.d.ts" }));
+        // Write a minimal tsconfig — noLib: true prevents tsc from looking for
+        // standard lib files; our lib.d.ts is included via the include array.
+        const tsconfig = {
+            compilerOptions: {
+                strict: true,
+                noEmit: true,
+                skipLibCheck: false,
+                noLib: true,
+                target: "ES2022",
+                module: "ES2022",
+                moduleResolution: "bundler",
+            },
+            include: ["lib.d.ts", "index.d.ts"],
+        };
+        writeFileSync(join(dir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2));
+        // Run tsc using absolute path to avoid npx/cwd resolution issues
+        const rt = getRuntime();
+        const tscBin = resolveTsc();
+        const cmd = tscBin === "tsc"
+            ? [rt.commands.exec, "tsc", "--noEmit", "--project", "tsconfig.json"]
+            : [rt.commands.runner, tscBin, "--noEmit", "--project", "tsconfig.json"];
+        const { stdout, stderr, exitCode } = await rt.spawn(cmd, { cwd: dir });
+        // Parse diagnostics from stdout (tsc writes errors to stdout)
+        const output = stdout + stderr;
+        const diagnostics = output
+            .split("\n")
+            .filter((line) => line.trim().length > 0)
+            .filter((line) => /error TS\d+/.test(line) || /:\d+:\d+/.test(line));
+        return {
+            ok: exitCode === 0,
+            diagnostics,
+            fileCount: 1,
+        };
+    }
+    finally {
+        // Cleanup
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // Best effort cleanup
+        }
+    }
+}

package/dist/codegen/validate.js

@@ -0,0 +1,200 @@
+/**
+ * Generic validation framework for lexicon artifacts.
+ *
+ * Provides configurable validation checks that any lexicon can use
+ * by passing lexicon-specific configuration.
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { computeCoverage, checkThresholds } from "./coverage.js";
+import { extractSurface, diffSurface, parseSnapshot, formatDelta } from "./surface-snapshot.js";
+/**
+ * Set by the publish workflow to arm the release-time surface gate
+ * (chant #1473). Absent in ordinary CI, where upstream drift is expected.
+ */
+export const RELEASE_GATE_ENV = "CHANT_RELEASE_GATE";
+/**
+ * Set by `chant dev surface-diff --update-snapshot` for the validate run it
+ * performs before rewriting the baseline (chant #1825). When set to "1", the
+ * `surface-matches-snapshot` check is skipped. That check fails on exactly the
+ * staleness the update run exists to fix, and with an `"always"` gate (#1475)
+ * the two would deadlock: validate cannot pass until the snapshot is updated,
+ * and the snapshot cannot be updated until validate passes. Every other check
+ * still runs, so a broken generate cannot be baselined.
+ */
+export const SNAPSHOT_UPDATE_ENV = "CHANT_SNAPSHOT_UPDATE";
+/**
+ * Validate generated lexicon artifacts using the provided configuration.
+ */
+export async function validateLexiconArtifacts(config) {
+    const generatedDir = config.generatedDir ?? join(config.basePath, "src", "generated");
+    const checks = [];
+    // Check 1: lexicon JSON exists and parses
+    const lexiconPath = join(generatedDir, config.lexiconJsonFilename);
+    let lexiconData = null;
+    if (!existsSync(lexiconPath)) {
+        checks.push({ name: "lexicon-json-exists", ok: false, error: `${config.lexiconJsonFilename} not found` });
+    }
+    else {
+        try {
+            const raw = readFileSync(lexiconPath, "utf-8");
+            lexiconData = JSON.parse(raw);
+            checks.push({ name: "lexicon-json-exists", ok: true });
+        }
+        catch (err) {
+            checks.push({
+                name: "lexicon-json-exists",
+                ok: false,
+                error: `Failed to parse ${config.lexiconJsonFilename}: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    // Check 2: index.d.ts exists
+    const dtsPath = join(generatedDir, "index.d.ts");
+    if (!existsSync(dtsPath)) {
+        checks.push({ name: "types-exist", ok: false, error: "index.d.ts not found" });
+    }
+    else {
+        checks.push({ name: "types-exist", ok: true });
+    }
+    // Check 3: Required backward-compatible names present in lexicon JSON
+    if (lexiconData && config.requiredNames.length > 0) {
+        const keys = Object.keys(lexiconData);
+        const present = config.requiredNamesMatchSubstring
+            ? (name) => keys.some((k) => k.includes(name))
+            : (name) => name in lexiconData;
+        const missing = config.requiredNames.filter((name) => !present(name));
+        if (missing.length > 0) {
+            checks.push({
+                name: "required-names",
+                ok: false,
+                error: `Missing required names: ${missing.join(", ")}`,
+            });
+        }
+        else {
+            checks.push({ name: "required-names", ok: true });
+        }
+    }
+    else if (!lexiconData && config.requiredNames.length > 0) {
+        checks.push({
+            name: "required-names",
+            ok: false,
+            error: "Skipped — lexicon JSON not available",
+        });
+    }
+    // Check 4: Coverage thresholds (only if lexicon JSON was loaded)
+    if (lexiconData && config.coverageThresholds) {
+        try {
+            const raw = readFileSync(lexiconPath, "utf-8");
+            const report = computeCoverage(raw);
+            const result = checkThresholds(report, config.coverageThresholds);
+            if (result.ok) {
+                checks.push({ name: "coverage-thresholds", ok: true });
+            }
+            else {
+                checks.push({
+                    name: "coverage-thresholds",
+                    ok: false,
+                    error: result.violations.join("; "),
+                });
+            }
+        }
+        catch (err) {
+            checks.push({
+                name: "coverage-thresholds",
+                ok: false,
+                error: `Coverage check failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    // Check 5: Type-check generated .d.ts
+    if (existsSync(dtsPath)) {
+        try {
+            const { typecheckDTS } = await import("./typecheck.js");
+            const dtsContent = readFileSync(dtsPath, "utf-8");
+            const tcResult = await typecheckDTS(dtsContent);
+            if (tcResult.ok) {
+                checks.push({ name: "types-compile", ok: true });
+            }
+            else {
+                checks.push({
+                    name: "types-compile",
+                    ok: false,
+                    error: `TypeScript errors: ${tcResult.diagnostics.slice(0, 5).join("; ")}`,
+                });
+            }
+        }
+        catch (err) {
+            checks.push({
+                name: "types-compile",
+                ok: false,
+                error: `Type-check failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    // Check: the generated API matches the reviewed one (chant #1473).
+    //
+    // This is the gate that makes a release trustworthy. `prepack` regenerates
+    // from upstream, and for aws that upstream republishes schemas several times
+    // a day, so the input can differ from the one whose delta a human accepted.
+    // What must not differ is the API that ships. Comparing the just-generated
+    // artifacts against the committed `surface.snapshot.json` says exactly that,
+    // and says nothing about byte churn that changed no declaration.
+    //
+    // Runs on the artifacts already on disk — no second generation — and is
+    // skipped for a lexicon with no committed snapshot, which is the case for a
+    // new lexicon before its first baseline.
+    //
+    // A re-baseline run (`chant dev surface-diff --update-snapshot`) sets
+    // {@link SNAPSHOT_UPDATE_ENV} and is exempt: the check would fail on the
+    // stale snapshot that run is about to rewrite, deadlocking the documented
+    // update flow against an `"always"` gate (#1825). Only this check is exempt —
+    // every other check above still gates the run.
+    const snapshotPath = join(config.basePath, "surface.snapshot.json");
+    const env = config.env ?? process.env;
+    const surfaceGate = (config.checkSurfaceSnapshot === "always" ||
+        (config.checkSurfaceSnapshot === true && env[RELEASE_GATE_ENV] === "1")) &&
+        env[SNAPSHOT_UPDATE_ENV] !== "1";
+    if (surfaceGate && lexiconData && existsSync(snapshotPath) && existsSync(dtsPath)) {
+        try {
+            const fresh = extractSurface(readFileSync(lexiconPath, "utf-8"), readFileSync(dtsPath, "utf-8"));
+            const delta = diffSurface(parseSnapshot(readFileSync(snapshotPath, "utf-8")), fresh);
+            const moved = delta.added.length + delta.removed.length + delta.renamed.length + delta.changed.length;
+            checks.push(moved === 0
+                ? { name: "surface-matches-snapshot", ok: true }
+                : {
+                    name: "surface-matches-snapshot",
+                    ok: false,
+                    error: `The generated API differs from the reviewed surface.snapshot.json ` +
+                        `(${delta.added.length} added, ${delta.removed.length} removed, ${delta.renamed.length} renamed, ${delta.changed.length} changed). ` +
+                        `Accept it deliberately with \`chant dev surface-diff <lexicon> --update-snapshot --bump\`, ` +
+                        `never as a side effect of a release.\n${formatDelta(delta)}`,
+                });
+        }
+        catch (err) {
+            checks.push({
+                name: "surface-matches-snapshot",
+                ok: false,
+                error: `Failed to compare against surface.snapshot.json: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    return {
+        success: checks.every((c) => c.ok),
+        checks,
+    };
+}
+/**
+ * Print validation results to stderr and throw on failure.
+ */
+export function printValidationResult(result) {
+    for (const check of result.checks) {
+        const status = check.ok ? "OK" : "FAIL";
+        const msg = check.error ? ` — ${check.error}` : "";
+        console.error(`  [${status}] ${check.name}${msg}`);
+    }
+    if (!result.success) {
+        throw new Error("Validation failed");
+    }
+    console.error("All validation checks passed.");
+}

package/dist/codegen/version-bump.js

@@ -0,0 +1,35 @@
+/**
+ * 0.x-aware version bumping, shared by the pinned upgrade Op (#549) and the
+ * rolling drift re-baseline (#616). Centralised here so the single source of
+ * truth for the semver rule can't drift between the two callers.
+ */
+import { readFileSync, writeFileSync } from "fs";
+/**
+ * Compute a bumped semver from a current version and a surface severity.
+ *
+ * Pre-1.0 (major 0) never auto-promotes to 1.0.0: breaking → minor, additive →
+ * patch. At >= 1.0.0: breaking → major, additive → minor. Returns null for
+ * "none" or a version string that can't be parsed as MAJOR.MINOR.PATCH.
+ */
+export function bumpForSeverity(current, severity) {
+    if (severity === "none")
+        return null;
+    const parts = current.replace(/^v/, "").split(".").map(Number);
+    if (parts.length < 3 || parts.some((n) => Number.isNaN(n) || n < 0))
+        return null;
+    const [major, minor, patch] = parts;
+    if (major === 0) {
+        return severity === "breaking" ? `0.${minor + 1}.0` : `0.${minor}.${patch + 1}`;
+    }
+    return severity === "breaking" ? `${major + 1}.0.0` : `${major}.${minor + 1}.0`;
+}
+/**
+ * Read a package.json, set its `version`, and write it back — preserving all
+ * other fields, 2-space indent, and a trailing newline.
+ */
+export function bumpPackageJsonVersion(packageJsonPath, newVersion) {
+    const raw = readFileSync(packageJsonPath, "utf-8");
+    const pkg = JSON.parse(raw);
+    pkg["version"] = newVersion;
+    writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+}