@intentius/chant 0.124.12 → 0.124.14

package/dist/codegen/pinned-upgrade.js

@@ -0,0 +1,494 @@
+/**
+ * Pinned-version upgrade detection for any lexicon that declares `upstreamPin`
+ * (k8s, k3s, gcp, docker, gitlab, cedar, sql).
+ *
+ * For each lexicon with a pinned upstream version constant, this module:
+ *   1. Reads the currently pinned version from the source file.
+ *   2. Queries upstream for the latest stable release tag (no pre-release/rc).
+ *   3. Compares using semver ordering. If a newer version exists:
+ *      a. Edits the version constant in the source file.
+ *      b. Invokes regenLexicon to regenerate and surface-diff.
+ *      c. Reverts the constant edit (dry-run mode — never commits the bump).
+ *   4. Returns a structured report per lexicon.
+ *
+ * The upstream-query functions are injectable — pass a mock for unit tests.
+ * The actual HTTP calls use the GitHub Releases/Tags API.
+ *
+ * Design decisions:
+ * - "Latest stable" = highest semver excluding tags containing rc/alpha/beta/preview.
+ * - The bump is always reverted after regen so the working tree is unchanged.
+ *   Only the CLI reporter (#527) actually creates branches/PRs.
+ * - Each lexicon's upstream query is a pure async function: () => Promise<string | null>
+ *   (returns the latest version tag, or null when no stable release is found).
+ */
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+import { pathToFileURL } from "url";
+import { regenLexicon } from "./lexicon-regen.js";
+import { fetchWithRetry } from "./fetch.js";
+import { isLexiconPlugin } from "../lexicon.js";
+import { importLexiconPackage } from "../lexicon-module.js";
+import { ensureTypeScriptLoader } from "../ts-loader.js";
+// ── Version comparison ────────────────────────────────────────────────
+/**
+ * Parse a version string into numeric segments.
+ *
+ * Strips leading "v" and any build-metadata suffix after "-".
+ * Returns null when the string is not a parseable version.
+ */
+export function parseVersion(tag) {
+    // Strip leading "v"
+    const core = tag.startsWith("v") ? tag.slice(1) : tag;
+    // Strip build metadata suffix (e.g. "-ee" from "17.8.1-ee")
+    const base = core.split("-")[0];
+    if (!base)
+        return null;
+    const parts = base.split(".").map(Number);
+    if (parts.some((n) => Number.isNaN(n) || n < 0))
+        return null;
+    if (parts.length === 0)
+        return null;
+    return parts;
+}
+/**
+ * Compare two version tuples lexicographically.
+ * Returns -1 when a < b, 0 when equal, +1 when a > b.
+ */
+export function compareVersionTuples(a, b) {
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        if (av < bv)
+            return -1;
+        if (av > bv)
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Return true when `candidate` is strictly newer than `current`.
+ *
+ * Strips build-metadata suffixes (e.g. "-ee") before comparing so that
+ * "v17.9.0-ee" and "v17.9.0" compare by numeric part only.
+ */
+export function isNewer(candidate, current) {
+    const a = parseVersion(candidate);
+    const b = parseVersion(current);
+    if (!a || !b)
+        return false;
+    return compareVersionTuples(a, b) > 0;
+}
+/**
+ * Return true when a release tag looks like a pre-release.
+ * Filters out rc, alpha, beta, preview, nightly, dev, canary suffixes.
+ */
+export function isPreRelease(tag) {
+    return /[\-_\.](rc|alpha|beta|preview|nightly|dev|canary)\d*/i.test(tag);
+}
+/**
+ * Read the current pinned version from a source file using a regex pattern.
+ * Returns null when the pattern is not found.
+ */
+export function readPinnedVersion(location) {
+    let content;
+    try {
+        content = readFileSync(location.filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const match = location.pattern.exec(content);
+    return match ? (match[1] ?? null) : null;
+}
+/**
+ * Apply a version bump by replacing the constant in the source file.
+ * Returns the original file content so it can be reverted.
+ */
+export function applyVersionBump(location, newVersion) {
+    const original = readFileSync(location.filePath, "utf-8");
+    const lines = original.split("\n");
+    const updated = lines.map((line) => {
+        const match = location.pattern.exec(line);
+        if (!match)
+            return line;
+        const currentVersion = match[1] ?? "";
+        return location.buildReplacement(newVersion, currentVersion, line);
+    });
+    writeFileSync(location.filePath, updated.join("\n"), "utf-8");
+    return original;
+}
+/**
+ * Revert a file to its original content (undo a bump).
+ */
+export function revertVersionBump(filePath, original) {
+    writeFileSync(filePath, original, "utf-8");
+}
+// ── Pin descriptor, loaded from the lexicon plugin ────────────────────
+/**
+ * Load a lexicon's `upstreamPin` descriptor from its plugin package
+ * (`@intentius/chant-lexicon-<name>`) — the lexicon's own declaration of where
+ * its version constant lives and which upstream repo to check. Returns null
+ * when the package can't be resolved or declares no `upstreamPin` (i.e. it is
+ * not self-upgradable). Mirrors ../components/capability-plugin-loader.ts's
+ * lexicon-borne loading.
+ */
+export async function loadUpstreamPin(lexicon, lexiconDir) {
+    return (await loadUpstreamPins(lexicon, lexiconDir))[0]?.pin ?? null;
+}
+/**
+ * Every pin a plugin declares: its `upstreamPin` (labelled by its own `label`,
+ * else the lexicon's name) followed by each `upstreamPins` entry. Empty when
+ * the plugin declares none or cannot be loaded.
+ */
+export function pinsOfPlugin(plugin, lexicon) {
+    const pins = [];
+    if (plugin.upstreamPin)
+        pins.push({ label: plugin.upstreamPin.label ?? lexicon, pin: plugin.upstreamPin });
+    for (const pin of plugin.upstreamPins ?? [])
+        pins.push({ label: pin.label ?? `${lexicon}-${pins.length}`, pin });
+    return pins;
+}
+/** Load every pin the lexicon's plugin declares; see {@link loadUpstreamPin} for where it looks. */
+export async function loadUpstreamPins(lexicon, lexiconDir) {
+    const pinsOf = (mod) => {
+        for (const value of Object.values(mod)) {
+            if (isLexiconPlugin(value)) {
+                const pins = pinsOfPlugin(value, lexicon);
+                if (pins.length > 0)
+                    return pins;
+            }
+        }
+        return [];
+    };
+    // The directory the caller pointed at wins: it is the checkout whose pin
+    // file will be edited, and it need not be installed under node_modules.
+    const entry = lexiconDir ? lexiconEntry(lexiconDir) : null;
+    if (entry) {
+        try {
+            ensureTypeScriptLoader();
+            const pins = pinsOf((await import(pathToFileURL(entry).href)));
+            if (pins.length > 0)
+                return pins;
+        }
+        catch {
+            // fall through to the package-name route
+        }
+    }
+    try {
+        return pinsOf((await importLexiconPackage(`@intentius/chant-lexicon-${lexicon}`)));
+    }
+    catch {
+        return [];
+    }
+}
+/** The module a lexicon directory's package.json exposes as ".", or null when it declares none. */
+function lexiconEntry(lexiconDir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(lexiconDir, "package.json"), "utf-8"));
+        let rel = pkg.main;
+        const root = typeof pkg.exports === "string" ? pkg.exports : pkg.exports?.["."];
+        if (typeof root === "string")
+            rel = root;
+        else if (root && typeof root === "object") {
+            const conds = root;
+            rel = conds.development ?? conds.default ?? conds.import ?? rel;
+        }
+        if (typeof rel !== "string")
+            return null;
+        const abs = resolve(lexiconDir, rel);
+        return existsSync(abs) ? abs : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The lexicon name a directory holds, from its package.json
+ * (`@intentius/chant-lexicon-<name>`), falling back to the directory name.
+ */
+export function lexiconNameOf(lexiconDir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(lexiconDir, "package.json"), "utf-8"));
+        const m = /^@intentius\/chant-lexicon-(.+)$/.exec(pkg.name ?? "");
+        if (m)
+            return m[1];
+    }
+    catch {
+        // no package.json
+    }
+    return resolve(lexiconDir).split("/").pop() ?? lexiconDir;
+}
+/** Build a concrete `PinLocation` (absolute path + patterns) from a lexicon's descriptor and its checkout dir. */
+function pinLocationFrom(pin, lexiconDir) {
+    return {
+        filePath: join(lexiconDir, pin.file),
+        pattern: pin.pattern,
+        buildReplacement: (newVer, _old, line) => pin.replace(newVer, line),
+    };
+}
+/**
+ * Pick the highest stable version from a list of GitHub release or tag items.
+ * Pure: the network lives in `latestGitHubRelease`.
+ */
+export function pickLatest(items, kind, opts = {}) {
+    const { tagSuffix, tagVersion } = opts;
+    const major = opts.sameMajorAs !== undefined ? majorOf(opts.sameMajorAs, tagVersion) : undefined;
+    let best = null;
+    let bestParsed = null;
+    for (const item of items) {
+        const rawTag = kind === "releases" ? (item.tag_name ?? "") : (item.name ?? "");
+        if (!rawTag)
+            continue;
+        // For releases, the GitHub API pre-release flag is authoritative
+        if (kind === "releases" && item.prerelease === true)
+            continue;
+        // Additional pre-release guard on tag name
+        if (isPreRelease(rawTag))
+            continue;
+        // Apply optional suffix filter (e.g. "-ee" for GitLab)
+        if (tagSuffix && !rawTag.endsWith(tagSuffix))
+            continue;
+        const candidate = tagVersion ? tagVersion(rawTag) : rawTag;
+        if (!candidate)
+            continue;
+        const parsed = parseVersion(candidate);
+        if (!parsed)
+            continue;
+        if (major !== undefined && parsed[0] !== major)
+            continue;
+        if (!bestParsed || compareVersionTuples(parsed, bestParsed) > 0) {
+            best = candidate;
+            bestParsed = parsed;
+        }
+    }
+    return best;
+}
+/** First numeric segment of a pinned value, which may be a mapped version or a raw tag. */
+function majorOf(value, tagVersion) {
+    const parsed = parseVersion(value) ?? (tagVersion ? parseVersion(tagVersion(value) ?? "") : null);
+    return parsed?.[0];
+}
+const TAG_PAGE_SIZE = 100;
+const TAG_MAX_PAGES = 20;
+/**
+ * Fetch GitHub releases or tags from the given repo and return the
+ * latest stable version tag (highest semver, no pre-release).
+ *
+ * `kind` selects whether to use the releases API (which has published
+ * stable releases) or the tags API (which has every git tag).
+ *
+ * `tagSuffix` filters tags to only those ending with the given string
+ * (e.g. "-ee" for GitLab). `tagVersion` and `sameMajorAs` are described on
+ * `UpstreamPin.upstream`; with `tagVersion` every page of tags is read.
+ */
+async function latestGitHubRelease(owner, repo, kind, opts = {}) {
+    const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+    const headers = {
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    };
+    if (token)
+        headers["Authorization"] = `Bearer ${token}`;
+    const paged = kind === "tags" && opts.tagVersion !== undefined;
+    const perPage = paged ? TAG_PAGE_SIZE : 50;
+    const items = [];
+    for (let page = 1; page <= (paged ? TAG_MAX_PAGES : 1); page++) {
+        const url = `https://api.github.com/repos/${owner}/${repo}/${kind}?per_page=${perPage}&page=${page}`;
+        const resp = await fetchWithRetry(url, 4, 1000, { headers });
+        const batch = (await resp.json());
+        items.push(...batch);
+        if (batch.length < perPage)
+            break;
+    }
+    return pickLatest(items, kind, opts);
+}
+/** Build the real GitHub-backed upstream resolver from a lexicon's declared `upstream` descriptor. */
+export function resolverFor(pin, from) {
+    const { owner, repo, kind, tagSuffix, tagVersion, trackMajor } = pin.upstream;
+    return () => latestGitHubRelease(owner, repo, kind, { tagSuffix, tagVersion, sameMajorAs: trackMajor ? from : undefined });
+}
+// ── Main function ─────────────────────────────────────────────────────
+/**
+ * Check whether a newer upstream release exists for a pinned lexicon.
+ *
+ * When a newer version is found:
+ *   1. Applies the version bump to the source constant.
+ *   2. Runs regenLexicon (surface-diff pipeline).
+ *   3. Reverts the bump unconditionally.
+ *
+ * The caller receives the full result including the regen validation output
+ * without any lasting change to the working tree.
+ */
+export async function checkPinnedUpgrade(opts) {
+    const selected = await selectPins(opts);
+    if ("error" in selected)
+        return selected.error;
+    return checkOnePin(selected.pins[0], opts, selected.multiple);
+}
+/**
+ * Check every pin the plugin declares (or the one named by `opts.pin`), one
+ * result each, in declaration order. A plugin with one pin gives one result,
+ * the same as `checkPinnedUpgrade`. Pins are checked one after another: each
+ * dry-run bump edits and reverts a file, and regenerates.
+ */
+export async function checkPinnedUpgrades(opts) {
+    const selected = await selectPins({ ...opts, pin: opts.pin });
+    if ("error" in selected)
+        return [selected.error];
+    const results = [];
+    for (const labeled of selected.pins)
+        results.push(await checkOnePin(labeled, opts, selected.multiple));
+    return results;
+}
+/** Choose the pins to check: all of them, or the one `opts.pin` names. */
+async function selectPins(opts) {
+    const { lexiconDir, lexicon } = opts;
+    const fail = (fetchError) => ({
+        error: { lexicon, hasUpgrade: false, from: "(unknown)", to: null, validation: null, fetchError },
+    });
+    const all = await loadUpstreamPins(lexicon, lexiconDir);
+    if (all.length === 0) {
+        return fail(`Lexicon "${lexicon}" declares no upstreamPin, so there is no pinned upstream version to check (see lexicon-authoring/generate, "Pinning the upstream schema"), or its plugin could not be loaded from ${lexiconDir}.`);
+    }
+    const labels = all.map((p) => p.label);
+    const dup = labels.find((l, i) => labels.indexOf(l) !== i);
+    if (dup)
+        return fail(`Lexicon "${lexicon}" declares two pins labelled "${dup}"; each pin's label must be unique.`);
+    const multiple = all.length > 1;
+    if (opts.pin === undefined)
+        return { pins: all, multiple };
+    const chosen = all.find((p) => p.label === opts.pin);
+    if (!chosen)
+        return fail(`Lexicon "${lexicon}" has no pin labelled "${opts.pin}". Pins: ${labels.join(", ")}.`);
+    return { pins: [chosen], multiple };
+}
+async function checkOnePin(labeled, opts, multiple) {
+    const { lexiconDir, lexicon, force = false, verbose = false, skipBuild, skipBundle, skipLint } = opts;
+    const { pin } = labeled;
+    const tag = multiple ? { pin: labeled.label } : {};
+    const location = pinLocationFrom(pin, lexiconDir);
+    // Read current pin
+    const from = readPinnedVersion(location);
+    if (!from) {
+        return {
+            lexicon,
+            ...tag,
+            hasUpgrade: false,
+            from: "(unknown)",
+            to: null,
+            validation: null,
+            fetchError: `Could not read pinned version constant from ${location.filePath}`,
+        };
+    }
+    // Query upstream
+    const resolver = opts.resolverOverride ?? resolverFor(pin, from);
+    let latestTag;
+    try {
+        latestTag = await resolver();
+    }
+    catch (e) {
+        return {
+            lexicon,
+            ...tag,
+            hasUpgrade: false,
+            from,
+            to: null,
+            validation: null,
+            fetchError: String(e),
+        };
+    }
+    // The pin may hold the raw tag (REL_18_6) where the resolver returns the mapped version (18.6).
+    const fromVersion = parseVersion(from) ? from : (pin.upstream.tagVersion?.(from) ?? from);
+    if (!latestTag || !isNewer(latestTag, fromVersion)) {
+        return {
+            lexicon,
+            ...tag,
+            hasUpgrade: false,
+            from,
+            to: latestTag,
+            validation: null,
+            fetchError: null,
+        };
+    }
+    // A pin the descriptor's `replace` cannot move alone (a companion digest,
+    // say): report the new version and how to move it. Editing the version
+    // line only would leave a pin that fails generation.
+    if (pin.alsoMoves) {
+        return {
+            lexicon,
+            ...tag,
+            hasUpgrade: true,
+            from,
+            to: latestTag,
+            validation: null,
+            fetchError: null,
+            manualPin: { file: pin.file, instructions: pin.alsoMoves },
+        };
+    }
+    // Apply bump, regen, then revert
+    let originalContent;
+    try {
+        originalContent = applyVersionBump(location, latestTag);
+    }
+    catch (e) {
+        return {
+            lexicon,
+            ...tag,
+            hasUpgrade: true,
+            from,
+            to: latestTag,
+            validation: null,
+            fetchError: `Failed to apply version bump to ${location.filePath}: ${String(e)}`,
+        };
+    }
+    let validation;
+    try {
+        validation = await regenLexicon({
+            lexiconDir,
+            force,
+            verbose,
+            skipBuild: skipBuild ?? false,
+            skipBundle: skipBundle ?? false,
+            skipLint: skipLint ?? false,
+            skipExamples: true,
+        });
+    }
+    finally {
+        // Always revert — even if regenLexicon throws
+        revertVersionBump(location.filePath, originalContent);
+    }
+    return {
+        lexicon,
+        ...tag,
+        hasUpgrade: true,
+        from,
+        to: latestTag,
+        validation,
+        fetchError: null,
+    };
+}
+// ── Branch-commit helper ──────────────────────────────────────────────
+/**
+ * Apply a version bump for a lexicon permanently (without reverting).
+ *
+ * Called by LexiconUpgradeOp when it has already decided to commit the bump
+ * to a branch. Returns the absolute path to the modified file so the caller
+ * can stage it with `git add`.
+ *
+ * Unlike `applyVersionBump` (which is generic), this function takes only a
+ * lexicon id and directory — it resolves the pin location from the lexicon's
+ * declared `upstreamPin` descriptor.
+ */
+export async function applyPinnedVersionBump(lexicon, lexiconDir, newVersion, pinLabel) {
+    const pins = await loadUpstreamPins(lexicon, lexiconDir);
+    const pin = (pinLabel === undefined ? pins[0] : pins.find((p) => p.label === pinLabel))?.pin;
+    if (!pin)
+        throw new Error(`Lexicon "${lexicon}" declares no upstreamPin (not self-upgradable).`);
+    if (pin.alsoMoves) {
+        throw new Error(`Lexicon "${lexicon}" cannot have its pin rewritten generically: ${pin.alsoMoves}`);
+    }
+    const location = pinLocationFrom(pin, lexiconDir);
+    applyVersionBump(location, newVersion);
+    return { filePath: location.filePath };
+}

