@miragon/pulse-analytics-connector 0.0.0-bootstrap.0 → 0.21.0

package/src/brand-gates.test.ts

@@ -0,0 +1,69 @@
+import { fileURLToPath } from "node:url"
+import { describe, expect, it } from "vitest"
+import {
+  catalogTextFindings,
+  scanColors,
+  scanGlyphs,
+  scanIconSizes,
+  scanTypeScale,
+} from "@miragon/pulse-widget-shell/testing"
+import { deAskAi } from "./messages/de.ask-ai.js"
+import { deBuilder } from "./messages/de.builder.js"
+import { deServer } from "./messages/de.server.js"
+import { deSweep } from "./messages/de.sweep.js"
+import { enAskAi } from "./messages/en.ask-ai.js"
+import { enBuilder } from "./messages/en.builder.js"
+import { enServer } from "./messages/en.server.js"
+import { enSweep } from "./messages/en.sweep.js"
+
+/**
+ * The analytics module under the brand gates every widget package runs
+ * (`@miragon/pulse-widget-shell/testing`, CLAUDE.md invariant 6): brand-lint
+ * reads Markdown, not the strings inside `.ts`/`.tsx`, so these hold the
+ * catalogs to the voice rules and the widget code to Lucide icons and role
+ * colours. The terms themselves are `messages/glossary.test.ts`.
+ */
+describe("analytics copy follows the voice rules", () => {
+  it.each([
+    ["widget texts (de)", deSweep, "de"],
+    ["widget texts (en)", enSweep, "en"],
+    ["Ask-AI intents (de)", deAskAi, "de"],
+    ["Ask-AI intents (en)", enAskAi, "en"],
+    ["model summaries (de)", deServer, "de"],
+    ["model summaries (en)", enServer, "en"],
+    ["view builder names (de)", deBuilder, "de"],
+    ["view builder names (en)", enBuilder, "en"],
+  ] as const)("%s", (_, catalog, language) => {
+    expect(catalogTextFindings(catalog, { language })).toEqual([])
+  })
+})
+
+const dir = (rel: string) => fileURLToPath(new URL(rel, import.meta.url))
+
+describe("analytics widgets draw icons with Lucide, never glyphs or emoji", () => {
+  it.each(["./widgets", "./messages"])("%s has no forbidden glyph in JSX or strings", (rel) => {
+    expect(scanGlyphs(dir(rel))).toEqual([])
+  })
+})
+
+describe("analytics widgets draw icons at the CI sizes", () => {
+  // The kit Icon's 16 px in chrome (`dense` for table cells and chips),
+  // 24 px previews: a 12 or 14 px icon is a third size in the same view.
+  it("src/widgets has no icon at a size other than 16 or 24 px", () => {
+    expect(scanIconSizes(dir("./widgets"))).toEqual([])
+  })
+})
+
+describe("analytics widgets colour through role names only", () => {
+  it("src/widgets has no palette class or raw colour", () => {
+    expect(scanColors(dir("./widgets"))).toEqual([])
+  })
+})
+
+describe("analytics widgets set their text on the CI type scale", () => {
+  // Both rules: no Tailwind size (text-sm, text-xl …) and nothing below the
+  // 13 px floor (text-xs); the steps say what the text is (CI §4).
+  it("src/widgets uses only the type-scale steps", () => {
+    expect(scanTypeScale(dir("./widgets"))).toEqual([])
+  })
+})

package/src/builder-texts.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest"
+import {
+  displayTextCatalog,
+  displayTextsSentToModel,
+  missingDisplayTexts,
+} from "@miragon/pulse-widget-shell/testing"
+import { definition } from "./definition.js"
+import { catalogs } from "./messages/index.js"
+
+/**
+ * The view builder (toolkit 2.8) shows people each widget, data source and
+ * props field by its title and summary, else by its id. analytics names every
+ * one of them in English and German, from the `builder.*` entries of its
+ * catalogs — where `brand-gates.test.ts` and `messages/glossary.test.ts` hold
+ * them to the voice and the glossary like the widget texts.
+ */
+describe("analytics names every builder piece for people", () => {
+  it("every widget, step and props field has an en and a de title and summary", () => {
+    expect(missingDisplayTexts(definition)).toEqual([])
+  })
+
+  it("none of those texts reaches the model through get-framework-manifest", () => {
+    expect(displayTextsSentToModel(definition)).toEqual([])
+  })
+
+  it.each(["en", "de"] as const)("%s: no builder entry in the catalog goes unused", (language) => {
+    const shown = new Set(Object.values(displayTextCatalog(definition, language)))
+    const unused = Object.entries(catalogs[language])
+      .filter(([key]) => key.startsWith("builder."))
+      .filter(([, text]) => typeof text !== "string" || !shown.has(text))
+      .map(([key]) => key)
+    expect(unused).toEqual([])
+  })
+
+  it("both languages name the same pieces", () => {
+    const keys = (language: "en" | "de") =>
+      Object.keys(catalogs[language]).filter((key) => key.startsWith("builder."))
+    expect(keys("de")).toEqual(keys("en"))
+  })
+})

