@dogsbay/adapter-tigera 0.0.0-stage → 0.2.0-beta.135

package/dist/includes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Where a Tigera `_includes/` partial import points.
+ *
+ * Tigera authors share content via Docusaurus MDX imports:
+ *
+ *   import Selectors from '@site/calico/_includes/content/_selectors.mdx';
+ *   ...
+ *   <Selectors />
+ *
+ * Spliced in place by the importer's own splicer (`splicePartials`, called from the adapter's
+ * preprocess so `$[variable]` substitution reaches the partials' text), verbatim and with NO
+ * heading-level offset: Docusaurus renders a partial's headings at their literal levels.
+ * `--partial-mode include` writes them as includes instead (structural.ts), with this resolver.
+ */
+import { type PreprocessContext } from "@dogsbay/format-docusaurus/adapter";
+/**
+ * Resolve an import specifier (`@site/` or relative) to the partial it names, through the corpus:
+ * a corpus path inside the project, an absolute path in an `--include-root` folder (CLI), or null.
+ * The corpus is the containment: `@site/../x`, `../../x` or a symlink out of the project resolve
+ * to nothing.
+ */
+export declare function resolveSpec(spec: string, ctx: PreprocessContext): string | null;

package/dist/includes.js

@@ -0,0 +1,29 @@
+/**
+ * Where a Tigera `_includes/` partial import points.
+ *
+ * Tigera authors share content via Docusaurus MDX imports:
+ *
+ *   import Selectors from '@site/calico/_includes/content/_selectors.mdx';
+ *   ...
+ *   <Selectors />
+ *
+ * Spliced in place by the importer's own splicer (`splicePartials`, called from the adapter's
+ * preprocess so `$[variable]` substitution reaches the partials' text), verbatim and with NO
+ * heading-level offset: Docusaurus renders a partial's headings at their literal levels.
+ * `--partial-mode include` writes them as includes instead (structural.ts), with this resolver.
+ */
+import { partialFiles } from "@dogsbay/format-docusaurus/adapter";
+/**
+ * Resolve an import specifier (`@site/` or relative) to the partial it names, through the corpus:
+ * a corpus path inside the project, an absolute path in an `--include-root` folder (CLI), or null.
+ * The corpus is the containment: `@site/../x`, `../../x` or a symlink out of the project resolve
+ * to nothing.
+ */
+export function resolveSpec(spec, ctx) {
+    if (ctx.file === undefined)
+        return null;
+    if (!spec.startsWith("@site/") && !spec.startsWith("."))
+        return null; // a package
+    const relSpec = spec.startsWith(".") && !spec.startsWith("./") && !spec.startsWith("../") ? `./${spec}` : spec;
+    return partialFiles(ctx).resolve(relSpec, ctx.file) ?? null;
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @dogsbay/adapter-tigera
+ *
+ * Site adapter for the Tigera/Calico docs (docs.tigera.io). Injected into the
+ * generic @dogsbay/format-docusaurus importer via `--adapter tigera`. Holds
+ * everything Tigera layered on top of standard Docusaurus:
+ *   - `$[variable]` substitution (custom remark plugin → adapter preprocess)
+ *   - Tigera-specific MDX components (DocCardLink, GeekDetails, If, ...)
+ *
+ * The generic importer contains ZERO Tigera code; all of it lives here.
+ */
+import { type DocusaurusAdapter } from "@dogsbay/format-docusaurus/adapter";
+export declare const tigeraAdapter: DocusaurusAdapter;
+export { loadVariables, substituteVariables } from "./variables.js";
+/**
+ * Is this the Tigera docs repo (docs.tigera.io)? From its paths, relative to the site's folder
+ * (a detection's `root`, as `migrate` takes them): Tigera's own `$[variable]` remark plugin, and a `variables.js` in a docs folder. For
+ * a host offering the adapter, never applying it silently.
+ */
+export declare function detect(paths: Iterable<string>): boolean;

package/dist/index.js

@@ -0,0 +1,144 @@
+/**
+ * @dogsbay/adapter-tigera
+ *
+ * Site adapter for the Tigera/Calico docs (docs.tigera.io). Injected into the
+ * generic @dogsbay/format-docusaurus importer via `--adapter tigera`. Holds
+ * everything Tigera layered on top of standard Docusaurus:
+ *   - `$[variable]` substitution (custom remark plugin → adapter preprocess)
+ *   - Tigera-specific MDX components (DocCardLink, GeekDetails, If, ...)
+ *
+ * The generic importer contains ZERO Tigera code; all of it lives here.
+ */
+import { splicePartials } from "@dogsbay/format-docusaurus/adapter";
+import { loadVariables, substituteVariables } from "./variables.js";
+import { toStructural } from "./structural.js";
+// ── Tigera custom components ────────────────────────────
+//
+// Mappings keep output clean instead of leaking raw JSX. Card-like components
+// map to Dogsbay cards; conditional/wrapper components keep their inner content;
+// data-driven components with no static content are stripped (self-closing).
+const TIGERA_COMPONENTS = {
+    // Cross-page link cards (from /src/___new___/components). They reference a
+    // target via `docId` (Docusaurus doc id); the card title comes from that
+    // doc's frontmatter. Emit `docId` for the generic parser to resolve into
+    // title + href (an explicit title/href attr still wins if present).
+    DocCardLink: {
+        type: "card",
+        container: false,
+        propsFromAttrs: (a) => ({ docId: a.docId, title: a.title || a.label, href: a.to || a.href }),
+    },
+    PaidProductDocCardLink: {
+        type: "card",
+        container: false,
+        propsFromAttrs: (a) => ({ docId: a.docId, title: a.title || a.label, href: a.to || a.href }),
+    },
+    DocCardLinkLayout: { type: "cards", container: true },
+    CalicoProducts: { type: "cards", container: true },
+    // Conditional rendering — keep the inner content, drop the wrapper.
+    If: { type: "if", container: true, strip: true },
+    // Metadata/badge components with no reproducible static content.
+    GeekDetails: { type: "badge", container: false, strip: true },
+    // NOTE: `<Screenshot>` (a plain <img> wrapper) is handled by an inline
+    // transform → markdown image, NOT a strip mapping — see TIGERA_INLINE_TRANSFORMS.
+};
+// `_includes/components/*.js` — data-driven React components (render tables from
+// JSON, generate env files, etc.). They are CODE and can't be inlined like the
+// .mdx content partials. Map them to a placeholder (not a silent strip) so they
+// don't leak as raw `<Tag/>` text AND don't leave a container empty — a stripped
+// component that was the sole content of a tab made the tab label vanish.
+const TIGERA_JS_COMPONENTS = [
+    "AutoHostendpointsMigrate",
+    "CalicoWindowsInstall",
+    "ComponentVersions",
+    "ConfigDataplaneOpenShiftManifests",
+    "DownloadOpenShiftManifests",
+    "EnvironmentFile",
+    "HostEndpointsUpgrade",
+    "InstallOpenShiftManifests",
+    "MaintenanceImageOptionsAlternateRegistry",
+    "FelixConfig",
+];
+for (const name of TIGERA_JS_COMPONENTS) {
+    TIGERA_COMPONENTS[name] = { type: "__placeholder", container: true };
+}
+// Self-closing Tigera tags (no closing tag expected).
+const TIGERA_SELF_CLOSING = [
+    "DocCardLink",
+    "PaidProductDocCardLink",
+    "GeekDetails",
+    "CalicoProducts",
+    ...TIGERA_JS_COMPONENTS,
+];
+// Inline replacements for icon components used within prose.
+const TIGERA_INLINE_TRANSFORMS = [
+    // Chakra checkmark icon → unicode check.
+    [/<CheckIcon\b[^>]*\/>/g, "✓"],
+    // @docusaurus/Link (`<Link to=…>` or `<Link href=…>`) → a raw <a> so it works
+    // both in prose AND inside raw-HTML tables (a markdown link wouldn't render
+    // inside an HTML `<td>`). Reads either the `to` or `href` attribute.
+    [
+        /<Link\b([^>]*?)>([\s\S]*?)<\/Link>/g,
+        (_m, attrs, text) => {
+            const url = attrs.match(/\b(?:to|href)=["']([^"']+)["']/)?.[1];
+            const inner = text.trim();
+            return url ? `<a href="${url}">${inner}</a>` : inner;
+        },
+    ],
+    // <Screenshot src alt /> is a plain <img> wrapper → markdown image (the src is
+    // then `/_assets`-rewritten by the generic parser, and the static file copied).
+    [
+        /<Screenshot\b([^>]*?)\/>/g,
+        (_m, attrs) => {
+            const src = attrs.match(/\bsrc=["']([^"']*)["']/)?.[1] ?? "";
+            const alt = attrs.match(/\balt=["']([^"']*)["']/)?.[1] ?? "";
+            return src ? `![${alt}](${src})` : "";
+        },
+    ],
+];
+export const tigeraAdapter = {
+    name: "tigera",
+    splicesPartials: true,
+    preprocess(source, ctx) {
+        // Tigera numbers figures with an MDX counter (`export let figCount = 1` +
+        // `{figCount++}` in captions). The export is stripped and the expression
+        // can't be evaluated, so substitute sequential numbers per page.
+        let fig = 0;
+        let text = source.replace(/\{\s*figCount\+\+\s*\}/g, () => String(++fig));
+        // MDX whitespace expressions `{' '}` / `{" "}` (used to force a space, e.g.
+        // inside table cells) → a literal space.
+        text = text.replace(/\{\s*(['"])(\s*)\1\s*\}/g, "$2");
+        // Partials: either splice bodies in place (inline, default; the importer's splicer, here so
+        // the variables below reach them) or emit {% include %}/{% set %}/{% if %} directives +
+        // collect fragments (include).
+        const partials = ctx.partialMode === "include"
+            ? // .md partials, which include mode does not write as includes, are spliced
+                splicePartials(toStructural(text, ctx), ctx)
+            : splicePartials(text, ctx);
+        // Substitute $[variables] (Phase 1 keeps this literal in both modes).
+        if (ctx.instanceRoot === undefined)
+            return partials;
+        return substituteVariables(partials, loadVariables(ctx));
+    },
+    components: TIGERA_COMPONENTS,
+    selfClosingTags: TIGERA_SELF_CLOSING,
+    inlineTransforms: TIGERA_INLINE_TRANSFORMS,
+};
+export { loadVariables, substituteVariables } from "./variables.js";
+/**
+ * Is this the Tigera docs repo (docs.tigera.io)? From its paths, relative to the site's folder
+ * (a detection's `root`, as `migrate` takes them): Tigera's own `$[variable]` remark plugin, and a `variables.js` in a docs folder. For
+ * a host offering the adapter, never applying it silently.
+ */
+export function detect(paths) {
+    let plugin = false;
+    let variables = false;
+    for (const p of paths) {
+        if (/^src\/remark\/variablesPlugin\.[cm]?[jt]s$/.test(p))
+            plugin = true;
+        else if (/^[^/]+(?:_versioned_docs\/[^/]+)?\/variables\.js$/.test(p))
+            variables = true;
+        if (plugin && variables)
+            return true;
+    }
+    return false;
+}

package/dist/structural.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Structural partial mode (mirrors AsciiDoc's `inlineIncludes: false`).
+ *
+ * Instead of inlining `_includes/` partials, emit Minja directives as text and
+ * collect each referenced `.mdx` partial as a *fragment* to be written at its
+ * include path. The build-time Minja preprocessor resolves them later.
+ *
+ * Transforms (text → text, before parsing):
+ *   - `export const X = '…'`                 → `{% set X = "…" %}`
+ *   - `<Partial a="1" b={x} />` (.mdx import)→ `{% set a = "1" %}` (only when a≠source)
+ *                                              `{% include "…/_partial.md" %}`
+ *   - `<If condition={props.x === 'y'}>…</If>`→ `{% if x == "y" %}…{% endif %}`
+ *
+ * `$[var]` substitution still runs afterwards (Phase 1; structural variables are
+ * Phase 2). `.js` component partials are left for the component-map strip.
+ */
+import { type PreprocessContext } from "@dogsbay/format-docusaurus/adapter";
+/**
+ * Translate a Docusaurus `<If condition={…}>` JSX expression into a Minja
+ * expression. Supports the subset that actually appears in Tigera:
+ *   props.x, ===, !==, &&, ||, !, parentheses, string/number/bool literals.
+ * Returns null when the expression is outside this grammar (caller falls back
+ * to inline + warn).
+ */
+export declare function jsxConditionToMinja(expr: string): string | null;
+/**
+ * Map a partial (a corpus path, or an absolute path in an `--include-root` folder) to its
+ * include path, relative to the instance folder. A partial elsewhere in the project is stored
+ * under `_project/`, one from an `--include-root` folder under `_include-roots/<folder name>/`
+ * (the CLI places it, by real path): relative to the instance either would climb out of the
+ * content root and be written outside the output. Undefined when the partial is in none of
+ * them (it is then not collected).
+ */
+export declare function fragmentIncludePath(path: string, ctx: Pick<PreprocessContext, "instanceRoot" | "projectRoot" | "external">): string | undefined;
+/**
+ * Translate `<If condition={…}>…</If>` blocks to `{% if … %}…{% endif %}`.
+ * Returns the rewritten source plus a flag set when any block could not be
+ * translated (caller can decide to fall back to inline for that page/partial).
+ */
+export declare function rewriteIfBlocks(source: string): {
+    text: string;
+    untranslated: number;
+};
+/**
+ * Apply the structural transform: emit Minja directives + collect fragments.
+ * Used for both pages and (recursively, via the importer draining
+ * `ctx.fragments`) the partial fragments themselves.
+ */
+export declare function toStructural(source: string, ctx: PreprocessContext): string;

package/dist/structural.js

@@ -0,0 +1,243 @@
+/**
+ * Structural partial mode (mirrors AsciiDoc's `inlineIncludes: false`).
+ *
+ * Instead of inlining `_includes/` partials, emit Minja directives as text and
+ * collect each referenced `.mdx` partial as a *fragment* to be written at its
+ * include path. The build-time Minja preprocessor resolves them later.
+ *
+ * Transforms (text → text, before parsing):
+ *   - `export const X = '…'`                 → `{% set X = "…" %}`
+ *   - `<Partial a="1" b={x} />` (.mdx import)→ `{% set a = "1" %}` (only when a≠source)
+ *                                              `{% include "…/_partial.md" %}`
+ *   - `<If condition={props.x === 'y'}>…</If>`→ `{% if x == "y" %}…{% endif %}`
+ *
+ * `$[var]` substitution still runs afterwards (Phase 1; structural variables are
+ * Phase 2). `.js` component partials are left for the component-map strip.
+ */
+import { posix, relativeDir } from "@dogsbay/format-docusaurus/adapter";
+import { resolveSpec } from "./includes.js";
+// ── JSX condition → Minja expression ────────────────────
+/**
+ * Translate a Docusaurus `<If condition={…}>` JSX expression into a Minja
+ * expression. Supports the subset that actually appears in Tigera:
+ *   props.x, ===, !==, &&, ||, !, parentheses, string/number/bool literals.
+ * Returns null when the expression is outside this grammar (caller falls back
+ * to inline + warn).
+ */
+export function jsxConditionToMinja(expr) {
+    let s = expr.trim();
+    if (!s)
+        return null;
+    // Reject constructs we don't translate (calls, member access beyond props.x,
+    // ternaries, template literals, arithmetic).
+    if (/`|\?|=>|\.\s*\w+\s*\(|\bfunction\b/.test(s))
+        return null;
+    // props.x → x  (also bare `props` is invalid on its own)
+    s = s.replace(/\bprops\.([A-Za-z_$][\w$]*)/g, "$1");
+    if (/\bprops\b/.test(s))
+        return null;
+    // Operators: order matters (=== before ==, !== before !).
+    s = s.replace(/===/g, "==").replace(/!==/g, "!=");
+    s = s.replace(/&&/g, " and ").replace(/\|\|/g, " or ");
+    // Unary not: `!x` / `!(…)` → `not x`. Leave `!=` intact (already handled).
+    s = s.replace(/!(?!=)\s*/g, "not ");
+    // Normalize double/single quotes to double for Minja string literals.
+    s = s.replace(/'([^']*)'/g, '"$1"');
+    // Whitelist final character set — identifiers, comparison, logic, literals.
+    // (Defensive: anything exotic that slipped through → bail.)
+    if (/[^\w\s."'=!<>()and ortnu]/.test(s.replace(/"[^"]*"/g, '""'))) {
+        // Allow only a safe charset outside string literals.
+        // (The regex above is intentionally loose; rely on the rejects above too.)
+    }
+    return s.replace(/\s+/g, " ").trim();
+}
+function parseMdxImports(source, ctx) {
+    const out = [];
+    const re = /^\s*import\s+([A-Z][A-Za-z0-9_]*)\s+from\s+['"]([^'"]+)['"]\s*;?\s*$/gm;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        const [, name, spec] = m;
+        if (!spec.endsWith(".mdx"))
+            continue;
+        const path = resolveSpec(spec, ctx);
+        if (path)
+            out.push({ name, resolvedPath: path });
+    }
+    return out;
+}
+/** `path` relative to the folder `root` (corpus paths), or undefined when it is not inside it. */
+function inside(path, root) {
+    if (!root)
+        return path;
+    return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : undefined;
+}
+/**
+ * Map a partial (a corpus path, or an absolute path in an `--include-root` folder) to its
+ * include path, relative to the instance folder. A partial elsewhere in the project is stored
+ * under `_project/`, one from an `--include-root` folder under `_include-roots/<folder name>/`
+ * (the CLI places it, by real path): relative to the instance either would climb out of the
+ * content root and be written outside the output. Undefined when the partial is in none of
+ * them (it is then not collected).
+ */
+export function fragmentIncludePath(path, ctx) {
+    let rel;
+    if (path.startsWith("/"))
+        rel = ctx.external?.storagePath(path);
+    else {
+        rel = ctx.instanceRoot !== undefined ? inside(path, ctx.instanceRoot) : undefined;
+        if (rel === undefined) {
+            const inProject = inside(path, ctx.projectRoot ?? "");
+            if (inProject !== undefined)
+                rel = `_project/${inProject}`;
+        }
+    }
+    return rel === undefined ? undefined : rel.replace(/\.mdx$/, ".md");
+}
+// ── export const → {% set %} ────────────────────────────
+function rewriteExportConsts(source) {
+    // `export const platform='kubernetes';` → `{% set platform = "kubernetes" %}`
+    return source.replace(/^\s*export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:"([^"]*)"|'([^']*)')\s*;?\s*$/gm, (_m, name, dq, sq) => `{% set ${name} = "${dq ?? sq}" %}`);
+}
+// ── <If> → {% if %} (with fallback signalling) ──────────
+/**
+ * Translate `<If condition={…}>…</If>` blocks to `{% if … %}…{% endif %}`.
+ * Returns the rewritten source plus a flag set when any block could not be
+ * translated (caller can decide to fall back to inline for that page/partial).
+ */
+export function rewriteIfBlocks(source) {
+    let untranslated = 0;
+    // Pass 1 — inline `<If cond>content</If>` (open + close on ONE line): a prose
+    // sentence or a single <td> cell. Emit an inline `{% if %}…{% endif %}` so the
+    // line (and any <td>/<tr> it sits in) stays intact.
+    const inlineRe = /<If\s+condition=\{([^}]*)\}\s*>([^\n]*?)<\/If>/g;
+    let text = source.replace(inlineRe, (whole, cond, inner) => {
+        const minja = jsxConditionToMinja(cond);
+        if (minja == null) {
+            untranslated++;
+            return whole; // leave for the If component-map strip
+        }
+        return `{% if ${minja} %}${inner}{% endif %}`;
+    });
+    // Pass 2 — block `<If>` on its own line (wraps block content: <tr> rows, list
+    // items). Table-aware: INSIDE an HTML <table>, emit flush directives with NO
+    // blank-line padding — blank lines would split the <table> into separate HTML
+    // blocks and the indented <tr> rows would parse as literal code. Minja still
+    // resolves the rows before markdown-it sees the table. OUTSIDE a table, emit
+    // flush + blank-padded so block conditionals don't fuse with markdown lists.
+    const lines = text.split("\n");
+    const out = [];
+    let tableDepth = 0;
+    const stack = [];
+    const openLine = /^[ \t]*<If\s+condition=\{([^}]*)\}\s*>[ \t]*$/;
+    const closeLine = /^[ \t]*<\/If>[ \t]*$/;
+    for (const line of lines) {
+        const m = openLine.exec(line);
+        if (m) {
+            const minja = jsxConditionToMinja(m[1]);
+            const inTable = tableDepth > 0;
+            if (minja == null) {
+                untranslated++;
+                stack.push({ ok: false, inTable });
+                out.push("<If>");
+                continue;
+            }
+            stack.push({ ok: true, inTable });
+            // Inside a table, use Minja whitespace control (`{%- … -%}`) so resolving
+            // the directive leaves NO blank line — a blank line would fragment the
+            // <table> and the indented <tr> rows would parse as an indented code block.
+            if (inTable)
+                out.push(`{%- if ${minja} -%}`);
+            else
+                out.push("", `{% if ${minja} %}`, "");
+            continue;
+        }
+        if (closeLine.test(line)) {
+            const rec = stack.pop();
+            if (!rec || !rec.ok) {
+                out.push("</If>"); // untranslated → keep for the If component-map strip
+                continue;
+            }
+            if (rec.inTable)
+                out.push("{%- endif -%}");
+            else
+                out.push("", "{% endif %}", "");
+            continue;
+        }
+        out.push(line);
+        tableDepth += (line.match(/<table\b/g) ?? []).length;
+        tableDepth -= (line.match(/<\/table>/g) ?? []).length;
+        if (tableDepth < 0)
+            tableDepth = 0;
+    }
+    return { text: out.join("\n"), untranslated };
+}
+// ── Partial usage → {% include %} + fragment collection ─
+function emitIncludes(source, imports, ctx) {
+    // The directory of the CURRENT file's output (.md), relative to the instance
+    // root. Include paths are emitted relative to this, because the build-time
+    // Minja preprocessor resolves `{% include %}` against the consuming file's dir
+    // (`basePath: dirname(sourcePath)`), not the content root.
+    const currentOut = ctx.file !== undefined ? fragmentIncludePath(ctx.file, ctx) : undefined;
+    const currentOutDir = currentOut === undefined ? "" : posix.dirname(currentOut).replace(/^\.$/, "");
+    let result = source;
+    for (const imp of imports) {
+        // Stable storage path (content-root-relative) — the exporter writes the
+        // fragment here, and it's the fragments-collector key.
+        const storagePath = fragmentIncludePath(imp.resolvedPath, ctx);
+        // A partial with nowhere inside the output to live is not collected: its usage stays
+        // as written and is reported as an unmapped component
+        if (storagePath === undefined)
+            continue;
+        ctx.fragments?.set(imp.resolvedPath, storagePath);
+        // Page-relative directive path (e.g. ../../_includes/partials/_x.md).
+        let rel = relativeDir(currentOutDir, storagePath);
+        if (!rel.startsWith("."))
+            rel = `./${rel}`;
+        const selfClosing = new RegExp(`<${imp.name}((?:\\s[^>]*?)?)/>`, "g");
+        const paired = new RegExp(`<${imp.name}((?:\\s[^>]*?)?)>[\\s\\S]*?</${imp.name}>`, "g");
+        const directiveFor = (attrText) => {
+            const sets = propSetDirectives(attrText);
+            return `\n\n${sets}{% include "${rel}" %}\n\n`;
+        };
+        result = result
+            .replace(paired, (_m, attrs) => directiveFor(attrs))
+            .replace(selfClosing, (_m, attrs) => directiveFor(attrs));
+    }
+    return result;
+}
+/**
+ * Emit `{% set %}` lines only for props that need them: a literal value, or a
+ * prop whose name differs from the forwarded variable. `name={name}` (same name,
+ * the Tigera pattern) needs nothing — the page-level set is already in scope.
+ */
+function propSetDirectives(attrText) {
+    const sets = [];
+    const attrRe = /([A-Za-z_$][\w$]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{([^}]*)\})/g;
+    let m;
+    while ((m = attrRe.exec(attrText)) !== null) {
+        const [, name, dq, sq, expr] = m;
+        if (dq !== undefined || sq !== undefined) {
+            sets.push(`{% set ${name} = "${dq ?? sq}" %}\n`);
+        }
+        else if (expr !== undefined) {
+            const e = expr.trim();
+            if (e !== name)
+                sets.push(`{% set ${name} = ${e} %}\n`); // rename only
+            // same-name forward (e === name) → inherited, no set needed
+        }
+    }
+    return sets.join("");
+}
+// ── Entry point ─────────────────────────────────────────
+/**
+ * Apply the structural transform: emit Minja directives + collect fragments.
+ * Used for both pages and (recursively, via the importer draining
+ * `ctx.fragments`) the partial fragments themselves.
+ */
+export function toStructural(source, ctx) {
+    const imports = parseMdxImports(source, ctx);
+    let text = rewriteExportConsts(source);
+    text = rewriteIfBlocks(text).text;
+    text = emitIncludes(text, imports, ctx);
+    return text;
+}

package/dist/variables.d.ts

@@ -0,0 +1,18 @@
+import { type PreprocessContext } from "@dogsbay/format-docusaurus/adapter";
+/**
+ * Substitute `$[path]` tokens using `vars`. Unknown tokens and tokens that
+ * resolve to non-primitive values are left untouched (and reported via onWarn).
+ */
+export declare function substituteVariables(source: string, vars: Record<string, unknown>, onWarn?: (token: string) => void): string;
+/**
+ * Load `variables.js` from a product/version folder (a CommonJS data module that may
+ * `require('./releases.json')`), through the corpus. Cached per corpus and folder; an empty
+ * object when absent.
+ *
+ * READ as data by default (`@dogsbay/literal`, through format-docusaurus's `readDataModule`):
+ * on the Tigera repo that is 23 of 24 calico keys and every calico-cloud key; a value computed
+ * with `.split()`/`.slice()` is left unresolved and named, and its `$[token]` stays as written.
+ * With `--eval-config` the CLI RUNS the file instead (`ctx.runModule`) — code from the source
+ * repo, for a repo you trust.
+ */
+export declare function loadVariables(ctx: Pick<PreprocessContext, "corpus" | "instanceRoot" | "projectRoot" | "runModule" | "warn">): Record<string, unknown>;

package/dist/variables.js

@@ -0,0 +1,80 @@
+import { readDataModule } from "@dogsbay/format-docusaurus/adapter";
+// Tokens may use array indices (`releases.0`) and keys containing slashes
+// (`components.calico/node.version`), so the charset includes digits and `/`.
+const TOKEN_RE = /\$\[([a-zA-Z0-9_./]+)\]/g;
+/** Resolve a dotted path (e.g. "tigeraOperator.version") within an object. */
+function resolvePath(vars, path) {
+    return path.split(".").reduce((acc, key) => {
+        if (acc && typeof acc === "object" && key in acc) {
+            return acc[key];
+        }
+        return undefined;
+    }, vars);
+}
+/**
+ * Substitute `$[path]` tokens using `vars`. Unknown tokens and tokens that
+ * resolve to non-primitive values are left untouched (and reported via onWarn).
+ */
+export function substituteVariables(source, vars, onWarn) {
+    return source.replace(TOKEN_RE, (whole, path) => {
+        const value = resolvePath(vars, path);
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            return String(value);
+        }
+        onWarn?.(path);
+        return whole;
+    });
+}
+/**
+ * Variables read per corpus and folder. Per corpus, not per process: a browser converts one
+ * repo after another, and a folder name (`calico`) means a different file in each.
+ */
+const cache = new WeakMap();
+/**
+ * Load `variables.js` from a product/version folder (a CommonJS data module that may
+ * `require('./releases.json')`), through the corpus. Cached per corpus and folder; an empty
+ * object when absent.
+ *
+ * READ as data by default (`@dogsbay/literal`, through format-docusaurus's `readDataModule`):
+ * on the Tigera repo that is 23 of 24 calico keys and every calico-cloud key; a value computed
+ * with `.split()`/`.slice()` is left unresolved and named, and its `$[token]` stays as written.
+ * With `--eval-config` the CLI RUNS the file instead (`ctx.runModule`) — code from the source
+ * repo, for a repo you trust.
+ */
+export function loadVariables(ctx) {
+    const corpus = ctx.corpus;
+    if (!corpus || ctx.instanceRoot === undefined)
+        return {};
+    let byFolder = cache.get(corpus);
+    if (!byFolder)
+        cache.set(corpus, (byFolder = new Map()));
+    const key = `${ctx.runModule ? "run" : "read"}:${ctx.instanceRoot}`;
+    const hit = byFolder.get(key);
+    if (hit)
+        return hit;
+    const file = ctx.instanceRoot ? `${ctx.instanceRoot}/variables.js` : "variables.js";
+    let vars = {};
+    if (corpus.paths.includes(file))
+        vars = ctx.runModule ? runVariables(file, ctx) : readVariables(file, corpus, ctx);
+    byFolder.set(key, vars);
+    return vars;
+}
+function runVariables(file, ctx) {
+    try {
+        const mod = ctx.runModule(file);
+        return mod && typeof mod === "object" ? mod : {};
+    }
+    catch (err) {
+        ctx.warn?.(`Warning: could not load ${file} (${err.message}); $[vars] left as-is.`);
+        return {};
+    }
+}
+function readVariables(file, corpus, ctx) {
+    const { value, unresolved } = readDataModule(corpus, file, { root: ctx.projectRoot ?? "", fallbackExport: "variables" });
+    if (unresolved.length) {
+        ctx.warn?.(`Warning: ${file}: ${unresolved.length} value(s) could not be read as data and are left out ` +
+            `(their $[tokens] stay as written; --eval-config runs the file instead):\n` +
+            unresolved.map((u) => `    ${u.startsWith(`${file}: `) ? u.slice(file.length + 2) : u}`).join("\n"));
+    }
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@dogsbay/adapter-tigera",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-beta.135",
+  "description": "Tigera/Calico site adapter for @dogsbay/format-docusaurus — resolves $[variable] substitution and Tigera-specific MDX components.",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@dogsbay/corpus": "0.2.0-beta.135",
+    "@dogsbay/format-docusaurus": "0.2.0-beta.135"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/adapter-tigera"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.