@intentius/chant 0.124.12 → 0.124.14

package/dist/codegen/json-schema.js

@@ -0,0 +1,246 @@
+/**
+ * Generic JSON Schema resolution utilities for lexicon code generation.
+ *
+ * These functions handle the common subset of JSON Schema used by
+ * infrastructure-as-code formats (CloudFormation, Terraform, Azure ARM, etc.).
+ * Lexicon-specific entry points call these with a `resolveDefName` callback
+ * to produce their own naming conventions.
+ */
+// --- Functions ---
+/** Shared empty cycle guard, so the common call allocates nothing. */
+const EMPTY_SEEN = new Set();
+/**
+ * Get the primary type from a type field that can be string or string[].
+ * Returns first non-"null" type, or "any" if empty.
+ */
+export function primaryType(type) {
+    if (!type)
+        return "any";
+    if (typeof type === "string")
+        return type;
+    for (const t of type) {
+        if (t !== "null")
+            return t;
+    }
+    return type.length > 0 ? type[0] : "any";
+}
+/** The branch list a property carries under `oneOf` or `anyOf`, or undefined. */
+function branchesOf(prop) {
+    if (prop.oneOf && prop.oneOf.length > 0)
+        return prop.oneOf;
+    if (prop.anyOf && prop.anyOf.length > 0)
+        return prop.anyOf;
+    return undefined;
+}
+/** A union of string literals, sorted, from a list of enum values. */
+function enumUnion(values) {
+    return [...values].sort().map((v) => JSON.stringify(v)).join(" | ");
+}
+/**
+ * `T[]`, parenthesized when `T` is a union.
+ *
+ * `[]` binds tighter than `|`, so an unparenthesized `"a" | "b"[]` reads as
+ * `"a" | ("b"[])`: it accepts the bare string `"a"` and rejects `["a"]`.
+ */
+function arrayOf(itemType) {
+    return itemType.includes(" | ") ? `(${itemType})[]` : `${itemType}[]`;
+}
+/**
+ * The branch of a `oneOf`/`anyOf` that narrows a string property to an enum.
+ *
+ * CloudFormation writes several string properties as a `type: "string"` beside
+ * a branch list whose first branch is the real enum and whose other branches
+ * are case-insensitive `pattern`s for the same values (`AWS::AmazonMQ::Broker`'s
+ * `EngineType`). The branch list relaxes the enum rather than summing shapes, so
+ * the enum is the useful type. Only strings qualify: anything else is a real sum.
+ */
+function relaxedEnumBranch(prop, branches) {
+    if (prop.type !== undefined && primaryType(prop.type) !== "string")
+        return undefined;
+    for (const b of branches) {
+        if (!b.enum || b.enum.length === 0)
+            continue;
+        if (b.type !== undefined && primaryType(b.type) !== "string")
+            return undefined;
+        if (!b.enum.every((v) => typeof v === "string"))
+            return undefined;
+        return b.enum;
+    }
+    return undefined;
+}
+/**
+ * The single content-bearing branch of an `allOf`, when that is the whole shape.
+ *
+ * Every `allOf` in the CloudFormation Registry is one `$ref` beside an
+ * annotation object (`{ "default": "MCP" }`), which types exactly as the `$ref`
+ * alone. An `allOf` that intersects two real shapes has no single answer and is
+ * left to the caller.
+ */
+function soleTypedBranch(branches) {
+    const typed = branches.filter((b) => b.$ref || b.type || b.properties || b.items || (b.enum && b.enum.length > 0) || branchesOf(b));
+    return typed.length === 1 ? typed[0] : undefined;
+}
+/**
+ * Resolve a schema property to its TypeScript type string.
+ *
+ * @param prop - The property to resolve
+ * @param schema - The containing schema document (for $ref resolution)
+ * @param resolveDefName - Callback to produce a TypeScript name from a definition.
+ *   Receives (defName: string) and should return the TS type name for that definition.
+ *   When null, $ref to object definitions resolves to "any".
+ * @param seen - Definition names already on the current resolution path, so a
+ *   list definition that reaches itself terminates instead of recursing forever.
+ */
+export function resolvePropertyType(prop, schema, resolveDefName, seen = EMPTY_SEEN) {
+    if (!prop)
+        return "any";
+    // `allOf` of one real branch and some annotations types as that branch.
+    if (prop.allOf && prop.allOf.length > 0 && !prop.$ref && !prop.type && !prop.enum) {
+        const sole = soleTypedBranch(prop.allOf);
+        if (sole)
+            return resolvePropertyType(sole, schema, resolveDefName, seen);
+    }
+    const branches = branchesOf(prop);
+    if (branches) {
+        // A branch list beside a `type` relaxes that type; the enum branch, when
+        // there is one, is the narrowest reading of it.
+        const relaxed = relaxedEnumBranch(prop, branches);
+        if (relaxed)
+            return enumUnion(relaxed);
+        // With nothing beside it the branch list is a sum of shapes, which this
+        // emitter does not express yet (chant #2278).
+        if (!prop.$ref && !prop.type && !(prop.enum && prop.enum.length > 0))
+            return "any";
+        // Otherwise fall through and read the sibling keywords.
+    }
+    // Handle $ref
+    if (prop.$ref) {
+        return resolveRef(prop.$ref, schema, resolveDefName, seen);
+    }
+    // Inline enum → union of string literals
+    if (prop.enum && prop.enum.length > 0) {
+        return enumUnion(prop.enum);
+    }
+    const pt = primaryType(prop.type);
+    switch (pt) {
+        case "string":
+            return "string";
+        case "integer":
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "array":
+            if (prop.items) {
+                return arrayOf(resolvePropertyType(prop.items, schema, resolveDefName, seen));
+            }
+            return "any[]";
+        case "object":
+            return "Record<string, any>";
+        default:
+            return "any";
+    }
+}
+/**
+ * Resolve a $ref pointer to a TypeScript type name.
+ *
+ * @param ref - The $ref string (e.g. "#/definitions/Foo")
+ * @param schema - The containing schema document
+ * @param resolveDefName - Callback to produce a TS name for object definitions.
+ *   Receives (defName: string). When null, object defs resolve to "any".
+ */
+export function resolveRef(ref, schema, resolveDefName, seen = EMPTY_SEEN) {
+    const prefix = "#/definitions/";
+    if (!ref.startsWith(prefix))
+        return "any";
+    const defName = ref.slice(prefix.length);
+    const def = schema.definitions?.[defName];
+    if (!def)
+        return "any";
+    // A list definition whose items reach it again would recurse without end.
+    if (seen.has(defName))
+        return "any";
+    // String enum → named type (via resolveDefName) or string
+    if (isEnumDefinition(def)) {
+        return resolveDefName ? resolveDefName(defName) : "string";
+    }
+    // Object with properties → named type
+    if (def.properties) {
+        return resolveDefName ? resolveDefName(defName) : "any";
+    }
+    // Primitive type
+    if (def.type) {
+        const pt = primaryType(def.type);
+        switch (pt) {
+            case "string": return "string";
+            case "integer":
+            case "number": return "number";
+            case "boolean": return "boolean";
+            case "object": return "Record<string, any>";
+            // CloudFormation names its list shapes: `Tags` is a `$ref` to a `TagList`
+            // definition whose items are the `Tag` definition one hop away. Resolve
+            // through `items` the way the inline `array` case does. (chant #2205)
+            case "array": {
+                if (!def.items)
+                    return "any[]";
+                const nested = new Set(seen);
+                nested.add(defName);
+                return arrayOf(resolvePropertyType(def.items, schema, resolveDefName, nested));
+            }
+        }
+    }
+    // An `allOf`/`oneOf`/`anyOf` definition types as its property form would.
+    if (def.allOf || def.oneOf || def.anyOf) {
+        const nested = new Set(seen);
+        nested.add(defName);
+        const viaBranches = resolvePropertyType(def, schema, resolveDefName, nested);
+        if (viaBranches !== "any")
+            return viaBranches;
+    }
+    return "any";
+}
+/**
+ * Extract property constraints from a schema property.
+ */
+export function extractConstraints(prop) {
+    const c = {};
+    if (prop.pattern)
+        c.pattern = prop.pattern;
+    if (prop.minLength !== undefined)
+        c.minLength = prop.minLength;
+    if (prop.maxLength !== undefined)
+        c.maxLength = prop.maxLength;
+    if (prop.minimum !== undefined)
+        c.minimum = prop.minimum;
+    if (prop.maximum !== undefined)
+        c.maximum = prop.maximum;
+    if (prop.format)
+        c.format = prop.format;
+    if (prop.const !== undefined)
+        c.const = prop.const;
+    if (prop.default !== undefined)
+        c.default = prop.default;
+    if (prop.enum && prop.enum.length > 0)
+        c.enum = prop.enum;
+    return c;
+}
+/**
+ * Check whether a PropertyConstraints object is empty (all fields undefined/absent).
+ */
+export function constraintsIsEmpty(c) {
+    return (!c.pattern &&
+        c.minLength === undefined &&
+        c.maxLength === undefined &&
+        c.minimum === undefined &&
+        c.maximum === undefined &&
+        !c.format &&
+        c.const === undefined &&
+        c.default === undefined &&
+        (!c.enum || c.enum.length === 0));
+}
+/**
+ * Check whether a schema definition is a pure string enum (no properties).
+ */
+export function isEnumDefinition(def) {
+    return (def.enum != null && def.enum.length > 0) && !def.properties;
+}

