@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/spec/overlay.ts

@@ -0,0 +1,105 @@
+/**
+ * The correction overlay: checked-in patches applied to the vendored schemas
+ * before type generation and validation.
+ *
+ * The vendored foundation-sdk schemas are stricter than Grafana's own CUE
+ * (`additionalProperties: false` everywhere, `options` typed as a record
+ * where the CUE says `_`, fields required that the CUE defaults) and lag it
+ * (no `MatcherConfig.scope`). Each `src/spec/overlay/<name>.overlay.json`
+ * lists patches for one schema. A patch is a small JSON-patch operation
+ * (`add`, `replace` or `remove`, RFC 6902 paths) and cites the Grafana
+ * source line it follows, so every correction is traceable and can be
+ * dropped when the pin catches up.
+ *
+ * Applying is strict: `add` refuses a key that is already there and
+ * `replace`/`remove` refuse a path that is not, so bumping the pin to a
+ * schema that already carries a fix fails `npm run generate` until the
+ * patch is removed.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import type { SchemaName } from "../pin";
+
+export interface OverlayPatch {
+  op: "add" | "replace" | "remove";
+  /** JSON pointer into the vendored schema. */
+  path: string;
+  value?: unknown;
+  /** The Grafana source this follows: `<repo path>:<line>` at the tag named in the file. */
+  source: string;
+  /** Why the vendored schema is wrong here. */
+  why: string;
+}
+
+export interface SchemaOverlay {
+  $comment?: string;
+  schema: SchemaName;
+  /** The Grafana tag(s) the `source` lines refer to. */
+  grafana: string;
+  patches: OverlayPatch[];
+}
+
+export function overlayDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "overlay");
+}
+
+export function overlayPath(name: SchemaName): string {
+  return join(overlayDir(), `${name}.overlay.json`);
+}
+
+/** The overlay for one schema, or undefined when it has none. */
+export function loadOverlay(name: SchemaName): SchemaOverlay | undefined {
+  const path = overlayPath(name);
+  if (!existsSync(path)) return undefined;
+  const overlay = JSON.parse(readFileSync(path, "utf-8")) as SchemaOverlay;
+  if (overlay.schema !== name) throw new Error(`grafana overlay ${path}: names schema "${overlay.schema}", expected "${name}"`);
+  return overlay;
+}
+
+function unescape(token: string): string {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function fail(name: string, i: number, p: OverlayPatch, msg: string): never {
+  throw new Error(`grafana overlay ${name} patch ${i} (${p.op} ${p.path}): ${msg}`);
+}
+
+/** A copy of `schema` with every patch applied, in order. */
+export function applyOverlay(schema: Record<string, unknown>, overlay: SchemaOverlay): Record<string, unknown> {
+  const out = structuredClone(schema);
+  overlay.patches.forEach((p, i) => {
+    if (!p.source || !p.why) fail(overlay.schema, i, p, "every patch needs a source and a why");
+    if (!p.path.startsWith("/")) fail(overlay.schema, i, p, "path must be a JSON pointer");
+    const tokens = p.path.slice(1).split("/").map(unescape);
+    const last = tokens.pop()!;
+    let parent: unknown = out;
+    for (const t of tokens) {
+      parent = Array.isArray(parent) ? parent[Number(t)] : (parent as Record<string, unknown> | undefined)?.[t];
+      if (parent === undefined || parent === null || typeof parent !== "object") fail(overlay.schema, i, p, `no parent at "${t}"`);
+    }
+    if (Array.isArray(parent)) {
+      const idx = last === "-" ? parent.length : Number(last);
+      if (!Number.isInteger(idx) || idx < 0 || idx > parent.length) fail(overlay.schema, i, p, "bad array index");
+      if (p.op === "add") parent.splice(idx, 0, structuredClone(p.value));
+      else if (idx >= parent.length) fail(overlay.schema, i, p, "no such element");
+      else if (p.op === "replace") parent[idx] = structuredClone(p.value);
+      else parent.splice(idx, 1);
+      return;
+    }
+    const obj = parent as Record<string, unknown>;
+    const has = Object.prototype.hasOwnProperty.call(obj, last);
+    if (p.op === "add") {
+      if (has) fail(overlay.schema, i, p, "already present in the vendored schema; drop this patch");
+      obj[last] = structuredClone(p.value);
+    } else if (!has) {
+      fail(overlay.schema, i, p, "not present in the vendored schema");
+    } else if (p.op === "replace") {
+      obj[last] = structuredClone(p.value);
+    } else {
+      delete obj[last];
+    }
+  });
+  return out;
+}

package/src/spec/schemas/barchart.jsonschema.json

@@ -0,0 +1,419 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "Options": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "orientation",
+        "xTickLabelRotation",
+        "xTickLabelMaxLength",
+        "stacking",
+        "showValue",
+        "barWidth",
+        "groupWidth",
+        "legend",
+        "tooltip",
+        "fullHighlight"
+      ],
+      "properties": {
+        "xField": {
+          "type": "string",
+          "description": "Manually select which field from the dataset to represent the x field."
+        },
+        "colorByField": {
+          "type": "string",
+          "description": "Use the color value for a sibling field to color each bar value."
+        },
+        "orientation": {
+          "$ref": "#/definitions/VizOrientation",
+          "description": "Controls the orientation of the bar chart, either vertical or horizontal.",
+          "default": "auto"
+        },
+        "barRadius": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 0.5,
+          "description": "Controls the radius of each bar.",
+          "default": 0
+        },
+        "xTickLabelRotation": {
+          "type": "integer",
+          "minimum": -90,
+          "maximum": 90,
+          "description": "Controls the rotation of the x axis labels.",
+          "default": 0
+        },
+        "xTickLabelMaxLength": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Sets the max length that a label can have before it is truncated."
+        },
+        "xTickLabelSpacing": {
+          "type": "integer",
+          "description": "Controls the spacing between x axis labels.\nnegative values indicate backwards skipping behavior",
+          "default": 0
+        },
+        "stacking": {
+          "$ref": "#/definitions/StackingMode",
+          "description": "Controls whether bars are stacked or not, either normally or in percent mode.",
+          "default": "none"
+        },
+        "showValue": {
+          "$ref": "#/definitions/VisibilityMode",
+          "description": "This controls whether values are shown on top or to the left of bars.",
+          "default": "auto"
+        },
+        "barWidth": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Controls the width of bars. 1 = Max width, 0 = Min width.",
+          "default": 0.97
+        },
+        "groupWidth": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Controls the width of groups. 1 = max with, 0 = min width.",
+          "default": 0.7
+        },
+        "legend": {
+          "$ref": "#/definitions/VizLegendOptions"
+        },
+        "tooltip": {
+          "$ref": "#/definitions/VizTooltipOptions"
+        },
+        "text": {
+          "$ref": "#/definitions/VizTextDisplayOptions"
+        },
+        "fullHighlight": {
+          "type": "boolean",
+          "description": "Enables mode which highlights the entire bar area and shows tooltip when cursor\nhovers over highlighted area",
+          "default": false
+        }
+      }
+    },
+    "FieldConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "lineWidth": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10,
+          "description": "Controls line width of the bars.",
+          "default": 1
+        },
+        "fillOpacity": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Controls the fill opacity of the bars.",
+          "default": 80
+        },
+        "gradientMode": {
+          "$ref": "#/definitions/GraphGradientMode",
+          "description": "Set the mode of the gradient fill. Fill gradient is based on the line color. To change the color, use the standard color scheme field option.\nGradient appearance is influenced by the Fill opacity setting.",
+          "default": "none"
+        },
+        "axisPlacement": {
+          "$ref": "#/definitions/AxisPlacement"
+        },
+        "axisColorMode": {
+          "$ref": "#/definitions/AxisColorMode"
+        },
+        "axisLabel": {
+          "type": "string"
+        },
+        "axisWidth": {
+          "type": "number"
+        },
+        "axisSoftMin": {
+          "type": "number"
+        },
+        "axisSoftMax": {
+          "type": "number"
+        },
+        "axisGridShow": {
+          "type": "boolean"
+        },
+        "scaleDistribution": {
+          "$ref": "#/definitions/ScaleDistributionConfig"
+        },
+        "axisCenteredZero": {
+          "type": "boolean"
+        },
+        "hideFrom": {
+          "$ref": "#/definitions/HideSeriesConfig"
+        },
+        "thresholdsStyle": {
+          "$ref": "#/definitions/GraphThresholdsStyleConfig",
+          "description": "Threshold rendering"
+        },
+        "axisBorderShow": {
+          "type": "boolean"
+        }
+      }
+    },
+    "VizOrientation": {
+      "enum": [
+        "auto",
+        "vertical",
+        "horizontal"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "StackingMode": {
+      "enum": [
+        "none",
+        "normal",
+        "percent"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "VisibilityMode": {
+      "enum": [
+        "auto",
+        "never",
+        "always"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "VizLegendOptions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "displayMode",
+        "placement",
+        "showLegend",
+        "calcs"
+      ],
+      "properties": {
+        "displayMode": {
+          "$ref": "#/definitions/LegendDisplayMode",
+          "default": "list"
+        },
+        "placement": {
+          "$ref": "#/definitions/LegendPlacement",
+          "default": "bottom"
+        },
+        "showLegend": {
+          "type": "boolean"
+        },
+        "asTable": {
+          "type": "boolean"
+        },
+        "isVisible": {
+          "type": "boolean"
+        },
+        "sortBy": {
+          "type": "string"
+        },
+        "sortDesc": {
+          "type": "boolean"
+        },
+        "width": {
+          "type": "number"
+        },
+        "calcs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        }
+      },
+      "description": "TODO docs"
+    },
+    "VizTooltipOptions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode",
+        "sort"
+      ],
+      "properties": {
+        "mode": {
+          "$ref": "#/definitions/TooltipDisplayMode"
+        },
+        "sort": {
+          "$ref": "#/definitions/SortOrder"
+        },
+        "maxWidth": {
+          "type": "number"
+        },
+        "maxHeight": {
+          "type": "number"
+        },
+        "hideZeros": {
+          "type": "boolean"
+        }
+      },
+      "description": "TODO docs"
+    },
+    "VizTextDisplayOptions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "titleSize": {
+          "type": "number",
+          "description": "Explicit title text size"
+        },
+        "valueSize": {
+          "type": "number",
+          "description": "Explicit value text size"
+        },
+        "percentSize": {
+          "type": "number",
+          "description": "Explicit percent text size"
+        }
+      },
+      "description": "TODO docs"
+    },
+    "GraphGradientMode": {
+      "enum": [
+        "none",
+        "opacity",
+        "hue",
+        "scheme"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "AxisPlacement": {
+      "enum": [
+        "auto",
+        "top",
+        "right",
+        "bottom",
+        "left",
+        "hidden"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "AxisColorMode": {
+      "enum": [
+        "text",
+        "series"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "ScaleDistributionConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "type": {
+          "$ref": "#/definitions/ScaleDistribution"
+        },
+        "log": {
+          "type": "number"
+        },
+        "linearThreshold": {
+          "type": "number"
+        }
+      },
+      "description": "TODO docs"
+    },
+    "HideSeriesConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "tooltip",
+        "legend",
+        "viz"
+      ],
+      "properties": {
+        "tooltip": {
+          "type": "boolean"
+        },
+        "legend": {
+          "type": "boolean"
+        },
+        "viz": {
+          "type": "boolean"
+        }
+      },
+      "description": "TODO docs"
+    },
+    "GraphThresholdsStyleConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode"
+      ],
+      "properties": {
+        "mode": {
+          "$ref": "#/definitions/GraphThresholdsStyleMode"
+        }
+      },
+      "description": "TODO docs"
+    },
+    "LegendDisplayMode": {
+      "enum": [
+        "list",
+        "table",
+        "hidden"
+      ],
+      "type": "string",
+      "description": "TODO docs\nNote: \"hidden\" needs to remain as an option for plugins compatibility"
+    },
+    "LegendPlacement": {
+      "enum": [
+        "bottom",
+        "right"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "TooltipDisplayMode": {
+      "enum": [
+        "single",
+        "multi",
+        "none"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "SortOrder": {
+      "enum": [
+        "asc",
+        "desc",
+        "none"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "ScaleDistribution": {
+      "enum": [
+        "linear",
+        "log",
+        "ordinal",
+        "symlog"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "GraphThresholdsStyleMode": {
+      "enum": [
+        "off",
+        "line",
+        "dashed",
+        "area",
+        "line+area",
+        "dashed+area",
+        "series"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    }
+  }
+}