gloomberb 0.16.4 → 0.16.6

package/src/plugins/builtin/holders/headless.ts

@@ -1,110 +1,36 @@
 import type {
-  HeadlessPaneColumn,
   HeadlessPaneContext,
   HeadlessPaneDefinition,
   HeadlessPaneLoadArgs,
 } from "../../../types/plugin";
-import { formatCompact } from "../../../utils/format";
 import { loadHolderSnapshot } from "./client";
-import {
-  displayDate,
-  formatHolderOwnershipPercent,
-  formatMaybePercent,
-  formatMoneyCompact,
-  formatSignedCompact,
-  holderValueCurrency,
-  resolveHolderOwnershipPercent,
-} from "./format";
-import { buildRows, sortRows } from "./table-model";
+import { holderValueCurrency } from "./format";
 import type { HolderData } from "../../../types/financials";
-import type { HolderColumnId } from "./types";
 import { SEC_FILINGS } from "../shared/report-freshness";
-import {
-  holderShareBasisMarker,
-  holderShareBasisNote,
-  holderValueBasis,
-  holdersHeaderLine,
-  moneyColumnHeader,
-  nonUsHolderCaveat,
-  sharedReportDate,
-} from "./report-header";
-
-/** Columns a source fills only when it reports the quarter's change. */
-const CHANGE_COLUMN_KEYS = new Set(["changeShares", "changePercent"]);
-/** Shown only when some row is held as depositary receipts, as on a home line abroad. */
-const BASIS_COLUMN_KEY = "shareBasis";
 import type { BeneficialOwnersPayload } from "../../../api-client/beneficial-owners";
 import { fetchBeneficialOwners, type BeneficialOwnersRequest } from "./beneficial-client";
 import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
 import type { BeneficialColumnId } from "./beneficial-model";
 import {
-  BENEFICIAL_REPORT_COLUMNS,
   beneficialCoverageNotices,
   beneficialListComplete,
   beneficialListFacts,
+  beneficialReportColumns,
+  beneficialReportLegend,
   beneficialRouteForm,
   buildBeneficialReportRows,
   HOLDER_FORMS,
   parseHolderForm,
 } from "./beneficial-report";
