gloomberb 0.13.3 → 0.14.0

package/src/plugins/builtin/thirteenf/model.ts

@@ -22,10 +22,12 @@ import type {
   ThirteenFFund,
   ThirteenFHoldingRecord,
   ThirteenFTopFund,
+  ThirteenFPeriodReport,
 } from "./types";
 
 export const THIRTEENF_PANE_ID = "thirteenf-funds";
 export const THIRTEENF_TEMPLATE_ID = "thirteenf-funds-pane";
+export const THIRTEENF_OPTIONS_NOTE = "Option values and shares refer to the underlying; 13F % is share of reported value.";
 
 export const FUND_DETAIL_TABS: Array<{ label: string; value: ThirteenFDetailTab }> = [
   { label: "Holdings", value: "holdings" },
@@ -72,19 +74,14 @@ export function normalizeQuarterDate(value: Date): string {
 }
 
 export function latestLikely13FQuarter(now = new Date()): string {
-  const year = now.getUTCFullYear();
-  const quarterEnds = [
-    Date.UTC(year - 1, 11, 31),
-    Date.UTC(year, 2, 31),
-    Date.UTC(year, 5, 30),
-    Date.UTC(year, 8, 30),
-    Date.UTC(year, 11, 31),
-  ];
-  const availableAt = quarterEnds
-    .map((timestamp) => timestamp + 50 * 24 * 60 * 60_000)
-    .filter((timestamp) => timestamp <= now.getTime())
-    .at(-1) ?? quarterEnds[0]!;
-  return normalizeQuarterDate(new Date(availableAt - 50 * 24 * 60 * 60_000));
+  const currentQuarterStart = Math.floor(now.getUTCMonth() / 3) * 3;
+  // Allow the provider's existing 50-day reporting buffer, including January
+  // when the latest broadly available filing period is the previous Q3.
+  for (let offset = 0; offset < 8; offset += 1) {
+    const end = new Date(Date.UTC(now.getUTCFullYear(), currentQuarterStart - offset * 3, 0));
+    if (end.getTime() + 50 * 86_400_000 <= now.getTime()) return normalizeQuarterDate(end);
+  }
+  return "";
 }
 
 export function dateYearsAgo(years: number, now = new Date()): string {
@@ -109,41 +106,62 @@ export function buildBrowserRows(options: {
   funds?: ThirteenFFund[];
   topFunds?: ThirteenFTopFund[];
   forms?: Map<string, ThirteenFFormSummary>;
+  reports?: Map<string, ThirteenFPeriodReport>;
   latestFilings?: ThirteenFFormSummary[];
   source: FundBrowserRow["source"];
 }): FundBrowserRow[] {
   if (options.latestFilings) {
-    return dedupeLatestForms(options.latestFilings).map((form) => ({
-      id: `${options.source}:${form.cik}`,
-      cik: form.cik,
-      name: form.companyName || form.cik,
-      periodOfReport: form.periodOfReport,
-      filedAsOfDate: form.filedAsOfDate,
-      tableValueTotal: form.tableValueTotal,
-      tableEntryTotal: form.tableEntryTotal,
-      source: options.source,
-    }));
+    return dedupeLatestForms(options.latestFilings).map((form) => {
+      const report = options.reports?.get(form.cik);
+      return {
+        id: `${options.source}:${form.cik}`,
+        cik: form.cik,
+        name: form.companyName || form.cik,
+        periodOfReport: form.periodOfReport,
+        filedAsOfDate: form.filedAsOfDate,
+        tableValueTotal: browserReportTotal(form, report, "tableValueTotal"),
+        tableEntryTotal: browserReportTotal(form, report, "tableEntryTotal"),
+        source: options.source,
+      };
+    });
   }
 
   const topByCik = new Map((options.topFunds ?? []).map((fund) => [fund.cik, fund]));
   const funds = options.funds ?? options.topFunds ?? [];
   return funds.map((fund) => {
     const topFund = topByCik.get(fund.cik);
-    const form = options.forms?.get(fund.cik);
+    const report = options.reports?.get(fund.cik);
+    const latestForm = report?.filings.at(-1) ?? options.forms?.get(fund.cik);
+    // Performance belongs to its supplied quarter; a later (or stale) filing
+    // cannot supply that quarter's portfolio value or filing date.
+    const periodOfReport = options.source === "performance"
+      ? topFund?.periodOfReport ?? latestForm?.periodOfReport
+      : latestForm?.periodOfReport ?? topFund?.periodOfReport;
+    const form = latestForm?.periodOfReport === periodOfReport ? latestForm : undefined;
     return {
       id: `${options.source}:${fund.cik}`,
       cik: fund.cik,
       name: fund.name,
-      periodOfReport: form?.periodOfReport ?? topFund?.periodOfReport,
+      periodOfReport,
       filedAsOfDate: form?.filedAsOfDate,
-      tableValueTotal: form?.tableValueTotal,
-      tableEntryTotal: form?.tableEntryTotal,
-      estQuarterReturn: topFund?.pnl ?? null,
+      tableValueTotal: browserReportTotal(form, report, "tableValueTotal"),
+      tableEntryTotal: browserReportTotal(form, report, "tableEntryTotal"),
+      estQuarterReturn: topFund && topFund.periodOfReport === periodOfReport ? topFund.pnl : null,
       source: options.source,
     };
   });
 }
 
+function browserReportTotal(
+  form: ThirteenFFormSummary | undefined,
+  report: ThirteenFPeriodReport | undefined,
+  key: "tableValueTotal" | "tableEntryTotal",
+): number | null | undefined {
+  if (!form) return undefined;
+  if (report?.periodOfReport === form.periodOfReport) return report.complete ? report[key] : null;
+  return !form.isAmendment || form.amendmentType?.trim().toUpperCase() === "RESTATEMENT" ? form[key] : null;
+}
+
 export function dedupeLatestForms(forms: ThirteenFFormSummary[]): ThirteenFFormSummary[] {
   const byCik = new Map<string, ThirteenFFormSummary>();
   for (const form of forms) {
@@ -155,36 +173,37 @@ export function dedupeLatestForms(forms: ThirteenFFormSummary[]): ThirteenFFormS
   return [...byCik.values()].sort((left, right) => compareFormRecency(right, left));
 }
 
-export function selectLatestFormsByPeriod(forms: ThirteenFFormSummary[]): ThirteenFFormSummary[] {
-  const byPeriod = new Map<string, ThirteenFFormSummary>();
-  for (const form of forms) {
-    const current = byPeriod.get(form.periodOfReport);
-    if (!current || shouldReplacePeriodForm(current, form)) {
-      byPeriod.set(form.periodOfReport, form);
+/** SEC Form 13F special instruction 3: restatements replace the report;
+ * NEW HOLDINGS filings add entries to the existing public report. Row counts
+ * cannot establish which kind of amendment a filer submitted. */
+export function buildPeriodReports(forms: ThirteenFFormSummary[]): ThirteenFPeriodReport[] {
+  const byPeriod = new Map<string, ThirteenFPeriodReport>();
+  const unique = [...new Map(forms.map((form) => [form.accessionNumber, form])).values()];
+  for (const form of unique.sort(compareFormRecency)) {
+    let report = byPeriod.get(form.periodOfReport);
+    const amendmentType = form.amendmentType?.trim().toUpperCase();
+    if (!form.isAmendment || amendmentType === "RESTATEMENT") {
+      report = { periodOfReport: form.periodOfReport, filings: [form], complete: true,
+        tableValueTotal: form.tableValueTotal, tableEntryTotal: form.tableEntryTotal };
+    } else if (amendmentType === "NEW HOLDINGS") {
+      report = report ?? { periodOfReport: form.periodOfReport, filings: [], complete: false,
+        tableValueTotal: null, tableEntryTotal: null };
+      report.filings.push(form);
+      report.tableValueTotal = addKnown(report.tableValueTotal, form.tableValueTotal);
+      report.tableEntryTotal = addKnown(report.tableEntryTotal, form.tableEntryTotal);
+    } else {
+      // An untyped amendment could replace or supplement the report. Display
+      // its disclosed entries without inventing a reconciled full portfolio.
+      report = { periodOfReport: form.periodOfReport, filings: [form], complete: false,
+        tableValueTotal: null, tableEntryTotal: null };
     }
+    byPeriod.set(form.periodOfReport, report);
   }
-  return [...byPeriod.values()].sort((left, right) => compareFormPeriod(right, left));
-}
-
-function isSupplementalAmendment(form: ThirteenFFormSummary): boolean {
-  if (!form.isAmendment) return false;
-  const amendmentType = form.amendmentType?.toUpperCase() ?? "";
-  return amendmentType.length > 0 && amendmentType !== "RESTATEMENT";
-}
-
-function shouldReplacePeriodForm(current: ThirteenFFormSummary, candidate: ThirteenFFormSummary): boolean {
-  if (isSupplementalAmendment(candidate) && !isSupplementalAmendment(current)) return false;
-  if (!isSupplementalAmendment(candidate) && isSupplementalAmendment(current)) return true;
-  if (candidate.isAmendment && !current.isAmendment) {
-    const candidateRows = candidate.tableEntryTotal ?? 0;
-    const currentRows = current.tableEntryTotal ?? 0;
-    if (currentRows > 0 && candidateRows < currentRows * 0.75) return false;
-  }
-  return compareFormRecency(candidate, current) > 0;
+  return [...byPeriod.values()].sort((left, right) => right.periodOfReport.localeCompare(left.periodOfReport));
 }
 
-function compareFormPeriod(left: ThirteenFFormSummary, right: ThirteenFFormSummary): number {
-  return left.periodOfReport.localeCompare(right.periodOfReport);
+function addKnown(left: number | null, right: number | null): number | null {
+  return left != null && right != null ? left + right : null;
 }
 
 function compareFormRecency(left: ThirteenFFormSummary, right: ThirteenFFormSummary): number {
@@ -203,17 +222,16 @@ interface HoldingAggregate {
   titleOfClass: string;
   putCall: string;
   shareType: string;
-  value: number;
-  shares: number;
+  value: number | null;
+  shares: number | null;
   accessionNumber: string;
 }
 
 function holdingKey(holding: ThirteenFHoldingRecord): string {
   return [
-    holding.ticker || "NO-TICKER",
-    holding.cusip,
-    holding.putCall || "",
-    holding.titleOfClass || "",
+    holding.cusip.trim().toUpperCase(),
+    holding.putCall.trim().toUpperCase(),
+    holding.shareType.trim().toUpperCase(),
   ].join("|");
 }
 
@@ -222,11 +240,11 @@ function aggregateHoldings(holdings: ThirteenFHoldingRecord[]): Map<string, Hold
   for (const holding of holdings) {
     const id = holdingKey(holding);
     const current = aggregates.get(id);
-    const value = holding.value ?? 0;
-    const shares = holding.shares ?? 0;
+    const value = holding.value;
+    const shares = holding.shares;
     if (current) {
-      current.value += value;
-      current.shares += shares;
+      current.value = addKnown(current.value, value);
+      current.shares = addKnown(current.shares, shares);
       if (!current.ticker && holding.ticker) current.ticker = holding.ticker;
       continue;
     }
@@ -250,6 +268,7 @@ function resolveAction(current: HoldingAggregate | undefined, previous: HoldingA
   if (current && !previous) return "new";
   if (!current && previous) return "exit";
   if (!current || !previous) return "held";
+  if (current.shares == null || previous.shares == null) return "unknown";
   const delta = current.shares - previous.shares;
   if (delta > 0) return "add";
   if (delta < 0) return "trim";
@@ -261,8 +280,11 @@ function estimateHoldingPnl(
   previous: HoldingAggregate | undefined,
 ): number | null {
   if (!current || !previous) return null;
-  if (current.value <= 0 || previous.value <= 0) return null;
-  if (current.shares <= 0 || previous.shares <= 0) return null;
+  // A 13F option value is underlying notional. Its change cannot price the
+  // option, and the filing does not identify strike, expiry or premium.
+  if (current.putCall || previous.putCall) return null;
+  if (current.value == null || previous.value == null || current.value <= 0 || previous.value <= 0) return null;
+  if (current.shares == null || previous.shares == null || current.shares <= 0 || previous.shares <= 0) return null;
 
   const currentPrice = current.value / current.shares;
   const previousPrice = previous.value / previous.shares;
@@ -270,13 +292,30 @@ function estimateHoldingPnl(
   return (currentPrice - previousPrice) * overlappingShares;
 }
 
+export function hasComparable13FQuarter(data: FundDetailData): boolean {
+  if (data.latestReport?.complete === false || data.previousReport?.complete === false) return false;
+  const current = data.latestForm?.periodOfReport;
+  const previous = data.previousForm?.periodOfReport;
+  return adjacentQuarterPeriods(current, previous);
+}
+
+function adjacentQuarterPeriods(current: string | undefined, previous: string | undefined): boolean {
+  if (!current || !previous) return false;
+  const date = new Date(`${current}T00:00:00Z`);
+  if (!Number.isFinite(date.getTime())) return false;
+  const priorEnd = new Date(Date.UTC(date.getUTCFullYear(), Math.floor(date.getUTCMonth() / 3) * 3, 0));
+  return previous === priorEnd.toISOString().slice(0, 10);
+}
+
 export function buildFundHoldingRows(data: FundDetailData | null): FundHoldingRow[] {
   if (!data?.latestForm) return [];
   const current = aggregateHoldings(data.latestHoldings);
-  const previous = aggregateHoldings(data.previousHoldings);
+  const comparable = hasComparable13FQuarter(data);
+  const previous = aggregateHoldings(comparable ? data.previousHoldings : []);
   const allKeys = new Set([...current.keys(), ...previous.keys()]);
-  const totalValue = data.latestForm.tableValueTotal
-    ?? [...current.values()].reduce((sum, item) => sum + item.value, 0);
+  const totalValue = data.latestReport
+    ? data.latestReport.complete ? data.latestReport.tableValueTotal : null
+    : data.latestForm.tableValueTotal;
 
   return [...allKeys].map((id) => {
     const currentHolding = current.get(id);
@@ -286,10 +325,10 @@ export function buildFundHoldingRows(data: FundDetailData | null): FundHoldingRo
     const shares = currentHolding?.shares ?? null;
     const previousValue = previousHolding?.value ?? null;
     const previousShares = previousHolding?.shares ?? null;
-    const valueChange = value != null || previousValue != null
+    const valueChange = comparable && (!currentHolding || value != null) && (!previousHolding || previousValue != null)
       ? (value ?? 0) - (previousValue ?? 0)
       : null;
-    const sharesChange = shares != null || previousShares != null
+    const sharesChange = comparable && (!currentHolding || shares != null) && (!previousHolding || previousShares != null)
       ? (shares ?? 0) - (previousShares ?? 0)
       : null;
     const sharesChangePercent = sharesChange != null && previousShares && previousShares !== 0
@@ -312,7 +351,7 @@ export function buildFundHoldingRows(data: FundDetailData | null): FundHoldingRo
       estimatedPnl: estimateHoldingPnl(currentHolding, previousHolding),
       sharesChange,
       sharesChangePercent,
-      action: resolveAction(currentHolding, previousHolding),
+      action: comparable ? resolveAction(currentHolding, previousHolding) : "unknown",
       accessionNumber: display.accessionNumber,
     };
   });
@@ -322,8 +361,8 @@ export function buildFilingPositionRows(
   holdings: ThirteenFHoldingRecord[],
   reportedTotalValue?: number | null,
 ): FilingPositionRow[] {
-  const computedTotalValue = holdings.reduce((sum, holding) => sum + (holding.value ?? 0), 0);
-  const totalValue = reportedTotalValue ?? computedTotalValue;
+  // Filing details are paginated; the loaded page cannot supply a full-report denominator.
+  const totalValue = reportedTotalValue;
   return holdings.map((holding, index) => ({
     id: [
       holding.accessionNumber,
@@ -352,12 +391,20 @@ export function buildFilingPositionRows(
 }
 
 export function buildTimelineRows(forms: ThirteenFFormSummary[]): FundTimelineRow[] {
-  const selected = selectLatestFormsByPeriod(forms);
-  return selected.map((form, index) => {
-    const previous = selected[index + 1];
-    const valueChangePercent = form.tableValueTotal != null
-      && previous?.tableValueTotal != null
-      && previous.tableValueTotal !== 0
+  const reports = buildPeriodReports(forms);
+  const selected = [...new Map(forms.map((form) => [form.accessionNumber, form])).values()]
+    .sort((left, right) => compareFormRecency(right, left));
+  return selected.map((form) => {
+    const index = reports.findIndex((report) => report.periodOfReport === form.periodOfReport);
+    const report = reports[index];
+    const previous = reports[index + 1];
+    // A single filing's value is not the combined value of an amended period.
+    // Keep every source filing visible, and compare only full adjacent reports.
+    const comparable = report?.complete && report.filings.length === 1
+      && report.filings[0]?.accessionNumber === form.accessionNumber
+      && previous?.complete && adjacentQuarterPeriods(form.periodOfReport, previous.periodOfReport);
+    const valueChangePercent = comparable && form.tableValueTotal != null
+      && previous.tableValueTotal != null && previous.tableValueTotal !== 0
       ? (form.tableValueTotal - previous.tableValueTotal) / previous.tableValueTotal
       : null;
     return {
@@ -562,7 +609,7 @@ export function buildFilingPositionColumns(width: number): FilingPositionColumn[
     { id: "type", label: "TYPE", width: typeWidth, align: "left" },
     { id: "issuer", label: "ISSUER", width: issuerWidth, align: "left" },
     { id: "value", label: "VALUE", width: valueWidth, align: "right" },
-    { id: "weight", label: "WEIGHT", width: weightWidth, align: "right" },
+    { id: "weight", label: "13F %", width: weightWidth, align: "right" },
     { id: "shares", label: "SHARES", width: sharesWidth, align: "right" },
     { id: "cusip", label: "CUSIP", width: cusipWidth, align: "left" },
     { id: "discretion", label: "DISCR", width: discretionWidth, align: "left" },
@@ -586,7 +633,7 @@ export function buildHoldingColumns(width: number): FundHoldingColumn[] {
     { id: "issuer", label: "ISSUER", width: issuerWidth, align: "left" },
     { id: "value", label: "VALUE", width: valueWidth, align: "right" },
     { id: "estimatedPnl", label: "EST P&L", width: pnlWidth, align: "right" },
-    { id: "weight", label: "WEIGHT", width: weightWidth, align: "right" },
+    { id: "weight", label: "13F %", width: weightWidth, align: "right" },
     { id: "shares", label: "SHARES", width: sharesWidth, align: "right" },
     { id: "sharesChange", label: "QOQ", width: changeWidth, align: "right" },
     { id: "action", label: "ACTION", width: actionWidth, align: "left" },

package/src/plugins/builtin/thirteenf/pane.test.tsx

@@ -1,18 +1,12 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { act, useReducer } from "react";
-import { testRender } from "../../../renderers/opentui/test-utils";
-import {
-  AppContext,
-  PaneInstanceProvider,
-  appReducer,
-  createInitialState,
-  type AppState,
-} from "../../../state/app/context";
+import { emitKeypress as emitTuiKeypress, testRender, type TestKeyEvent } from "../../../renderers/opentui/test-utils";
+import { appReducer, createInitialState, type AppState } from "../../../state/app/context";
 import { createTestPluginRuntime } from "../../../test-support/plugin-runtime";
 import { createDefaultConfig } from "../../../types/config";
 import { setHttpFetchTransport } from "../../../utils/http-transport";
-import { PluginRenderProvider } from "../../runtime";
 import { ThirteenFPane } from "./pane";
+import { TestPaneProvider } from "../../../test-support/pane";
 
 const PANE_ID = "thirteenf-pane-test";
 
@@ -37,19 +31,15 @@ function Harness() {
   latestState = state;
 
   return (
-    <AppContext value={{ state, dispatch }}>
-      <PaneInstanceProvider paneId={PANE_ID}>
-        <PluginRenderProvider pluginId="ticker-research" runtime={createTestPluginRuntime()}>
-          <ThirteenFPane
-            paneId={PANE_ID}
-            paneType="thirteenf-funds"
-            focused
-            width={96}
-            height={18}
-          />
-        </PluginRenderProvider>
-      </PaneInstanceProvider>
-    </AppContext>
+    <TestPaneProvider state={state} dispatch={dispatch} paneId={PANE_ID} pluginId="ticker-research" runtime={createTestPluginRuntime()}>
+      <ThirteenFPane
+        paneId={PANE_ID}
+        paneType="thirteenf-funds"
+        focused
+        width={96}
+        height={18}
+      />
+    </TestPaneProvider>
   );
 }
 
@@ -62,76 +52,13 @@ async function renderFrames(count = 4) {
   }
 }
 
-async function emitKeypress(event: {
-  name?: string;
-  sequence?: string;
-  defaultPrevented?: boolean;
-  propagationStopped?: boolean;
-}) {
-  await act(async () => {
-    let defaultPrevented = event.defaultPrevented === true;
-    let propagationStopped = event.propagationStopped === true;
-    testSetup!.renderer.keyInput.emit("keypress", {
-      ctrl: false,
-      meta: false,
-      option: false,
-      shift: false,
-      eventType: "press",
-      repeated: false,
-      ...event,
-      get defaultPrevented() {
-        return defaultPrevented;
-      },
-      get propagationStopped() {
-        return propagationStopped;
-      },
-      preventDefault: () => {
-        defaultPrevented = true;
-      },
-      stopPropagation: () => {
-        propagationStopped = true;
-      },
-    } as any);
-    await testSetup!.renderOnce();
-  });
-}
+const emitKeypress = (event: TestKeyEvent) => emitTuiKeypress(testSetup!, event, { trackPropagation: true });
 
-async function emitKeypressBatch(events: Array<{
-  name?: string;
-  sequence?: string;
-}>) {
-  await act(async () => {
-    for (const event of events) {
-      let defaultPrevented = false;
-      let propagationStopped = false;
-      testSetup!.renderer.keyInput.emit("keypress", {
-        ctrl: false,
-        meta: false,
-        option: false,
-        shift: false,
-        eventType: "press",
-        repeated: false,
-        ...event,
-        get defaultPrevented() {
-          return defaultPrevented;
-        },
-        get propagationStopped() {
-          return propagationStopped;
-        },
-        preventDefault: () => {
-          defaultPrevented = true;
-        },
-        stopPropagation: () => {
-          propagationStopped = true;
-        },
-      } as any);
-    }
-    await testSetup!.renderOnce();
-  });
-}
+const emitKeypressBatch = (events: TestKeyEvent[]) => emitTuiKeypress(testSetup!, events, { trackPropagation: true });
 
-function installAlpha13FTransport() {
+function installAlpha13FTransport(urls: string[] = []) {
   setHttpFetchTransport(async (url) => {
+    urls.push(String(url));
     const parsed = new URL(String(url));
     const path = parsed.pathname;
     if (path.endsWith("/topfunds")) {
@@ -310,8 +237,9 @@ describe("ThirteenFPane", () => {
     expect(holdingsFrame).not.toContain("Accession");
   });
 
-  test("filing detail shows filing metadata and backspace returns to filings", async () => {
-    installAlpha13FTransport();
+  test("filing detail owns refresh requests and backspace returns to filings", async () => {
+    const urls: string[] = [];
+    installAlpha13FTransport(urls);
 
     await act(async () => {
       testSetup = await testRender(<Harness />, { width: 100, height: 24 });
@@ -335,12 +263,19 @@ describe("ThirteenFPane", () => {
     expect(detailFrame).toContain("037833100");
     expect(detailFrame).toContain("SOLE");
 
+    urls.length = 0;
+    await emitKeypress({ name: "r", sequence: "r" });
+    await renderFrames(6);
+    expect(urls).toHaveLength(1);
+    expect(new URL(urls[0]!).pathname).toEndWith("/form");
+    expect(new URL(urls[0]!).searchParams.get("accession_number")).toBe("0000000001-26-000001");
+
     await emitKeypress({ name: "backspace", sequence: "\u007f" });
     await renderFrames(2);
 
     const filingsFrame = testSetup!.captureCharFrame();
     expect(filingsFrame).toContain("PERIOD");
-    expect(filingsFrame).toContain("13F-HR/A");
+    expect(filingsFrame).toContain("Restatement");
     expect(filingsFrame).toContain("Back Alpha Capital");
     expect(filingsFrame).not.toContain("Accession");
   });