@intentius/chant-lexicon-grafana 0.124.30 → 0.124.32

package/dist/catalog.js

@@ -0,0 +1,198 @@
+/**
+ * The built-in entity catalog: every class this package exports, keyed by
+ * class name. It feeds the packaged registry (`dist/meta.json`), LSP
+ * completions and hover, and the docs.
+ */
+import { DATASOURCE_PROVISIONING_TYPE, DATASOURCE_TYPE, EXTERNAL_DATASOURCE_TYPE } from "./datasource.js";
+import { FOLDER_TYPE } from "./folder.js";
+import { LIBRARY_PANEL_REF_TYPE, LIBRARY_PANEL_TYPE } from "./library-panel.js";
+import { DASHBOARD_TYPE, DASHBOARD_PROVIDER_TYPE } from "./dashboard.js";
+import * as panels from "./panels.js";
+import * as queries from "./query.js";
+import { VARIABLE_TYPE_PREFIX } from "./variables.js";
+import { ALERT_QUERY_TYPE, ALERT_RULE_GROUP_TYPE, ALERT_RULE_TYPE, CONTACT_POINT_TYPE, EXPRESSION_TYPE_PREFIX, MUTE_TIMING_TYPE, NOTIFICATION_POLICY_TYPE, NOTIFICATION_TEMPLATE_TYPE, } from "./alerting.js";
+function isClassWith(v, key) {
+    return typeof v === "function" && typeof v[key] === "object";
+}
+const panelEntries = Object.entries(panels)
+    .filter((e) => isClassWith(e[1], "definition"))
+    .map(([className, cls]) => ({
+    className,
+    entityType: `${panels.PANEL_TYPE_PREFIX}${cls.definition.type}`,
+    kind: "panel",
+    entityKind: "property",
+    pluginId: cls.definition.type,
+    description: cls.definition.description ?? "",
+}));
+const queryEntries = Object.entries(queries)
+    .filter((e) => isClassWith(e[1], "definition"))
+    .map(([className, cls]) => ({
+    className,
+    entityType: `${queries.QUERY_TYPE_PREFIX}${cls.definition.datasourceType}`,
+    kind: "query",
+    entityKind: "property",
+    pluginId: cls.definition.datasourceType,
+    description: cls.definition.description ?? "",
+}));
+const VARIABLES = [
+    ["QueryVariable", "query", "A variable whose values come from a datasource query"],
+    ["CustomVariable", "custom", "A variable with a fixed list of values"],
+    ["IntervalVariable", "interval", "A time interval to choose, for range selectors"],
+    ["DatasourceVariable", "datasource", "A choice of datasource of one plugin type; usable wherever a datasource is"],
+    ["ConstantVariable", "constant", "A hidden, fixed value"],
+    ["TextboxVariable", "textbox", "A free-text box"],
+    ["AdhocVariable", "adhoc", "Key/value filters Grafana adds to every query sent to the variable's datasource"],
+    ["GroupByVariable", "groupby", "A choice of label keys Grafana groups every query to the variable's datasource by (experimental in Grafana)"],
+    ["SwitchVariable", "switch", "An on/off switch with a value for each state (Grafana 12.3 and later)"],
+];
+const EXPRESSIONS = [
+    ["ReduceExpression", "reduce", "A server-side expression reducing each series to one number (last, mean, max, ...)"],
+    ["MathExpression", "math", "A server-side math expression over other results by refId, e.g. $A / $B"],
+    ["ThresholdExpression", "threshold", "A server-side threshold, with an optional recovery threshold"],
+    ["ResampleExpression", "resample", "A server-side expression resampling a time series to a fixed window"],
+    ["ClassicConditionsExpression", "classic_conditions", "Grafana's legacy classic conditions, as a server-side expression"],
+    ["SqlExpression", "sql", "A server-side SQL expression over the other results"],
+];
+export const BUILTIN_CATALOG = [
+    {
+        className: "Dashboard",
+        entityType: DASHBOARD_TYPE,
+        kind: "dashboard",
+        entityKind: "resource",
+        description: "A dashboard: title, uid, time range, variables, rows, panels and links, written as the JSON Grafana imports",
+    },
+    {
+        className: "Datasource",
+        entityType: DATASOURCE_TYPE,
+        kind: "datasource",
+        entityKind: "resource",
+        description: "A datasource, declared once and referenced by panels, queries and variables",
+    },
+    {
+        className: "ExternalDatasource",
+        entityType: EXTERNAL_DATASOURCE_TYPE,
+        kind: "datasource",
+        entityKind: "resource",
+        description: "A datasource that already exists in Grafana: referenced like a Datasource and checked by GRAF101/GRAF102, never provisioned",
+    },
+    {
+        className: "Folder",
+        entityType: FOLDER_TYPE,
+        kind: "folder",
+        entityKind: "resource",
+        description: "A folder with a stable uid, nested with parent; a dashboard's folder may be one instead of a path",
+    },
+    {
+        className: "LibraryPanel",
+        entityType: LIBRARY_PANEL_TYPE,
+        kind: "library",
+        entityKind: "resource",
+        description: "A panel kept in Grafana's library and shared by dashboards; the build writes it into their __elements, and the API applier into the library",
+    },
+    {
+        className: "DatasourceProvisioning",
+        entityType: DATASOURCE_PROVISIONING_TYPE,
+        kind: "provider",
+        entityKind: "resource",
+        description: "The datasource provisioning file's prune (on by default) and deleteDatasources",
+    },
+    {
+        className: "DashboardProvider",
+        entityType: DASHBOARD_PROVIDER_TYPE,
+        kind: "provider",
+        entityKind: "resource",
+        description: "An entry in the dashboard provisioning file; a default one is written when none is declared",
+    },
+    {
+        className: "Row",
+        entityType: panels.ROW_TYPE,
+        kind: "row",
+        entityKind: "property",
+        description: "A full-width row header; its panels are placed below it, or inside it when collapsed",
+    },
+    {
+        className: "LibraryPanelRef",
+        entityType: LIBRARY_PANEL_REF_TYPE,
+        kind: "library",
+        entityKind: "property",
+        description: "A library panel placed on a dashboard, with its own gridPos, id and title; names a LibraryPanel, or { uid, name } of one already in Grafana",
+    },
+    {
+        className: "AlertRuleGroup",
+        entityType: ALERT_RULE_GROUP_TYPE,
+        kind: "alerting",
+        entityKind: "resource",
+        description: "A group of Grafana-managed alert and recording rules in a folder, evaluated together at one interval",
+    },
+    {
+        className: "ContactPoint",
+        entityType: CONTACT_POINT_TYPE,
+        kind: "alerting",
+        entityKind: "resource",
+        description: "A contact point: the integrations (email, Slack, webhook, ...) alerts are sent to, under one name",
+    },
+    {
+        className: "NotificationPolicy",
+        entityType: NOTIFICATION_POLICY_TYPE,
+        kind: "alerting",
+        entityKind: "resource",
+        description: "An organisation's notification policy tree: the root receiver and the routes that match alerts to contact points",
+    },
+    {
+        className: "MuteTiming",
+        entityType: MUTE_TIMING_TYPE,
+        kind: "alerting",
+        entityKind: "resource",
+        description: "A named time interval that mutes (or, as active_time_intervals, enables) notifications",
+    },
+    {
+        className: "NotificationTemplate",
+        entityType: NOTIFICATION_TEMPLATE_TYPE,
+        kind: "alerting",
+        entityKind: "resource",
+        description: "A notification template group, Go templates contact point settings can use",
+    },
+    {
+        className: "AlertRule",
+        entityType: ALERT_RULE_TYPE,
+        kind: "alerting",
+        entityKind: "property",
+        description: "A Grafana-managed alert or recording rule: queries, expressions and the condition that fires it",
+    },
+    {
+        className: "AlertQuery",
+        entityType: ALERT_QUERY_TYPE,
+        kind: "alerting",
+        entityKind: "property",
+        description: "A datasource query of an alert rule, with its model as Grafana stores it and its time range",
+    },
+    ...EXPRESSIONS.map(([className, type, description]) => ({
+        className,
+        entityType: `${EXPRESSION_TYPE_PREFIX}${type}`,
+        kind: "expression",
+        entityKind: "property",
+        description,
+    })),
+    ...panelEntries,
+    ...queryEntries,
+    ...VARIABLES.map(([className, type, description]) => ({
+        className,
+        entityType: `${VARIABLE_TYPE_PREFIX}${type}`,
+        kind: "variable",
+        entityKind: "property",
+        description,
+    })),
+];
+/**
+ * The catalog as a chant lexicon registry, keyed by class name. Every class
+ * is listed as a resource, including the property-kind panels, queries and
+ * variables: the registry drives `new …` completions, and an author writes
+ * `new TimeSeriesPanel(…)` the same way as `new Dashboard(…)`.
+ */
+export function lexiconRegistry() {
+    const out = {};
+    for (const e of [...BUILTIN_CATALOG].sort((a, b) => a.className.localeCompare(b.className))) {
+        out[e.className] = { resourceType: e.entityType, kind: "resource", lexicon: "grafana" };
+    }
+    return out;
+}