package/src/builder-texts.ts

@@ -0,0 +1,15 @@
+import { createBuilderTexts } from "@miragon/pulse-widget-shell/server"
+import { catalogs } from "./messages/index.js"
+
+/**
+ * How the view builder (toolkit 2.8) names analytics' widgets, pipeline steps
+ * and props fields for people, in English and German: the `builder.*`
+ * entries of analytics' catalogs (`messages/{en,de}.builder.ts`), held to the
+ * voice and glossary gates like the widget texts. The definitions'
+ * `description`s stay the model's text.
+ */
+const texts = createBuilderTexts(catalogs, "analytics")
+
+export const builderAppTitle = texts.appTitle
+export const builderText = texts.text
+export const fieldText = texts.field

package/src/definition.ts

@@ -0,0 +1,181 @@
+import { z } from "zod"
+import type { AppDefinition } from "@miragon/mcp-toolkit-core"
+import { PERIODS } from "@miragon/pulse-analytics-client"
+import { loadDashboardStep, loadFailureDashboardStep } from "./steps/index.js"
+import { builderAppTitle, builderText, fieldText } from "./builder-texts.js"
+
+/** The self-fetch's engine scope — a configured engine id or several; omitted = all of them. */
+const engineScopeProp = z
+  .union([z.string(), z.array(z.string())])
+  .optional()
+  .describe(
+    "Configured engine id(s) the self-fetch is scoped to. When omitted, every configured engine is aggregated.",
+  )
+
+const dashboardPropsSchema = z.toJSONSchema(
+  z.object({
+    processDefinitionKey: z
+      .string()
+      .optional()
+      .describe(
+        "Scope the dashboard to a single process definition (e.g. 'miraveloLeasing'). When omitted, all processes are aggregated.",
+      )
+      .meta(fieldText("dashboard.processDefinitionKey")),
+    period: z
+      .enum(PERIODS)
+      .optional()
+      .describe("Time window for the self-fetch when no upstream pipeline step populates data.")
+      .meta(fieldText("dashboard.period")),
+    engine: engineScopeProp.meta(fieldText("dashboard.engine")),
+  }),
+)
+
+const failurePropsSchema = z.toJSONSchema(
+  z.object({ engine: engineScopeProp.meta(fieldText("failure.engine")) }),
+)
+
+const engineLandscapePropsSchema = z.toJSONSchema(
+  z.object({
+    engine: z
+      .union([z.string(), z.array(z.string())])
+      .optional()
+      .describe(
+        "Engine ids to include in the landscape; when omitted, every configured engine (one reporting no metrics shows as not reporting).",
+      )
+      .meta(fieldText("engineLandscape.engine")),
+  }),
+)
+
+export const definition: AppDefinition = {
+  name: "analytics",
+  // The view builder's names for people (en + de); `description` is the model's text.
+  title: builderAppTitle(),
+  steps: [loadDashboardStep, loadFailureDashboardStep],
+  widgets: [
+    {
+      id: "analytics:execution-summary-kpi",
+      ...builderText("widget.execution-summary-kpi"),
+      description:
+        "Top-line KPIs: instances started and completed and incidents created within the period, plus instances running and incidents open right now.",
+      requires: [],
+      consumes: ["analytics:dashboard"],
+      size: "full",
+      propsSchema: dashboardPropsSchema,
+    },
+    {
+      id: "analytics:execution-performance-kpi",
+      ...builderText("widget.execution-performance-kpi"),
+      description:
+        "Duration KPIs of the instances that ended within the period (avg, median, p95) and incidents per 100 started instances.",
+      requires: [],
+      consumes: ["analytics:dashboard"],
+      size: "full",
+      propsSchema: dashboardPropsSchema,
+    },
+    {
+      id: "analytics:process-definition-breakdown",
+      ...builderText("widget.process-definition-breakdown"),
+      description:
+        "Per-process-definition breakdown: instances started and completed and incidents created within the period, instances running now, average duration.",
+      requires: [],
+      consumes: ["analytics:dashboard"],
+      size: "full",
+      propsSchema: dashboardPropsSchema,
+    },
+    {
+      id: "analytics:activity-bottleneck-table",
+      ...builderText("widget.activity-bottleneck-table"),
+      description:
+        "Top (process, activity) pairs by total time spent within the period — surfaces bottlenecks across the process landscape.",
+      requires: [],
+      consumes: ["analytics:dashboard"],
+      size: "full",
+      propsSchema: dashboardPropsSchema,
+    },
+    {
+      id: "analytics:failure-summary-kpi",
+      ...builderText("widget.failure-summary-kpi"),
+      description:
+        "Failure summary KPIs right now (open incidents, incident groups by type × process, most affected process).",
+      requires: [],
+      consumes: ["analytics:failureDashboard"],
+      size: "full",
+      propsSchema: failurePropsSchema,
+    },
+    {
+      id: "analytics:error-patterns-table",
+      ...builderText("widget.error-patterns-table"),
+      description:
+        "The incidents open right now, grouped by incident type and process definition, with counts.",
+      requires: [],
+      consumes: ["analytics:failureDashboard"],
+      size: "full",
+      propsSchema: failurePropsSchema,
+    },
+    {
+      id: "analytics:failure-rate-table",
+      ...builderText("widget.failure-rate-table"),
+      description:
+        "Per-process live failure state: running instances, dead jobs, open incidents and open incidents per 100 running instances.",
+      requires: [],
+      consumes: ["analytics:failureDashboard"],
+      size: "full",
+      propsSchema: failurePropsSchema,
+    },
+    {
+      id: "analytics:cluster-compare",
+      ...builderText("widget.cluster-compare"),
+      description:
+        "Side-by-side before/after comparison of instance KPIs around a deployment timestamp.",
+      requires: [],
+      consumes: ["analytics:clusterCompare"],
+      size: "full",
+    },
+    {
+      id: "analytics:version-compare",
+      ...builderText("widget.version-compare"),
+      description:
+        "Side-by-side per-version comparison of KPIs (starts, durations of the instances that ended; incident rates are not measured per version) across two process versions.",
+      requires: [],
+      consumes: ["analytics:versionCompare"],
+      size: "full",
+    },
+    {
+      id: "analytics:engine-compare",
+      ...builderText("widget.engine-compare"),
+      description:
+        "Side-by-side comparison of KPIs (starts, incident rate, durations of the instances that ended) for ONE process definition as it runs on two engines (e.g. prod-a vs prod-b). Requires a processDefinitionKey — see analytics:engine-landscape for which definitions qualify.",
+      requires: [],
+      consumes: ["analytics:engineCompare"],
+      size: "full",
+    },
+    {
+      id: "analytics:engine-landscape",
+      ...builderText("widget.engine-landscape"),
+      description:
+        "Cross-engine overview: the process × engine inventory matrix, absolute load per engine (running instances, incidents, failed jobs) and the process-independent job backlog. Counts rather than rates, because engines run different process mixes; highlights the definitions deployed on several engines as the valid comparison targets.",
+      requires: [],
+      consumes: ["analytics:engineLandscape"],
+      size: "full",
+      propsSchema: engineLandscapePropsSchema,
+    },
+    {
+      id: "analytics:bpmn-heatmap",
+      ...builderText("widget.bpmn-heatmap"),
+      description:
+        "BPMN diagram with a per-element heat overlay from metrics, toggling between traversal frequency and average duration. Node-only; rendered on the latest deployed version's diagram.",
+      requires: [],
+      consumes: ["analytics:bpmnHeatmap"],
+      size: "full",
+    },
+    {
+      id: "analytics:settings",
+      ...builderText("widget.settings"),
+      description:
+        "The analytics module's settings section: default look-back period and minimum comparison bucket size, applied when analytics calls omit them.",
+      requires: [],
+      consumes: ["analytics:settings"],
+      size: "full",
+    },
+  ],
+}

