@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/src/spec/schemas.ts

@@ -1,25 +1,28 @@
 /**
- * Read the vendored Grafana schemas (`src/spec/schemas/*.jsonschema.json`) and check
- * them against the digests in `GRAFANA_SCHEMA_PIN`.
+ * Read the vendored Grafana schemas (`src/spec/schemas/*.jsonschema.json`), check
+ * them against the digests in `GRAFANA_SCHEMA_PIN`, and apply the correction
+ * overlay (`src/spec/overlay/`, see `./overlay.ts`) on top.
+ *
+ * This is the source side, for `npm run generate`, the lexicon's own
+ * validate step, the importer's tests and the fetch scripts: it reads files
+ * next to this module. Nothing a build or lint runs imports it. Validation
+ * reads the generated `./schemas.gen.ts`, which generate writes from
+ * {@link loadSchema}.
  */
 
 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";
+import { GRAFANA_SCHEMA_PIN, VENDORED_SCHEMA_NAMES, type SchemaName, type VendoredSchemaName } from "../pin";
+import { applyOverlay, loadOverlay } from "./overlay";
 
-/**
- * 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.
- */
+/** Where the vendored files live: beside this module, under `src/`. */
 export function schemasDir(): string {
   return join(dirname(fileURLToPath(import.meta.url)), "schemas");
 }
 