package/dist/codegen/docs-cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.js

@@ -0,0 +1,130 @@
+/**
+ * Documentation generation for the grafana lexicon: the generated reference
+ * pages from the core docs pipeline, plus the authored pages in docs/pages/.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+function serviceFromType(resourceType) {
+    const parts = resourceType.split("::");
+    return parts.length >= 2 ? parts[1] : "Grafana";
+}
+const overview = `The grafana lexicon types what a [Grafana](https://grafana.com/docs/grafana/latest/) dashboard
+shows: datasources, dashboards, rows, panels, queries and variables, and
+Grafana-managed alerting. \`chant build\`
+writes one JSON file per dashboard, the JSON Grafana imports as it is, plus the
+provisioning files Grafana reads for dashboards and datasources. Grafana server
+settings, users and plugins are out of scope.
+
+\`\`\`ts
+import { Datasource, PromQuery, TimeSeriesPanel, Dashboard } from "@intentius/chant-lexicon-grafana";
+
+const prometheus = new Datasource({ name: "Prometheus", type: "prometheus", url: "http://prometheus:9090" });
+const rate = new PromQuery({ expr: "sum(rate(http_requests_total[$__rate_interval]))" });
+const requests = new TimeSeriesPanel({ title: "Requests per second", datasource: prometheus, targets: [rate] });
+
+export const overview = new Dashboard({ title: "Overview", panels: [requests] });
+\`\`\`
+
+Panels: time series, stat, gauge, table, logs, traces, heatmap, text, bar
+chart, bar gauge, pie chart, state timeline, status history, histogram, node
+graph, XY chart, trend, canvas, geomap, candlestick, annotations list, dashboard list, news, data grid, flame graph and alert list, plus rows.
+Queries: Prometheus (PromQL), Tempo (TraceQL), Loki (LogQL), Elasticsearch,
+CloudWatch, Azure Monitor, Cloud Monitoring, BigQuery, Pyroscope, and SQL for
+PostgreSQL, MySQL and MSSQL. Panel options and query fields are generated from
+Grafana's own schemas at a pinned version, corrected against Grafana's CUE, and
+track Grafana 12.4 and 13.x. Every build validates the dashboards against the
+same schemas.
+Dashboards are written in the classic (v1) JSON model. Grafana 13's v2 model
+(tabs, auto grids, conditional rendering) cannot be declared yet; import and
+drift read a v2 dashboard by converting it to the classic model, and say what
+the conversion loses.
+\`definePanel\` and \`defineQuery\` add plugins chant doesn't ship.
+\`chant import\` turns dashboard JSON exported from Grafana into this TypeScript,
+and it builds back to the same dashboard (see
+[Importing Dashboards](./importing/)). \`chant lifecycle diff --live\` reports
+a dashboard edited in Grafana as drift, property by property, and
+\`chant import --from <env>\` writes a running Grafana's dashboards as
+TypeScript (see [Drift and Live Export](./observing/)). \`grafanaApply\` writes
+a build to a running Grafana over its HTTP API, with folders and library
+panels, and prunes the project's own dashboards and folders (see
+[Apply over the API](./applying/)).
+
+Grafana-managed alerting is typed too: rule groups with their queries and
+server-side expressions (reduce, math, threshold, resample, classic
+conditions, SQL), contact points, the notification policy tree, mute timings
+and templates, written to Grafana's alerting provisioning file.
+\`SloAlertRules\` turns a prometheus \`Slo\` into burn-rate alert rules. See
+[Alerting](./alerting/).
+
+Three composites build whole dashboards from declarations in other lexicons:
+\`RedDashboard\` from an otel \`spanmetrics\` connector, \`SloDashboard\` from a
+prometheus \`Slo\` and \`AgentDashboard\` from the otel GenAI preset. Metric names
+come from the declaration, so renaming one moves the panels. See
+[Dashboards from Declarations](./composites/).
+
+Checks catch a query aimed at a datasource nobody declared, with
+\`Datasource\` or \`ExternalDatasource\` (GRAF101), or of the
+wrong type (GRAF102), a \`$variable\` the dashboard doesn't declare (GRAF103),
+duplicate uids and ids (GRAF104), panels off the grid or overlapping (GRAF105),
+anything Grafana's dashboard schema rejects (GRAF107), PromQL sent to a
+Prometheus that doesn't parse (GRAF108), LogQL sent to a Loki and TraceQL
+sent to a Tempo that don't parse (GRAF116, GRAF117), dashboard providers that load a
+dashboard twice or not into its declared folder (GRAF109), a panel repeated over a variable that only ever
+holds one value (GRAF110), and a unit Grafana doesn't know (GRAF115). For alerting, they catch rules whose condition or expressions name
+no query (GRAF111), queries to undeclared datasources (GRAF112), routes to
+undeclared contact points or mute timings (GRAF113), and uids, intervals and
+duplicates Grafana refuses (GRAF114).
+`;
+const outputFormat = `The grafana lexicon writes Grafana's own files, keyed by path under the
+directory of the \`-o\` output:
+
+- \`dashboards/<uid>.json\`, or \`dashboards/<folder>/<uid>.json\` for a
+  dashboard with a \`folder\`: the dashboard JSON, one file per dashboard.
+- \`provisioning/datasources/chant.yaml\`: every declared datasource.
+- \`provisioning/dashboards/chant.yaml\`: a file provider for the dashboards
+  directory; a default one unless a \`DashboardProvider\` is declared.
+- \`provisioning/alerting/chant.yaml\`: rule groups, contact points, the
+  notification policy tree, mute timings and templates, when the build
+  declares any.
+
+The primary output (the \`-o\` file itself) is a JSON index of the dashboards,
+datasources, alerting and files that were built.
+
+- Dashboard JSON carries the pinned schema's \`schemaVersion\`, no numeric \`id\`,
+  and every field Grafana's schema requires (link defaults, an empty
+  \`annotations.list\`, \`fieldConfig.overrides\`).
+- Panels without a position are laid out in declaration order on the 24-column
+  grid. Ids and query \`refId\`s are assigned in order unless set.
+- A declared \`Datasource\` is written as \`{ type, uid }\` wherever it is
+  referenced, and as its uid inside another datasource's \`jsonData\`.
+- \`chant build\` rewrites JSON files with sorted keys; Grafana does not care
+  about key order.
+- The dashboard JSON carries no ownership marker. Grafana keeps who manages a
+  dashboard in the resource's metadata on its \`dashboard.grafana.app\` API,
+  not in the JSON: for a provisioned dashboard, the name of the provider that
+  loaded it, which is \`chant\` unless a \`DashboardProvider\` names another.
+  \`chant lifecycle diff --live\` reads that back (see
+  [Drift and Live Export](../observing/)).
+`;
+export async function generateDocs(opts) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const config = {
+        name: "grafana",
+        displayName: "Grafana",
+        description: "Typed Grafana dashboards, panels, queries and datasources, built to dashboard JSON and provisioning files",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/grafana/",
+        overview,
+        outputFormat,
+        serviceFromType,
+        srcDir: join(pkgDir, "src"),
+        examplesDir: join(pkgDir, "examples"),
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (opts?.verbose) {
+        console.error(`Generated ${result.pages.size} documentation pages`);
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for `npm run generate` in lexicon-grafana.
+ */
+import { generate, writeGeneratedFiles } from "./generate.js";
+const result = await generate({ verbose: true });
+writeGeneratedFiles(result);

