@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/cli/commands/market.ts

@@ -3,6 +3,7 @@ import type { CliCommandDef } from "../../types/plugin";
 import { TIME_RANGES, type TimeRange } from "../../time-series/range";
 import { yearToDateStartIndex } from "../../market-data/market/year-to-date";
 import type { EarningsEvent, QuoteBatchResult, QuoteSubscriptionTarget, SecFilingItem } from "../../types/data-provider";
+import { companyDataNotes, type CompanyFrom } from "../../types/company-from";
 import type { NewsArticle, NewsFeed, NewsQuery } from "../../news/types";
 import type {
   AnalystResearchData,
@@ -12,7 +13,7 @@ import type {
   Quote,
   TickerFinancials,
 } from "../../types/financials";
-import { currencyPriceMinDigits, formatMarketPrice, formatMarketPriceWithCurrency, quoteFormatOptions, resolveAssetDisplayKind, withCurrencyMinorDigits } from "../../market-data/market/format";
+import { currencyPriceMinDigits, formatMarketPrice, formatMarketPriceWithCurrency, penceFigure, quoteFormatOptions, resolveAssetDisplayKind, withCurrencyMinorDigits } from "../../market-data/market/format";
 import { INDEX_POINTS_EXPORT_UNIT, isIndexLevel, reportedQuoteVolume } from "../../market-data/market/index-level";
 import { changeBasisJson, changeBasisLabel, changeBasisNote, quoteChangeBasis, quotePreviousCloseDate, quoteSettleText } from "../../market-data/market/change-basis";
 import {
@@ -41,6 +42,7 @@ import {
 import { cliArrow, cliStyles, colorBySign, renderSection, renderStats } from "../../utils/cli-output";
 import { filledPeriodsNote, stalePeriodNote, statementHistoryNotes } from "../../utils/financial-statements";
 import { formatPerShareNumber } from "../../utils/reported-money";
+import { isCurrencyPairListing } from "../../utils/fx-market-hours";
 import {
   analystTargetCurrency,
   formatAnalystPrice,
@@ -58,7 +60,7 @@ import {
 } from "../../market-data/options-alternatives";
 import {
   atReportTtmRate, cliFuturesContract, futuresContractMetrics, exportedDividendFundamentals, fundamentalsReportTables, loadDividendDistributions,
-  loadReportBondFacts, renderFundamentalsReport, writesCurrencyCodes,
+  loadReportFundFacts, renderFundamentalsReport, writesCurrencyCodes,
 } from "./ticker";
 import { createBaseConverter } from "../base-converter";
 import { loadStatementFilings } from "../statement-filings";
@@ -75,6 +77,7 @@ import {
   loadOptionModelInputs,
   loadOptionsChainOpenInterest,
   chainCoinCurrency,
+  chainHasFilledIv,
   formatCoinPremiumCell,
   formatOptionDeltaCell,
   formatOptionDollarCell,
@@ -90,6 +93,7 @@ import {
   optionsBasisFields,
   optionsBasisFootnote,
   parseOptionExpiration,
+  takeExpirationOption,
   valueChainAtModelSpot,
   type OptionsChainBasis,
 } from "./options-chain";
@@ -139,6 +143,7 @@ import {
   historyPriceDecimals,
   historyRows,
   historyUnit,
+  quotedPriceDivisor,
   historyVolume,
   historyVolumeText,
   type HistoryRow,
@@ -153,7 +158,7 @@ import {
   symbolListNotes,
   type HistoryListRow,
 } from "../history-export";
-import { isCliFailure } from "../errors";
+import { fail, isCliFailure, NO_DATA_CODE } from "../errors";
 import { mapWithConcurrency } from "../../utils/concurrency";
 import { MISSING_VOLUME_TEXT } from "../../utils/price-history-integrity";
 import { CRYPTO_BOARD_HINT, quoteNotes } from "./crypto-hints";
@@ -161,6 +166,7 @@ import { bareFuturesCode, futuresBoardContract } from "../../market-data/futures
 import { commodityNamedIn, commoditySearchName } from "../../market-data/commodity-names";
 import { newsEmptyMessage } from "./news-hints";
 import {
+  closestStoriesReason,
   commodityNewsRoute,
   commonWordCandidate,
   METALS_NEWS_TOPIC,
@@ -175,6 +181,7 @@ import {
   noMetalStoriesMessage,
   noStoriesMessage,
   quotedSearchCommand,
+  searchClosestNewsStories,
   searchNewsStories,
   wordMeansMore,
 } from "./news-search";
@@ -185,7 +192,7 @@ import { exportedFundamentals } from "../../utils/price-earnings";
 import { fundamentalsFreshness, fxPairFreshness, quotesFreshness, rowsFreshness, valuationFreshness } from "../freshness";
 import { fxRateNotes } from "../../plugins/builtin/shared/fx-rate-freshness";
 import { quoteBarNotes } from "../../market-data/quotes/intraday-bar";
-import { depositaryPairText, isReceiptSide, listingDepositaryPair } from "../../market-data/depositary-pair";
+import { cedearRatioText, depositaryPairText, isReceiptSide, listingCedearRatio, listingDepositaryPair } from "../../market-data/depositary-pair";
 import { isPesoDollarPair, loadPesoDollarRates, pesoDollarRateLines, pesoDollarRatesJson } from "../peso-dollar-rates";
 import { atRegularSessionPrice, regularSessionValuationPrice } from "../../market-data/quotes/regular-session-valuation";
 import { viewMarketCapitalization } from "../../utils/market-capitalization";
@@ -195,6 +202,7 @@ import {
   cloudNewsFreshness,
   cloudRealtimeAccess,
   REPORTED_DATA,
+  SEC_FILING_ROWS,
   SEC_FILINGS,
 } from "../../plugins/builtin/shared/report-freshness";
 import {
@@ -215,6 +223,7 @@ import {
   type ResolvedEarningsEvent,
 } from "../../plugins/builtin/shared/earnings-calendar";
 import {
+  coinListingNotes,
   EXCHANGE_OPTION,
   listingHeading,
   listingIdentity,
@@ -237,7 +246,7 @@ import {
   type ListingIdentity,
 } from "../listing-arg";
 import { bareListingNote, listingFateNotes, noLongerTradingNote, tradingListing } from "../../tickers/listing-fate";
-import { isYieldIndexSymbol } from "../index-roots";
+import { isYieldIndexSymbol } from "../../tickers/index-roots";
 import {
   analyzeTaxEquivalent, distributionBasis, loadTreasuryTenors, parseTaxRates, TAX_RATE_HELP_OPTIONS, taxEquivalentJson, type TaxRates,
 } from "../../market-data/tax-equivalent";
@@ -303,6 +312,7 @@ import {
   unvaluedHoldersNote,
 } from "../../plugins/builtin/holders/report-rows";
 import { fetchBeneficialOwners } from "../../plugins/builtin/holders/beneficial-client";
+import { fundHoldersAnswer } from "../../plugins/builtin/holders/fund-holders";
 import { centralBankEventsMessage } from "../central-bank-events";
 import { classSharesAsOf, classSharesToday } from "../../plugins/builtin/holders/client";
 import {
@@ -465,7 +475,8 @@ const QUOTE_LEAD_COLUMNS = [
       row.error && !row.price
         // A typo is not an outage: say what is wrong with the symbol itself.
         ? isNotATickerMessage(row.error) ? cliStyles.warning("not a ticker") : cliStyles.danger("unavailable")
-        : yieldLevelCell(row.price, row)
+        // A London line adds the pence it trades in, as the exchange and RNS write it, muted as a table cell's note is: £6.308 630.8p.
+        : `${yieldLevelCell(row.price, row)}${row.pence ? ` ${cliStyles.muted(row.pence)}` : ""}`
     ),
   },
   {
@@ -729,10 +740,12 @@ function quoteRows(results: QuoteCliRecord[], now = Date.now()) {
     // A price in cents says what it is per, as the contract terms word it: 314.95¢/lb.
     const per = display.price != null ? futuresPricePer(result.futuresContract, quote?.currency) : "";
     const previousClose = display.price != null && display.change != null ? display.price - display.change : quote?.previousClose;
+    const last = price(display.price);
     return {
       symbol: result.target.symbol,
       name: quote?.name || result.listing?.name || "",
-      price: `${price(display.price)}${per}`,
+      price: `${last}${per}`,
+      pence: penceFigure(display.price, quote, /\.(\d+)/.exec(last)?.[1]?.length ?? 0),
       rawPrice: display.price,
       priceBasis: quote?.priceBasis ?? null,
       instrumentType: quote?.instrumentType ?? null,
@@ -904,7 +917,7 @@ function corporateActionRows(data: CorporateActionsData) {
     ...declaredDividends(data).map((event) => ({
       type: "dividend",
       date: event.exDate,
-      detail: `declared ${currency ? formatDistributionAmount(event.amount, currency) : cleanDecimal(event.amount)}`
+      detail: `declared ${event.special ? "special " : ""}${currency ? formatDistributionAmount(event.amount, currency) : cleanDecimal(event.amount)}`
         + (event.payDate ? `, payable ${event.payDate}` : ""),
     })),
     ...data.splits.map((event) => ({
@@ -1096,13 +1109,15 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
         const quiet = ended ? null : noPrintsTodayText(row.quote, now);
         return [ended ?? (quiet ? `${label}: ${quiet}` : []), quoteBarNotes(label, row.quote, now)].flat();
       }),
-      // A receipt and its home line each say the ratio, as `ticker` does.
+      // A receipt and its home line each say the ratio, as `ticker` does; a CEDEAR names itself in its own.
       ...data.flatMap((row) => {
+        const cedear = listingCedearRatio({ quote: row.quote });
+        if (cedear) return [`${cedearRatioText(cedear)}.`];
         const pair = listingDepositaryPair({ quote: row.quote });
         return pair ? [`${row.target.symbol}: ${depositaryPairText(pair, isReceiptSide({ quote: row.quote }))}.`] : [];
       }),
       // A cell shows only "unavailable", and an exported row only its status, so stderr names each failure; the JSON rows carry each reason.
-      ...ctx.cliOptions.format !== "json" ? quoteNotes(data, { exchange }) : [],
+      ...ctx.cliOptions.format !== "json" ? quoteNotes(data) : [],
     ];
     const columns = commandName === "compare" ? compareColumns() : quoteColumns();
     const basisNotes = changeBasisNotes(data, now);
@@ -1117,7 +1132,8 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
       // close does not read as a contradiction of DGS10 or GC for the same day.
       // Dated by the quotes as served, which say whether one is the saved copy.
       freshness: withSavedCopy(
-        quotesFreshness(data.map((row) => row.quote), yieldsOnly ? { schedule: `Cboe close ${CBOE_YIELD_INDEX_CLOSE}` } : undefined),
+        // A table across markets (US and London lines) dates each market's session and says when each opens.
+        quotesFreshness(data.map((row) => row.quote), { datesEachVenue: true, ...yieldsOnly ? { schedule: `Cboe close ${CBOE_YIELD_INDEX_CLOSE}` } : {} }),
         answers.map(({ result }) => result.quote),
       ),
     }, {
@@ -1399,7 +1415,11 @@ async function loadListingHistory(
   };
   // A coin's volume is traded value in its quote currency: said in every row and on the status line.
   const volume = historyVolume(unit, traded);
-  const rows = historyRows(points, resolution, unit.currency, unit.unit, volume);
+  // Spot FX has no exchange to count its trades: a source's 0 is no volume, printed as missing.
+  const pair = quote?.instrumentType === "CURRENCY" || isCurrencyPairListing(symbol, exchange);
+  // A London line's bars were priced in pence: cleaned there, and printed to the pence decimals `quote` shows.
+  const priceDivisor = quotedPriceDivisor(quote);
+  const rows = historyRows(pair ? points.map(({ volume: _volume, ...point }) => point) : points, resolution, unit.currency, unit.unit, volume, priceDivisor);
   // Bars stop arriving on the listing's own trading days, not New York's.
   const venue = quote?.listingExchangeName || exchange || undefined;
   const served = range === "YTD" && !window ? rows.slice(Math.max(0, yearToDateStartIndex(rows.map((row) => row.date), rows[0]?.interval, venue))) : rows;
@@ -1450,7 +1470,7 @@ async function loadListingHistory(
   ].flat();
   return {
     listing, identity, unit, data, resolution, interval, intraday, volume, freshness, notes,
-    decimals: historyPriceDecimals(data, listing.saved?.metadata.assetCategory),
+    decimals: historyPriceDecimals(data, listing.saved?.metadata.assetCategory, priceDivisor),
   };
 }
 
@@ -1720,6 +1740,22 @@ const STATEMENT_COLUMNS: CliResultColumn<ReturnType<typeof financialStatementRow
   { key: "currency", header: "Cur" },
 ];
 
+/** A symbol as typed in capitals (`NEE`, `BP:LSE`, `7203.T`), never a word of a company's name. */
+const TYPED_SYMBOL = /^[A-Z0-9][A-Z0-9.:^=&-]{0,15}$/;
+
+/**
+ * The symbols of a command given several where it takes one: `NEE FSLR` as
+ * two words, or as one (`"NEE FSLR"`, `NEE,FSLR`). One word with spaces is
+ * a list only when every part is a symbol as typed, so a company's name
+ * (`"Bank of America"`) is still searched for. Null for one symbol.
+ */
+export function comparedSymbols(args: readonly string[]): string[] | null {
+  const words = args.flatMap((arg) => arg.split(/[\s,]+/)).filter(Boolean);
+  if (words.length < 2) return null;
+  if (args.length > 1 || args.some((arg) => arg.includes(","))) return words;
+  return words.every((word) => TYPED_SYMBOL.test(word)) ? words : null;
+}
+
 async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1], view: FinancialsView) {
   const args = [...rawArgs];
   const exchangeOption = takeOption(args, "--exchange");
@@ -1744,6 +1780,12 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
   const tabular = ctx.cliOptions.format === "csv" || ctx.cliOptions.format === "ndjson";
   if (sectionFlag && !tabular) ctx.fail("--section picks one table of --csv or --ndjson output.");
   if (sectionFlag && !section?.trim()) ctx.fail("--section needs a section title or number.");
+  // Several symbols are a comparison, which RV draws side by side.
+  const compared = view === "valuation" ? comparedSymbols(args) : null;
+  if (compared) {
+    ctx.fail(`valuation takes one symbol; got ${compared.join(" ")}.`,
+      `To compare their valuations side by side: gloom fn RV ${compared.join(",")}\nUsage: gloom valuation <symbol>`);
+  }
   const raw = requireOneArg(args, `${commandName} <symbol>`, "symbol", ctx);
   const selectTables = (tables: CliReportTables) => {
     try {
@@ -1765,8 +1807,8 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
     // declared distribution it annualizes (not in JSON), and one whose dividend stopped says so; read beside the listing notes.
     const distributions = view === "statements" ? null : loadDividendDistributions(
       market.dataProvider, listing.request, financials, { declared: ctx.cliOptions.format !== "json" });
-    // A bond fund's SEC yield, yield to worst and duration, beside its distribution yield.
-    const bondFund = view === "statements" ? null : loadReportBondFacts(listing.request.symbol,
+    // A fund's facts: its bond figures beside its distribution yield, and whether fn ETF has any to point to.
+    const fundFacts = view === "statements" ? null : loadReportFundFacts(listing.request.symbol,
       financials.quote?.tradingExchangeName || listing.request.exchange || financials.quote?.listingExchangeName || financials.quote?.exchangeName,
       financials, listing.saved);
     const treasury = rates ? loadTreasuryTenors() : null;
@@ -1795,13 +1837,14 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
           loadBankFigures(market.statementSources, listing.request, financials),
         ])
         : [null, { bank: null, note: null }];
-      const bond = await bondFund;
+      const facts = await fundFacts;
+      const bond = facts?.bond ?? null;
       // On the SEC yield when the sponsor publishes one, else the distribution yield the line above shows.
       const taxEquivalent = rates ? analyzeTaxEquivalent({
         symbol: identity.symbol || listing.key, bond, rates, treasury: await treasury,
         distribution: distributionBasis(priced.fundamentals?.dividendYield, priced.fundamentals?.dividendYieldBasis === "trailing" ? "trailing" : "forward"),
       }) : null;
-      const report = { ...data, distributions: await distributions, statementFilings, bank: bank.bank, bankNote: bank.note, bondFund: bond, taxEquivalent,
+      const report = { ...data, distributions: await distributions, statementFilings, bank: bank.bank, bankNote: bank.note, bondFund: bond, fundFacts: facts, taxEquivalent,
         // A base currency other than USD reads every amount with its code, as `ticker` does.
         currencyCodes: writesCurrencyCodes(market.config) };
       ctx.printResult({
@@ -1895,26 +1938,29 @@ const NEWS_COLUMNS = [
 async function printNewsSearch(
   text: string,
   articles: NewsArticle[],
-  { reason, empty, commodity = true, failure, ticker = null }: {
+  { reason, empty, commodity = true, failure, ticker = null, closest = false }: {
     reason?: string;
     empty?: string;
     commodity?: boolean;
     failure?: string;
     /** The listing a coin pair's search stands in for. */
     ticker?: string | null;
+    /** No story has every word: these are the ones with the most. */
+    closest?: boolean;
   },
   ctx: Parameters<CliCommandDef["execute"]>[1],
 ) {
   const searched = failure === undefined;
   const named = searched && commodity && articles.length === 0 && commodityNamedIn(text) !== null;
   const route = named ? await commodityNewsRoute(text) : null;
+  const closestReason = closest && articles.length > 0 ? closestStoriesReason(text) : null;
   ctx.printResult({
     data: articles,
     ...(searched ? {} : { warnings: [`Searching stories for "${text}" failed: ${failure}`] }),
-    metadata: { ticker, search: text, feed: null, ...(route ? { futuresNews: route.command } : {}) },
+    metadata: { ticker, search: text, feed: null, ...(closestReason ? { match: "closest" } : {}), ...(route ? { futuresNews: route.command } : {}) },
     freshness: rowsFreshness(newsRows(articles), cloudNewsFreshness(await cloudRealtimeAccess())),
   }, {
-    heading: newsSearchHeading(text, reason),
+    heading: newsSearchHeading(text, [reason, closestReason].filter(Boolean).join("  ·  ") || undefined),
     rows: newsRows,
     columns: NEWS_COLUMNS,
     empty: named ? noStoriesMessage(text, route) : empty ?? (searched ? noStoriesMessage(text, null) : "No stories to show."),
@@ -1976,7 +2022,8 @@ async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     if (exchangeOption || feed) ctx.fail(`${exchangeOption ? "--exchange" : "--feed"} goes with a symbol, not with text to search stories for.`, "Usage: gloom news <query>");
     const problem = newsSearchTextProblem(text);
     if (problem) ctx.fail(problem);
-    await printNewsSearch(text, await searchNewsStories(text, limit), {}, ctx);
+    const answer = await searchClosestNewsStories(text, limit);
+    await printNewsSearch(text, answer.found, { closest: answer.closest }, ctx);
     return;
   }
   // A metal's future or name is its market's news, not a company's: GOLD in capitals stays Gold.com's.
@@ -2043,7 +2090,8 @@ async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
       return;
     }
     const empty = emptyMessage(false);
-    const read = listing ? listingReadNotes(listing) : [];
+    // A bare coin ticker read as another listing (ETH, the Grayscale fund) says where the coin is, as `quote` does.
+    const read = listing ? [...listingReadNotes(listing), ...coinListingNotes(listing, quote)] : [];
     // A word that is also the company's name ("gold" for Gold.com Inc.) says once which ticker it found and how
     // to search the stories that mention it instead, when those stories are mostly about something else.
     const typed = args[0]?.trim() ?? "";
@@ -2155,7 +2203,7 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
           ...listingMetadata(resolved), ...(form ? { form } : {}),
           ...(page ? { announcementsPage: page.url } : {}),
         },
-        freshness: rowsFreshness(filingRows(filings), { ...SEC_FILINGS, observedKey: "filingDate" }),
+        freshness: rowsFreshness(filingRows(filings), SEC_FILING_ROWS),
         ...(choice.length > 0 ? { warnings: choice } : {}),
       }, {
         heading: listingHeading(resolved),
@@ -2167,7 +2215,7 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         empty: [form ? `No ${form} filings found for ${listingTitle(resolved)}.`
           : identity ? noSecReportsNotice(resolved)
           : `No SEC filings found for ${listingTitle(resolved)}.`, pageLine].filter(Boolean).join("\n"),
-        ...(pageLine ? { footnote: pageLine, exportNotes: [pageLine] } : {}),
+        ...filingsFootnote(pageLine, filings[0]?.companyFrom),
       });
     } catch (error) {
       if (!(error instanceof SecRegistrantMismatchError)) throw error;
@@ -2185,6 +2233,16 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   });
 }
 
+/**
+ * The lines `filings` prints under its rows and CSV writes as notes: an ASX
+ * listing's announcements page, and whose filings a foreign line shows when
+ * they are its company's home line's.
+ */
+function filingsFootnote(pageLine: string | null | undefined, companyFrom: CompanyFrom | undefined): { footnote?: string; exportNotes?: string[] } {
+  const lines = [...(pageLine ? [pageLine] : []), ...companyDataNotes(companyFrom)];
+  return lines.length ? { footnote: lines.join("\n"), exportNotes: lines } : {};
+}
+
 /**
  * `filings` for a company on ASX that files nothing with the SEC: its latest
  * ASX announcements from Gloom Cloud, newest first, under the line saying it
@@ -2355,7 +2413,8 @@ async function printBeneficialOwners(
     heading: `${listingHeading(identity)}${cliStyles.muted(beneficialListFacts(payload, form, rows.length, history).map((fact) => `  ·  ${fact}`).join(""))}`,
     // Text draws each column as the HDS report does; CSV and JSON keep the raw values.
     textColumns: BENEFICIAL_REPORT_COLUMNS.map((column) => ({ ...column, format: column.textFormat ?? column.format })),
-    ...(legend ? { footnote: legend } : {}),
+    // A foreign line's owners read from its company's home line say whose.
+    ...(legend || payload.companyFrom ? { footnote: [legend, ...companyDataNotes(payload.companyFrom)].filter(Boolean).join("\n") } : {}),
     columns: [
       ...BENEFICIAL_REPORT_COLUMNS.map(({ key, header, align }) => ({ key, header, ...(align ? { align } : {}) })),
       { key: "otherPersons", header: "Other persons" },
@@ -2401,14 +2460,20 @@ async function runHolders(
     // --tail counts back from the end of the rows loaded, so it loads at least as many as it asks for.
     const tail = ctx.cliOptions.tail;
     const indexLimit = Math.min(ctx.cliOptions.limit ?? Math.max(tail ?? 0, HOLDERS_DEFAULT_ROWS), HOLDER_ROWS_MAX);
+    const quoted = loadListingQuote(market.dataProvider, listing);
     const [source, quote, form4, index] = await Promise.all([
       loadForListing(
         listing, market, ctx,
         () => market.dataProvider.getHolders(listing.request.symbol, listing.request.exchange),
         (found) => found.holders.length === 0,
         { command: commandName, noun: "holder data" },
-      ),
-      loadListingQuote(market.dataProvider, listing),
+      ).catch(async (error: unknown) => {
+        // A fund has no ownership breakdown: say so, and what reads it, rather than the source's NO_DATA.
+        const fund = await fundHoldersAnswer(listing.symbol, error, await quoted, apiClient);
+        if (fund) fail(fund.message, fund.details.join("\n") || undefined, NO_DATA_CODE);
+        throw error;
+      }),
+      quoted,
       insiderCommand ? loadForm4Report(market, listing) : null,
       indexTicker ? loadIndexedHolders(indexTicker, indexLimit).catch(logFailure("cli.commands-market", "Read the 13F holder index failed", null)) : null,
     ]);
@@ -2450,7 +2515,7 @@ async function runHolders(
     const columns = holderReportColumns(shownRows, valueCurrency);
     // Dated as HDS dates it: by the list's as-of; an insider report of Form 4 filings alone as INS dates it, by the newest.
     const freshness = form4Only
-      ? rowsFreshness(form4?.newestFiled ? [{ filingDate: form4.newestFiled }] : [], { ...SEC_FILINGS, basis: "Form 4 filings", observedKey: "filingDate" })
+      ? rowsFreshness(form4?.newestFiled ? [{ filingDate: form4.newestFiled }] : [], { ...SEC_FILING_ROWS, basis: "Form 4 filings" })
       : rowsFreshness(shownRows, { ...SEC_FILINGS, basis: "13F filings" }, { asOf: data.asOf ?? null });
     // Named as fn HDS takes it, so the closing notes point to the same listing.
     const requested = exchangeOption && !raw.includes(":") ? `${raw}:${exchangeOption.toUpperCase()}` : raw;
@@ -2520,6 +2585,8 @@ async function runHolders(
         insiderCommand ? insiderSummary(data, listing, identity, form4) : "",
       ].filter(Boolean).join("\n"),
       empty: `No holders reported for ${listingTitle(identity)}.`,
+      // Holders read from the company's home line say whose; the SEC index's are the listing's own.
+      ...(!indexed && data.companyFrom ? { footnote: companyDataNotes(data.companyFrom).join("\n") } : {}),
     });
   });
 }
@@ -2616,12 +2683,13 @@ async function runEvents(rawArgs: string[], ctx: Parameters<CliCommandDef["execu
 async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
   const leapsOptions = takeLeapsOptions(args);
-  const expiration = takeOption(args, "--expiration");
+  const expirationOption = takeExpirationOption(args);
+  const { value: expiration, flag: expirationFlag } = expirationOption;
+  if (expirationOption.both) ctx.fail("--expiry is --expiration; give one of them.", `Usage: gloom ${OPTIONS_USAGE}`);
   const exchangeOption = takeOption(args, "--exchange");
   if (leapsOptions.leaps) {
     // With --leaps, --expiration is a window of one expiry.
-    const expirationGiven = expiration != null || rawArgs.some((arg) => arg === "--expiration" || arg.startsWith("--expiration="));
-    const criteria = parseLeapsCriteria({ ...leapsOptions.raw, ...expirationGiven ? { "--expiration": expiration ?? "" } : {} });
+    const criteria = parseLeapsCriteria({ ...leapsOptions.raw, ...expirationOption.given ? { "--expiration": expiration ?? "" } : {} });
     if ("error" in criteria) ctx.fail(criteria.error, `Usage: gloom ${LEAPS_USAGE}`);
     const entries = normalizeSymbols(args);
     if (entries.length === 0) ctx.fail("--leaps needs at least one symbol.", `Usage: gloom ${LEAPS_USAGE}`);
@@ -2633,11 +2701,11 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   }
   const raw = requireOneArg(args, OPTIONS_USAGE, "symbol", ctx);
   let expirationDate: number | undefined;
-  if (expiration != null || rawArgs.includes("--expiration")) {
+  if (expirationOption.given) {
     const parsed = expiration == null ? null : parseOptionExpiration(expiration);
     if (parsed == null) {
       ctx.fail(
-        expiration == null ? "--expiration needs a date." : `Invalid --expiration "${expiration}".`,
+        expiration == null ? `${expirationFlag} needs a date.` : `Invalid ${expirationFlag} "${expiration}".`,
         `Use ${OPTION_EXPIRATION_FORMAT}.${expiration == null ? "" : expirationHint(expiration)}\nUsage: gloom ${OPTIONS_USAGE}`,
       );
     }
@@ -2669,7 +2737,7 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       const listed = await readChain(undefined).then(({ chain }) => chain.expirationDates,
         logFailure("cli-market", "Read available option expirations failed", []));
       ctx.fail(`expiry ${expiryIsoDate(expirationDate)} for ${listing.key} `
-        + expiredExpiryText(expirationDate, listed, now, { exchange: expiryVenue, flag: "expiration" }),
+        + expiredExpiryText(expirationDate, listed, now, { exchange: expiryVenue, flag: expirationFlag.slice(2) }),
       `Run gloom options ${listing.key} to list the live expiries.`);
     }
     const { result, chain: read } = await loadForListing(listing, market, ctx, async () => {
@@ -2711,7 +2779,7 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     // IV and delta are valued at one spot and instant, named under the table and on every exported row.
     const { chain, spot: modelSpot } = valueChainAtModelSpot(loaded, inputs, Date.now(), identity.exchange);
     const basis: OptionsChainBasis = { spot: modelSpot, dividendYield: inputs.dividendYield ?? null,
-      openInterest: await loadOptionsChainOpenInterest(symbol, chain) };
+      openInterest: await loadOptionsChainOpenInterest(symbol, chain), ivFilled: chainHasFilledIv(chain) };
     const basisFields = optionsBasisFields(basis);
     const currency = [...chain.calls, ...chain.puts].find((contract) => contract.currency?.trim())?.currency.trim().toUpperCase()
       ?? quote?.currency ?? null;
@@ -2783,6 +2851,7 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         { key: "bid", header: "Bid" },
         { key: "ask", header: "Ask" },
         { key: "iv", header: "IV (annualized decimal)" },
+        { key: "ivSource", header: "IV source" },
         { key: "delta", header: "Delta (decimal)" },
         { key: "volume", header: "Vol" },
         { key: "openInterest", header: "OI" },
@@ -2810,7 +2879,7 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         { key: "coinAsk", header: `Ask ${coin}`, align: "right", format: formatCoinPremiumCell },
         { key: "coinMark", header: `Mark ${coin}`, align: "right", format: formatCoinPremiumCell },
         { key: "mark", header: "Mark $", align: "right", format: formatOptionDollarCell },
-        { key: "iv", header: "IV", align: "right", format: formatOptionIvCell },
+        { key: "iv", header: "IV", align: "right", format: (value, row) => formatOptionIvCell(value, row) },
         { key: "delta", header: "Delta", align: "right", format: formatOptionDeltaCell },
         { key: "gamma", header: "Gamma", align: "right", format: formatOptionGammaCell, optional: true, dropPriority: 3 },
         { key: "vega", header: "Vega $", align: "right", format: formatOptionDollarCell, optional: true, dropPriority: 2 },
@@ -2826,7 +2895,7 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         { key: "last", header: "Last", align: "right" },
         { key: "bid", header: "Bid", align: "right", format: (_value, row) => formatOptionQuoteCell(row, "bid") },
         { key: "ask", header: "Ask", align: "right", format: (_value, row) => formatOptionQuoteCell(row, "ask") },
-        { key: "iv", header: "IV", align: "right", format: formatOptionIvCell },
+        { key: "iv", header: "IV", align: "right", format: (value, row) => formatOptionIvCell(value, row) },
         { key: "delta", header: "Delta", align: "right", format: formatOptionDeltaCell },
         { key: "volume", header: "Vol", align: "right", format: formatCountCell, optional: true, dropPriority: 1 },
         { key: "openInterest", header: "OI", align: "right", format: formatCountCell, optional: true, dropPriority: 1 },
@@ -3250,7 +3319,7 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
       usage: [OPTIONS_USAGE, LEAPS_USAGE],
       options: [
         {
-          flags: `--expiration <${OPTION_EXPIRATION_PLACEHOLDER}>`,
+          flags: `--expiration <${OPTION_EXPIRATION_PLACEHOLDER}>, --expiry <${OPTION_EXPIRATION_PLACEHOLDER}>`,
           description: "Expiration as a date (2028-01-21) or Unix seconds; defaults to the nearest one, and lists the others. With --leaps: rank that expiry alone",
         },
         EXCHANGE_OPTION,

package/src/cli/commands/news-search.ts

@@ -82,6 +82,28 @@ export async function searchNewsStories(text: string, limit: number, topics?: re
   return response.items.map((item) => mapCloudNewsArticle(item));
 }
 
+/** A search's stories, and whether they are its closest ones because no story has every word. */
+export interface NewsSearchAnswer {
+  found: NewsArticle[];
+  closest: boolean;
+}
+
+/**
+ * The stories matching the text; when no story has every word of a search of
+ * several, the ones with the most of them, most words first. Spellings of
+ * one word are one word to the service: lockup, lock-up and lock up;
+ * spinoff and spin-off; expiry and expiration.
+ */
+export async function searchClosestNewsStories(text: string, limit: number): Promise<NewsSearchAnswer> {
+  const response = await apiClient.searchCloudNews(text, limit, undefined, { closest: true });
+  return { found: response.items.map((item) => mapCloudNewsArticle(item)), closest: response.match === "closest" };
+}
+
+/** What the heading says of a search no story has every word of. */
+export function closestStoriesReason(text: string): string {
+  return `no story has every word of "${text}"; the closest, most words first`;
+}
+
 /** The NI code of the metal markets: prices, futures, bullion and the trusts that hold it, not a miner's releases. */
 export const METALS_NEWS_TOPIC = "metals";