-export function schemaPath(name: SchemaName): string {
+export function schemaPath(name: VendoredSchemaName): string {
   return join(schemasDir(), `${name}.jsonschema.json`);
 }
 
@@ -28,26 +31,37 @@ export function sha256(text: string | Buffer): string {
 }
 
 /** The raw bytes of one vendored schema. */
-export function readSchemaText(name: SchemaName): string {
+export function readSchemaText(name: VendoredSchemaName): string {
   return readFileSync(schemaPath(name), "utf-8");
 }
 
+/** One vendored schema exactly as pinned, parsed, without the overlay. */
+export function loadVendoredSchema(name: VendoredSchemaName): Record<string, unknown> {
+  return JSON.parse(readSchemaText(name)) as Record<string, unknown>;
+}
+
 const parsed = new Map<SchemaName, Record<string, unknown>>();
 
-/** One vendored schema, parsed (cached per process). */
+/**
+ * One schema as the lexicon uses it: the vendored file with its overlay
+ * applied (cached per process). Generate writes the types and
+ * `./schemas.gen.ts` from this, so GRAF107 sees the same schema.
+ */
 export function loadSchema(name: SchemaName): Record<string, unknown> {
   let schema = parsed.get(name);
   if (!schema) {
-    schema = JSON.parse(readSchemaText(name)) as Record<string, unknown>;
+    const vendored = loadVendoredSchema(name);
+    const overlay = loadOverlay(name);
+    schema = overlay ? applyOverlay(vendored, overlay) : vendored;
     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) {
+export function digestMismatches(): Array<{ name: VendoredSchemaName; expected: string; actual: string }> {
+  const out: Array<{ name: VendoredSchemaName; expected: string; actual: string }> = [];
+  for (const name of VENDORED_SCHEMA_NAMES) {
     const actual = sha256(readFileSync(schemaPath(name)));
     const expected = GRAFANA_SCHEMA_PIN.files[name];
     if (actual !== expected) out.push({ name, expected, actual });

package/src/spec/units.gen.ts

@@ -0,0 +1,281 @@
+// Generated by `just fetch-units` (src/spec/fetch-units-cli.ts). Do not edit.
+// Source: https://github.com/grafana/grafana/blob/v13.2.2/packages/grafana-data/src/valueFormats/categories.ts
+// Commit 3db12332b66497c31f8ad2a5fb0eb0fe0ca05a7e, sha256 5ce5651bfb5bfee2d3134fa1a664e9568a4a19689479e5d9bae643f068f3bfcb.
+// The ids Grafana's getValueFormat() indexes, plus the legacy aliases it resolves (valueFormats.ts).
+
+export const GRAFANA_UNIT_IDS: readonly string[] = [
+  "none",
+  "string",
+  "short",
+  "sishort",
+  "percent",
+  "percentunit",
+  "humidity",
+  "dB",
+  "candela",
+  "hex0x",
+  "hex",
+  "sci",
+  "locale",
+  "pixel",
+  "accMS2",
+  "accFS2",
+  "accG",
+  "degree",
+  "radian",
+  "grad",
+  "arcmin",
+  "arcsec",
+  "areaM2",
+  "areaF2",
+  "areaMI2",
+  "acres",
+  "hectares",
+  "flops",
+  "mflops",
+  "gflops",
+  "tflops",
+  "pflops",
+  "eflops",
+  "zflops",
+  "yflops",
+  "ppm",
+  "conppb",
+  "conngm3",
+  "conngNm3",
+  "conμgm3",
+  "conμgNm3",
+  "conmgm3",
+  "conmgNm3",
+  "congm3",
+  "congNm3",
+  "conmgdL",
+  "conmmolL",
+  "currencyUSD",
+  "currencyGBP",
+  "currencyEUR",
+  "currencyJPY",
+  "currencyRUB",
+  "currencyUAH",
+  "currencyBRL",
+  "currencyDKK",
+  "currencyISK",
+  "currencyNOK",
+  "currencySEK",
+  "currencyCZK",
+  "currencyCHF",
+  "currencyPLN",
+  "currencyBTC",
+  "currencymBTC",
+  "currencyμBTC",
+  "currencyZAR",
+  "currencyINR",
+  "currencyKRW",
+  "currencyIDR",
+  "currencyPHP",
+  "currencyVND",
+  "currencyTRY",
+  "currencyMYR",
+  "currencyXPF",
+  "currencyBGN",
+  "currencyPYG",
+  "currencyUYU",
+  "currencyILS",
+  "bytes",
+  "decbytes",
+  "bits",
+  "decbits",
+  "kbytes",
+  "deckbytes",
+  "mbytes",
+  "decmbytes",
+  "gbytes",
+  "decgbytes",
+  "tbytes",
+  "dectbytes",
+  "pbytes",
+  "decpbytes",
+  "pps",
+  "binBps",
+  "Bps",
+  "binbps",
+  "bps",
+  "KiBs",
+  "Kibits",
+  "KBs",
+  "Kbits",
+  "MiBs",
+  "Mibits",
+  "MBs",
+  "Mbits",
+  "GiBs",
+  "Gibits",
+  "GBs",
+  "Gbits",
+  "TiBs",
+  "Tibits",
+  "TBs",
+  "Tbits",
+  "PiBs",
+  "Pibits",
+  "PBs",
+  "Pbits",
+  "dateTimeAsIso",
+  "dateTimeAsIsoNoDateIfToday",
+  "dateTimeAsUS",
+  "dateTimeAsUSNoDateIfToday",
+  "dateTimeAsLocal",
+  "dateTimeAsLocalNoDateIfToday",
+  "dateTimeAsSystem",
+  "dateTimeFromNow",
+  "watt",
+  "kwatt",
+  "megwatt",
+  "gwatt",
+  "mwatt",
+  "Wm2",
+  "voltamp",
+  "kvoltamp",
+  "voltampreact",
+  "kvoltampreact",
+  "watth",
+  "watthperkg",
+  "kwatth",
+  "kwattm",
+  "mwatth",
+  "amph",
+  "kamph",
+  "mamph",
+  "joule",
+  "ev",
+  "amp",
+  "kamp",
+  "mamp",
+  "volt",
+  "kvolt",
+  "mvolt",
+  "dBm",
+  "mohm",
+  "ohm",
+  "kohm",
+  "Mohm",
+  "farad",
+  "µfarad",
+  "nfarad",
+  "pfarad",
+  "ffarad",
+  "henry",
+  "mhenry",
+  "µhenry",
+  "lumens",
+  "flowgpm",
+  "flowcms",
+  "flowcfs",
+  "flowcfm",
+  "litreh",
+  "flowlpm",
+  "flowmlpm",
+  "lux",
+  "forceNm",
+  "forcekNm",
+  "forceN",
+  "forcekN",
+  "Hs",
+  "KHs",
+  "MHs",
+  "GHs",
+  "THs",
+  "PHs",
+  "EHs",
+  "massmg",
+  "massg",
+  "masslb",
+  "masskg",
+  "masst",
+  "lengthmm",
+  "lengthcm",
+  "lengthin",
+  "lengthft",
+  "lengthm",
+  "lengthkm",
+  "lengthmi",
+  "pressurembar",
+  "pressurebar",
+  "pressurekbar",
+  "pressurepa",
+  "pressurehpa",
+  "pressurekpa",
+  "pressurehg",
+  "pressurepsi",
+  "radbq",
+  "radci",
+  "radgy",
+  "radrad",
+  "radsv",
+  "radmsv",
+  "radusv",
+  "radrem",
+  "radexpckg",
+  "radr",
+  "radsvh",
+  "radmsvh",
+  "radusvh",
+  "rotrpm",
+  "rothz",
+  "rotkhz",
+  "rotmhz",
+  "rotghz",
+  "rotrads",
+  "rotdegs",
+  "celsius",
+  "fahrenheit",
+  "kelvin",
+  "hertz",
+  "ns",
+  "µs",
+  "ms",
+  "s",
+  "m",
+  "h",
+  "d",
+  "dtdurationms",
+  "dtdurations",
+  "dthms",
+  "dtdhms",
+  "timeticks",
+  "clockms",
+  "clocks",
+  "cps",
+  "ops",
+  "reqps",
+  "rps",
+  "wps",
+  "iops",
+  "eps",
+  "mps",
+  "recps",
+  "rowsps",
+  "cpm",
+  "opm",
+  "reqpm",
+  "rpm",
+  "wpm",
+  "epm",
+  "mpm",
+  "recpm",
+  "rowspm",
+  "velocityms",
+  "velocitykmh",
+  "velocitymph",
+  "velocityknot",
+  "mlitre",
+  "litre",
+  "m3",
+  "Nm3",
+  "dm3",
+  "gallons",
+  "bool",
+  "bool_yes_no",
+  "bool_on_off",
+  "farenheit",
+];

package/src/spec/units.ts

@@ -0,0 +1,77 @@
+/**
+ * The units Grafana knows, for GRAF115.
+ *
+ * A field's `unit` is a free string in the dashboard schema. Grafana looks it
+ * up in its value-format registry (`getValueFormat()` in
+ * `packages/grafana-data/src/valueFormats/valueFormats.ts`): a registered id
+ * formats the value, `<kind>:<arg>` builds a custom unit, and anything else is
+ * shown after the value as a literal suffix. So `"byte"` renders `5 byte`
+ * where `"bytes"` would render `5 B`, and nothing complains.
+ *
+ * The ids in `units.gen.ts` are taken from the registry at
+ * `GRAFANA_UNITS_SOURCE` by `just fetch-units`.
+ */
+
+import { GRAFANA_UNIT_IDS } from "./units.gen";
+
+export const GRAFANA_UNITS_SOURCE = Object.freeze({
+  repo: "grafana/grafana",
+  ref: "v13.2.2",
+  commit: "3db12332b66497c31f8ad2a5fb0eb0fe0ca05a7e",
+  path: "packages/grafana-data/src/valueFormats/categories.ts",
+});
+
+/** Old ids `buildFormats()` in valueFormats.ts still resolves (v13.2.2). */
+export const LEGACY_UNIT_ALIASES: readonly string[] = ["farenheit"];
+
+/**
+ * The `<kind>:` prefixes `getValueFormat()` turns into a custom unit
+ * (v13.2.2): `prefix:$`, `suffix: req`, `time:YYYY-MM-DD`, `si:mF`,
+ * `count:reqs`, `currency:€` (or `currency:financial:€[:suffix]`) and
+ * `bool:yes/no`.
+ */
+export const CUSTOM_UNIT_KINDS: readonly string[] = ["prefix", "suffix", "time", "si", "count", "currency", "bool"];
+
+const KNOWN = new Set(GRAFANA_UNIT_IDS);
+
+export { GRAFANA_UNIT_IDS };
+
+/** Whether Grafana formats `unit` as a unit rather than showing it as a literal suffix. An empty unit means none. */
+export function isGrafanaUnit(unit: string): boolean {
+  if (unit === "" || KNOWN.has(unit)) return true;
+  const colon = unit.indexOf(":");
+  return colon > 0 && CUSTOM_UNIT_KINDS.includes(unit.slice(0, colon));
+}
+
+function distance(a: string, b: string): number {
+  const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const next = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = next;
+    }
+  }
+  return row[b.length];
+}
+
+/** The registered id `unit` most likely meant: same letters in another case, or one or two edits away. */
+export function closestGrafanaUnit(unit: string): string | undefined {
+  const lower = unit.toLowerCase();
+  const sameCase = GRAFANA_UNIT_IDS.filter((id) => id.toLowerCase() === lower);
+  if (sameCase.length === 1) return sameCase[0];
+  if (unit.length < 3) return undefined;
+  let best: string | undefined;
+  let bestDistance = Math.min(2, Math.floor(unit.length / 3));
+  for (const id of GRAFANA_UNIT_IDS) {
+    if (LEGACY_UNIT_ALIASES.includes(id)) continue;
+    const d = distance(lower, id.toLowerCase());
+    if (d < bestDistance || (d === bestDistance && best === undefined)) {
+      best = id;
+      bestDistance = d;
+    }
+  }
+  return best;
+}

package/src/transformations.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vitest";
+import { TRANSFORMATION_IDS, customTransformation, transformation, untypedTransformationReason, type Transformation } from "./transformations";
+import { TablePanel } from "./panels";
+import { Dashboard } from "./dashboard";
+import { dashboardJson } from "./build";
+
+describe("transformation types", () => {
+  test("cover every transformer Grafana v13.2.2 registers (DataTransformerID less the unregistered append)", () => {
+    // packages/grafana-data/src/transformations/transformers/ids.ts at v13.2.2.
+    const ids =
+      "reduce order organize rename calculateField seriesToColumns seriesToRows merge concatenate labelsToFields filterFields " +
+      "filterFieldsByName filterFrames filterByRefId renameByRegex filterByValue noop ensureColumns groupBy sortBy histogram " +
+      "configFromData rowsToFields prepareTimeSeries convertFieldType convertFrameType fieldLookup heatmap spatial joinByField " +
+      "joinByLabels extractFields groupingToMatrix limit partitionByValues timeSeriesTable transpose formatTime formatString " +
+      "regression smoothing groupToNestedTable";
+    expect([...TRANSFORMATION_IDS].sort()).toEqual(ids.split(" ").sort());
+  });
+
+  test("typed transformations, the helper and the escape hatch serialize as Grafana stores them", () => {
+    const transformations: Transformation[] = [
+      { id: "organize", options: { excludeByName: { Time: true }, renameByName: { Value: "Requests" } } },
+      transformation("reduce", { reducers: ["max", "p95"], mode: "reduceFields" }, { disabled: true }),
+      transformation("merge"),
+      customTransformation("my-plugin-transformer", { level: 3 }, { topic: "annotations" }),
+    ];
+    const d = new Dashboard({ title: "T", uid: "t", panels: [new TablePanel({ title: "p", transformations })] });
+    const panel = (JSON.parse(dashboardJson(d)) as { panels: Array<{ transformations: unknown }> }).panels[0];
+    expect(panel.transformations).toEqual([
+      { id: "organize", options: { excludeByName: { Time: true }, renameByName: { Value: "Requests" } } },
+      { id: "reduce", options: { reducers: ["max", "p95"], mode: "reduceFields" }, disabled: true },
+      { id: "merge", options: {} },
+      { id: "my-plugin-transformer", options: { level: 3 }, topic: "annotations" },
+    ]);
+  });
+
+  test("the types reject an unknown id, an unknown option and a bad enum value", () => {
+    const bad: Transformation[] = [
+      // @ts-expect-error: not a transformer Grafana registers; customTransformation() takes one
+      { id: "my-plugin-transformer", options: {} },
+      // @ts-expect-error: organize has excludeByName, not excludeByname
+      { id: "organize", options: { excludeByname: {} } },
+      // @ts-expect-error: not a ReducerID
+      { id: "reduce", options: { reducers: ["maximum"] } },
+    ];
+    // @ts-expect-error: sortBy takes `sort`, not `fields`; the helper checks against the one transformer
+    transformation("sortBy", { fields: {} });
+    expect(bad).toHaveLength(3);
+  });
+});
+
+describe("untypedTransformationReason, which the importer uses", () => {
+  test("is undefined for what the types hold", () => {
+    expect(untypedTransformationReason({ id: "organize", options: { excludeByName: {}, indexByName: {} }, disabled: false })).toBeUndefined();
+    expect(untypedTransformationReason({ id: "merge", options: {} })).toBeUndefined();
+    expect(untypedTransformationReason({ id: "timeSeriesTable", options: { A: { stat: "mean" } } })).toBeUndefined();
+    expect(untypedTransformationReason({ id: "limit" })).toBeUndefined();
+  });
+
+  test("names what they don't", () => {
+    expect(untypedTransformationReason({ id: "grafana-plugin-x", options: {} })).toBe('"grafana-plugin-x" is not a transformer Grafana v13.2.2 registers');
+    expect(untypedTransformationReason({ id: "sortBy", options: { fields: {}, sort: [] } })).toBe('the sortBy transformer takes no option "fields"');
+    expect(untypedTransformationReason({ id: "merge", options: {}, name: "x" })).toBe('it has "name" beside its id and options');
+    expect(untypedTransformationReason({ id: "reduce", options: [] })).toBe("its options are not an object");
+  });
+});