package/dist/codegen/generate.js

@@ -0,0 +1,97 @@
+/**
+ * The grafana lexicon's generate step, offline and deterministic.
+ *
+ * 1. `src/schema/<name>.gen.ts` from each vendored schema in `src/spec/schemas/`
+ *    (see `src/pin.ts`). These are committed, and a test fails when they
+ *    drift from what this step would write.
+ * 2. `src/spec/schemas.gen.ts`, the same schemas with the overlay applied, as
+ *    JSON text. Validation (GRAF107, the `/validation` subpath) reads them
+ *    from there rather than from the files, so it needs no filesystem access
+ *    and works bundled. Committed and checked the same way.
+ * 3. `src/generated/lexicon-grafana.json`, the registry of entity classes
+ *    the package exports, derived from the catalog so the packaged
+ *    `dist/meta.json` cannot disagree with the classes.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { mkdirSync, writeFileSync } from "fs";
+import { SCHEMA_NAMES } from "../pin.js";
+import { digestMismatches, loadSchema } from "../spec/schemas.js";
+import { schemaModule } from "./schema-types.js";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+/** The dashboard schema's own default `schemaVersion`, the one the serializer emits. */
+function dashboardExtras(schema) {
+    const defs = schema.definitions;
+    const v = defs.Dashboard?.properties?.schemaVersion?.default;
+    if (typeof v !== "number")
+        throw new Error("grafana: dashboard schema has no default schemaVersion");
+    return ["/** The dashboard `schemaVersion` the pinned schema defaults to, and the one chant emits. */", `export const DASHBOARD_SCHEMA_VERSION = ${v};`];
+}
+/** `src/spec/schemas.gen.ts`: each schema validation uses, overlay applied, as one line of JSON text. */
+export function schemaDataModule() {
+    const lines = [
+        "// Code generated by chant generate. DO NOT EDIT.",
+        "// The vendored Grafana schemas (src/spec/schemas/, see src/pin.ts) with the",
+        "// correction overlay (src/spec/overlay/) applied, as JSON text, for",
+        "// src/schema-validate.ts. A module rather than a file read, so validation",
+        "// needs no filesystem access and survives bundling; text rather than object",
+        "// literals, so loading it costs little until a schema is parsed.",
+        "",
+        'import type { SchemaName } from "../pin.js";',
+        "",
+        "export const SCHEMA_JSON: Readonly<Record<SchemaName, string>> = {",
+    ];
+    for (const name of SCHEMA_NAMES) {
+        lines.push(`  ${JSON.stringify(name)}: ${JSON.stringify(JSON.stringify(loadSchema(name)))},`);
+    }
+    lines.push("};", "");
+    return lines.join("\n");
+}
+/** Every generated schema module, keyed by path relative to the package root. */
+export function schemaModules() {
+    const out = {};
+    for (const name of SCHEMA_NAMES) {
+        const schema = loadSchema(name);
+        const extra = name === "dashboard" ? dashboardExtras(schema) : [];
+        out[`src/schema/${name}.gen.ts`] = schemaModule(name, schema, extra).source;
+    }
+    out["src/spec/schemas.gen.ts"] = schemaDataModule();
+    return out;
+}
+/** The packaged types entry re-exports the compiled declarations. */
+const TYPES_DTS = `// The grafana lexicon's entity classes are hand-written in src/, with panel
+// and query types generated into src/schema/; this entry re-exports them.
+export * from "../index.js";
+`;
+export async function generate(opts) {
+    const bad = digestMismatches();
+    if (bad.length > 0) {
+        throw new Error(`grafana: vendored schemas do not match GRAFANA_SCHEMA_PIN: ${bad.map((b) => `${b.name} (${b.actual.slice(0, 12)}…)`).join(", ")}. ` +
+            "Run `just fetch-schemas` and update src/pin.ts.");
+    }
+    const modules = schemaModules();
+    for (const [rel, source] of Object.entries(modules)) {
+        mkdirSync(dirname(join(pkgDir, rel)), { recursive: true });
+        writeFileSync(join(pkgDir, rel), source);
+    }
+    const { BUILTIN_CATALOG, lexiconRegistry } = await import("../catalog.js");
+    const lexiconJSON = `${JSON.stringify(lexiconRegistry(), null, 2)}\n`;
+    if (opts?.verbose) {
+        console.error(`grafana: ${Object.keys(modules).length} schema modules, ${BUILTIN_CATALOG.length} entity classes`);
+    }
+    return {
+        lexiconJSON,
+        typesDTS: TYPES_DTS,
+        indexTS: "",
+        resources: BUILTIN_CATALOG.length,
+        properties: 0,
+        enums: 0,
+        warnings: [],
+    };
+}
+/** Write the registry to src/generated/lexicon-grafana.json, for tools that read it from there. */
+export function writeGeneratedFiles(result) {
+    const dir = join(pkgDir, "src", "generated");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "lexicon-grafana.json"), result.lexiconJSON);
+}

