@intentius/chant-lexicon-grafana 0.96.0

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

@@ -0,0 +1,471 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "Options": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "legend",
+        "tooltip"
+      ],
+      "properties": {
+        "timezone": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/TimeZone"
+          }
+        },
+        "legend": {
+          "$ref": "#/definitions/VizLegendOptions",
+          "default": {
+            "calcs": [],
+            "displayMode": "list",
+            "placement": "bottom"
+          }
+        },
+        "tooltip": {
+          "$ref": "#/definitions/VizTooltipOptions"
+        },
+        "orientation": {
+          "$ref": "#/definitions/VizOrientation"
+        }
+      }
+    },
+    "FieldConfig": {
+      "$ref": "#/definitions/GraphFieldConfig"
+    },
+    "TimeZone": {
+      "type": "string",
+      "description": "A specific timezone from https://en.wikipedia.org/wiki/Tz_database"
+    },
+    "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"
+    },
+    "VizOrientation": {
+      "enum": [
+        "auto",
+        "vertical",
+        "horizontal"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "GraphFieldConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "drawStyle": {
+          "$ref": "#/definitions/GraphDrawStyle"
+        },
+        "gradientMode": {
+          "$ref": "#/definitions/GraphGradientMode"
+        },
+        "thresholdsStyle": {
+          "$ref": "#/definitions/GraphThresholdsStyleConfig"
+        },
+        "transform": {
+          "$ref": "#/definitions/GraphTransform"
+        },
+        "lineColor": {
+          "type": "string"
+        },
+        "lineWidth": {
+          "type": "number"
+        },
+        "lineInterpolation": {
+          "$ref": "#/definitions/LineInterpolation"
+        },
+        "lineStyle": {
+          "$ref": "#/definitions/LineStyle"
+        },
+        "fillColor": {
+          "type": "string"
+        },
+        "fillOpacity": {
+          "type": "number"
+        },
+        "showPoints": {
+          "$ref": "#/definitions/VisibilityMode"
+        },
+        "pointSize": {
+          "type": "number"
+        },
+        "pointColor": {
+          "type": "string"
+        },
+        "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"
+        },
+        "barAlignment": {
+          "$ref": "#/definitions/BarAlignment"
+        },
+        "barWidthFactor": {
+          "type": "number"
+        },
+        "stacking": {
+          "$ref": "#/definitions/StackingConfig"
+        },
+        "hideFrom": {
+          "$ref": "#/definitions/HideSeriesConfig"
+        },
+        "insertNulls": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "number"
+            }
+          ]
+        },
+        "spanNulls": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "number"
+            }
+          ],
+          "description": "Indicate if null values should be treated as gaps or connected.\nWhen the value is a number, it represents the maximum delta in the\nX axis that should be considered connected.  For timeseries, this is milliseconds"
+        },
+        "fillBelowTo": {
+          "type": "string"
+        },
+        "pointSymbol": {
+          "type": "string"
+        },
+        "axisBorderShow": {
+          "type": "boolean"
+        },
+        "barMaxWidth": {
+          "type": "number"
+        }
+      },
+      "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"
+    },
+    "GraphDrawStyle": {
+      "enum": [
+        "line",
+        "bars",
+        "points"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "GraphGradientMode": {
+      "enum": [
+        "none",
+        "opacity",
+        "hue",
+        "scheme"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "GraphThresholdsStyleConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode"
+      ],
+      "properties": {
+        "mode": {
+          "$ref": "#/definitions/GraphThresholdsStyleMode"
+        }
+      },
+      "description": "TODO docs"
+    },
+    "GraphTransform": {
+      "enum": [
+        "constant",
+        "negative-Y"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "LineInterpolation": {
+      "enum": [
+        "linear",
+        "smooth",
+        "stepBefore",
+        "stepAfter"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "LineStyle": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "fill": {
+          "enum": [
+            "solid",
+            "dash",
+            "dot",
+            "square"
+          ],
+          "type": "string"
+        },
+        "dash": {
+          "type": "array",
+          "items": {
+            "type": "number"
+          }
+        }
+      },
+      "description": "TODO docs"
+    },
+    "VisibilityMode": {
+      "enum": [
+        "auto",
+        "never",
+        "always"
+      ],
+      "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"
+    },
+    "BarAlignment": {
+      "enum": [
+        -1,
+        0,
+        1
+      ],
+      "type": "integer",
+      "description": "TODO docs"
+    },
+    "StackingConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": {
+          "$ref": "#/definitions/StackingMode"
+        },
+        "group": {
+          "type": "string"
+        }
+      },
+      "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"
+    },
+    "GraphThresholdsStyleMode": {
+      "enum": [
+        "off",
+        "line",
+        "dashed",
+        "area",
+        "line+area",
+        "dashed+area",
+        "series"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "ScaleDistribution": {
+      "enum": [
+        "linear",
+        "log",
+        "ordinal",
+        "symlog"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    },
+    "StackingMode": {
+      "enum": [
+        "none",
+        "normal",
+        "percent"
+      ],
+      "type": "string",
+      "description": "TODO docs"
+    }
+  }
+}

package/src/spec/schemas.ts

@@ -0,0 +1,56 @@
+/**
+ * Read the vendored Grafana schemas (`src/spec/schemas/*.jsonschema.json`) and check
+ * them against the digests in `GRAFANA_SCHEMA_PIN`.
+ */
+
+import { createHash } from "crypto";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { GRAFANA_SCHEMA_PIN, SCHEMA_NAMES, type SchemaName } from "../pin";
+
+/**
+ * Where the vendored files live: beside this module, under `src/`, so they
+ * ship with the source the package runs from and GRAF107 can read them.
+ * A function, not a module-scope constant, so edge bundles that import the
+ * lexicon never evaluate a filesystem path at load.
+ */
+export function schemasDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "schemas");
+}
+
+export function schemaPath(name: SchemaName): string {
+  return join(schemasDir(), `${name}.jsonschema.json`);
+}
+
+export function sha256(text: string | Buffer): string {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+/** The raw bytes of one vendored schema. */
+export function readSchemaText(name: SchemaName): string {
+  return readFileSync(schemaPath(name), "utf-8");
+}
+
+const parsed = new Map<SchemaName, Record<string, unknown>>();
+
+/** One vendored schema, parsed (cached per process). */
+export function loadSchema(name: SchemaName): Record<string, unknown> {
+  let schema = parsed.get(name);
+  if (!schema) {
+    schema = JSON.parse(readSchemaText(name)) as Record<string, unknown>;
+    parsed.set(name, schema);
+  }
+  return schema;
+}
+
+/** Vendored files whose digest does not match the pin, with what was found. */
+export function digestMismatches(): Array<{ name: SchemaName; expected: string; actual: string }> {
+  const out: Array<{ name: SchemaName; expected: string; actual: string }> = [];
+  for (const name of SCHEMA_NAMES) {
+    const actual = sha256(readFileSync(schemaPath(name)));
+    const expected = GRAFANA_SCHEMA_PIN.files[name];
+    if (actual !== expected) out.push({ name, expected, actual });
+  }
+  return out;
+}

package/src/util.ts

@@ -0,0 +1,43 @@
+/** Small helpers shared by the entity modules and the builder. */
+
+/** Every field optional, all the way down; arrays keep their element type partial too. */
+export type DeepPartial<T> = T extends (infer U)[]
+  ? DeepPartial<U>[]
+  : T extends object
+    ? { [K in keyof T]?: DeepPartial<T[K]> }
+    : T;
+
+/** Grafana's uid alphabet: letters, digits, `-` and `_`, at most 40 characters. */
+export const UID_PATTERN = /^[A-Za-z0-9_-]{1,40}$/;
+
+export function isValidUid(uid: string): boolean {
+  return UID_PATTERN.test(uid);
+}
+
+/**
+ * A uid from free text (an export name or a datasource name): camelCase and
+ * spaces become `-`, anything outside the uid alphabet is dropped, and the
+ * result is cut to 40 characters.
+ */
+export function slugUid(text: string): string {
+  const slug = text
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^A-Za-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+  return slug.slice(0, 40).replace(/-$/, "") || "dashboard";
+}
+
+/** Copy `value` with every `undefined` property dropped, recursively; keeps key order. */
+export function compact<T>(value: T): T {
+  if (Array.isArray(value)) return value.map((v) => compact(v)) as unknown as T;
+  if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (v !== undefined) out[k] = compact(v);
+    }
+    return out as T;
+  }
+  return value;
+}

package/src/validate-cli.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+import { validate } from "./validate";
+
+const result = await validate();
+printValidationResult(result);
+if (!result.success) process.exit(1);