package/dist/codegen/registry.js

@@ -0,0 +1,60 @@
+/**
+ * Locating a lexicon's generated registry (#1367).
+ *
+ * The registry — every resource type the lexicon knows, keyed by class name —
+ * is written to two places by `npm run --prefix lexicons/<name> prepack`:
+ * `src/generated/lexicon-<name>.json` by the generate step, and `dist/meta.json`
+ * by the bundle step, byte-identical. Both are gitignored, so a fresh clone has
+ * neither until that command runs; CI runs it explicitly before anything else.
+ *
+ * That is a legitimate state. Being silent about it is not, and the two readers
+ * that needed the registry were silent in opposite directions:
+ *
+ * - AWS's import generator `require`d `dist/meta.json` with no catch, so a
+ *   fresh clone got `Cannot find module …/lexicons/aws/dist/meta.json` — from
+ *   `chant import`, and from twelve tests that mention neither modules nor
+ *   registries.
+ * - Azure's caught the failure and continued with an empty map, so the import
+ *   emitted `// Unknown resource type: Microsoft.Network/virtualNetworks` and
+ *   its round-trip tests failed as though the registry were incomplete. That is
+ *   the worse of the two: it looks like a coverage gap in the lexicon.
+ *
+ * Both now go through here, which tries the dev path first (matching what the
+ * azure serializer already did) and, failing both, says what to run.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Thrown when neither copy of the registry exists — carries the fix. */
+export class LexiconRegistryMissingError extends Error {
+    constructor(lexicon) {
+        super(`${lexicon} lexicon registry not found — it is a build artifact and this checkout has not built it.\n` +
+            `Run: npm run --prefix lexicons/${lexicon} prepack\n` +
+            `(generate writes src/generated/lexicon-${lexicon}.json; bundle writes dist/meta.json)`);
+        this.lexicon = lexicon;
+        this.name = "LexiconRegistryMissingError";
+    }
+}
+/**
+ * Read a lexicon's generated registry, dev copy first.
+ *
+ * `pkgDir` is the lexicon PACKAGE directory (the one holding `src/` and
+ * `dist/`) — callers pass an `import.meta.dirname`-derived path, so this stays
+ * free of assumptions about where it is imported from. Throws
+ * {@link LexiconRegistryMissingError} when neither copy exists, rather than
+ * returning an empty map that reads downstream as a lexicon with no resource
+ * types at all.
+ */
+export function loadLexiconRegistry(pkgDir, lexicon) {
+    for (const candidate of [
+        join(pkgDir, "src", "generated", `lexicon-${lexicon}.json`),
+        join(pkgDir, "dist", "meta.json"),
+    ]) {
+        try {
+            return JSON.parse(readFileSync(candidate, "utf-8"));
+        }
+        catch {
+            // Try the next candidate; only both failing is an error.
+        }
+    }
+    throw new LexiconRegistryMissingError(lexicon);
+}

