gloomberb 0.17.2 → 0.17.4

package/src/cli/commands/ticker.ts

@@ -3,7 +3,7 @@ import { formatReportedMoney } from "../../utils/reported-money";
 import { convertedPriceEarningsNote, enterpriseValueLabel, enterpriseValueReconciliationNote, epsConversionNote, fundamentalsCurrency, reportedEnterpriseValue, ttmConversionNote } from "../../utils/fundamentals";
 import { latestFinancialPeriod } from "../../utils/latest-financial-period";
 import { exportedFundamentals, formatPriceEarnings, priceEarningsOnEarnings } from "../../utils/price-earnings";
-import { describeFundamentalMarketCap, selectMarketCapitalization } from "../../utils/market-capitalization";
+import { describeFundamentalMarketCap, marketCapShareBasisNote, selectMarketCapitalization } from "../../utils/market-capitalization";
 import {
   formatCompact,
   formatCurrency,
@@ -32,9 +32,9 @@ import {
 import type { FuturesContractTermsPayload } from "../../api-client/futures-curve";
 import { futuresContractLines, futuresSettleText, isFuturesInstrument, loadFuturesContractTerms } from "../../market-data/futures-contract";
 import type { AppConfig } from "../../types/config";
-import type { FinancialStatement, Quote, TickerFinancials } from "../../types/financials";
+import type { DeclaredDividendAction, FinancialStatement, Quote, TickerFinancials } from "../../types/financials";
 import { quoteTradingDay } from "../../market-data/quotes/day-range";
-import { atRegularSessionPrice } from "../../market-data/quotes/regular-session-valuation";
+import { atRegularSessionPrice, regularSessionValuationPrice } from "../../market-data/quotes/regular-session-valuation";
 import { computeTickerPriceReturns } from "../../market-data/ticker-price-returns";
 import { instrumentTypeLabel, isCryptoVenuePerpetual, resolveTickerInstrumentKind } from "../../tickers/instrument-kind";
 import type { SecFilingItem } from "../../types/data-provider";
@@ -69,6 +69,7 @@ import { exportEntriesTable, reportFooterLines, type CliReportTables } from "../
 import type { ReportFreshness } from "../pane-functions/freshness";
 import { fundamentalsFreshness, quotesFreshness } from "../freshness";
 import { forwardDividendBasis } from "../../utils/forward-dividend";
+import { declaredDividends } from "../../utils/declared-dividends";
 import { notTheCoinNote } from "./crypto-hints";
 
 const NEWS_ITEM_LIMIT = 5;
@@ -347,11 +348,38 @@ function percentFigure(fraction: number | null | undefined, format: (value: numb
   return fraction != null ? { text: format(fraction), value: fraction * 100, unit: "%" } : { text: "—" };
 }
 
-/** A forward yield says what it annualizes and when, as DVD does (a declared distribution by its ex-date); any other yield is the figure alone. */
-function forwardYieldFigure(fundamentals: TickerFinancials["fundamentals"]): MetricFigure {
+/** The declared, unpaid distributions a forward yield dated ahead is named from, in their own currency. */
+export interface ForwardYieldDeclarations {
+  rows: DeclaredDividendAction[];
+  currency?: string;
+}
+
+/**
+ * The listing's declared distributions, read only for a forward yield whose
+ * ex-date is still ahead (the one case its basis names one); null otherwise,
+ * and when they cannot be read, which leaves the basis to its dates.
+ */
+export async function loadForwardYieldDeclarations(
+  dataProvider: Pick<MarketContext["dataProvider"], "getCorporateActions">,
+  listing: { symbol: string; exchange: string },
+  fundamentals: TickerFinancials["fundamentals"],
+  now = new Date(),
+): Promise<ForwardYieldDeclarations | null> {
+  const exDate = fundamentals?.dividendYieldBasis === "forward" ? fundamentals.exDividendDate ?? "" : "";
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(exDate) || exDate <= now.toISOString().slice(0, 10) || !dataProvider.getCorporateActions) return null;
+  try {
+    const actions = await dataProvider.getCorporateActions(listing.symbol, listing.exchange);
+    return { rows: declaredDividends(actions, now), ...(actions.currency ? { currency: actions.currency } : {}) };
+  } catch {
+    return null;
+  }
+}
+
+/** A forward yield says what it annualizes and when, as DVD does (a declared distribution by its ex-date and stated amount); any other yield is the figure alone. */
+function forwardYieldFigure(fundamentals: TickerFinancials["fundamentals"], declared: ForwardYieldDeclarations | null): MetricFigure {
   const figure = percentFigure(fundamentals?.dividendYield, formatFractionPercentCell);
   return fundamentals?.dividendYieldBasis === "forward" && fundamentals.dividendYield != null
-    ? { ...figure, text: `${figure.text} (${forwardDividendBasis(fundamentals.exDividendDate)})` }
+    ? { ...figure, text: `${figure.text} (${forwardDividendBasis(fundamentals.exDividendDate, { declared: declared?.rows, currency: declared?.currency })})` }
     : figure;
 }
 
@@ -368,6 +396,7 @@ function fundamentalsMetrics(
   priceReturns: { return1Y?: number | null; return3Y?: number | null },
   reportingCurrency: string | undefined,
   enterpriseValue = reportedMoney(reportedEnterpriseValue(fundamentals), enterpriseValueCurrency(quote, fundamentals)),
+  declared: ForwardYieldDeclarations | null = null,
 ): FundamentalsMetric[] {
   const signed = (value: number) => colorBySign(formatPercent(value), value);
   const receipt = fundamentals?.sharesOutstanding != null && sharesOutstandingInReceipts(quote, fundamentals, profile?.description);
@@ -382,7 +411,7 @@ function fundamentalsMetrics(
     { label: "EPS (TTM)", ...reportedMoney(fundamentals?.eps, fundamentals?.epsCurrency?.trim() || reportingCurrency, true) },
     {
       label: `Dividend Yield${fundamentals?.dividendYieldBasis ? ` (${fundamentals.dividendYieldBasis})` : ""}`,
-      ...forwardYieldFigure(fundamentals),
+      ...forwardYieldFigure(fundamentals, declared),
     },
     { label: "Revenue (TTM)", ...reportedMoney(fundamentals?.revenue, reportingCurrency) },
     { label: "Net Income (TTM)", ...reportedMoney(fundamentals?.netIncome, reportingCurrency) },
@@ -404,6 +433,34 @@ function fundamentalsMetrics(
   ];
 }
 
+/**
+ * The float and the short interest `fundamentals` prints after the share count: the shares short, short % of float
+ * and days to cover of one settlement, dated, as the JSON gives them and `SI` and `SIW` show them.
+ */
+function floatAndShortInterestMetrics(
+  quote: TickerFinancials["quote"],
+  fundamentals: TickerFinancials["fundamentals"],
+  profile: TickerFinancials["profile"],
+): FundamentalsMetric[] {
+  const finite = (value: number | undefined): value is number => value != null && Number.isFinite(value);
+  const float = fundamentals?.floatShares;
+  const short = fundamentals?.sharesShort;
+  const days = fundamentals?.shortRatio;
+  const date = fundamentals?.shortInterestDate;
+  const receipt = finite(float) && sharesOutstandingInReceipts(quote, fundamentals, profile?.description);
+  return [
+    finite(float) && float > 0
+      ? { label: "Float", text: formatCompact(float), value: float, ...(receipt ? { unit: "ADR equivalent" } : {}) }
+      : { label: "Float", text: "—" },
+    finite(short)
+      ? { label: "Short Interest", text: `${formatCompact(short)}${date ? ` (settled ${date})` : ""}`, value: short, unit: "shares" }
+      : { label: "Short Interest", text: "—" },
+    ...finite(short) && date ? [{ label: "Short Interest Settlement", text: date, value: date, exportOnly: true }] : [],
+    { label: "Short % of Float", ...percentFigure(fundamentals?.shortPercentOfFloat, formatFractionPercentCell) },
+    finite(days) ? { label: "Days to Cover", text: formatNumber(days, 2), value: days } : { label: "Days to Cover", text: "—" },
+  ];
+}
+
 function metricLines(metrics: readonly FundamentalsMetric[]): Array<[string, string]> {
   return metrics.filter((metric) => !metric.exportOnly).map((metric) => [metric.label, metric.text]);
 }
@@ -411,28 +468,35 @@ function metricLines(metrics: readonly FundamentalsMetric[]): Array<[string, str
 const TRAILING_MONEY_METRICS = new Set(["EPS (TTM)", "Revenue (TTM)", "Net Income (TTM)", "Operating Cash Flow (TTM)", "Free Cash Flow (TTM)"]);
 
 /**
- * The notes under shown fundamentals: how a labelled or withdrawn EV compares with market cap + debt - cash, what a
- * converted TTM block was converted from, an EPS in another currency than the amounts beside it, and what a P/E on
- * such an EPS divides.
+ * The notes under shown fundamentals: a market cap that does not rest on the share count shown, how a labelled or
+ * withdrawn EV compares with market cap + debt - cash, what a converted TTM block was converted from, an EPS in
+ * another currency than the amounts beside it, and what a P/E on such an EPS divides. `priced` is the snapshot at
+ * the regular session price (atRegularSessionPrice), the figures the lines show, so each note reads those.
  */
 function fundamentalsNotes(
-  fundamentals: TickerFinancials["fundamentals"],
+  priced: Pick<TickerFinancials, "quote" | "fundamentals">,
   metrics: readonly FundamentalsMetric[],
   quoteCurrency: string | undefined,
 ): string[] {
+  const fundamentals = priced.fundamentals;
   const shown = (label: string) => metrics.some((metric) => metric.label === label && metric.text !== "—");
+  const shareBasis = shown("Market Cap") && shown("Shares Outstanding")
+    ? marketCapShareBasisNote(selectMarketCapitalization(priced.quote, fundamentals), fundamentals?.sharesOutstanding,
+      regularSessionValuationPrice(priced.quote), priced.quote?.currency)
+    : undefined;
   const conversion = [...TRAILING_MONEY_METRICS].some(shown) ? ttmConversionNote(fundamentals) : undefined;
   const eps = shown("EPS (TTM)") ? epsConversionNote(fundamentals) : undefined;
   const priceEarnings = metrics.some((metric) => metric.label === "P/E (TTM)" && typeof metric.value === "number")
     ? convertedPriceEarningsNote(fundamentals, quoteCurrency)
     : undefined;
   const enterpriseValue = shown("Enterprise Value") ? enterpriseValueReconciliationNote(fundamentals) : undefined;
-  return [enterpriseValue, conversion, eps, priceEarnings].filter((note): note is string => !!note);
+  return [shareBasis, enterpriseValue, conversion, eps, priceEarnings].filter((note): note is string => !!note);
 }
 
-const VALUATION_METRICS = new Set(["Market Cap", "Enterprise Value", "P/E (TTM)", "Forward P/E", "PEG", "EPS (TTM)"]);
+// The share count is the market cap's basis: the cap is the count times the price, or a note says why not.
+const VALUATION_METRICS = new Set(["Market Cap", "Shares Outstanding", "Enterprise Value", "P/E (TTM)", "Forward P/E", "PEG", "EPS (TTM)"]);
 
-type FundamentalsReportData = TickerFinancials & { symbol: string; exchange?: string };
+type FundamentalsReportData = TickerFinancials & { symbol: string; exchange?: string; declaredDividends?: ForwardYieldDeclarations | null };
 
 /**
  * What a fund's report cannot show yet, and for a US listing where its SEC
@@ -502,9 +566,16 @@ function fundamentalsReportMetrics(snapshot: FundamentalsReportData, view: "fund
   const marketCap: MetricFigure = capitalization
     ? { text: `${formatCompact(capitalization.value)} ${capitalization.currency}`, value: capitalization.value, unit: capitalization.currency }
     : { text: "—" };
-  const metrics = fundamentalsMetrics(quote, fundamentals, financials.profile, marketCap, computeTickerPriceReturns(financials), fundamentalsCurrency(financials));
-  if (view === "fundamentals") return metrics.filter((metric) => metric.text !== "—");
-  const valuation = metrics.filter(({ label, text }) => (VALUATION_METRICS.has(label) || label.startsWith("Dividend Yield")) && text !== "—");
+  const metrics = fundamentalsMetrics(quote, fundamentals, financials.profile, marketCap, computeTickerPriceReturns(financials), fundamentalsCurrency(financials),
+    undefined, snapshot.declaredDividends ?? null);
+  if (view === "fundamentals") {
+    return [...metrics, ...floatAndShortInterestMetrics(quote, fundamentals, financials.profile)]
+      .filter((metric) => metric.text !== "—");
+  }
+  const valued = metrics.filter(({ label, text }) => (VALUATION_METRICS.has(label) || label.startsWith("Dividend Yield")) && text !== "—");
+  // The share count follows the market cap it is the basis of.
+  const shares = valued.filter((metric) => metric.label === "Shares Outstanding");
+  const valuation = valued.flatMap((metric) => metric.label === "Shares Outstanding" ? [] : metric.label === "Market Cap" ? [metric, ...shares] : [metric]);
   // A listing with no valuation (a fund) says so rather than printing its price alone.
   return valuation.length === 0 ? [] : [...valuationPriceMetrics(financials).filter((metric) => metric.text !== "—"), ...valuation];
 }
@@ -532,7 +603,7 @@ export function renderFundamentalsReport(
   const fund = fundFactsNote(symbol, financials.exchange || quote?.exchangeName, financials);
   if (lines.length === before) lines.push("", cliStyles.muted([`No ${view} reported for ${financials.symbol}.`, fund].filter(Boolean).join(" ")));
   else if (fund) lines.push(cliStyles.muted(fund));
-  for (const note of fundamentalsNotes(financials.fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
+  for (const note of fundamentalsNotes(atRegularSessionPrice(financials), metrics, quote?.currency)) lines.push(cliStyles.muted(note));
   if (view === "fundamentals") appendTextSection(lines, "Description", profile?.description);
   return lines.join("\n");
 }
@@ -572,7 +643,7 @@ export function fundamentalsReportTables(
       notes: [
         ...metrics.length === 0
           ? [`No ${view} reported for ${financials.symbol}.`]
-          : fundamentalsNotes(financials.fundamentals, metrics, financials.quote?.currency),
+          : fundamentalsNotes(atRegularSessionPrice(financials), metrics, financials.quote?.currency),
         ...fund ? [fund] : [],
       ],
     }),
@@ -605,8 +676,11 @@ export async function buildTickerReport({
   recentNews = [],
   recentSecFilings = [],
   futuresContract = null,
+  declaredDividends: declared = null,
 }: {
   symbol: string;
+  /** The declared distributions a forward yield dated ahead is named from (loadForwardYieldDeclarations). */
+  declaredDividends?: ForwardYieldDeclarations | null;
   /** The exchange the command named, as a canonical code. */
   listingExchange?: string;
   /** A futures symbol's contract terms and latest confirmed settlement. */
@@ -732,10 +806,11 @@ export async function buildTickerReport({
     ]);
   }
 
-  const metrics = fundamentalsMetrics(quote, priced.fundamentals, profile, { text: marketCapText }, priceReturns, fundamentalsCurrency(financials), { text: enterpriseValueText });
+  const metrics = fundamentalsMetrics(quote, priced.fundamentals, profile, { text: marketCapText }, priceReturns, fundamentalsCurrency(financials),
+    { text: enterpriseValueText }, declared);
   const beforeFundamentals = lines.length;
   appendMetricSection(lines, "Fundamentals", metricLines(metrics));
-  for (const note of fundamentalsNotes(fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
+  for (const note of fundamentalsNotes(priced, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
   // Where a fund's facts would go: under its fundamentals, or in their place.
   const fund = fundFactsNote(quote?.symbol ?? symbol,
     quote?.tradingExchangeName || listingExchange || quote?.listingExchangeName || quote?.exchangeName || tickerFile?.metadata.exchange, financials, tickerFile);
@@ -948,6 +1023,9 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
 
     const notesFiles = new NotesFiles(dataDir);
     const listingName = listingIdentity(listing, quote).name;
+    // The text report's yield basis, read beside the rest for a forward yield dated ahead only; it never fails the report.
+    const declarations = dependencies.printResult ? null
+      : loadForwardYieldDeclarations(dataProvider, { symbol: requestSymbol, exchange }, resolvedFinancials.fundamentals);
     const [notesResult, newsResult, secFilingsResult] = await Promise.allSettled([
       notesFiles.load(tickerFile?.metadata.ticker ?? normalized),
       dataProvider.getNews({
@@ -1013,6 +1091,7 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
         recentNews,
         recentSecFilings,
         futuresContract,
+        declaredDividends: await declarations,
     }));
     if (freshness) console.log(`\n${cliFreshnessFooter(freshness)}`);
   });

package/src/cli/desktop-pane-shot.ts

@@ -60,9 +60,12 @@ export interface DesktopPaneShotPayload {
   statusLine?: boolean;
   /**
    * The tallest the capture may grow, in cells, to show every row its tables
-   * scroll past; absent keeps the requested height (`--height`, most panes).
+   * scroll past or all the text its reader scrolls past; absent keeps the
+   * requested height (`--height`, most panes).
    */
   maxHeightCells?: number;
+  /** The `data-gloom-role`s of the scrolling boxes the capture grows to fit; the tables' bodies when absent. */
+  fitRoles?: string[];
   tickers: TickerRecord[];
   /** Broker accounts as last synced, by profile, so a broker portfolio shows its equity and cash. */
   brokerAccounts?: Record<string, BrokerAccount[]>;
@@ -127,6 +130,12 @@ interface DesktopPaneShotSurface {
 
 export interface DesktopPaneShotRenderResult {
   visibleText: string;
+  /**
+   * The visible text a line per block of the page, as the browser lays it out,
+   * where `visibleText` has run them together: the words of a pane that is prose
+   * and not a table, to be read as paragraphs. Absent in a capture that did not read it.
+   */
+  visibleLines?: string[];
   /**
    * The rows a report reads, when a table reports every row (an option chain's
    * strike window) rather than those in the viewport; `rows` stays what the
@@ -222,7 +231,13 @@ export async function renderDesktopPaneScreenshot(
       userDataDir: join(tempDir, "chrome-profile"),
       captureImage: options.captureImage !== false,
       statusLine: payload.statusLine ? options.statusLine : undefined,
-      ...(payload.maxHeightCells ? { fitRows: { heightCells: payload.heightCells, maxHeightCells: payload.maxHeightCells } } : {}),
+      ...(payload.maxHeightCells ? {
+        fitRows: {
+          heightCells: payload.heightCells,
+          maxHeightCells: payload.maxHeightCells,
+          roles: payload.fitRoles ?? ["data-table-body-scroll"],
+        },
+      } : {}),
     });
   } finally {
     server?.stop(true);
@@ -458,7 +473,7 @@ async function capturePageScreenshot({
   userDataDir: string;
   captureImage: boolean;
   statusLine?: ShotStatusLine;
-  fitRows?: { heightCells: number; maxHeightCells: number };
+  fitRows?: { heightCells: number; maxHeightCells: number; roles: readonly string[] };
 }): Promise<DesktopPaneShotRenderResult> {
   await mkdir(userDataDir, { recursive: true });
   const port = 43000 + Math.floor(Math.random() * 10000);
@@ -531,9 +546,10 @@ async function capturePageScreenshot({
 }
 
 /**
- * Grows the viewport and the pane by the rows their tables scroll past, up to
- * `maxHeightCells`, then waits for the taller pane to settle: a board a
- * default capture would cut (FUT's last sectors) shows every row.
+ * Grows the viewport and the pane by the rows their tables scroll past, or the
+ * text a reader's body scrolls past, up to `maxHeightCells`, then waits for the
+ * taller pane to settle: a board a default capture would cut (FUT's last
+ * sectors) shows every row, and a docs page its whole text.
  */
 async function growToFitRows(session: CdpSession, size: {
   widthPx: number;
@@ -541,9 +557,11 @@ async function growToFitRows(session: CdpSession, size: {
   deviceScaleFactor: number;
   heightCells: number;
   maxHeightCells: number;
+  roles: readonly string[];
 }): Promise<void> {
+  const selector = size.roles.map((role) => `[data-gloom-role="${role}"]`).join(", ");
   const result = await session.send("Runtime.evaluate", {
-    expression: `Math.max(0, ...[...document.querySelectorAll('[data-gloom-role="data-table-body-scroll"]')]
+    expression: `Math.max(0, ...[...document.querySelectorAll(${JSON.stringify(selector)})]
       .map((element) => element.scrollHeight - element.clientHeight))`,
     returnByValue: true,
   }) as { result?: { value?: unknown } };
@@ -646,6 +664,7 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
         const table = element.closest('[data-gloom-role="data-table"]');
         return !!table && reportedTables.has(table);
       };
+      const managesRows = (element) => element.getAttribute("data-gloom-role") === "data-table-body-scroll";
       const markScrollTruncation = (element) => {
         if (!(element instanceof HTMLElement) || !isVisible(element)) return;
         const reasons = scrollReasons({
@@ -655,8 +674,10 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
           scrollLeft: element.scrollLeft,
           scrollWidth: element.scrollWidth,
           clientWidth: element.clientWidth,
-          scrollbarY: element.getAttribute("data-gloom-scrollbar-y") === "visible",
-          scrollbarX: element.getAttribute("data-gloom-scrollbar-x") === "visible",
+          // A scroll box draws its scrollbar by default and its content is all in the page, so its
+          // measures say what is cut; only a table's body holds rows it has not drawn.
+          scrollbarY: managesRows(element) && element.getAttribute("data-gloom-scrollbar-y") === "visible",
+          scrollbarX: managesRows(element) && element.getAttribute("data-gloom-scrollbar-x") === "visible",
         });
         reasons.forEach((reason) => truncationReasons.add(reason));
         if (!inReportedTable(element)) reasons.forEach((reason) => reportTruncationReasons.add(reason));
@@ -810,8 +831,12 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
   if (textShowsEllipsis && !truncationReasons.includes("one or more cells are visibly clipped")) {
     truncationReasons.push("one or more cells are visibly clipped");
   }
+  const visibleLines = (value?.visibleText ?? "").split("\n")
+    .map((line) => line.replace(/\u00a0/g, " ").trimEnd())
+    .filter((line) => line.trim().length > 0);
   return {
     visibleText,
+    visibleLines,
     footerText: typeof value?.footerText === "string" ? value.footerText : "",
     visibleKeyValues: Array.isArray(value?.visibleKeyValues) ? value.visibleKeyValues : [],
     ...(Array.isArray(value?.surfaces) && value.surfaces.length > 0 ? { surfaces: value.surfaces } : {}),

package/src/cli/fx-pair.ts

@@ -13,11 +13,28 @@ export interface FxRequest {
 
 const CURRENCY_CODE = /^[A-Z]{3}$/;
 
+let knownCurrencies: ReadonlySet<string> | undefined;
+
+/** An ISO 4217 code the runtime lists, or the offshore yuan it has none for. */
+function isKnownCurrency(code: string): boolean {
+  if (!knownCurrencies) {
+    try {
+      knownCurrencies = new Set([...Intl.supportedValuesOf("currency"), "CNH"]);
+    } catch {
+      knownCurrencies = new Set();
+    }
+  }
+  return knownCurrencies.has(code);
+}
+
 /** The request, or the sentence saying what is wrong with the argument. */
 export function parseFxRequest(raw: string, baseCurrency: string): FxRequest | { error: string } {
   const text = raw.trim().toUpperCase();
   const parts = text.split("/").map((part) => part.trim());
   if (parts.length > 2 || parts.some((part) => !part)) return { error: `"${raw}" is not a currency or a pair such as USD/NGN.` };
+  // EURUSD is the pair typed without its slash: say how to write it.
+  const joined = parts.length === 1 && /^[A-Z]{6}$/.test(text) && isKnownCurrency(text.slice(0, 3)) && isKnownCurrency(text.slice(3));
+  if (joined) return { error: `${text} is not a currency code; write the pair as ${text.slice(0, 3)}/${text.slice(3)}.` };
   const bad = parts.filter((part) => !CURRENCY_CODE.test(part));
   if (bad.length > 0) return { error: `${bad.join(" and ")} ${bad.length > 1 ? "are not currency codes" : "is not a currency code"}; use three letters such as NGN.` };
   return parts.length === 2

package/src/cli/glossary.ts

@@ -1,8 +1,9 @@
 import { cliStyles, cliTerminalWidth, renderDefinitions, renderSection, wrapText } from "../utils/cli-output";
 
 /**
- * Plain-words meanings of the rates, auction, energy, perpetual-futures, portfolio
- * and fund terms the functions show in their rows, headers and footers.
+ * Plain-words meanings of the rates, auction, energy, perpetual-futures, portfolio,
+ * fund, short interest, quote-board, futures and economic-calendar terms the functions
+ * show in their rows, headers and footers.
  * `catalog glossary` lists them, `catalog explain <term>` prints one, and
  * `fn <function> --explain` and `portfolio show --explain` follow a report with
  * the ones it shows. Only terms a pane or report actually prints belong here.
@@ -286,8 +287,11 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     definition: "EU Allowance: the right to emit one tonne of CO2 under the EU Emissions Trading System, priced in euros per tonne.",
   },
   {
-    term: "Front month", aliases: ["front-month", "front contract", "continuous contract", "front-month contract"], functions: ["FUT", "CTM"],
-    definition: "The nearest contract still trading. FUT quotes each root's front month by its continuous symbol (TTF=F), which rolls to the next contract as one expires.",
+    term: "Front month", aliases: ["front-month", "front contract", "continuous contract", "front-month contract", "most active", "most active contract"],
+    functions: ["FUT", "CTM"], shown: ["most active"],
+    definition: "The nearest contract still trading, which is the one about to expire. Rolls follow volume: a continuous symbol (CL=F), "
+      + "and FUT with it, moves to the next contract when that one becomes the most active (it holds more open interest, or trades more "
+      + "where none is reported), usually days before expiry, and until then FUT names the nearer contract and its expiry.",
   },
   // Perpetual futures (PERP).
   {
@@ -370,6 +374,122 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     definition: "How loosely a fund follows its index: how much the gap between the fund's return and the index's swings, usually over a year. "
       + "Fees, cash and holdings that differ from the index widen it.",
   },
+  // Short interest (SI, SIW) and daily short volume (SIV).
+  {
+    term: "Short interest", short: "SI", aliases: ["shares short", "short position", "short positions", "short shares"],
+    functions: ["SI", "SIW"], shown: ["Shares Short", "Short interest"],
+    definition: "The number of shares sold short and not yet bought back, counted across US broker-dealers on each settlement date. "
+      + "It is a position, not trading volume, and it is published seven business days after the date it counts.",
+  },
+  {
+    term: "Settlement", aliases: ["settlement date", "settlement dates", "settled", "reporting settlement date"],
+    functions: ["SI", "SIW"], shown: ["Date", "Settled", "settlement"],
+    definition: "The date short positions are counted, twice a month: the 15th (the business day before when it is not one) and the month's last business day. "
+      + "FINRA publishes each count seven business days later, and the report's source line gives that date and the next settlement's.",
+  },
+  {
+    term: "Days to cover", aliases: ["short ratio", "short interest ratio", "days-to-cover", "dtc"], functions: ["SI", "SIW"],
+    shown: ["Days to cover"],
+    definition: "Shares short divided by the average daily volume FINRA reports with the settlement: how many days of normal trading it would take "
+      + "the shorts to buy their shares back. The overview, fundamentals, SI, SIW and EQS all give FINRA's figure. "
+      + "A higher number means a squeeze would take longer to unwind.",
+  },
+  {
+    term: "Average daily volume", short: "ADV", aliases: ["avg daily vol", "avg daily volume", "average daily share volume", "avg volume"], functions: ["SI"],
+    shown: ["Avg Daily Vol"],
+    definition: "The shares traded per day on average, as FINRA reports it with each settlement. Days to cover divides shares short by it.",
+  },
+  {
+    term: "Float", aliases: ["free float", "public float", "float shares", "floating stock", "% float", "percent of float"],
+    functions: ["SI", "SIW"], shown: ["Float"],
+    definition: "The shares open to public trading: those outstanding less shares held by insiders and strategic holders, never more than the shares outstanding. "
+      + "% Float is shares short over today's float, so a settlement is measured against the float as it is now, not as it was then; "
+      + "SI gives it for the latest settlement only.",
+  },
+  {
+    // SIW's Setup column prints these two words.
+    term: "Crowded", aliases: ["crowded short", "crowded shorts", "crowded trade", "crowded, rising", "crowded rising", "setup"], functions: ["SIW"],
+    shown: ["Crowded", "Crowded, rising"],
+    definition: "SIW's flag for a heavily shorted name: at least 10% of the float short, or five or more days to cover with at least 5% of the float short "
+      + "(days to cover alone when the float is unknown). Crowded, rising adds a price up over the month. A fixed threshold, not a squeeze forecast.",
+  },
+  {
+    term: "Squeeze", aliases: ["short squeeze", "squeezes", "short covering"], functions: ["SIW"], shown: ["Short squeeze watch"],
+    definition: "A price rise that forces short sellers to buy shares back to limit their losses, which lifts the price further. "
+      + "It needs a crowded short and little trading to absorb the buying; SIW lists the names where that could happen and does not predict one.",
+  },
+  {
+    term: "SI change", aliases: ["si chg", "short interest change"], functions: ["SIW"], shown: ["SI Chg %"],
+    definition: "The change in shares short from the settlement before, in percent. A split between the two settlements is not adjusted.",
+  },
+  {
+    term: "1M return", aliases: ["1m", "one month return", "month move"], functions: ["SIW"], shown: ["1M %"],
+    definition: "The price change over one calendar month, from the latest daily close to the last close on or before the same day a month earlier.",
+  },
+  {
+    term: "Short volume", aliases: ["daily short volume", "short sale volume", "exempt volume"], functions: ["SIV"],
+    shown: ["Short volume", "Short %", "Exempt volume"],
+    definition: "Shares sold short in a day's off-exchange trading, which FINRA publishes daily; Short % is its share of the day's volume there. "
+      + "It is a flow of trades, not the open position short interest counts, and it includes exempt volume.",
+  },
+  // Quote boards (QQ). The words a beginner meets in a quote's rows and its status line.
+  {
+    term: "Ticker", aliases: ["tickers", "ticker symbol", "symbol", "stock symbol"], functions: ["QQ"], shown: ["Ticker", "Symbol"],
+    definition: "The short code a security trades under, such as AAPL for Apple or ^GSPC for the S&P 500. Type it after a function: fn QQ AAPL.",
+  },
+  {
+    term: "Pre-market", aliases: ["pre-mkt", "pre-market session", "pre-market trading", "pre-market price"], functions: ["QQ"],
+    shown: ["Pre-Market", "pre-market", "PRE-MKT"],
+    definition: "Trading in a US stock before the regular session opens, from 4:00 to 9:30 am New York time, when fewer trades happen and prices can jump. "
+      + "An index does not trade then: its pre-market status means it has not opened, and its level is still the last close.",
+  },
+  {
+    term: "After hours", aliases: ["after-hrs", "post-market", "extended hours", "after-hours trading"], functions: ["QQ"],
+    shown: ["After Hours", "after hours", "AFTER-HRS"],
+    definition: "Trading in a US stock after the regular session closes, from 4:00 to 8:00 pm New York time. "
+      + "Like the pre-market it is thin, so a price there can move more than the regular close suggests.",
+  },
+  {
+    term: "Regular close", aliases: ["close", "closing price", "last close", "prior close", "regular session", "regular session close"],
+    functions: ["QQ"], shown: ["close", "Close"],
+    definition: "The last price of the regular session, 9:30 am to 4:00 pm New York time for US stocks. "
+      + "From the close until the next open a quote's Last and change stay at it, and pre-market and after-hours prices are shown beside it.",
+  },
+  {
+    term: "Delayed", aliases: ["delayed quote", "delayed quotes", "delay", "15 min delayed", "live", "real-time"], functions: ["QQ", "FUT"],
+    shown: ["delayed", "Delayed"],
+    definition: "A price that reaches you some minutes after it traded; the status line gives the lag, such as 15 min delayed. A live (real-time) price has no lag.",
+  },
+  // Futures (FUT, CTM).
+  {
+    term: "Futures contract", aliases: ["futures", "future", "futures contracts", "contract", "contract month", "expiry", "expiration"],
+    functions: ["FUT", "CTM"], shown: ["CONTRACT", "Contract"],
+    definition: "An agreement to buy or sell something, such as oil, gold or the S&P 500, at a set price on a set date. Each contract has a month (Dec 26) and expires, "
+      + "and most traders close out before then. A contract's own Settlement line says how it ends: in cash or by physical delivery.",
+  },
+  {
+    term: "Settle (futures)", aliases: ["settle", "settle price", "settlement price", "futures settle", "daily settlement price"],
+    functions: ["FUT", "CTM"], shown: ["Settle", "PREV"],
+    definition: "A futures contract's official price for the day, set by its exchange from trading near the close. "
+      + "The day's change and margin are measured from it, and it can differ from the last trade. FUT's PREV is the previous one.",
+  },
+  // The economic calendar (ECO).
+  {
+    term: "Actual", aliases: ["actual release", "actual value"], functions: ["ECO"], shown: ["ACTUAL", "Actual"],
+    definition: "The figure a release came in at, filled in once it is published. A dash means it is still to come.",
+  },
+  {
+    term: "Forecast", aliases: ["forecasts", "consensus", "expected"], functions: ["ECO"], shown: ["FORECAST", "Forecast"],
+    definition: "What economists expected the release to show, the consensus before it comes out. Markets move on the gap between Actual and Forecast more than on the number alone.",
+  },
+  {
+    term: "Prior", aliases: ["previous", "prior value", "previous release"], functions: ["ECO"], shown: ["PRIOR", "Prior"],
+    definition: "The previous release's figure, the one Actual and Forecast are compared with.",
+  },
+  {
+    term: "Impact", short: "IMP", aliases: ["importance", "event impact", "high impact"], functions: ["ECO"],
+    definition: "How much a release usually moves markets: HIGH for the big ones (CPI, jobs, rate decisions), MED and LOW for speeches and smaller data.",
+  },
 ];
 
 const ANSI = /\x1b\[[0-9;]*m/g;
@@ -390,7 +510,10 @@ function names(entry: GlossaryEntry): string[] {
 export interface GlossaryLookup {
   /** The entries the query names: by the term, its abbreviation or an alias. */
   exact: GlossaryEntry[];
-  /** The others whose names start a word with each word of the query: `stop-out` finds stop-out vs average. */
+  /**
+   * The others whose names start a word with each word of the query: `stop-out` finds stop-out vs average.
+   * Those that hold the words whole come first.
+   */
   partial: GlossaryEntry[];
 }
 
@@ -407,7 +530,12 @@ export function lookupGlossary(query: string): GlossaryLookup {
     const have = names(entry).flatMap(words);
     return wanted.every((word) => have.some((name) => name.startsWith(word)));
   });
-  return { exact, partial };
+  // The entries that hold the words whole come before those that only start with them: `float` is the float, not the floating rate note.
+  const whole = (entry: GlossaryEntry) => {
+    const have = names(entry).flatMap(words);
+    return wanted.every((word) => have.includes(word));
+  };
+  return { exact, partial: partial.sort((left, right) => Number(whole(right)) - Number(whole(left))) };
 }
 
 function escapeRegExp(text: string): string {

package/src/cli/history-rows.ts

@@ -67,6 +67,8 @@ export interface HistoryRow {
   partial?: true;
   /** The bar's prices were rebuilt from hourly bars where the source left the day empty. */
   filled?: true;
+  /** A future's session has closed but its settlement is not confirmed yet: the close is the last trade. */
+  unsettled?: true;
   /** What the volume counts, when the history says: a coin's is traded value in its quote currency (`USD`). */
   volumeUnit?: string;
   /** Why a coin's bar has no volume: `day in progress`, `rebuilt from hourly bars`, `not reported`. */
@@ -216,6 +218,7 @@ export function historyRows(
       flag: flags.length > 0 ? flags.join(",") : null,
       ...(point.partial ? { partial: true as const } : {}),
       ...(point.filled ? { filled: true as const } : {}),
+      ...(point.unsettled ? { unsettled: true as const } : {}),
       ...(volume ? { volumeUnit: volume.unit } : {}),
       // A coin trades every day, so a bar without volume says why.
       ...(volume && values.volume == null
@@ -255,13 +258,18 @@ function listDates(dates: readonly string[]): string {
 }
 
 /**
- * What the partial and filled bars are: "2026-10-12 is still forming
- * (partial), with no volume until the day closes", and the bars rebuilt from
- * hourly bars. Null when no bar is either.
+ * What the partial, filled and unsettled bars are: "2026-10-12 is still
+ * forming (partial), with no volume until the day closes", the bars rebuilt
+ * from hourly bars, and a future's closed session that "closes on its last
+ * trade until its settlement is confirmed (unsettled)". Null when no bar is
+ * any of them.
  */
-export function historyBarStatusNote(rows: readonly Pick<HistoryRow, "date" | "partial" | "filled" | "volume">[]): string | null {
+export function historyBarStatusNote(
+  rows: readonly Pick<HistoryRow, "date" | "partial" | "filled" | "unsettled" | "volume">[],
+): string | null {
   const partial = rows.filter((row) => row.partial);
   const filled = rows.filter((row) => row.filled);
+  const unsettled = rows.filter((row) => row.unsettled);
   const notes = [
     partial.length > 0
       ? `${listDates(partial.map((row) => row.date))} ${partial.length === 1 ? "is" : "are"} still forming (partial)`
@@ -271,6 +279,10 @@ export function historyBarStatusNote(rows: readonly Pick<HistoryRow, "date" | "p
       ? `${listDates(filled.map((row) => row.date))} ${filled.length === 1 ? "was" : "were"} rebuilt from hourly bars (filled)`
         + (filled.every((row) => row.volume == null) ? ", without volume" : "")
       : null,
+    unsettled.length > 0
+      ? `${listDates(unsettled.map((row) => row.date))} ${unsettled.length === 1 ? "closes" : "close"} on the last trade until the`
+        + ` settlement is confirmed (unsettled)`
+      : null,
   ].filter((note): note is string => note != null);
   return notes.length > 0 ? notes.join("; ") : null;
 }