-
-const HOLDER_COLUMNS: HeadlessPaneColumn[] = [
-  { key: "name", header: "Holder" },
-  { key: "ownerType", header: "Type" },
-  {
-    key: "value",
-    header: "Mkt value",
-    align: "right",
-    format: (value, row) => formatMoneyCompact(
-      value == null ? undefined : Number(value),
-      String(row.currency ?? "USD"),
-    ),
-  },
-  {
-    key: "shares",
-    header: "Amount",
-    align: "right",
-    format: (value) => value == null ? "-" : formatCompact(Number(value)),
-  },
-  {
-    key: BASIS_COLUMN_KEY,
-    header: "Basis",
-    format: (_value, row) => holderShareBasisMarker(row),
-  },
-  {
-    key: "changeShares",
-    header: "Chg",
-    align: "right",
-    format: (value) => formatSignedCompact(value == null ? undefined : Number(value)),
-  },
-  {
-    key: "changePercent",
-    header: "Chg%",
-    align: "right",
-    format: (value) => formatMaybePercent(value == null ? undefined : Number(value)),
-  },
-  {
-    key: "percentHeld",
-    header: "Held",
-    align: "right",
-    format: (value) => formatHolderOwnershipPercent(value == null ? undefined : Number(value)),
-  },
-  {
-    key: "reportDate",
-    header: "Period",
-    format: (value) => displayDate(typeof value === "string" ? value : undefined),
-  },
-];
-
-const SORT_COLUMNS: Record<string, HolderColumnId> = {
-  holder: "holder",
-  value: "value",
-  shares: "shares",
-  change: "changeShares",
-  "change-percent": "changePercent",
-  held: "percentHeld",
-  date: "reportDate",
-};
+import {
+  HOLDER_REPORT_COLUMNS,
+  HOLDER_SORT_KEYS,
+  holderReportColumns,
+  holderReportNotices,
+  holderReportDates,
+  holderReportRows,
+  holderReportUnits,
+} from "./report-rows";
 
 /** The same sort keys order the 13D/13G rows; `value` and `held` are the percent of class. */
 const BENEFICIAL_SORT_COLUMNS: Record<string, BeneficialColumnId> = {
@@ -120,6 +46,8 @@ const BENEFICIAL_SORT_COLUMNS: Record<string, BeneficialColumnId> = {
 interface HolderSnapshot {
   data: HolderData;
   marketCap?: number;
+  /** Today's shares outstanding, which a 13D/13G percent of class is set against. */
+  sharesOutstanding?: number | null;
 }
 
 export interface HoldersHeadlessDependencies {
@@ -164,7 +92,7 @@ export function createHoldersHeadless(
         key: "sort",
         description: "Column used to sort holder rows.",
         type: "enum",
-        values: Object.keys(SORT_COLUMNS).map((value) => ({ value })),
+        values: Object.keys(HOLDER_SORT_KEYS).map((value) => ({ value })),
         defaultValue: "value",
       },
       {
@@ -205,7 +133,7 @@ export function createHoldersHeadless(
         defaultValue: false,
       },
     ],
-    columns: HOLDER_COLUMNS,
+    columns: HOLDER_REPORT_COLUMNS,
     describe: (args) => `Holders | ${args.symbols[0]}`,
     async load(args, ctx) {
       const symbol = args.symbols[0]!;
@@ -219,6 +147,7 @@ export function createHoldersHeadless(
           // The 13F column is a join; the 13D/13G rows stand without it.
           dependencies.loadSnapshot(symbol, args, ctx).catch(() => null),
         ]);
+        const sharesOutstanding = snapshot?.sharesOutstanding ?? null;
         const rows = buildBeneficialReportRows(payload, {
           history,
           holders: snapshot?.data ?? null,
@@ -226,10 +155,12 @@ export function createHoldersHeadless(
             columnId: BENEFICIAL_SORT_COLUMNS[String(args.options.sort)] ?? "percentOfClass",
             direction: args.options.order === "asc" ? "asc" : "desc",
           },
+          sharesOutstanding,
         });
         const limited = rows.slice(0, Number(args.options.limit));
+        const legend = beneficialReportLegend(limited, sharesOutstanding);
         return {
-          columns: BENEFICIAL_REPORT_COLUMNS,
+          columns: beneficialReportColumns(limited),
           rows: limited,
           // Reports that could not be read this time are missing from the rows.
           complete: beneficialListComplete(payload),
@@ -242,8 +173,10 @@ export function createHoldersHeadless(
             history,
             asOf: payload.asOf,
             coverage: payload.coverage,
+            sharesOutstanding,
             notices: [
               [payload.companyName || symbol, ...beneficialListFacts(payload, form, rows.length, history)].join(" · "),
+              ...(legend ? [legend] : []),
               ...beneficialCoverageNotices(payload.coverage),
             ],
             returned: limited.length,
@@ -255,52 +188,19 @@ export function createHoldersHeadless(
       const currency = data.currency ?? "USD";
       // A London line's values can be dollars from the 13F filings; they are labelled and formatted as such.
       const valueCurrency = holderValueCurrency(data, currency)!;
-      const sorted = sortRows(buildRows(data), {
-        columnId: SORT_COLUMNS[String(args.options.sort)] ?? "value",
-        direction: args.options.order === "asc" ? "asc" : "desc",
-      }, marketCap);
-      const rows = sorted
-        .slice(0, Number(args.options.limit))
-        .map((row) => ({
-          name: row.name,
-          ownerType: row.ownerType,
-          value: row.value ?? null,
-          shares: row.shares ?? null,
-          changeShares: row.changeShares ?? null,
-          changePercent: row.changePercent ?? null,
-          percentHeld: resolveHolderOwnershipPercent(row, marketCap) ?? null,
-          reportDate: row.reportDate ?? null,
-          currency: valueCurrency,
-          shareBasis: row.shareBasis ?? null,
-        }));
+      const sort = {
+        columnId: HOLDER_SORT_KEYS[String(args.options.sort)] ?? "value",
+        direction: args.options.order === "asc" ? "asc" as const : "desc" as const,
+      };
+      const sorted = holderReportRows(data, { marketCap, sort });
+      const rows = sorted.slice(0, Number(args.options.limit));
       const total = data.summary?.institutionsCount ?? null;
-      const changeReported = rows.some((row) => row.changeShares != null || row.changePercent != null);
-      const reportDate = sharedReportDate(rows);
-      const valueBasis = holderValueBasis(reportDate, data.valueBasis, valueCurrency);
-      const positionsBasis = rows.length > 0 ? nonUsHolderCaveat(data.exchange, currency) : null;
-      const shareBasisNote = holderShareBasisNote(data, rows);
-      const markedRows = rows.some((row) => holderShareBasisMarker(row));
-      // The title names the ticker and the closing line carries the as-of date.
-      const header = holdersHeaderLine({
-        name: data.name,
-        symbol: data.symbol && data.symbol !== symbol ? data.symbol : null,
-        exchange: data.exchange,
-        currency: valueCurrency,
-        listingCurrency: data.currency,
-        shown: rows.length,
-        reported: sorted.length,
-        total,
+      const { notices, valueBasis, positionsBasis, changeReported } = holderReportNotices({
+        data, requested: symbol, shown: rows, reported: sorted.length, total, sort,
       });
-      const basis = rows.length === 0 ? null : [
-        `Mkt value = ${valueBasis}.`,
-        changeReported ? "" : `Change vs prior quarter: not reported by this source; see fn 13F ${symbol}`,
-      ].filter(Boolean).join(" ");
       return {
-        // A change column that is empty on every row says nothing; the line above explains it once.
-        columns: HOLDER_COLUMNS
-          .filter((column) => changeReported || !CHANGE_COLUMN_KEYS.has(column.key))
-          .filter((column) => markedRows || column.key !== BASIS_COLUMN_KEY)
-          .map((column) => column.key === "value" ? { ...column, header: moneyColumnHeader(column.header, valueCurrency) } : column),
+        // A change column that is empty on every row says nothing; the notices explain it once.
+        columns: holderReportColumns(rows, valueCurrency),
         rows,
         metadata: {
           symbol: data.symbol || symbol,
@@ -308,10 +208,13 @@ export function createHoldersHeadless(
           exchange: data.exchange ?? null,
           currency,
           valueCurrency,
+          units: holderReportUnits(valueCurrency),
           ...(data.isDepositaryReceipt != null ? { isDepositaryReceipt: data.isDepositaryReceipt } : {}),
           ...(data.shareBasis ? { shareBasis: data.shareBasis } : {}),
           ...(data.adrRatio != null ? { adrRatio: data.adrRatio } : {}),
           asOf: data.asOf ?? null,
+          // Each holder's latest period; several when the list mixes quarters.
+          reportDates: holderReportDates(rows),
           summary: data.summary ?? null,
           shown: rows.length,
           reported: sorted.length,
@@ -320,7 +223,7 @@ export function createHoldersHeadless(
           valueBasis,
           changeReported,
           positionsBasis,
-          notices: [header, basis, positionsBasis, shareBasisNote].filter((line): line is string => !!line),
+          notices,
         },
       };
     },

package/src/plugins/builtin/holders/pane.tsx

@@ -30,7 +30,7 @@ import {
   holderValueCurrency,
   resolveHolderOwnershipPercent,
 } from "./format";
-import { holderShareBasisMarker } from "./report-header";
+import { holderPeriodsDiffer, holderShareBasisMarker } from "./report-header";
 import {
   buildColumns,
   hasHolderChanges,
@@ -40,7 +40,7 @@ import {
   sortRows,
   VIEW_TABS,
 } from "./table-model";
-import { loadHolderData } from "./client";
+import { classSharesToday, loadHolderData } from "./client";
 import { HoldersTreemap } from "./treemap";
 import { BeneficialOwnersView } from "./beneficial-view";
 import { useIssuerListing } from "../shared/ticker-request";
@@ -84,7 +84,10 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   useTickerQuoteStream(ticker ? symbol : null, ticker, { surface: "detail", visible: false, weight: 30 });
   const liveMarketCap = holderStakeMarketCap(financials?.quote?.marketCap, financials?.quote?.currency, currency);
   const marketCap = useSampledValue(liveMarketCap, HOLDER_MARKET_CAP_SAMPLE_MS, `${symbol ?? ""}:${currency}`);
+  // Today's share count, which a 13D/13G report's own base is checked against.
+  const sharesOutstanding = classSharesToday(financials);
   const rows = useMemo(() => buildRows(data), [data]);
+  const periodsDiffer = useMemo(() => holderPeriodsDiffer(rows), [rows]);
   const sortedRows = useMemo(() => sortRows(rows, sortPreference, marketCap), [marketCap, rows, sortPreference]);
   // Change columns only when the source reports a change; otherwise they read "-" on every row.
   const showChange = useMemo(() => hasHolderChanges(rows), [rows]);
@@ -271,7 +274,10 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
     if (viewMode === "13dg") return null;
     return {
       info: [
-        ...(data?.asOf ? [{ id: "as-of", parts: [{ text: data.asOf, tone: "value" as const }] }] : []),
+        // One date only when every holder's row is of it; the PERIOD column dates each row.
+        ...(periodsDiffer
+          ? [{ id: "as-of", parts: [{ text: "latest period per holder", tone: "muted" as const }] }]
+          : data?.asOf ? [{ id: "as-of", parts: [{ text: data.asOf, tone: "value" as const }] }] : []),
         ...loadingErrorFooterInfo(loading, data ? error : null),
         ...(fundMatching ? [{ id: "fund-matching", parts: [{ text: "13F matching", tone: "muted" as const }] }] : []),
       ],
@@ -282,7 +288,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
         ...(selectedFundMatch ? [{ id: "fund", key: "o", label: "pen 13F", onPress: () => openFundDetail(selectedRow) }] : []),
       ],
     };
-  }, [data, error, fundMatching, loading, openFundDetail, selectedFundMatch, selectedRow, viewMode]);
+  }, [data, error, fundMatching, loading, openFundDetail, periodsDiffer, selectedFundMatch, selectedRow, viewMode]);
 
   const selectView = useCallback((value: string) => setViewMode(value as ViewMode), [setViewMode]);
   // As a research tab, h/l move between research tabs; `s` switches the view.
@@ -342,6 +348,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
           listing={issuerListing}
           holderRows={rows}
           fundMatches={fundMatches}
+          sharesOutstanding={sharesOutstanding}
           onCycleView={toggleView}
           onRefreshHolders={refresh}
         />

package/src/plugins/builtin/holders/report-header.ts

@@ -20,6 +20,16 @@ export interface HolderReportFacts {
   listingCurrency?: string | null;
   /** Left out when the report's closing line already carries it. */
   asOf?: string | null;
+  /**
+   * What the list is as of, in place of `asOf`: `as of <date>` when every
+   * row shares one report date, `latest period per holder` when they differ.
+   */
+  period?: string | null;
+  /**
+   * False when the list is not the source's largest holders but the few
+   * filers that report the line at all (a home line abroad): no "top".
+   */
+  ranked?: boolean;
   /** Rows printed. */
   shown: number;
   /** Rows the source returned, before any limit. */
@@ -34,15 +44,39 @@ export function moneyColumnHeader(label: string, currency?: string | null): stri
   return unit ? `${label} (${unit})` : label;
 }
 
-function holderCountText(shown: number, reported: number, total?: number | null): string {
+function holderCountText(shown: number, reported: number, total?: number | null, ranked = true): string {
   if (total != null && Number.isFinite(total) && total >= reported) {
     return `${shown.toLocaleString("en-US")} of ${total.toLocaleString("en-US")} holders`;
   }
   if (reported === 0) return "none reported";
+  // A home line's few filers are all there is, not a top of anything.
+  if (!ranked) return shown < reported ? `${shown} of ${reported} reported` : `${reported} ${reported === 1 ? "holder" : "holders"} reported`;
   // Without a total the source's list is its largest holders, cut where it cuts it.
   return shown < reported ? `${shown} of top ${reported} reported` : `top ${reported} reported`;
 }
 
+/**
+ * What a holder list is as of. Each holder's row is its latest filed
+ * period, so one date is claimed only when every row has it; rows of
+ * different quarters read `latest period per holder`, and an empty list
+ * keeps the source's date.
+ */
+export function holderListPeriod(
+  rows: ReadonlyArray<{ reportDate?: unknown }>,
+  asOf?: string | null,
+): string | null {
+  const dates = new Set(rows.flatMap((row) => typeof row.reportDate === "string" && row.reportDate ? [row.reportDate] : []));
+  if (dates.size > 1) return "latest period per holder";
+  const [only] = dates;
+  const date = only ?? asOf;
+  return date ? `as of ${date}` : null;
+}
+
+/** Whether a holder list's rows are of more than one report date. */
+export function holderPeriodsDiffer(rows: ReadonlyArray<{ reportDate?: unknown }>): boolean {
+  return holderListPeriod(rows) === "latest period per holder";
+}
+
 /** A venue the app knows by its short name (NasdaqGS is NASDAQ); any other as the source wrote it. */
 function venueLabel(exchange?: string | null): string {
   const canonical = canonicalExchange(exchange ?? "");
@@ -51,15 +85,15 @@ function venueLabel(exchange?: string | null): string {
 
 /** What the list is, after the listing is named: its unit, date and how much of it is shown. */
 export function holderListFacts(
-  facts: Pick<HolderReportFacts, "currency" | "listingCurrency" | "asOf" | "shown" | "reported" | "total">,
+  facts: Pick<HolderReportFacts, "currency" | "listingCurrency" | "asOf" | "period" | "shown" | "reported" | "total" | "ranked">,
 ): string[] {
   const unit = currencyUnitLabel(facts.currency);
   // Dollars on a London line: say they are the values' unit, not the listing's.
   const otherUnit = unit && facts.listingCurrency?.trim() && facts.listingCurrency.trim() !== facts.currency?.trim();
   return [
     otherUnit ? `values in ${unit}` : unit,
-    facts.asOf ? `as of ${facts.asOf}` : "",
-    holderCountText(facts.shown, facts.reported, facts.total),
+    facts.period ?? (facts.asOf ? `as of ${facts.asOf}` : ""),
+    holderCountText(facts.shown, facts.reported, facts.total, facts.ranked),
   ].filter(Boolean);
 }
 
@@ -132,5 +166,6 @@ export function nonUsHolderCaveat(exchange?: string | null, currency?: string |
   if (!isNonUsHolderListing(exchange, currency)) return null;
   const canonical = canonicalExchange(exchange ?? "");
   const venue = resolveExchangeTimeZone(canonical) ? canonical : "local";
-  return `Positions come from institutional filings (mostly US 13F), not the ${venue} share register.`;
+  // Few filers report a line abroad, so a small position can lead the list.
+  return `Positions come from institutional filings (mostly US 13F), not the ${venue} share register, so the line's largest holders may be missing.`;
 }

package/src/plugins/builtin/holders/report-rows.ts

@@ -0,0 +1,240 @@
+import type { HeadlessPaneColumn } from "../../../types/plugin";
+import type { HolderData, ShareBasis } from "../../../types/financials";
+import { formatCompact, formatPercentRaw } from "../../../utils/format";
+import {
+  displayDate,
+  formatMoneyCompact,
+  formatPercentHeld,
+  formatSignedCompact,
+  holderPercent,
+  holderValueCurrency,
+  resolveHolderOwnershipPercent,
+} from "./format";
+import {
+  holderListPeriod,
+  holderPeriodsDiffer,
+  holderShareBasisMarker,
+  holderShareBasisNote,
+  holderValueBasis,
+  holdersHeaderLine,
+  moneyColumnHeader,
+  nonUsHolderCaveat,
+  sharedReportDate,
+} from "./report-header";
+import { buildRows, DEFAULT_SORT, sortRows } from "./table-model";
+import type { HolderColumnId, SortPreference } from "./types";
+
+/**
+ * A holder as `holders` and `fn HDS` report it; the keys are the JSON
+ * contract. `value` is in `currency`, the values' own currency; the percents
+ * are in percent (0.59 is 0.59% of the shares outstanding, 13.15 a 13.15%
+ * change on the quarter). A figure the source did not give is null.
+ */
+export interface HolderReportRow {
+  name: string;
+  ownerType: string;
+  value: number | null;
+  shares: number | null;
+  changeShares: number | null;
+  changePercent: number | null;
+  percentHeld: number | null;
+  reportDate: string | null;
+  currency: string;
+  shareBasis: ShareBasis | null;
+  [key: string]: unknown;
+}
+
+/** Columns a source fills only when it reports the quarter's change. */
+const CHANGE_COLUMN_KEYS = new Set(["changeShares", "changePercent"]);
+/** Shown only when some row is held as depositary receipts, as on a home line abroad. */
+const BASIS_COLUMN_KEY = "shareBasis";
+const num = (value: unknown) => (typeof value === "number" && Number.isFinite(value) ? value : null);
+
+/**
+ * The HDS report's columns, which `holders --csv` and `--json` share. CSV
+ * reads `format`, so a value drawn as a plain figure exports its full number
+ * under a header naming the unit (`Mkt value (USD)`, `Held (%)`); the text
+ * report draws `textFormat`, with the currency sign and `<0.01%`.
+ */
+export const HOLDER_REPORT_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "name", header: "Holder" },
+  { key: "ownerType", header: "Type" },
+  {
+    key: "value",
+    header: "Mkt value",
+    align: "right",
+    format: (value) => num(value) == null ? "-" : formatCompact(num(value)!),
+    textFormat: (value, row) => formatMoneyCompact(num(value) ?? undefined, String(row.currency ?? "USD")),
+  },
+  {
+    key: "shares",
+    header: "Amount",
+    align: "right",
+    format: (value) => num(value) == null ? "-" : formatCompact(num(value)!),
+  },
+  {
+    key: BASIS_COLUMN_KEY,
+    header: "Basis",
+    format: (_value, row) => holderShareBasisMarker(row),
+  },
+  {
+    key: "changeShares",
+    header: "Chg",
+    align: "right",
+    format: (value) => formatSignedCompact(num(value) ?? undefined),
+  },
+  {
+    key: "changePercent",
+    header: "Chg%",
+    align: "right",
+    format: (value) => num(value) == null ? "-" : formatPercentRaw(num(value)!),
+  },
+  {
+    key: "percentHeld",
+    header: "Held",
+    align: "right",
+    format: (value) => num(value) == null ? "-" : `${num(value)!.toFixed(2)}%`,
+    textFormat: (value) => formatPercentHeld(num(value)),
+  },
+  {
+    key: "reportDate",
+    header: "Period",
+    format: (value) => displayDate(typeof value === "string" ? value : undefined),
+  },
+];
+
+/** `--sort` values, the same for `holders` and `fn HDS`. */
+export const HOLDER_SORT_KEYS: Record<string, HolderColumnId> = {
+  holder: "holder",
+  value: "value",
+  shares: "shares",
+  change: "changeShares",
+  "change-percent": "changePercent",
+  held: "percentHeld",
+  date: "reportDate",
+};
+
+/**
+ * Every holder of the list, largest value first unless another sort is
+ * asked for, with the stake and change in percent. A holder without a value
+ * sorts after those with one, whichever the direction. `ownerTypes` keeps
+ * only those kinds (`insider`, `13f`).
+ */
+export function holderReportRows(
+  data: HolderData,
+  {
+    marketCap,
+    sort = DEFAULT_SORT,
+    ownerTypes,
+  }: { marketCap?: number; sort?: SortPreference; ownerTypes?: ReadonlySet<string> } = {},
+): HolderReportRow[] {
+  const holders = ownerTypes ? data.holders.filter((holder) => ownerTypes.has(holder.ownerType)) : data.holders;
+  // The values' own currency: dollars from the 13F filings on a London line.
+  const currency = holderValueCurrency(data, "USD")!;
+  return sortRows(buildRows({ ...data, holders }), sort, marketCap).map((row) => ({
+    name: row.name,
+    ownerType: row.ownerType,
+    value: row.value ?? null,
+    shares: row.shares ?? null,
+    changeShares: row.changeShares ?? null,
+    changePercent: holderPercent(row.changePercent),
+    percentHeld: holderPercent(resolveHolderOwnershipPercent(row, marketCap)),
+    reportDate: row.reportDate ?? null,
+    currency,
+    shareBasis: row.shareBasis ?? null,
+  }));
+}
+
+/** The report dates of the rows, newest first: one when the list is of one quarter. */
+export function holderReportDates(rows: readonly HolderReportRow[]): string[] {
+  return [...new Set(rows.flatMap((row) => row.reportDate ? [row.reportDate] : []))].sort().reverse();
+}
+
+/** What the JSON rows' numbers are in, for `metadata.units`. */
+export function holderReportUnits(valueCurrency: string): Record<string, string> {
+  return { value: valueCurrency, changePercent: "%", percentHeld: "%" };
+}
+
+/** Whether any holder carries the quarter's change; many sources report none. */
+function holderChangeReported(rows: readonly HolderReportRow[]): boolean {
+  return rows.some((row) => row.changeShares != null || row.changePercent != null);
+}
+
+/**
+ * The report's columns for these rows: the change columns only when a row
+ * has a change, the basis column only when a row is held as receipts, and
+ * the value column named with its currency.
+ */
+export function holderReportColumns(rows: readonly HolderReportRow[], valueCurrency: string | null | undefined): HeadlessPaneColumn[] {
+  const changeReported = holderChangeReported(rows);
+  const marked = rows.some((row) => holderShareBasisMarker(row));
+  return HOLDER_REPORT_COLUMNS
+    .filter((column) => changeReported || !CHANGE_COLUMN_KEYS.has(column.key))
+    .filter((column) => marked || column.key !== BASIS_COLUMN_KEY)
+    .map((column) => column.key === "value" ? { ...column, header: moneyColumnHeader(column.header, valueCurrency) } : column);
+}
+
+/**
+ * The lines above the HDS table, which `holders --csv` also closes with: the
+ * listing, unit and count, how a value was reached (and where the change is
+ * when the source gives none), and what the positions and shares are.
+ */
+export function holderReportNotices({
+  data,
+  requested,
+  shown,
+  reported,
+  total,
+  sort = DEFAULT_SORT,
+}: {
+  data: HolderData;
+  /** The symbol as asked for, which `fn 13F` takes. */
+  requested: string;
+  shown: readonly HolderReportRow[];
+  /** Holders on the list before a limit. */
+  reported: number;
+  total: number | null;
+  sort?: SortPreference;
+}): { notices: string[]; valueBasis: string; positionsBasis: string | null; changeReported: boolean } {
+  const valueCurrency = holderValueCurrency(data, "USD")!;
+  const changeReported = holderChangeReported(shown);
+  const valueBasis = holderValueBasis(sharedReportDate(shown), data.valueBasis, valueCurrency);
+  const positionsBasis = shown.length > 0 ? nonUsHolderCaveat(data.exchange, data.currency ?? "USD") : null;
+  // The title names the ticker and the closing line carries the as-of date,
+  // which is one date only when every row has it.
+  const header = holdersHeaderLine({
+    name: data.name,
+    symbol: data.symbol && data.symbol !== requested ? data.symbol : null,
+    exchange: data.exchange,
+    currency: valueCurrency,
+    listingCurrency: data.currency,
+    period: holderPeriodsDiffer(shown) ? holderListPeriod(shown) : null,
+    shown: shown.length,
+    reported,
+    total,
+    ranked: !positionsBasis,
+  });
+  const basis = shown.length === 0 ? null : [
+    `Mkt value = ${valueBasis}.`,
+    changeReported ? "" : `Change vs prior quarter: not reported by this source; see fn 13F ${requested}`,
+  ].filter(Boolean).join(" ");
+  return {
+    notices: [header, basis, positionsBasis, holderShareBasisNote(data, shown), unvaluedHoldersNote(shown, sort)]
+      .filter((line): line is string => !!line),
+    valueBasis,
+    positionsBasis,
+    changeReported,
+  };
+}
+
+/**
+ * Holders the list gives no value for (a home line's position its filing
+ * could not tie to a priced security) sort after every valued one, and a
+ * value-ordered report says so rather than ranking them silently.
+ */
+export function unvaluedHoldersNote(rows: readonly HolderReportRow[], sort: SortPreference = DEFAULT_SORT): string | null {
+  if (sort.columnId !== "value") return null;
+  const unvalued = rows.filter((row) => row.value == null).length;
+  if (unvalued === 0 || unvalued === rows.length) return null;
+  return `${unvalued} ${unvalued === 1 ? "holder has" : "holders have"} no value and ${unvalued === 1 ? "is" : "are"} listed last.`;
+}