@scope-profiler/plotly 0.1.0

package/LICENSE.txt

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) scope-profiler contributors

package/README.md

@@ -0,0 +1,17 @@
+# @scope-profiler/plotly
+
+Pure, framework-neutral Plotly figure builders for JSON written by
+`scope-profiler export plot-data --format json`. The package does not import
+Plotly; applications choose their own Plotly bundle.
+
+```js
+import Plotly from "plotly.js-dist-min";
+import { buildGanttFigure, renderFigure } from "@scope-profiler/plotly";
+
+const payload = await fetch("/figures/gantt_data.json").then((response) => response.json());
+const figure = buildGanttFigure(payload);
+await renderFigure(Plotly, document.querySelector("#gantt"), figure);
+```
+
+Builders accept both the current scope-profiler payloads and versioned payloads
+with `format: "scope-profiler-plot-data"` and `format_version: 1`.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@scope-profiler/plotly",
+  "version": "0.1.0",
+  "description": "Framework-neutral Plotly figure builders for scope-profiler plot-data JSON.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/max-models/scope-profiler.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": ["src", "README.md", "LICENSE.txt"],
+  "publishConfig": { "access": "public" },
+  "scripts": { "test": "node --test" },
+  "keywords": ["scope-profiler", "plotly", "profiling", "gantt", "flamegraph"]
+}

package/src/index.d.ts

@@ -0,0 +1,8 @@
+export interface Figure { data: object[]; layout: object }
+export interface PlotlyLike { newPlot(element: Element | string, data: object[], layout: object, config?: object): unknown }
+export interface BuildOptions { colors?: Record<string, string>; filterRegion?: (region: string, row: object) => boolean; layout?: object; metric?: string; xField?: string; ideal?: boolean; rootLabel?: string }
+export function buildGanttFigure(payload: object, options?: BuildOptions): Figure;
+export function buildFlameFigure(payload: object, options?: BuildOptions): Figure;
+export function buildDurationsFigure(payload: object, options?: BuildOptions): Figure;
+export function buildSpeedupFigure(payload: object, options?: BuildOptions): Figure;
+export function renderFigure(plotly: PlotlyLike, element: Element | string, figure: Figure, config?: object): unknown;

package/src/index.js

