@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/cli/commands/overview.ts

@@ -23,6 +23,7 @@ import {
   type MoverRankBasis,
 } from "../../plugins/builtin/market-movers/model";
 import { MOVER_CANDIDATES } from "../../plugins/builtin/market-movers/client";
+import { hasPartialFloat, meetsMinFloat, minFloatShares, normalizeMinFloat, PARTIAL_FLOAT_NOTE } from "../../plugins/builtin/market-movers/min-float";
 import { fetchEconCalendarFrom } from "../../plugins/builtin/econ/calendar-source";
 import { computedFredSeriesNote, seriesNotOnFred } from "../../sources/gloomberb-cloud/fred-series";
 import { EXTENDED_SESSION_LABELS, getQuoteSessionFields, type ExtendedSession } from "../../market-data/market/status";
@@ -41,7 +42,7 @@ import {
   type CountryFilter,
   type ImpactFilter,
 } from "../../plugins/builtin/econ/calendar-model";
-import { hasNoReleaseTime, hasNoStatedTime } from "../../plugins/builtin/econ/types";
+import { hasNoReleaseTime, hasNoStatedTime, type EconEvent } from "../../plugins/builtin/econ/types";
 import { econRowFigures } from "../../plugins/builtin/econ/figures";
 import { isoDate, rejectExtraArgs, requireArg, requireOneArg, takeFlag, takeOption } from "./command-utils";
 import { buildCorrelationSeries } from "../../plugins/builtin/correlation/matrix/model";
@@ -141,7 +142,7 @@ const MOVER_LISTS: Record<string, ScreenerCategory | "trending"> = {
   "most-active": "most_actives",
   trending: "trending",
 };
-const MOVERS_USAGE = "movers [gainers|losers|active|trending] [--session regular|extended]";
+const MOVERS_USAGE = "movers [gainers|losers|active|trending] [--session regular|extended] [--min-float <shares>]";
 /** The most rows the movers list serves in one request. */
 const MOVER_REQUEST_CAP = 100;
 /** A one-shot list waits this long for its rows' average volumes and sizes, as `fn MOST` does. */
@@ -154,6 +155,16 @@ function moverRankBasis(value: string | undefined, ctx: Parameters<CliCommandDef
   return basis;
 }
 