package/dist/codegen/package.js

@@ -0,0 +1,28 @@
+/**
+ * grafana lexicon packaging, delegating to core's packagePipeline.
+ */
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { packagePipeline, collectSkills, } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+import { grafanaSkills } from "../skill-defs.js";
+// src/codegen/package.ts -> src/
+const srcDir = dirname(moduleSourceDir(import.meta.url));
+export async function packageLexicon(opts = {}) {
+    const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+    return packagePipeline({
+        generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+        buildManifest: () => ({
+            name: "grafana",
+            version: pkgJson.version ?? "0.0.1",
+            chantVersion: ">=0.1.0",
+            namespace: "Grafana",
+            intrinsics: [],
+            pseudoParameters: {},
+        }),
+        srcDir,
+        collectSkills: () => collectSkills(grafanaSkills()),
+        version: pkgJson.version ?? "0.0.1",
+    }, opts);
+}

package/dist/codegen/schema-types.js

@@ -0,0 +1,159 @@
+/**
+ * JSON Schema (draft-07, the subset cog emits) to TypeScript declarations.
+ *
+ * Each vendored schema, with its correction overlay applied, becomes one
+ * module under `src/schema/`: one exported type per entry in `definitions`,
+ * with the schema's descriptions as doc comments. `required` is kept, so the types say what the schema says; the
+ * entity props wrap panel options in `DeepPartial` where Grafana fills the
+ * rest in on import.
+ */
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/**
+ * Keys written quoted even though they are identifiers. The repo's egress
+ * scan (test/egress-catalogue.ts) reads a bare `fetch` as a call to the
+ * global, and the dashboard schema has an action option named `fetch`.
+ */
+const QUOTED_KEYS = new Set(["fetch"]);
+/** `dataquery` -> `Dataquery`: every exported type starts upper-case. */
+export function typeName(defName) {
+    return defName.charAt(0).toUpperCase() + defName.slice(1);
+}
+function refName(ref) {
+    const m = /^#\/definitions\/(.+)$/.exec(ref);
+    if (!m)
+        throw new Error(`schema-types: only local #/definitions refs are supported, got "${ref}"`);
+    return typeName(m[1]);
+}
+function literal(value) {
+    return JSON.stringify(value);
+}
+function paren(t) {
+    return /[|&]/.test(t) && !/^\{[\s\S]*\}$/.test(t) ? `(${t})` : t;
+}
+function union(parts) {
+    const uniq = [...new Set(parts)];
+    if (uniq.includes("unknown"))
+        return "unknown";
+    return uniq.length === 0 ? "never" : uniq.join(" | ");
+}
+function docComment(node, indent) {
+    const lines = [];
+    const text = typeof node.description === "string" ? node.description.trim() : "";
+    const deprecated = node.deprecated === true || typeof node["x-deprecation-message"] === "string";
+    if (!text && !deprecated)
+        return lines;
+    lines.push(`${indent}/**`);
+    for (const raw of text ? text.replace(/\*\//g, "*\\/").split("\n") : []) {
+        const l = raw.trimEnd();
+        lines.push(`${indent} *${l ? ` ${l}` : ""}`);
+    }
+    if (deprecated) {
+        const msg = typeof node["x-deprecation-message"] === "string" ? ` ${String(node["x-deprecation-message"])}` : "";
+        lines.push(`${indent} * @deprecated${msg.replace(/\*\//g, "*\\/")}`);
+    }
+    lines.push(`${indent} */`);
+    return lines;
+}
+function objectType(node, indent) {
+    const props = node.properties ?? {};
+    const required = new Set(node.required ?? []);
+    const inner = `${indent}  `;
+    const lines = ["{"];
+    for (const [key, child] of Object.entries(props)) {
+        lines.push(...docComment(child, inner));
+        const k = IDENT.test(key) && !QUOTED_KEYS.has(key) ? key : JSON.stringify(key);
+        lines.push(`${inner}${k}${required.has(key) ? "" : "?"}: ${tsType(child, inner)};`);
+    }
+    const ap = node.additionalProperties;
+    if (ap !== undefined && ap !== false) {
+        const t = ap === true || Object.keys(ap).length === 0 ? "unknown" : tsType(ap, inner);
+        lines.push(`${inner}[key: string]: ${Object.keys(props).length > 0 ? "unknown" : t};`);
+    }
+    lines.push(`${indent}}`);
+    return lines.length === 2 ? "Record<string, never>" : lines.join("\n");
+}
+/**
+ * A branch that only constrains which keys are present (`{ required: [...] }`),
+ * like the overlay's "a panel has a `type` or a `libraryPanel`". It says
+ * nothing about the shape, so the type ignores it and validation enforces it.
+ */
+function constraintOnly(branches) {
+    return Array.isArray(branches) && branches.every((b) => Object.keys(b).every((k) => k === "required"));
+}
+/** The TypeScript type for one schema node. */
+export function tsType(node, indent = "") {
+    if (node === undefined || node === true)
+        return "unknown";
+    if (node === false)
+        return "never";
+    if (node.$ref)
+        return refName(node.$ref);
+    if (node.const !== undefined)
+        return literal(node.const);
+    if (Array.isArray(node.enum))
+        return union(node.enum.map(literal));
+    if (node.oneOf && !constraintOnly(node.oneOf))
+        return union(node.oneOf.map((n) => paren(tsType(n, indent))));
+    if (node.anyOf && !constraintOnly(node.anyOf))
+        return union(node.anyOf.map((n) => paren(tsType(n, indent))));
+    if (node.allOf)
+        return node.allOf.map((n) => paren(tsType(n, indent))).join(" & ");
+    const types = Array.isArray(node.type) ? node.type : node.type ? [node.type] : [];
+    if (types.length === 0)
+        return node.properties ? objectType(node, indent) : "unknown";
+    return union(types.map((t) => {
+        switch (t) {
+            case "string":
+                return "string";
+            case "number":
+            case "integer":
+                return "number";
+            case "boolean":
+                return "boolean";
+            case "null":
+                return "null";
+            case "array": {
+                if (Array.isArray(node.items))
+                    return `[${node.items.map((n) => tsType(n, indent)).join(", ")}]`;
+                return `${paren(tsType(node.items, indent))}[]`;
+            }
+            case "object": {
+                if (node.properties)
+                    return objectType(node, indent);
+                const ap = node.additionalProperties;
+                if (ap === false)
+                    return "Record<string, never>";
+                if (ap === undefined || ap === true || Object.keys(ap).length === 0)
+                    return "Record<string, unknown>";
+                return `Record<string, ${tsType(ap, indent)}>`;
+            }
+            default:
+                return "unknown";
+        }
+    }));
+}
+/** One schema file to one TypeScript module. */
+export function schemaModule(name, schema, extra = []) {
+    const defs = (schema.definitions ?? {});
+    const out = [
+        "// Code generated by chant generate from the vendored Grafana schema",
+        `// src/spec/schemas/${name}.jsonschema.json (see src/pin.ts) and its correction`,
+        "// overlay in src/spec/overlay/ (see src/spec/overlay.ts). DO NOT EDIT.",
+        "/* eslint-disable */",
+        "",
+    ];
+    const types = [];
+    for (const [defName, def] of Object.entries(defs)) {
+        const tn = typeName(defName);
+        types.push(tn);
+        out.push(...docComment(def, ""));
+        const t = tsType(def, "");
+        if (t.startsWith("{"))
+            out.push(`export interface ${tn} ${t}`);
+        else
+            out.push(`export type ${tn} = ${t};`);
+        out.push("");
+    }
+    out.push(...extra);
+    return { source: `${out.join("\n").replace(/\n+$/, "")}\n`, types };
+}