package/dist/codegen/lexicon-regen.js

@@ -0,0 +1,412 @@
+/**
+ * Lexicon regen-validate pipeline.
+ *
+ * Given a lexicon root directory, this module:
+ *   1. Runs the prepack chain (generate -> bundle -> validate -> build)
+ *      by invoking `npm run <script>` in the lexicon directory.
+ *   2. Runs `chant lint` on any examples found under `examples/`.
+ *   3. Extracts the generated public API surface.
+ *   4. Diffs the fresh surface against the committed per-lexicon baseline
+ *      (`surface.snapshot.json` at the lexicon root).
+ *   5. Returns { ok, changed, severity, delta, failures } — never throws.
+ *
+ * Supply-chain guarantee:
+ *   All spec fetching happens through the lexicon's own `generate` script,
+ *   which is pinned to the lexicon's existing fetch layer (cached, TTL-based).
+ *   When `force` is true, the cache is bypassed and the spec is re-downloaded.
+ *   This module never executes spec-provided content — it only reads the
+ *   artifacts that the generate script produced.
+ *
+ * Never auto-fix:
+ *   Any failure is captured into `failures` and returned. This module never
+ *   rewrites examples, skips checks, or masks errors.
+ */
+import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import { SNAPSHOT_UPDATE_ENV } from "./validate.js";
+import { extractSurface, diffSurface, serializeSnapshot, parseSnapshot, formatDelta, } from "./surface-snapshot.js";
+// ── Pipeline ──────────────────────────────────────────────────────────
+export const SNAPSHOT_FILENAME = "surface.snapshot.json";
+/**
+ * Run the full regen-validate pipeline for a lexicon and return the result.
+ */
+export async function regenLexicon(opts) {
+    const { lexiconDir, force = false, verbose = false, skipBundle = false, skipBuild = false, skipLint = false, skipExamples = true, updatingSnapshot = false, } = opts;
+    const failures = [];
+    // Verify lexicon directory
+    if (!existsSync(join(lexiconDir, "package.json"))) {
+        failures.push({
+            step: "setup",
+            output: `No package.json found at ${lexiconDir}`,
+        });
+        return makeResult(false, failures, null, null);
+    }
+    // Step 1: Verify pinned digest (supply-chain gate, runs before fetch)
+    if (opts.pinnedDigestPath) {
+        const digestFailure = await verifyPinnedDigest(lexiconDir, opts.pinnedDigestPath);
+        if (digestFailure) {
+            failures.push(digestFailure);
+            return makeResult(false, failures, null, null);
+        }
+    }
+    // Step 2: generate
+    // Pass CHANT_FORCE_FETCH=1 so lexicons that check this env var will bypass cache.
+    const genEnv = force
+        ? { ...process.env, CHANT_FORCE_FETCH: "1" }
+        : { ...process.env };
+    const genFail = runScript(lexiconDir, "generate", genEnv, verbose);
+    if (genFail) {
+        failures.push(genFail);
+        // Cannot proceed without generated artifacts
+        return makeResult(false, failures, null, null);
+    }
+    // Step 3: bundle (optional)
+    if (!skipBundle) {
+        const bundleFail = runScript(lexiconDir, "bundle", process.env, verbose);
+        if (bundleFail) {
+            failures.push(bundleFail);
+            // Continue to extract surface even if bundle fails
+        }
+    }
+    // Step 4: validate
+    // A re-baseline run is exempt from the surface-matches-snapshot check only
+    // (#1825) — see RegenOptions.updatingSnapshot.
+    const validateEnv = updatingSnapshot
+        ? { ...process.env, [SNAPSHOT_UPDATE_ENV]: "1" }
+        : process.env;
+    const validateFail = runScript(lexiconDir, "validate", validateEnv, verbose);
+    if (validateFail) {
+        failures.push(validateFail);
+    }
+    // Step 5: build (tsc)
+    if (!skipBuild) {
+        const buildFail = runScript(lexiconDir, "build", process.env, verbose);
+        if (buildFail) {
+            failures.push(buildFail);
+        }
+    }
+    // Step 6: lint examples
+    if (!skipLint) {
+        const lintFail = runLintOnExamples(lexiconDir, verbose);
+        if (lintFail) {
+            failures.push(lintFail);
+        }
+    }
+    // Step 7: example harness (opt-in only; requires cloud credentials)
+    if (!skipExamples) {
+        const exFail = runExampleHarness(lexiconDir, verbose);
+        if (exFail) {
+            failures.push(exFail);
+        }
+    }
+    // Step 8: extract surface from generated artifacts
+    const freshSnapshot = extractFreshSurface(lexiconDir);
+    if (!freshSnapshot) {
+        failures.push({
+            step: "surface-extract",
+            output: `Could not read generated artifacts in ${join(lexiconDir, "src", "generated")}. The generate step should have produced them.`,
+        });
+        return makeResult(false, failures, null, null);
+    }
+    // Step 9: diff against baseline
+    const baselinePath = join(lexiconDir, SNAPSHOT_FILENAME);
+    let delta;
+    if (existsSync(baselinePath)) {
+        try {
+            const baselineJSON = readFileSync(baselinePath, "utf-8");
+            const baseline = parseSnapshot(baselineJSON);
+            delta = diffSurface(baseline, freshSnapshot);
+        }
+        catch (err) {
+            failures.push({
+                step: "surface-diff",
+                output: `Failed to read or parse baseline snapshot at ${baselinePath}: ${String(err)}`,
+            });
+            return makeResult(false, failures, freshSnapshot, null);
+        }
+    }
+    else {
+        // No baseline — treat entire current surface as "added"
+        const emptyBaseline = {
+            schemaVersion: 1,
+            generatedAt: new Date(0).toISOString(),
+            entries: {},
+        };
+        delta = diffSurface(emptyBaseline, freshSnapshot);
+    }
+    const ok = failures.length === 0;
+    return makeResult(ok, failures, freshSnapshot, delta);
+}
+/**
+ * Write the fresh surface snapshot to the lexicon's committed baseline file.
+ * Call this after a successful regen when the snapshot should be updated.
+ */
+export function writeSurfaceSnapshot(lexiconDir, snapshot) {
+    const path = join(lexiconDir, SNAPSHOT_FILENAME);
+    writeFileSync(path, serializeSnapshot(snapshot), "utf-8");
+}
+// ── Subprocess helpers ────────────────────────────────────────────────
+/**
+ * Run one npm script in the lexicon directory.
+ * Returns a RegenFailure on non-zero exit; null on success.
+ */
+function runScript(cwd, script, env, verbose) {
+    try {
+        const out = execSync(`npm run --silent ${script}`, {
+            cwd,
+            env,
+            stdio: verbose ? "inherit" : "pipe",
+            encoding: "utf-8",
+            timeout: 10 * 60 * 1000, // 10 minutes
+        });
+        if (verbose && typeof out === "string" && out)
+            process.stderr.write(out);
+        return null;
+    }
+    catch (err) {
+        const e = err;
+        const captured = [e.stdout ?? "", e.stderr ?? ""].filter(Boolean).join("\n");
+        return {
+            step: script,
+            exitCode: e.status ?? 1,
+            output: captured || e.message || String(err),
+        };
+    }
+}
+/**
+ * Run `chant lint` on each example subdirectory.
+ */
+function runLintOnExamples(lexiconDir, verbose) {
+    const examplesDir = join(lexiconDir, "examples");
+    if (!existsSync(examplesDir))
+        return null;
+    let entries;
+    try {
+        entries = readdirSync(examplesDir, { withFileTypes: true, encoding: "utf-8" });
+    }
+    catch {
+        return null;
+    }
+    const exampleDirs = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => join(examplesDir, e.name))
+        .filter((d) => existsSync(join(d, "chant.config.ts")) || existsSync(join(d, "src")));
+    if (exampleDirs.length === 0)
+        return null;
+    const chantBin = resolveChantBin(lexiconDir);
+    const outputs = [];
+    let failed = false;
+    for (const exDir of exampleDirs) {
+        try {
+            const out = execSync(`${chantBin} lint ${exDir}`, {
+                stdio: verbose ? "inherit" : "pipe",
+                encoding: "utf-8",
+                timeout: 60 * 1000,
+            });
+            if (verbose && typeof out === "string" && out)
+                process.stderr.write(out);
+        }
+        catch (err) {
+            const e = err;
+            const captured = [e.stdout ?? "", e.stderr ?? ""].filter(Boolean).join(" ").trim();
+            outputs.push(`[${exDir}] exit ${e.status ?? 1}: ${captured}`);
+            failed = true;
+        }
+    }
+    if (failed) {
+        return { step: "lint", output: outputs.join("\n") };
+    }
+    return null;
+}
+/**
+ * Run `npm run build --if-present` in each example directory.
+ * Opt-in only — requires cloud credentials in most cases.
+ */
+function runExampleHarness(lexiconDir, verbose) {
+    const examplesDir = join(lexiconDir, "examples");
+    if (!existsSync(examplesDir))
+        return null;
+    let entries;
+    try {
+        entries = readdirSync(examplesDir, { withFileTypes: true, encoding: "utf-8" });
+    }
+    catch {
+        return null;
+    }
+    const exampleDirs = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => join(examplesDir, e.name))
+        .filter((d) => existsSync(join(d, "package.json")));
+    const outputs = [];
+    let failed = false;
+    for (const exDir of exampleDirs) {
+        try {
+            const out = execSync("npm run build --if-present", {
+                cwd: exDir,
+                stdio: verbose ? "inherit" : "pipe",
+                encoding: "utf-8",
+                timeout: 5 * 60 * 1000,
+            });
+            if (verbose && typeof out === "string" && out)
+                process.stderr.write(out);
+        }
+        catch (err) {
+            const e = err;
+            const captured = [e.stdout ?? "", e.stderr ?? ""].filter(Boolean).join(" ").trim();
+            outputs.push(`[${exDir}] exit ${e.status ?? 1}: ${captured}`);
+            failed = true;
+        }
+    }
+    if (failed) {
+        return { step: "examples", output: outputs.join("\n") };
+    }
+    return null;
+}
+/**
+ * Extract the fresh surface from the generated artifacts in the lexicon directory.
+ */
+function extractFreshSurface(lexiconDir) {
+    const generatedDir = join(lexiconDir, "src", "generated");
+    if (!existsSync(generatedDir))
+        return null;
+    let files;
+    try {
+        files = readdirSync(generatedDir, { encoding: "utf-8" });
+    }
+    catch {
+        return null;
+    }
+    const lexiconFile = files.find((f) => f.startsWith("lexicon-") && f.endsWith(".json"));
+    if (!lexiconFile)
+        return null;
+    let lexiconJSON;
+    try {
+        lexiconJSON = readFileSync(join(generatedDir, lexiconFile), "utf-8");
+    }
+    catch {
+        return null;
+    }
+    let typesDTS = "";
+    const dtsPath = join(generatedDir, "index.d.ts");
+    if (existsSync(dtsPath)) {
+        try {
+            typesDTS = readFileSync(dtsPath, "utf-8");
+        }
+        catch {
+            // Proceed without .d.ts — props won't be extracted
+        }
+    }
+    try {
+        return extractSurface(lexiconJSON, typesDTS);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify the spec cache file against a pinned SHA-256 digest.
+ *
+ * Digest file format (shasum -a 256 style):
+ *   sha256:<64-hex-chars>  <relative-path-to-spec-file>
+ */
+async function verifyPinnedDigest(lexiconDir, digestPath) {
+    if (!existsSync(digestPath)) {
+        return {
+            step: "digest-verify",
+            output: `Pinned digest file not found: ${digestPath}`,
+        };
+    }
+    let digestContent;
+    try {
+        digestContent = readFileSync(digestPath, "utf-8").trim();
+    }
+    catch (err) {
+        return {
+            step: "digest-verify",
+            output: `Cannot read digest file ${digestPath}: ${String(err)}`,
+        };
+    }
+    const digestMatch = /^sha256:([a-f0-9]{64})\s+(.+)$/.exec(digestContent);
+    if (!digestMatch) {
+        return {
+            step: "digest-verify",
+            output: `Malformed digest file (expected "sha256:<hex>  <filename>"): ${digestPath}`,
+        };
+    }
+    const [, expectedHex, relFilename] = digestMatch;
+    const specPath = join(lexiconDir, relFilename);
+    if (!existsSync(specPath)) {
+        return {
+            step: "digest-verify",
+            output: `Spec file referenced in digest not found: ${specPath}. Run generate first or check the digest file path.`,
+        };
+    }
+    try {
+        const { createHash } = await import("crypto");
+        const data = readFileSync(specPath);
+        const actualHex = createHash("sha256").update(data).digest("hex");
+        if (actualHex !== expectedHex) {
+            return {
+                step: "digest-verify",
+                output: [
+                    `Spec digest mismatch for ${relFilename}:`,
+                    `  expected: ${expectedHex}`,
+                    `  actual:   ${actualHex}`,
+                    "",
+                    "The cached spec does not match the pinned digest.",
+                    "Re-fetch with --force to update the cache, then update the digest file.",
+                ].join("\n"),
+            };
+        }
+        return null;
+    }
+    catch (err) {
+        return {
+            step: "digest-verify",
+            output: `Digest computation failed: ${String(err)}`,
+        };
+    }
+}
+/**
+ * Resolve the chant binary path from the lexicon's workspace node_modules.
+ */
+function resolveChantBin(lexiconDir) {
+    // Try workspace root node_modules (two levels up from lexicons/<name>)
+    const rootBin = join(lexiconDir, "..", "..", "node_modules", ".bin", "chant");
+    if (existsSync(rootBin))
+        return rootBin;
+    // Try lexicon-local node_modules
+    const localBin = join(lexiconDir, "node_modules", ".bin", "chant");
+    if (existsSync(localBin))
+        return localBin;
+    // Fall back to npx
+    return "npx chant";
+}
+/**
+ * Build the final RegenResult.
+ */
+function makeResult(ok, failures, freshSnapshot, delta) {
+    const emptyDelta = {
+        added: [],
+        changed: [],
+        removed: [],
+        renamed: [],
+        severity: "none",
+    };
+    const effectiveDelta = delta ?? emptyDelta;
+    const changed = effectiveDelta.added.length > 0 ||
+        effectiveDelta.changed.length > 0 ||
+        effectiveDelta.removed.length > 0 ||
+        effectiveDelta.renamed.length > 0;
+    const deltaText = changed ? formatDelta(effectiveDelta) : "";
+    return {
+        ok,
+        changed,
+        severity: effectiveDelta.severity,
+        delta: effectiveDelta,
+        deltaText,
+        failures,
+        freshSnapshot,
+    };
+}