gloomberb 0.9.9 → 0.10.0

package/src/cli/pane-functions/resolver.ts

@@ -1,5 +1,8 @@
 import type { PaneInstanceConfig } from "../../types/config";
+import { CHART_COMPOSER_PANE_ID } from "../../types/config";
 import type { PaneDef, PaneTemplateCreateOptions, PaneTemplateDef } from "../../types/plugin";
+import { applyChartComposerCapabilityOptions } from "../../plugins/builtin/chart-composer/cli-options";
+import { parseChartSpec } from "../../plugins/builtin/chart-composer/chart-spec";
 import { normalizeTickerInput } from "../../tickers/search";
 import { slugifyName } from "../../utils/slugify";
 import type { MarketContext } from "../types";
@@ -15,6 +18,13 @@ import {
   optionSettings,
   type ParsedPaneFunctionArgs,
 } from "./options";
+import {
+  capabilityPaneSettings,
+  getPaneFunctionCapability,
+  normalizeCapabilityOptions,
+  type NormalizedPaneFunctionOptions,
+  type PaneFunctionCapability,
+} from "./capabilities";
 
 export interface ResolvedPaneFunction {
   token: string;
@@ -26,10 +36,12 @@ export interface ResolvedPaneFunction {
   instance: PaneInstanceConfig;
   createOptions: PaneTemplateCreateOptions | undefined;
   optionSettings: Record<string, unknown>;
+  capability: PaneFunctionCapability;
+  options: NormalizedPaneFunctionOptions;
 }
 
 async function buildPaneInstance(
-  resolved: Pick<ResolvedPaneFunction, "pane" | "template" | "createOptions" | "optionSettings">,
+  resolved: Pick<ResolvedPaneFunction, "pane" | "template" | "createOptions" | "optionSettings" | "capability" | "options">,
   context: MarketContext,
   target: string,
 ): Promise<PaneInstanceConfig> {
@@ -39,16 +51,28 @@ async function buildPaneInstance(
   const templateContext = buildTemplateContext(context, primarySymbol ?? null);
   const spec = await resolved.template?.createInstance?.(templateContext, resolved.createOptions) ?? {};
   const instanceId = `${resolved.pane.id}:cli-${slugifyName(target || resolved.pane.id, "pane")}`;
+  const settings = (() => {
+    if (resolved.pane.id !== CHART_COMPOSER_PANE_ID) {
+      return { ...spec.settings, ...resolved.optionSettings };
+    }
+    const chartSpec = parseChartSpec(spec.settings?.chartSpec);
+    if (!chartSpec) throw new Error("The chart template did not produce a valid chart specification.");
+    return {
+      ...spec.settings,
+      chartSpec: applyChartComposerCapabilityOptions(
+        chartSpec,
+        resolved.capability.id,
+        resolved.options,
+      ),
+    };
+  })();
   return {
     instanceId,
     paneId: resolved.pane.id,
     title: spec.title ?? primarySymbol ?? resolved.pane.name,
     binding: spec.binding ?? (primarySymbol ? { kind: "fixed", symbol: primarySymbol } : { kind: "none" }),
     params: spec.params,
-    settings: {
-      ...spec.settings,
-      ...resolved.optionSettings,
-    },
+    settings,
   };
 }
 
@@ -71,7 +95,6 @@ export async function resolvePaneFunction(
     throw new Error(`Unknown function or pane "${args.target}". Try one of: ${shortcuts.slice(0, 18).join(", ")}`);
   }
 
-  const settings = optionSettings(args.options);
   const template = "paneId" in entry && "description" in entry ? entry as PaneTemplateDef : undefined;
   const pane = template
     ? registry.panes.get(template.paneId)
@@ -80,6 +103,19 @@ export async function resolvePaneFunction(
     throw new Error(`Template "${template?.id}" points at missing pane "${template?.paneId}".`);
   }
   const createOptions = buildCreateOptions(template, args.arg);
+  const capability = getPaneFunctionCapability(template, pane);
+  const normalizedOptions = normalizeCapabilityOptions(capability, args.options, {
+    strict: args.requireBotSafe,
+  });
+  const settings = capability.botSafe
+    ? {
+      ...optionSettings(args.options),
+      ...capabilityPaneSettings(capability, normalizedOptions),
+    }
+    : optionSettings(args.options);
+  if (args.requireBotSafe) {
+    validateTickerCardinality(capability, createOptions);
+  }
   const resolved: ResolvedPaneFunction = {
     token: template?.shortcut?.prefix ?? template?.id ?? pane.id,
     label: template?.label ?? pane.name,
@@ -90,7 +126,35 @@ export async function resolvePaneFunction(
     instance: {} as PaneInstanceConfig,
     createOptions,
     optionSettings: settings,
+    capability,
+    options: normalizedOptions,
   };
   resolved.instance = await buildPaneInstance(resolved, context, args.arg || pane.id);
   return resolved;
 }
+
+function validateTickerCardinality(
+  capability: PaneFunctionCapability,
+  createOptions: PaneTemplateCreateOptions | undefined,
+): void {
+  if (!capability.botSafe || capability.tickerCardinality === "none") return;
+  const count = createOptions?.symbols?.length
+    ?? (createOptions?.symbol ? 1 : 0);
+  const valid = capability.tickerCardinality === "one"
+    ? count === 1
+    : capability.tickerCardinality === "one-or-more"
+      ? count >= 1
+      : capability.tickerCardinality === "two-or-more"
+        ? count >= 2
+        : count >= 1 && count <= 2;
+  if (valid) return;
+
+  const expectation = capability.tickerCardinality === "one"
+    ? "exactly one ticker"
+    : capability.tickerCardinality === "one-or-more"
+      ? "at least one ticker"
+      : capability.tickerCardinality === "two-or-more"
+        ? "at least two tickers"
+        : "one or two tickers";
+  throw new Error(`${capability.id} requires ${expectation}.`);
+}

package/src/cli/pane-functions/screenshot.test.ts

@@ -0,0 +1,431 @@
+import { describe, expect, test } from "bun:test";
+import type { RemoteUiNodeSnapshot } from "../../remote/types";
+import {
+  chartSeriesEvidenceWithinRange,
+  chartEvidenceMismatchesFor,
+  missingActiveTabSelections,
+  shotDataEvidenceFor,
+  shotPriceHistoryRange,
+  shotSemanticRowCount,
+  shotUnavailableSymbols,
+  type PaneScreenshotExpectedChartEvidence,
+  type PaneScreenshotExpectedSelection,
+} from "./screenshot";
+import { collectShotSymbols } from "./data";
+import type { DesktopPaneShotPayload } from "../desktop-pane-shot";
+import type { ResolvedPaneFunction } from "./resolver";
+import { buildCustomChartPreset } from "../../plugins/builtin/chart-composer/presets";
+import { CHART_COMPOSER_PANE_ID } from "../../types/config";
+
+describe("pane screenshot active-state verification", () => {
+  const expected: PaneScreenshotExpectedSelection[] = [
+    { control: "statement", label: "Cash Flow" },
+    { control: "period", value: "annual" },
+  ];
+
+  test("accepts selections confirmed by the rendered semantic tab state", () => {
+    expect(missingActiveTabSelections(renderedTabs("1", "annual"), expected)).toEqual([]);
+  });
+
+  test("rejects labels that are visible but not active", () => {
+    expect(missingActiveTabSelections(renderedTabs("0", "quarterly"), expected))
+      .toEqual(expected);
+  });
+});
+
+describe("pane screenshot chart-data verification", () => {
+  const expected: PaneScreenshotExpectedChartEvidence = {
+    kind: "price-comparison",
+    symbols: ["AAPL", "NVDA"],
+    rangePreset: "1Y",
+    axisMode: "percent",
+    resolution: "1d",
+    sourceSeries: [
+      {
+        symbol: "AAPL",
+        pointCount: 2,
+        first: { date: "2025-07-17T00:00:00.000Z", close: 100 },
+        last: { date: "2026-07-18T00:00:00.000Z", close: 150 },
+        projectionBaseValue: 110,
+        projectionLatestRawValue: 150,
+        projectionLatestValue: 36.36363636363637,
+      },
+      {
+        symbol: "NVDA",
+        pointCount: 2,
+        first: { date: "2025-07-17T00:00:00.000Z", close: 200 },
+        last: { date: "2026-07-18T00:00:00.000Z", close: 220 },
+        projectionBaseValue: 205,
+        projectionLatestRawValue: 220,
+        projectionLatestValue: 7.317073170731708,
+      },
+    ],
+  };
+
+  test("accepts exact rendered comparison inputs and projection values", () => {
+    expect(chartEvidenceMismatchesFor(renderedComparisonChart(), expected)).toEqual([]);
+  });
+
+  test("fetches the requested comparison range instead of a coarser five-year series", () => {
+    expect(shotPriceHistoryRange(resolved("price-comparison", { rangePreset: "1Y" })))
+      .toBe("1Y");
+  });
+
+  test("matches the exact chart window when the latest point is later in the day", () => {
+    expect(chartSeriesEvidenceWithinRange("MSFT", [
+      { date: new Date("2021-07-22T13:30:00.000Z"), close: 286.14 },
+      { date: new Date("2021-07-23T13:30:00.000Z"), close: 289.67 },
+      { date: new Date("2026-07-22T18:39:00.000Z"), close: 505.12 },
+    ], "5Y")).toEqual({
+      symbol: "MSFT",
+      pointCount: 2,
+      first: { date: "2021-07-23T13:30:00.000Z", close: 289.67 },
+      last: { date: "2026-07-22T18:39:00.000Z", close: 505.12 },
+    });
+  });
+
+  test("rejects a wrong range or rendered value even when symbols are visible", () => {
+    const nodes = renderedComparisonChart();
+    nodes[0]!.metadata!.rangePreset = "3M";
+    (nodes[0]!.metadata!.projectionSeries as Array<Record<string, unknown>>)[0]!.latestRawValue = 149;
+    expect(chartEvidenceMismatchesFor(nodes, expected)).toEqual([
+      "rendered chart range does not match",
+      "AAPL comparison latest value does not match",
+    ]);
+  });
+
+  test("accepts resolved mixed-source composer evidence", () => {
+    const expectedComposer: PaneScreenshotExpectedChartEvidence = {
+      kind: "chart-composer",
+      symbols: ["AAPL", "MSFT"],
+      rangePreset: "5Y",
+      resolution: "auto",
+      baseSeries: [
+        {
+          id: "aapl-price",
+          sourceKind: "security",
+          symbol: "AAPL",
+          fieldId: "market.ohlcv",
+          style: "candles",
+          transform: "raw",
+          panelId: "main",
+          visible: true,
+        },
+        {
+          id: "msft-revenue",
+          sourceKind: "security",
+          symbol: "MSFT",
+          fieldId: "fundamental.totalRevenue",
+          style: "step",
+          transform: "raw",
+          panelId: "main",
+          visible: true,
+        },
+        {
+          id: "cpi",
+          sourceKind: "economic",
+          economicSeriesId: "CPIAUCSL",
+          style: "step",
+          transform: "raw",
+          panelId: "macro",
+          visible: true,
+        },
+      ],
+    };
+    const metadata = {
+      ...expectedComposer,
+      projectedPointCount: 42,
+      baseSeries: expectedComposer.baseSeries?.map((series) => ({ ...series, pointCount: 12 })),
+    };
+    expect(chartEvidenceMismatchesFor([{
+      id: "chart-composer-data",
+      role: "chart-data",
+      actions: [],
+      metadata,
+    }], expectedComposer)).toEqual([]);
+  });
+});
+
+describe("pane screenshot chart-composer inputs", () => {
+  test("loads security symbols from the parsed chart spec instead of treating the expression as one ticker", () => {
+    const rawArg = "AAPL:price, MSFT:revenue, 3HNX:LSE:revenue, FRED:CPIAUCSL";
+    const chart = {
+      pane: { id: CHART_COMPOSER_PANE_ID },
+      instance: { settings: { chartSpec: buildCustomChartPreset(rawArg) } },
+      createOptions: { arg: rawArg },
+    } as unknown as ResolvedPaneFunction;
+
+    expect(collectShotSymbols(chart, rawArg)).toEqual(["AAPL", "MSFT", "3HNX:XLON"]);
+  });
+
+  test("uses rendered composer series for FRED-only screenshot readiness", () => {
+    const composer = resolved("chart-composer", {});
+    const semanticUi: RemoteUiNodeSnapshot[] = [{
+      id: "chart-composer-data",
+      role: "chart-data",
+      actions: [],
+      metadata: {
+        kind: "chart-composer",
+        baseSeries: [{
+          sourceKind: "economic",
+          economicSeriesId: "CPIAUCSL",
+          pointCount: 12,
+        }],
+      },
+    }];
+
+    expect(shotSemanticRowCount(composer, payload([]), semanticUi)).toBe(12);
+    expect(shotUnavailableSymbols(composer, payload([]), semanticUi)).toEqual([]);
+  });
+
+  test("reports an empty FRED composer source as unavailable", () => {
+    const semanticUi: RemoteUiNodeSnapshot[] = [{
+      id: "chart-composer-data",
+      role: "chart-data",
+      actions: [],
+      metadata: {
+        kind: "chart-composer",
+        baseSeries: [{
+          sourceKind: "economic",
+          economicSeriesId: "UNRATE",
+          pointCount: 0,
+        }],
+      },
+    }];
+
+    expect(shotUnavailableSymbols(resolved("chart-composer", {}), payload([]), semanticUi))
+      .toEqual(["FRED:UNRATE"]);
+  });
+});
+
+describe("pane screenshot structured data evidence", () => {
+  test("captures the exact single-price series rendered by a price chart", () => {
+    const evidence = shotDataEvidenceFor(
+      resolved("price-chart", { rangePreset: "3M" }),
+      payload([["AAPL", {
+        priceHistory: [
+          { date: "2026-04-01", close: 100 },
+          { date: "2026-07-01", close: 125 },
+        ],
+      }]]),
+    );
+
+    expect(evidence).toEqual({
+      kind: "price-series",
+      symbol: "AAPL",
+      range: "3M",
+      pointCount: 2,
+      first: { date: "2026-04-01T00:00:00.000Z", close: 100 },
+      last: { date: "2026-07-01T00:00:00.000Z", close: 125 },
+    });
+  });
+
+  test("captures the exact comparison projection inputs and return", () => {
+    const evidence = shotDataEvidenceFor(
+      resolved("price-comparison", { rangePreset: "1Y", axisMode: "percent" }),
+      payload([
+        ["AAPL", {
+          priceHistory: [
+            { date: "2025-07-01", close: 100 },
+            { date: "2026-07-01", close: 150 },
+          ],
+        }],
+        ["NVDA", {
+          priceHistory: [
+            { date: "2025-07-01", close: 200 },
+            { date: "2026-07-01", close: 220 },
+          ],
+        }],
+      ]),
+    );
+
+    expect(evidence).toEqual({
+      kind: "price-comparison",
+      symbols: ["AAPL", "NVDA"],
+      range: "1Y",
+      series: [
+        {
+          symbol: "AAPL",
+          base: { date: "2025-07-01T00:00:00.000Z", value: 100 },
+          latest: { date: "2026-07-01T00:00:00.000Z", value: 150 },
+          returnPercent: 50,
+        },
+        {
+          symbol: "NVDA",
+          base: { date: "2025-07-01T00:00:00.000Z", value: 200 },
+          latest: { date: "2026-07-01T00:00:00.000Z", value: 220 },
+          returnPercent: 10,
+        },
+      ],
+    });
+  });
+
+  test("captures rendered fundamental rows and headline statement values", () => {
+    const financials = {
+      priceHistory: [],
+      annualStatements: [
+        {
+          date: "2025-01-31",
+          totalRevenue: 100,
+          operatingCashFlow: 30,
+          capitalExpenditure: -10,
+          freeCashFlow: 20,
+        },
+        {
+          date: "2026-01-31",
+          totalRevenue: 120,
+          operatingCashFlow: 42,
+          capitalExpenditure: -12,
+          freeCashFlow: 30,
+        },
+      ],
+      quarterlyStatements: [],
+    };
+    const graphEvidence = shotDataEvidenceFor(
+      resolved("fundamental-series", {
+        metric: "operatingCashFlow",
+        period: "annual",
+        periods: 2,
+      }),
+      payload([["NVDA", financials]]),
+    );
+    expect(graphEvidence).toEqual({
+      kind: "fundamental-series",
+      metric: "operatingCashFlow",
+      period: "annual",
+      series: [{
+        symbol: "NVDA",
+        rows: [
+          { date: "2025-01-31", value: 30 },
+          { date: "2026-01-31", value: 42 },
+        ],
+      }],
+    });
+
+    const statementEvidence = shotDataEvidenceFor(
+      resolved("financial-statements", { statement: "cashflow", period: "annual" }),
+      payload([["NVDA", financials]]),
+    );
+    expect(statementEvidence).toMatchObject({
+      kind: "financial-statement",
+      symbol: "NVDA",
+      statement: "cashflow",
+      period: "annual",
+      latest: {
+        date: "2026-01-31",
+        metrics: expect.arrayContaining([
+          expect.objectContaining({ key: "operatingCashFlow", value: 42 }),
+          expect.objectContaining({ key: "capitalExpenditure", value: -12 }),
+          expect.objectContaining({ key: "freeCashFlow", value: 30 }),
+        ]),
+      },
+    });
+  });
+});
+
+function resolved(
+  capabilityId: string,
+  options: Record<string, string | number>,
+): ResolvedPaneFunction {
+  return {
+    capability: { id: capabilityId },
+    options,
+  } as unknown as ResolvedPaneFunction;
+}
+
+function payload(
+  financials: Array<[string, Record<string, unknown>]>,
+): DesktopPaneShotPayload {
+  return {
+    financials: financials.map(([symbol, value]) => [
+      symbol,
+      {
+        quote: null,
+        fundamentals: null,
+        profile: null,
+        annualStatements: [],
+        quarterlyStatements: [],
+        priceHistory: [],
+        ...value,
+      },
+    ]),
+  } as unknown as DesktopPaneShotPayload;
+}
+
+function renderedTabs(statement: string, period: string): RemoteUiNodeSnapshot[] {
+  return [
+    {
+      id: "statements",
+      role: "tabs",
+      actions: [],
+      metadata: {
+        activeValue: statement,
+        tabs: [
+          { label: "Income", value: "0" },
+          { label: "Cash Flow", value: "1" },
+          { label: "Balance Sheet", value: "2" },
+        ],
+      },
+    },
+    {
+      id: "period",
+      role: "tabs",
+      actions: [],
+      metadata: {
+        activeValue: period,
+        tabs: [
+          { label: "Annual", value: "annual" },
+          { label: "Quarterly", value: "quarterly" },
+        ],
+      },
+    },
+  ];
+}
+
+function renderedComparisonChart(): RemoteUiNodeSnapshot[] {
+  return [{
+    id: "comparison-chart-data",
+    role: "chart-data",
+    actions: [],
+    metadata: {
+      kind: "price-comparison",
+      symbols: ["AAPL", "NVDA"],
+      rangePreset: "1Y",
+      selectedResolution: "1d",
+      effectiveResolution: "1d",
+      requestedAxisMode: "percent",
+      effectiveAxisMode: "percent",
+      sourceSeries: [
+        {
+          symbol: "AAPL",
+          pointCount: 2,
+          first: { date: "2025-07-17T00:00:00.000Z", close: 100 },
+          last: { date: "2026-07-18T00:00:00.000Z", close: 150 },
+        },
+        {
+          symbol: "NVDA",
+          pointCount: 2,
+          first: { date: "2025-07-17T00:00:00.000Z", close: 200 },
+          last: { date: "2026-07-18T00:00:00.000Z", close: 220 },
+        },
+      ],
+      projectedPointCount: 2,
+      projectionSeries: [
+        {
+          symbol: "AAPL",
+          baseValue: 110,
+          latestRawValue: 150,
+          latestValue: 36.36363636363637,
+          pointCount: 2,
+        },
+        {
+          symbol: "NVDA",
+          baseValue: 205,
+          latestRawValue: 220,
+          latestValue: 7.317073170731708,
+          pointCount: 2,
+        },
+      ],
+    },
+  }];
+}