@@ -0,0 +1,104 @@
+/** Framework-neutral Plotly specifications for scope-profiler plot-data. */
+
+const DEFAULT_COLORS = ["#2a78d6", "#eb6834", "#1baf7a", "#eda100", "#e87ba4", "#008300", "#4a3aa7", "#e34948"];
+const NEUTRAL = "#898781";
+
+function colorMap(names, supplied = {}) {
+  const map = new Map();
+  let index = 0;
+  for (const name of names) {
+    if (map.has(name)) continue;
+    map.set(name, supplied[name] ?? DEFAULT_COLORS[index++ % DEFAULT_COLORS.length]);
+  }
+  return map;
+}
+
+function values(payload, key) {
+  if (!payload || !Array.isArray(payload[key])) throw new TypeError(`Expected a scope-profiler plot-data payload with a ${key} array.`);
+  return payload[key];
+}
+
+function baseLayout(overrides = {}) {
+  return {
+    paper_bgcolor: "transparent", plot_bgcolor: "transparent", font: { family: "system-ui, sans-serif" },
+    margin: { l: 100, r: 24, t: 32, b: 56 }, legend: { orientation: "h" }, ...overrides,
+  };
+}
+
+function filtered(rows, options) {
+  return typeof options?.filterRegion === "function" ? rows.filter((row) => options.filterRegion(row.region, row)) : rows;
+}
+
+/** Build a multi-run, multi-rank timeline. Regions are colored; file/rank are lanes. */
+export function buildGanttFigure(payload, options = {}) {
+  const intervals = filtered(values(payload, "intervals"), options);
+  const regions = [...new Set(intervals.map((row) => row.region))];
+  const colors = colorMap(regions, options.colors ?? payload.colors);
+  const lanes = [...new Set(intervals.map((row) => `${row.file ?? "run"} / rank ${row.rank ?? 0}`))];
+  const data = regions.map((region) => {
+    const rows = intervals.filter((row) => row.region === region);
+    return { type: "bar", orientation: "h", name: region,
+      y: rows.map((row) => `${row.file ?? "run"} / rank ${row.rank ?? 0}`),
+      x: rows.map((row) => row.end_seconds - row.start_seconds), base: rows.map((row) => row.start_seconds),
+      marker: { color: colors.get(region) },
+      customdata: rows.map((row) => [row.file, row.rank]),
+      hovertemplate: `<b>${region}</b><br>%{customdata[0]} / rank %{customdata[1]}<br>start: %{base:.6g} s<br>duration: %{x:.6g} s<extra></extra>`,
+    };
+  });
+  return { data, layout: baseLayout({ barmode: "overlay", height: Math.max(280, 48 * lanes.length + 150), xaxis: { title: "Time (s)" }, yaxis: { categoryorder: "array", categoryarray: lanes, autorange: "reversed" }, ...options.layout }) };
+}
+
+/** Build an icicle flame chart using scope-profiler's explicit call IDs. */
+export function buildFlameFigure(payload, options = {}) {
+  const calls = values(payload, "calls");
+  const regions = [...new Set(calls.map((call) => call.region))];
+  const colors = colorMap(regions, options.colors ?? payload.colors);
+  const root = "scope-profiler-root";
+  const ids = [root], labels = [options.rootLabel ?? "All calls"], parents = [""], markerColors = [NEUTRAL], hovertext = ["All calls"];
+  const roots = calls.filter((call) => call.parent_call_id == null);
+  const rootDuration = roots.reduce((sum, call) => sum + (call.inclusive_duration_seconds ?? call.end_seconds - call.start_seconds), 0);
+  const callKey = (call) => `${call.file ?? "run"}:${call.rank ?? 0}:${call.call_id}`;
+  for (const call of calls) {
+    ids.push(callKey(call)); labels.push(call.region);
+    parents.push(call.parent_call_id == null ? root : `${call.file ?? "run"}:${call.rank ?? 0}:${call.parent_call_id}`);
+    markerColors.push(colors.get(call.region));
+    hovertext.push(`<b>${call.region}</b><br>${call.file ?? "run"} / rank ${call.rank ?? 0}<br>start: ${call.start_seconds.toPrecision(6)} s<br>inclusive: ${(call.inclusive_duration_seconds ?? call.end_seconds - call.start_seconds).toPrecision(6)} s`);
+  }
+  return { data: [{ type: "icicle", ids, labels, parents, values: [rootDuration, ...calls.map((call) => call.inclusive_duration_seconds ?? call.end_seconds - call.start_seconds)], branchvalues: "total", tiling: { orientation: "h" }, marker: { colors: markerColors }, hovertext, hoverinfo: "text" }], layout: baseLayout({ height: 500, margin: { l: 24, r: 24, t: 24, b: 24 }, ...options.layout }) };
+}
+
+export function buildDurationsFigure(payload, options = {}) {
+  const metric = options.metric ?? payload.options?.metric ?? payload.metrics?.[0] ?? "total";
+  const bars = filtered(values(payload, "bars"), options).filter((bar) => bar.metric === metric);
+  // A stacked-children export is already decomposed into segments. Preserve
+  // that decomposition instead of letting duplicate region rows overwrite.
+  const stacked = bars.some((bar) => bar.segment != null);
+  const groups = [...new Set(bars.map((bar) => stacked ? bar.segment : bar.rank == null ? bar.file : `rank ${bar.rank}`))];
+  const regions = [...new Set(bars.map((bar) => bar.region))];
+  const colors = colorMap(groups, options.colors ?? payload.colors);
+  const data = groups.map((group) => {
+    const rows = bars.filter((bar) => (stacked ? bar.segment : bar.rank == null ? bar.file : `rank ${bar.rank}`) === group);
+    const byRegion = new Map(rows.map((bar) => [bar.region, bar.value_seconds]));
+    return { type: "bar", name: group, x: regions, y: regions.map((region) => byRegion.get(region) ?? null), marker: { color: colors.get(group) }, hovertemplate: `<b>%{x}</b><br>${group}: %{y:.6g} s<extra></extra>` };
+  });
+  return { data, layout: baseLayout({ barmode: stacked ? "stack" : "group", height: Math.max(360, 34 * regions.length + 180), xaxis: { tickangle: -35 }, yaxis: { title: `${metric} duration (s)` }, ...options.layout }) };
+}
+
+export function buildSpeedupFigure(payload, options = {}) {
+  const xField = options.xField ?? payload.options?.x_field ?? "num_ranks";
+  const points = filtered(values(payload, "points"), options);
+  const regions = [...new Set(points.map((point) => point.region))];
+  const colors = colorMap(regions, options.colors ?? payload.colors);
+  const xValues = [...new Set(points.map((point) => point[xField]))].sort((a, b) => typeof a === "number" && typeof b === "number" ? a - b : String(a).localeCompare(String(b)));
+  const numeric = xValues.every((value) => typeof value === "number");
+  const data = regions.map((region) => { const rows = points.filter((point) => point.region === region).sort((a, b) => xValues.indexOf(a[xField]) - xValues.indexOf(b[xField])); return { type: "scatter", mode: "lines+markers", name: region, x: rows.map((row) => row[xField]), y: rows.map((row) => row.speedup), line: { color: colors.get(region) }, marker: { color: colors.get(region) }, hovertemplate: `<b>%{x}</b><br>${region}: %{y:.3g}×<extra></extra>` }; });
+  const baseline = payload.options?.baseline ?? xValues[0];
+  if (numeric && options.ideal !== false) data.push({ type: "scatter", mode: "lines", name: "Ideal speedup", x: xValues, y: xValues.map((value) => value / baseline), line: { color: "#777", dash: "dash" }, hoverinfo: "skip" });
+  return { data, layout: baseLayout({ height: 420, xaxis: { title: payload.options?.x_label ?? xField, tickvals: xValues }, yaxis: { title: "Speedup" }, ...options.layout }) };
+}
+
+/** Render a figure with any Plotly-compatible bundle. */
+export function renderFigure(plotly, element, figure, config = {}) {
+  if (!plotly || typeof plotly.newPlot !== "function") throw new TypeError("renderFigure requires a Plotly-compatible object with newPlot().");
+  return plotly.newPlot(element, figure.data, figure.layout, { responsive: true, displaylogo: false, ...config });
+}