package/dist/codegen/rehype-base-url.mjs

@@ -0,0 +1,68 @@
+/**
+ * Rehype plugin: prepend a configured `base` to root-relative `<a href>` attributes.
+ *
+ * Astro/Starlight only base-prefixes its own internal navigation (sidebar `link:`
+ * entries, `slug:` entries). Root-relative links written in MD/MDX content body
+ * — e.g. `[AWS](/lexicons/aws/)` — are emitted verbatim and 404 in production
+ * when the site is served from a non-root `base`.
+ *
+ * This plugin walks the HAST tree, finds `<a>` elements whose href starts with
+ * `/` (single leading slash, not `//`), and prepends the site's `base`. It
+ * idempotently skips hrefs that already start with the site's own base or the
+ * project-wide base.
+ *
+ * @typedef {Object} RehypeBaseUrlOptions
+ * @property {string} base - Site base, e.g. "/chant" or "/chant/lexicons/aws". Trailing/leading slashes optional.
+ * @property {string} [projectBase] - Project-wide base used to detect already-correctly-prefixed cross-site links.
+ */
+
+const PROTOCOL_RE = /^[a-z][a-z0-9+.-]*:/i;
+
+function normalizeBase(value) {
+  return "/" + value.replace(/^\/+|\/+$/g, "");
+}
+
+/**
+ * @param {RehypeBaseUrlOptions} opts
+ */
+export default function rehypeBaseUrl(opts) {
+  const base = normalizeBase(opts.base);
+  if (base === "/") {
+    return () => {};
+  }
+  const ownPrefix = base + "/";
+  const projectPrefix = opts.projectBase
+    ? normalizeBase(opts.projectBase) + "/"
+    : null;
+
+  function rewrite(node) {
+    if (
+      node &&
+      node.type === "element" &&
+      node.tagName === "a" &&
+      node.properties &&
+      typeof node.properties.href === "string"
+    ) {
+      const href = node.properties.href;
+      if (
+        href.length > 0 &&
+        !href.startsWith("//") &&
+        !PROTOCOL_RE.test(href) &&
+        !href.startsWith("#") &&
+        href.startsWith("/") &&
+        href !== base &&
+        !href.startsWith(ownPrefix) &&
+        !(projectPrefix && href.startsWith(projectPrefix))
+      ) {
+        node.properties.href = base + href;
+      }
+    }
+    if (node && node.children) {
+      for (const child of node.children) rewrite(child);
+    }
+  }
+
+  return (tree) => {
+    rewrite(tree);
+  };
+}