package/src/engine-ids.ts

@@ -0,0 +1,85 @@
+import type { EngineFilterInput } from "@miragon/pulse-analytics-client"
+
+/**
+ * Which engines analytics may read on this server. A Prometheus (or Thanos /
+ * Mimir) is often shared across teams, and every analytics query reads every
+ * `engine_id` it holds unless told otherwise — so analytics covers exactly the
+ * server's CONFIGURED engine ids, never "whatever Prometheus has":
+ *
+ * - the composition root injects them (`SharedResources.engineIds`, from the
+ *   camunda7 module's engine list) — analytics has no engine-SDK dependency;
+ * - a standalone analytics boot names them in `ANALYTICS_ENGINE_IDS`;
+ * - with neither, analytics is FAIL-CLOSED: every engine-reading tool refuses
+ *   with {@link NO_ENGINE_SCOPE_MESSAGE} (and the boot warns) instead of
+ *   reading the whole Prometheus.
+ *
+ * An omitted `engine` argument resolves to all configured ids (the fleet
+ * view, labelled as such in results); an id outside them is refused.
+ */
+export interface AnalyticsEngineScope {
+  /** The configured ids, in configuration order; empty when none are configured. */
+  readonly ids: readonly string[]
+  /** The concrete ids a query reads for a caller's `engine` filter. Throws on an unknown id. */
+  resolve(requested: EngineFilterInput): string[]
+  /** One configured id (`field` names the argument in the refusal). */
+  require(id: string, field: string): string
+  /** True when `resolved` (a {@link resolve} result) covers every configured engine. */
+  coversFleet(resolved: readonly string[]): boolean
+}
+
+/**
+ * `args` with `engine` replaced by the concrete configured ids it resolves to
+ * — what every engine-reading tool hands its query, so no query ever runs
+ * unscoped against a shared Prometheus.
+ */
+export function withEngineScope<T extends { engine?: EngineFilterInput }>(
+  scope: AnalyticsEngineScope,
+  args: T,
+): Omit<T, "engine"> & { engine: string[] } {
+  return { ...args, engine: scope.resolve(args.engine) }
+}
+
+export const NO_ENGINE_SCOPE_MESSAGE =
+  "Analytics covers no engine: this server configures no engine ids. Activate the camunda7 module (its configured engines scope analytics) or set ANALYTICS_ENGINE_IDS to the engine_id values analytics may read."
+
+/** True when the caller named no engine — the request covers the whole configured fleet. */
+export function isFleetRequest(requested: EngineFilterInput): boolean {
+  if (requested === undefined || requested === null) return true
+  return (Array.isArray(requested) ? requested : [requested]).every((id) => id.length === 0)
+}
+
+export function createEngineScope(configured: readonly string[] | undefined): AnalyticsEngineScope {
+  const ids = [...new Set((configured ?? []).map((id) => id.trim()).filter((id) => id.length > 0))]
+
+  function assertConfigured(): void {
+    if (ids.length === 0) throw new Error(NO_ENGINE_SCOPE_MESSAGE)
+  }
+
+  function refuseUnknown(unknown: string[], field: string): never {
+    const list = unknown.map((id) => `"${id}"`).join(", ")
+    throw new Error(
+      `Unknown engine ${list} in ${field} — analytics covers only this server's configured engines: ${ids.join(", ")}.`,
+    )
+  }
+
+  return {
+    ids,
+    resolve(requested) {
+      assertConfigured()
+      if (isFleetRequest(requested)) return [...ids]
+      const list = typeof requested === "string" ? [requested] : (requested ?? [])
+      const named = [...new Set(list.filter((id) => id.length > 0))]
+      const unknown = named.filter((id) => !ids.includes(id))
+      if (unknown.length > 0) refuseUnknown(unknown, "engine")
+      return named
+    },
+    require(id, field) {
+      assertConfigured()
+      if (!ids.includes(id)) refuseUnknown([id], field)
+      return id
+    },
+    coversFleet(resolved) {
+      return ids.length > 0 && ids.every((id) => resolved.includes(id))
+    },
+  }
+}