+/** `--min-float` in shares, null for none; fails on a value that is not a share count. */
+function moverMinFloat(value: string | undefined, ctx: Parameters<CliCommandDef["execute"]>[1]): number | null {
+  if (value == null) return null;
+  try {
+    return minFloatShares(normalizeMinFloat(value));
+  } catch (error) {
+    ctx.fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
 function screenerCategory(args: readonly string[], ctx: Parameters<CliCommandDef["execute"]>[1]): ScreenerCategory | "trending" {
   rejectExtraArgs(args, 1, { usage: MOVERS_USAGE, takes: "one list" }, ctx);
   const list = args[0]?.toLowerCase() ?? "gainers";
@@ -199,12 +210,14 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   const args = [...rawArgs];
   const sessionOption = takeOption(args, "--session");
   const basis = moverRankBasis(sessionOption, ctx);
+  const minFloat = moverMinFloat(takeOption(args, "--min-float"), ctx);
   const category = screenerCategory(args, ctx);
   const limit = ctx.cliOptions.limit ?? 25;
   if (sessionOption != null && (category === "trending" || category === "most_actives")) {
     ctx.fail("--session ranks Gainers and Losers.", category === "trending"
       ? "Trending keeps its source's order." : "Most active ranks by volume.");
   }
+  if (minFloat != null && category === "trending") ctx.fail("--min-float filters Gainers, Losers and Most active.", "Trending carries no float.");
   if (category === "trending") {
     await withCliServices(ctx, async (services) => {
       const trending = await fetchTrending(limit, undefined, { forceRefresh: ctx.cliOptions.refresh });
@@ -220,8 +233,8 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   }
 
   // After the close a price list keeps only the rows moving its way on the basis
-  // asked for, so it reads more candidates than it shows.
-  const count = category === "most_actives" ? limit : Math.min(MOVER_REQUEST_CAP, Math.max(limit, MOVER_CANDIDATES));
+  // asked for, and a minimum float drops rows, so they read more candidates than they show.
+  const count = category === "most_actives" && minFloat == null ? limit : Math.min(MOVER_REQUEST_CAP, Math.max(limit, MOVER_CANDIDATES));
   // With the saved session, as MOST reads it: a Pro account gets the real-time lists, anyone else the delayed ones.
   const movers = await withMarketData(ctx, () =>
     fetchPreferredMarketMovers(category, count, { forceRefresh: ctx.cliOptions.refresh, session: basis, metadataWaitMs: MOVER_METADATA_WAIT_MS }));
@@ -230,7 +243,7 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   // the regular session's move (its close's after the close), or with
   // --session extended by the extended print's move from that close.
   const { quotes, rankedBy } = rankMoverQuotes(category, movers.quotes.map(moverRegularSession), basis);
-  const rows = quotes.slice(0, limit).map((quote) => {
+  const rows = quotes.filter((quote) => meetsMinFloat(quote.floatShares, minFloat)).slice(0, limit).map((quote) => {
     const { extended, ...row } = quote;
     return {
       ...row,
@@ -244,16 +257,18 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   // As the MOST report reads it: real-time for a Pro account, delayed otherwise, each row dated by its own last price.
   ctx.printResult({
     data: rows,
-    metadata: { category, rankedBy },
+    metadata: { category, rankedBy, ...(minFloat != null ? { minFloat } : {}) },
     ...(fellBack ? { warnings: ["No pre-market or after-hours prints now, so the list is ranked by the regular-session move."] } : {}),
     freshness: rowsFreshness(rows, { status: movers.source === "cloud" ? "live" : "delayed" }, { stale: movers.stale }),
   }, {
     heading: `Ranked by ${MOVER_RANKING_LABELS[rankedBy]}`,
+    ...(minFloat != null && hasPartialFloat(rows) ? { footnote: PARTIAL_FLOAT_NOTE } : {}),
     columns: [
       ...MOVER_COLUMNS.slice(0, 4),
       ...EXTENDED_COLUMNS,
       { key: "volume", header: "Volume", align: "right", value: (row) => formatCompact(Number(row.volume)) },
       { ...MARKET_CAP_CELL, value: (row) => row.marketCap == null ? "" : formatCompact(Number(row.marketCap)) },
+      ...(minFloat != null ? [{ key: "floatShares", header: "Float", align: "right" as const, value: (row: Record<string, unknown>) => formatCompact(Number(row.floatShares)) }] : []),
     ],
   });
 }
@@ -325,6 +340,19 @@ function econHeadColumns(viewerZone: string | null): CliResultColumn[] {
   ];
 }
 
+/**
+ * The text table's columns up to the event. Plain output keeps every column a
+ * query has, so a column that is empty by construction has to be left out
+ * here, not hidden by the table: the viewer's clock only exists with --tz, and
+ * the publisher's own clock only on rows a bank or statistics office times
+ * itself. Exports keep both, so a script's header never moves.
+ */
+function econTextHeadColumns(viewerZone: string | null, publisherTimed: boolean): CliResultColumn[] {
+  return econHeadColumns(viewerZone).filter((column) => (
+    column.key === "viewerTime" ? !!viewerZone : column.key === "localTime" ? publisherTimed : true
+  ));
+}
+
 /**
  * Actual, Forecast and Prior: as the text draws them (`30.3K`, `-4.1M bbl`) in the table, as
  * numbers in the exports (30300, -4100000), where Unit and Scale say what they count and how they were drawn.
@@ -349,6 +377,9 @@ const econExportColumns: CliResultColumn[] = [
   { key: "actualText", header: "actual_text" },
   { key: "forecastText", header: "forecast_text" },
   { key: "priorText", header: "prior_text" },
+  // Which feed the forecast was read from and when, so a consensus can be told from another read of it.
+  { key: "consensusFeed", header: "consensus_feed" },
+  { key: "consensusReadAt", header: "consensus_read_at" },
 ];
 
 /**
@@ -409,6 +440,16 @@ function blankTimeNotes(rows: ReadonlyArray<{ event: string; country: string; ti
   return [...byNote].map(([note, events]) => `No time for ${events.join(", ")}: ${note.charAt(0).toLowerCase()}${note.slice(1)}.`);
 }
 
+/**
+ * Whether a row has come out: it has an actual, or it has no figure at all (a
+ * speech, a meeting, a holiday) and its time has passed. A row with a forecast
+ * or a prior and no actual is still to come, whatever its time.
+ */
+function cameOut(event: Pick<EconEvent, "actual" | "forecast" | "prior" | "date">, now: number): boolean {
+  if (event.actual?.trim()) return true;
+  return !event.forecast?.trim() && !event.prior?.trim() && event.date.getTime() <= now;
+}
+
 /**
  * A `--from` the stored calendar does not reach back to, which Gloom Cloud refuses
  * with "The calendar reaches back 400 days": an input error naming the earliest
@@ -437,7 +478,8 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
   }
   rejectArgs(rawArgs, ECON_USAGE, ctx, "Filter with --country and --impact.");
   await withCliServices(ctx, async () => {
-    const todayStart = Math.floor(Date.now() / DAY_MS) * DAY_MS;
+    const now = Date.now();
+    const todayStart = Math.floor(now / DAY_MS) * DAY_MS;
     // An earlier day reads the stored calendar, which keeps past events after the week's listing drops them.
     // A server without it, a server error or no network lists the current calendar (cached when offline) instead.
     const stored = fromOption != null && fromOption < isoDate(new Date(todayStart))
@@ -497,11 +539,15 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
           // Who publishes the figure (Freddie Mac for the 30-year mortgage rate), the period it covers and its page.
           publisher: event.source?.name ?? null,
           referencePeriod: event.referencePeriod ?? null,
-          // When the figure came out: the row's time once it has an actual (its day alone when it states no time), null before.
-          released: event.actual?.trim() ? (hasNoReleaseTime(event) ? isoDate(event.date).slice(0, 10) : isoDate(event.date)) : null,
+          // When the figure came out: the row's time once it has an actual, and for a row with no figures (a speech, a
+          // meeting) once its time has passed; its day alone when it states no time, null before.
+          released: cameOut(event, now) ? (hasNoReleaseTime(event) ? isoDate(event.date).slice(0, 10) : isoDate(event.date)) : null,
           sourceUrl: event.source?.url ?? null,
-          // The same indicator from one release to the next; empty until Gloom Cloud names it.
+          // The same indicator from one release to the next, as Gloom Cloud names it.
           indicatorId: event.indicatorId ?? null,
+          // The feed the forecast was read from and when, for a row with a forecast.
+          consensusFeed: event.consensus?.source ?? null,
+          consensusReadAt: event.consensus?.readAt ?? null,
         };
       });
     // A filter of countries only, none of which has anything in the window, says so as its empty list.
@@ -535,7 +581,7 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
       }),
       // The exports add what a script needs to read a row; the text table keeps the columns it had.
       columns: [...econHeadColumns(viewerZone), ...econFigureColumns(false), ...econExportColumns],
-      textColumns: [...econHeadColumns(viewerZone), ...econFigureColumns(true), ECON_PUBLISHER_COLUMN],
+      textColumns: [...econTextHeadColumns(viewerZone, rows.some((row) => !!publisherClock(row.localTime, row.timeZone))), ...econFigureColumns(true), ECON_PUBLISHER_COLUMN],
     });
   });
 }
@@ -826,8 +872,11 @@ export const overviewCliCommands: CliCommandDef[] = [
       options: [{
         flags: "--session <basis>",
         description: "Rank gainers and losers by the regular-session move (regular, the default) or by the pre-market or after-hours move from the close (extended)",
+      }, {
+        flags: "--min-float <shares>",
+        description: "Keep the gainers, losers or most active whose float (the one EQS serves) is at least this many shares, such as 10M or 500k; a row with no float is left out",
       }],
-      examples: ["movers", "movers losers --limit 10", "movers gainers --session extended", "movers trending"],
+      examples: ["movers", "movers losers --limit 10", "movers gainers --session extended", "movers gainers --min-float 10M", "movers trending"],
     },
     execute: runMoverCommand,
   },

package/src/cli/commands/search.ts

@@ -133,7 +133,7 @@ export async function searchCandidatesForCli({
     const quote = BARE_SYMBOL.test(symbol) && candidates.some((candidate) => candidate.symbol.toUpperCase() === symbol)
       ? await (quoted ?? loadSearchedQuote(symbol, savedExchange, dataProvider))
       : null;
-    return withQuotedNames(symbol, withHomeListingPrimary(trimmedQuery, withPrimaryListingFirst(symbol, candidates, quote)), quote)
+    return withQuotedNames(symbol, withUsLineOfPrimary(withHomeListingPrimary(trimmedQuery, withPrimaryListingFirst(symbol, candidates, quote))), quote)
       .slice(0, totalLimit);
   } catch (error) {
     // Not "No matches found": a script or a reader would take that for a name nothing lists.
@@ -299,6 +299,26 @@ function withHomeListingPrimary(query: string, candidates: TickerSearchCandidate
   return [...rest.slice(0, at), { ...home, category: "Primary Listing" as const }, { ...primary, category: "Other Listings" as const }, ...rest.slice(at + 1)];
 }
 
+/**
+ * A company whose primary listing is abroad lists the US line of the same
+ * symbol right after it: the line `quote SHEL` reads (a bare symbol is its US
+ * listing), which a name search ("shell") would otherwise rank below the
+ * company's lines on other venues and cut. Any other list keeps its order.
+ */
+function withUsLineOfPrimary(candidates: TickerSearchCandidate[]): TickerSearchCandidate[] {
+  const primary = candidates.find((candidate) => candidate.category === "Primary Listing");
+  if (!primary || primary.kind !== "search" || isUsListingExchange(candidateExchange(primary))) return candidates;
+  const symbol = primary.symbol.toUpperCase();
+  const company = resolveSearchName(primary);
+  const us = candidates.find((candidate) => candidate !== primary && candidate.kind === "search" && !candidate.contractKey
+    && candidate.category !== "Funds & Derivatives" && candidate.symbol.toUpperCase() === symbol
+    && isUsListingExchange(candidateExchange(candidate)) && sameCompany(resolveSearchName(candidate), company));
+  if (!us) return candidates;
+  const rest = candidates.filter((candidate) => candidate !== us);
+  const at = rest.indexOf(primary) + 1;
+  return [...rest.slice(0, at), { ...us, category: "Other Listings" as const }, ...rest.slice(at)];
+}
+
 /** The candidate on the venue the quote prices; the US exchanges share one symbol, so a quote on any of them is its one US line. */
 function quotedCandidate(candidates: readonly TickerSearchCandidate[], quote: Quote | null): TickerSearchCandidate | undefined {
   const quoted = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName);

package/src/cli/commands/themes.ts

@@ -16,14 +16,23 @@ function themeChoicesText(): string {
   return `Themes: ${choices}. gloom config themes lists them with notes.`;
 }
 
+/** `Light themes: paper (Paper), github-light (GitHub Light), ...`, for `light` or `dark` typed as a theme; null for anything else. */
+function appearanceHint(input: string): string | null {
+  const appearance = input.trim().toLowerCase();
+  if (appearance !== "light" && appearance !== "dark") return null;
+  const matching = listThemes().filter((theme) => theme.appearance === appearance).map(({ id, name }) => `${id} (${name})`);
+  return matching.length > 0 ? ` ${appearance === "light" ? "Light" : "Dark"} themes: ${matching.join(", ")}.` : null;
+}
+
 /**
  * The id `input` names, by id or display name in any case. Anything else
- * fails with the closest id when there is one, and every id with its name.
+ * fails with the closest id when there is one, and every id with its name;
+ * `light` or `dark` with the themes of that look.
  */
 export function requireThemeId(input: string): string {
   const lookup = resolveThemeId(input);
   if (lookup.ok) return lookup.id;
-  const hint = lookup.suggestion ? ` Did you mean ${describeThemeId(lookup.suggestion)}?` : "";
+  const hint = appearanceHint(input) ?? (lookup.suggestion ? ` Did you mean ${describeThemeId(lookup.suggestion)}?` : "");
   return fail(`Unknown theme "${input.trim()}".${hint}`, themeChoicesText());
 }
 

package/src/cli/commands/ticker.ts

@@ -3,12 +3,12 @@ import { formatShortDate, parseDisplayDate } from "../../utils/datetime-format";
 import { formatReportedMoney } from "../../utils/reported-money";
 import {
   appTtmRate, computedEnterpriseValueNote, convertedPriceEarningsNote, enterpriseValueLabel, enterpriseValueReconciliationNote, epsConversionNote,
-  fundamentalsCurrency, reportedEnterpriseValue, ttmAtAppRate, ttmConversionNote,
+  fundamentalsCurrency, reportedEnterpriseValue, trailingEpsSourceNote, ttmAtAppRate, ttmConversionNote,
 } from "../../utils/fundamentals";
 import { latestFinancialPeriod } from "../../utils/latest-financial-period";
 import { burnsCash, cashRunway, SHORT_RUNWAY_HISTORY, formatRunwayMonths, offeringNote, offeringsAfter, runwayMethod, type CashRunway, type OfferingFiling, type RunwayEstimate } from "../../utils/cash-runway";
 import { exportedFundamentals, formatPriceEarnings, NOT_MEANINGFUL, priceEarningsOnEarnings } from "../../utils/price-earnings";
-import { describeFundamentalMarketCap, marketCapBasisNote, selectMarketCapitalization, viewMarketCapitalization } from "../../utils/market-capitalization";
+import { describeFundamentalMarketCap, marketCapBasisNote, selectMarketCapitalization, viewMarketCapitalization, withheldMarketCap } from "../../utils/market-capitalization";
 import {
   formatCompact,
   formatCurrency,
@@ -76,7 +76,7 @@ import { isKnownNonUsListing, secFilingItemCodes, US_FUND_FACTS_ONLY } from "../
 import { currentReportItemsLabel, hiddenFilingsNote, loadLatestFilings, type HiddenFilings } from "../../utils/sec-filings";
 import { canonicalExchange, exchangeLabel, isKnownExchangeCode, isUsListingExchange } from "../../utils/exchanges";
 import {
-  failIfNotTraded, failMovedSymbol, ListingArgError, listingChoiceNotes, listingFateLoader, listingIdentity, loadBareVenues,
+  coinListingNotes, failIfNotTraded, failMovedSymbol, ListingArgError, listingChoiceNotes, listingFateLoader, listingIdentity, loadBareVenues,
   resolveCliListing, type CliListing, type ListingDataRequest,
 } from "../listing-arg";
 import { movedAwayChange } from "../../tickers/ticker-changes";
@@ -92,12 +92,12 @@ import { fundamentalsFreshness, quotesFreshness } from "../freshness";
 import { distributionHistory, forwardDividendBasis, forwardDividendMayHaveLapsed, lapsedDividend, noCurrentDividend, TRAILING_DIVIDEND_BASIS, type DistributionHistory, type DividendLapse } from "../../utils/forward-dividend";
 import { declaredDividends } from "../../utils/declared-dividends";
 import { historyTrailingDividendYield, measuresTrailingYield } from "../../market-data/quotes/live-valuation";
-import { notTheCoinNote } from "./crypto-hints";
 import { loadOfferingFilings, loadStatementFilings, resultsReleaseText, statementPeriodText, type StatementFilingsReport } from "../statement-filings";
 import type { BankFiguresPayload } from "../../api-client/bank-figures";
 import { bankSection } from "../bank-section";
-import type { FundBondFacts } from "../../api-client/fund-facts";
-import { bondFigures, fetchFundBondFacts, NOT_SEC_YIELD } from "../../market-data/bond-funds";
+import type { FundBondFacts, FundFactsPayload } from "../../api-client/fund-facts";
+import { bondFigures, NOT_SEC_YIELD } from "../../market-data/bond-funds";
+import { readFundFacts } from "../../market-data/fund-facts";
 import { taxEquivalentLines, type TaxEquivalentAnalysis } from "../../market-data/tax-equivalent";
 import { isRoundTheClockCoin } from "../../utils/crypto-pair";
 import { coinNewsFallbackNotice } from "../../sources/gloomberb-cloud/news";
@@ -667,21 +667,23 @@ function isYieldMetric(label: string): boolean {
 }
 
 /**
- * A US-listed fund's bond facts for the yield lines; null for any other
- * listing, and when they cannot be read, which leaves the yield as it was.
+ * A US-listed fund's facts for the report: the bond figures its yield lines
+ * read, and whether `fn ETF` has figures to point to. Null for any other
+ * listing, and when they cannot be read, which leaves the yield as it was
+ * and points nowhere.
  */
-export async function loadReportBondFacts(
+export async function loadReportFundFacts(
   symbol: string,
   exchange: string | undefined,
   financials: Pick<TickerFinancials, "quote" | "quoteMetadata">,
   tickerFile: TickerRecord | null = null,
-  load: (symbol: string) => Promise<FundBondFacts | null> = fetchFundBondFacts,
-): Promise<FundBondFacts | null> {
+  load: (symbol: string) => Promise<FundFactsPayload> = (ticker) => readFundFacts(ticker),
+): Promise<FundFactsPayload | null> {
   if (resolveTickerInstrumentKind(tickerFile, financials) !== "fund" || (exchange && !isUsListingExchange(exchange))) return null;
   try {
     return await load(symbol);
   } catch (error) {
-    logFailure("cli.commands-ticker", "Read bond fund facts failed")(error);
+    logFailure("cli.commands-ticker", "Read fund facts failed")(error);
     return null;
   }
 }
@@ -712,7 +714,8 @@ function fundamentalsMetrics(
     { label: "P/E (TTM)", ...multipleFigure(priceEarningsOnEarnings(fundamentals?.trailingPE, fundamentals?.eps)) },
     { label: "Forward P/E", ...multipleFigure(priceEarningsOnEarnings(fundamentals?.forwardPE, fundamentals?.forwardEps)) },
     { label: "PEG", ...multipleFigure(fundamentals?.pegRatio) },
-    // The flows and EPS are one trailing-twelve-month block, the same twelve months for each line.
+    // EPS (TTM) is the last four filed quarters' (filed-trailing-eps), so its twelve months can end before those of
+    // the flows below, Gloom Cloud's trailing block; Gloom Cloud's EPS standing in is noted (trailingEpsSourceNote).
     { label: "EPS (TTM)", ...reportedMoney(fundamentals?.eps, fundamentals?.epsCurrency?.trim() || reportingCurrency, true, codes) },
     {
       label: dividendYieldLabel(fundamentals?.dividendYieldBasis, bond),
@@ -797,6 +800,7 @@ function fundamentalsNotes(
     : undefined;
   const conversion = [...TRAILING_MONEY_METRICS].some(shown) ? ttmConversionNote(fundamentals) : undefined;
   const eps = shown("EPS (TTM)") ? epsConversionNote(fundamentals) : undefined;
+  const epsSource = trailingEpsSourceNote(fundamentals, { eps: shown("EPS (TTM)"), pe: shown("P/E (TTM)") });
   const priceEarnings = metrics.some((metric) => metric.label === "P/E (TTM)" && typeof metric.value === "number")
     ? convertedPriceEarningsNote(fundamentals, quoteCurrency)
     : undefined;
@@ -804,7 +808,9 @@ function fundamentalsNotes(
   const enterpriseValue = shown("Enterprise Value")
     ? enterpriseValueReconciliationNote(fundamentals) ?? computedEnterpriseValueNote(fundamentals)
     : undefined;
-  return [shareBasis, enterpriseValue, conversion, eps, priceEarnings].filter((note): note is string => !!note);
+  // A cap Gloom Cloud withheld says why, as RV and EQS do.
+  const withheld = withheldMarketCap(fundamentals)?.note;
+  return [withheld, shareBasis, enterpriseValue, conversion, eps, epsSource, priceEarnings].filter((note): note is string => !!note);
 }
 
 // The share count is the market cap's basis: the cap is the count times the price, or a note says why not.
@@ -814,8 +820,10 @@ type FundamentalsReportData = TickerFinancials & {
   symbol: string;
   exchange?: string;
   distributions?: DividendDistributions | null;
-  /** A bond fund's SEC yield, yield to worst and duration (loadReportBondFacts). */
+  /** A bond fund's SEC yield, yield to worst and duration (loadReportFundFacts). */
   bondFund?: FundBondFacts | null;
+  /** A US-listed fund's facts (loadReportFundFacts): the note points to `fn ETF` only when they cover it. */
+  fundFacts?: FundFactsPayload | null;
   /** `fundamentals --tax-rate`: the tax-equivalent yield and muni/Treasury ratio. */
   taxEquivalent?: TaxEquivalentAnalysis | null;
   /** The filings behind the latest statements, and a newer quarter's results release. */
@@ -839,20 +847,25 @@ function statementFilingsNotes(report: StatementFilingsReport | null | undefined
 }
 
 /**
- * Where a fund's facts are: for a US listing, the ETF function (fee, NAV,
- * premium, net assets); a fund listed elsewhere has none yet. Only for a
- * fund: a stock's report says nothing of it.
+ * Where a fund's facts are: for a US listing, the ETF function, naming the
+ * figures it has (fee, NAV, premium, net assets), and only when it has some:
+ * a fund it has none for, or whose facts could not be read, gets no pointer
+ * to a pane that would only say why. A fund listed elsewhere has none yet.
+ * Only for a fund: a stock's report says nothing of it.
  */
 function fundFactsNote(
   symbol: string,
   exchange: string | undefined,
   financials: Pick<TickerFinancials, "quote" | "quoteMetadata">,
   tickerFile: TickerRecord | null = null,
+  facts: FundFactsPayload | null = null,
 ): string | null {
   if (resolveTickerInstrumentKind(tickerFile, financials) !== "fund") return null;
-  return !exchange || isUsListingExchange(exchange)
-    ? `Fund facts (fee, NAV, premium, net assets): fn ETF ${symbol}.`
-    : US_FUND_FACTS_ONLY;
+  if (exchange && !isUsListingExchange(exchange)) return US_FUND_FACTS_ONLY;
+  if (!facts?.covered) return null;
+  const figures = [facts.expenseRatio && "fee", facts.nav && "NAV", facts.premiumDiscount && "premium", facts.netAssets && "net assets"]
+    .filter((figure): figure is string => !!figure);
+  return `Fund facts${figures.length ? ` (${figures.join(", ")})` : ""}: fn ETF ${symbol}.`;
 }
 
 /**
@@ -947,7 +960,7 @@ export function renderFundamentalsReport(
   const before = lines.length;
   const metrics = fundamentalsReportMetrics(financials, view);
   appendMetricSection(lines, view === "valuation" ? "Valuation" : "Fundamentals", metricLines(metrics));
-  const fund = fundFactsNote(symbol, financials.exchange || quote?.exchangeName, financials);
+  const fund = fundFactsNote(symbol, financials.exchange || quote?.exchangeName, financials, null, financials.fundFacts);
   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(atRegularSessionPrice(financials), metrics, quote?.currency)) lines.push(cliStyles.muted(note));
@@ -987,7 +1000,8 @@ export function fundamentalsReportTables(
   freshness: ReportFreshness,
 ): CliReportTables {
   const metrics = fundamentalsReportMetrics(financials, view);
-  const fund = fundFactsNote(financials.quote?.symbol ?? financials.symbol, financials.exchange || financials.quote?.exchangeName, financials);
+  const fund = fundFactsNote(financials.quote?.symbol ?? financials.symbol, financials.exchange || financials.quote?.exchangeName, financials, null,
+    financials.fundFacts);
   const tables = [exportEntriesTable(
     view === "valuation" ? "Valuation" : "Fundamentals",
     metrics.map((metric) => ({ label: metric.label, value: metric.value, formatted: metric.text, unit: metric.unit })),
@@ -1064,6 +1078,7 @@ export async function buildTickerReport({
   distributions = null,
   statementFilings = null,
   bondFund = null,
+  fundFacts = null,
   memberships,
   offerings = [],
 }: {
@@ -1074,8 +1089,10 @@ export async function buildTickerReport({
   statementFilings?: StatementFilingsReport | null;
   /** The company's latest offering prospectuses (424B5, 424B4); those after the latest balance sheet get a note. */
   offerings?: readonly OfferingFiling[];
-  /** A bond fund's SEC yield, yield to worst and duration (loadReportBondFacts). */
+  /** A bond fund's SEC yield, yield to worst and duration (loadReportFundFacts). */
   bondFund?: FundBondFacts | null;
+  /** A US-listed fund's facts (loadReportFundFacts): the report points to `fn ETF` only when they cover it. */
+  fundFacts?: FundFactsPayload | null;
   /** The distributions a dividend yield is read with (loadDividendDistributions). */
   distributions?: DividendDistributions | null;
   /** The exchange the command named, as a canonical code. */
@@ -1091,7 +1108,7 @@ export async function buildTickerReport({
   notes?: string;
   /** Why there is no quote, when a source said; "Quote unavailable." otherwise. */
   quoteNote?: string;
-  /** "CAR = Avis Budget Group, NASDAQ (also XETRA, ASX)", for a bare symbol several companies list. */
+  /** "CAR = Avis Budget Group, NASDAQ (different companies on XETRA, ASX)", for a bare symbol several companies list. */
   listingNote?: string;
   recentNews?: NewsArticle[];
   recentSecFilings?: SecFilingItem[];
@@ -1254,7 +1271,8 @@ export async function buildTickerReport({
   if (lines.length > beforeFundamentals) for (const note of conversionNotes(toBase, convertedCurrencies, rates)) 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);
+    quote?.tradingExchangeName || listingExchange || quote?.listingExchangeName || quote?.exchangeName || tickerFile?.metadata.exchange, financials, tickerFile,
+    fundFacts);
   if (fund) lines.push(...lines.length === beforeFundamentals ? [""] : [], cliStyles.muted(fund));
 
   if (capitalization?.provenance.kind === "fundamentals") {
@@ -1535,10 +1553,11 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
     // The yield's distributions, read beside the rest when a trailing yield, a forward basis or its lapse needs them; they never fail the report.
     const distributions = loadDividendDistributions(dataProvider, { symbol: requestSymbol, exchange }, resolvedFinancials,
       { declared: !dependencies.printResult });
-    // A bond fund's SEC yield, yield to worst and duration, beside its distribution yield.
-    const bondFund = loadReportBondFacts(requestSymbol,
+    // A fund's facts: its bond figures beside its distribution yield, and whether fn ETF has any to point to.
+    const fundFacts = loadReportFundFacts(requestSymbol,
       quote?.tradingExchangeName || exchange || quote?.listingExchangeName || quote?.exchangeName || tickerFile?.metadata.exchange,
       resolvedFinancials, tickerFile);
+    const bondFund = fundFacts.then((facts) => facts?.bond ?? null);
     const statementFilings = loadStatementFilings(statementSources, { symbol: requestSymbol, exchange }, {
       quarter: latestFinancialPeriod(resolvedFinancials.quarterlyStatements, (row) => row.date),
       annual: latestFinancialPeriod(resolvedFinancials.annualStatements, (row) => row.date),
@@ -1589,17 +1608,18 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
     // The quote is the feed in this report; without one, the fundamentals date it.
     const freshness = quote ? quotesFreshness([quote]) : fundamentalsFreshness(resolvedFinancials);
     const quoteNote = quote ? undefined : await quoteUnavailableNote(dataProvider, requestSymbol, exchange);
-    const [choiceNote] = await listingChoiceNotes(listing, { store, dataProvider }, quote, venues);
-    // A bare coin ticker read as a fund says where the coin is, as `quote` does; a named listing was meant.
-    const coinNote = listing.exchange ? null
-      : notTheCoinNote(listing.symbol, quote ?? (tickerFile ? { name: tickerFile.metadata.name, instrumentType: tickerFile.metadata.assetCategory } : null));
-    const listingNote = [choiceNote, coinNote].filter((note): note is string => !!note).join("\n") || undefined;
+    // A bare coin ticker read as another listing says where the coin is, as `quote` does: from the quote, else from the saved listing.
+    const choiceNotes = [
+      ...await listingChoiceNotes(listing, { store, dataProvider }, quote, venues),
+      ...quote || !tickerFile ? [] : coinListingNotes(listing, { name: tickerFile.metadata.name, instrumentType: tickerFile.metadata.assetCategory }),
+    ];
+    const listingNote = choiceNotes.join("\n") || undefined;
     const memberships = await membershipsLoad;
     // A converted TTM block at the rate the rest of the report converts at, the one `fx` reports.
     const shownFinancials = await atReportTtmRate(resolvedFinancials, toBase);
     if (dependencies.printResult) {
       const newsNote = recentNews[0]?.searchedFor ? coinNewsFallbackNotice(requestSymbol, recentNews[0].searchedFor) : null;
-      const warnings = [choiceNote, coinNote, quoteNote, newsNote].filter((note): note is string => !!note);
+      const warnings = [...choiceNotes, quoteNote, newsNote].filter((note): note is string => !!note);
       dependencies.printResult({
         freshness,
         warnings: warnings.length > 0 ? warnings : undefined,
@@ -1643,6 +1663,7 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
         distributions: await distributions,
         statementFilings: await statementFilings,
         bondFund: await bondFund,
+        fundFacts: await fundFacts,
         memberships,
         offerings: await offerings,
     }));

package/src/cli/company-name-hint.ts

@@ -0,0 +1,41 @@
+import type { CliListing } from "./listing-arg";
+import { companyNameSuggestion, isUnsettledNoProvider, type ListingDeps } from "./listing-arg";
+import { describeSuggestion } from "./listing-suggestion";
+import { isNotATickerMessage, withListingSuggestion } from "./not-a-ticker";
+
+type SearchDeps = Pick<ListingDeps, "dataProvider">;
+
+/**
+ * "Not a ticker: PALANTIR TECHNOLOGIES. Did you mean PLTR (Palantir
+ * Technologies Inc.)?" for words typed where one ticker goes, with the
+ * company search names for them. Without one the sentence ends at the
+ * symbol, and the error printer adds the search to try.
+ */
+export async function notATickerWords(typed: string, deps: SearchDeps): Promise<string> {
+  const symbol = typed.trim().replace(/^\$/, "").toUpperCase();
+  const message = `Not a ticker: ${symbol}.`;
+  const suggestion = await companyNameSuggestion(typed, deps);
+  return suggestion ? withListingSuggestion(message, describeSuggestion(suggestion)) : message;
+}
+
+/**
+ * Why a command stops on a listing whose own quote failed with `error`, when
+ * the word typed for it is no ticker, or null when it is not known to be: the
+ * source's "Not a ticker: PALANTIR.", and a word a source could not answer for
+ * (a timeout, a rate limit) that search resolves to a company all the same, as
+ * `quote` says it of a name. Both name the company beside it. A real ticker a
+ * source failed to quote is not stopped here: it is not a company's name.
+ */
+export async function notATickerStop(
+  error: unknown,
+  listing: Pick<CliListing, "symbol" | "exchange" | "typed">,
+  deps: SearchDeps,
+): Promise<string | null> {
+  const message = error instanceof Error ? error.message : null;
+  const notATicker = isNotATickerMessage(message);
+  if (!notATicker && !isUnsettledNoProvider(error)) return null;
+  if (listing.exchange || !listing.typed) return notATicker ? message : null;
+  const suggestion = await companyNameSuggestion(listing.typed, deps);
+  if (!suggestion) return notATicker ? message : null;
+  return withListingSuggestion(notATicker ? message! : `Not a ticker: ${listing.symbol}.`, describeSuggestion(suggestion));
+}

package/src/cli/earnings-calendar.ts

@@ -43,7 +43,7 @@ export async function noListingCalendarNote(
 }
 
 /**
- * "SAN = Banco Santander, NYSE (also EPA, LSE)" for a bare symbol whose
+ * "SAN = Banco Santander, NYSE (different companies on EPA, LSE)" for a bare symbol whose
  * calendar date is its US line's, when several companies list the symbol:
  * the event names the company the date is for.
  */

package/src/cli/errors.ts

@@ -10,6 +10,8 @@ import { DATA_SERVICE_UNREACHABLE_MESSAGE, isNetworkFailure } from "../utils/net
 const USAGE_PREFIX = "Usage: ";
 /** The code of every error a command fails with: bad input, nothing found, an option it does not take. */
 export const CLI_ERROR_CODE = "cli_error";
+/** The code of a command that ran, and the data service has nothing for what it asked. */
+export const NO_DATA_CODE = "no_data";
 /** The code of a command whose requests never reached the data service. */
 export const SERVICE_UNREACHABLE_CODE = "service_unreachable";
 
@@ -61,6 +63,12 @@ export function failWithFields(message: string, code: string, fields: Record<str
   throw new CliFailure(message, undefined, code, undefined, fields);
 }
 
+/** Fails as `error` says: its code, message, details and whether to retry, and any field it carries beside them. */
+export function failWithError(error: CliErrorObject): never {
+  const { code, message, details, retryable, ...fields } = error;
+  throw new CliFailure(message, details, code, retryable, Object.keys(fields).length > 0 ? fields : undefined);
+}
+
 /** Fails with what asking again shortly may get past (a busy service): `--json` marks it `retryable`. */
 export function failRetryable(message: string, code: string): never {
   throw new CliFailure(message, undefined, code, true);

package/src/cli/glossary.ts

@@ -714,7 +714,30 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
   },
   {
     term: "Other reportables", aliases: ["other reportable", "other reportable traders"], functions: ["COT"], shown: ["Other Reportables"],
-    definition: "The disaggregated report's large traders that fit none of its other classes, such as proprietary traders and family offices.",
+    definition: "The disaggregated and TFF reports' large traders that fit none of their other classes, such as proprietary traders and family offices.",
+  },
+  // The Traders in Financial Futures report's classes, and the options it can count.
+  {
+    term: "Traders in Financial Futures", short: "TFF", aliases: ["tff report", "financial futures report", "financial traders report"], functions: ["COT"], shown: ["Financial (TFF)"],
+    definition: "The CFTC's report on financial futures, such as rates, currencies, stock indexes and VIX. "
+      + "It splits large traders into dealers, asset managers, leveraged funds and other reportables.",
+  },
+  {
+    term: "Leveraged funds", aliases: ["leveraged fund", "leveraged money", "lev funds"], functions: ["COT"], shown: ["Leveraged Funds"],
+    definition: "The TFF report's hedge funds, CTAs and other money managers trading for clients or with borrowed money: the speculators most watched in rates, currencies and indexes.",
+  },
+  {
+    term: "Asset manager/institutional", aliases: ["asset manager", "asset managers", "institutional", "real money"], functions: ["COT"], shown: ["Asset Manager/Institutional"],
+    definition: "The TFF report's pension funds, insurers, mutual funds and endowments, investing for the long run; usually net long stock index futures.",
+  },
+  {
+    term: "Dealer/intermediary", aliases: ["dealer intermediary", "intermediary", "intermediaries"], functions: ["COT"], shown: ["Dealer/Intermediary"],
+    definition: "The TFF report's banks and dealers on the sell side, taking the other side of their clients' trades and hedging it.",
+  },
+  {
+    term: "Futures and options combined", aliases: ["futures + options", "futures and options", "combined report", "combined positions"], functions: ["COT"], shown: ["Futures + options"],
+    definition: "A COT report that adds each group's options to its futures, delta-adjusted: an option counts as the futures it moves like. "
+      + "Futures only, the default, counts futures alone.",
   },
   // Futures basis and curve shape (CTM, FUT, PERP).
   {
@@ -800,7 +823,7 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     term: "Risk reversal", short: "RR", aliases: ["25d risk reversal", "25-delta risk reversal", "25 delta risk reversal", "rr25", "risk reversals"],
     functions: ["OVDV"], shown: ["RR"],
     definition: "The 25-delta call's implied volatility minus the 25-delta put's, in vol points, for one expiry. Negative means puts cost more than calls "
-      + "as far from the forward (downside protection is bid), positive that upside calls are. OVDV signs it call minus put.",
+      + "as far from the forward (downside protection is bid), positive that upside calls are. OVDV, VCA and HIVG's rr25d all sign it call minus put.",
   },
   {
     term: "Butterfly", short: "BF", aliases: ["25d butterfly", "25-delta butterfly", "25 delta butterfly", "bf25", "smile curvature", "fly"],