gloomberb 0.18.4 → 0.19.0

package/src/cli/listing-arg.ts

@@ -9,17 +9,18 @@ import {
   quotedOnVenue,
   readAmbiguousCurrencyPair,
   readSharedCode,
+  savedRowOfBareSymbol,
   type ListingDeps,
   type ListingStore,
   type ListingVenue,
 } from "../tickers/listing-venues";
 import { findUsListingOfCompany, type UsListing } from "../tickers/us-listing";
-import { findListingOfCompanyName, isCompanyNameInput, readTerminalCodeArg } from "../tickers/company-name-listing";
+import { findListingOfCompanyName, isCompanyNameInput, readTerminalCodeArg, type CompanyNameListing } from "../tickers/company-name-listing";
 import { movedAwayChange, startTickerChangeLookup, type MovedTickerChange } from "../tickers/ticker-changes";
 import { loadListingFate, MovedSymbolError, type ListingFate } from "../tickers/listing-fate";
 import { quotedListingName } from "../tickers/listing-name";
 import { cliStyles } from "../utils/cli-output";
-import { groupByCompany, sameCompany, shortCompanyName } from "../tickers/company-name";
+import { groupByCompany, namesDepositaryReceipt, sameCompany, sameListedName, shortCompanyName } from "../tickers/company-name";
 import {
   canonicalExchange,
   exchangeCodeVenues,
@@ -34,7 +35,7 @@ import {
 import { withMarketData } from "./scoped-context";
 import { failWithFields } from "./errors";
 import { stripStrayEdges } from "./symbol-args";
-import { isNoProviderMessage, isProviderBusy } from "../sources/provider-errors";
+import { isNoProviderMessage, isNoSourceAnswer, isProviderBusy } from "../sources/provider-errors";
 import { dashedCoinPair, MAJOR_COIN_NAMES } from "../utils/crypto-pair";
 import { boardCoinFor, primeBoardCoins } from "./board-coins";
 import { knownGapMessage } from "./known-gaps";
@@ -48,13 +49,16 @@ import {
   bloombergMarketHint,
   endsInLegalForm,
   isSearchOnlyVenue,
+  readLondonDottedSymbol,
   readNearMissListing,
   readTerminalListingCode,
   terminalCodeReadAs,
   unknownBloombergMarket,
+  type NearMissListing,
   type TerminalListingCode,
 } from "../tickers/terminal-codes";
 import { listingAbroadVenue } from "../utils/sec";
+import { savedAbroadForBareSymbol, savedUsListingOf } from "../tickers/search/bare-symbol";
 import { listingSuffixCandidate, listingSuffixVenue, tickerHasListingSuffix } from "../sources/listing-symbols";
 import { notTheCoinNote } from "./commands/crypto-hints";
 
@@ -336,6 +340,15 @@ export function isNoProviderError(error: unknown): boolean {
   return isNoProviderMessage(error instanceof Error ? error.message : String(error ?? ""));
 }
 
+/**
+ * The router's answer that no source served a request because one failed (a
+ * timeout, a rate limit, a refused session) rather than missed: it says
+ * nothing about whether the symbol exists, unlike "Not a ticker".
+ */
+export function isUnsettledNoProvider(error: unknown): boolean {
+  return isNoProviderError(error) && !isNoSourceAnswer(error);
+}
+
 const MAX_OTHER_LISTINGS = 5;
 
 type BareListing = Pick<CliListing, "symbol" | "exchange"> & Partial<Pick<CliListing, "saved">>;
@@ -357,33 +370,42 @@ function listsSeveralCompanies(venues: readonly ListingVenue[]): boolean {
   return groupByCompany(venues, (venue) => venue.name).length > 1;
 }
 
-/** Every other company that lists the symbol once, at its first venue in search order. */
+/**
+ * Every other company or fund that lists the symbol, once, at its first venue
+ * in search order. A venue is another's only when its name says so: one with
+ * no name, or a depositary receipt named unlike the company (a CEDEAR's short
+ * form of its fund's name), is left out rather than guessed at, and one
+ * fund's venues are one fund however each words it (`sameListedName`).
+ */
 function otherCompanies(venues: readonly ListingVenue[], company: string): ListingVenue[] {
-  return groupByCompany(venues, (venue) => venue.name)
-    .filter((group) => !group.some((venue) => sameCompany(venue.name, company)))
+  if (!company.trim()) return [];
+  const known = venues.filter((venue) => !namesDepositaryReceipt(venue.name) || sameListedName(venue.name, company));
+  return groupByCompany(known, (venue) => venue.name, sameListedName)
+    .filter((group) => !group.some((venue) => sameListedName(venue.name, company)))
     .map((group) => group[0]!);
 }
 
 /**
- * "CAR = Avis Budget Group, NASDAQ (also XETRA, ASX)": the listing a bare
- * symbol several companies list was read on, and where the others list it.
- * Null when one company lists it, so a symbol that means one thing says
- * nothing.
+ * "CAR = Avis Budget Group, NASDAQ (different companies on XETRA, ASX)": the
+ * listing a bare symbol several companies list was read on, and where the
+ * others list it. Null when no other company is known to list it, so a symbol
+ * that means one thing (XLK, and its receipt in Buenos Aires) says nothing.
  */
 export function listingChoiceNote(
   symbol: string,
   chosen: { exchange: string; name?: string | null },
   venues: readonly ListingVenue[],
 ): string | null {
-  if (!chosen.exchange || !listsSeveralCompanies(venues)) return null;
+  if (!chosen.exchange) return null;
   const chosenVenue = venues.find((venue) => venue.exchange === chosen.exchange);
   const name = chosen.name?.trim() || chosenVenue?.name || "";
   const others = otherCompanies(venues, chosenVenue?.name || name).map((venue) => venue.exchange)
     .filter((exchange) => exchange !== chosen.exchange);
   if (others.length === 0) return null;
   const more = others.length - MAX_OTHER_LISTINGS;
-  const also = `${others.slice(0, MAX_OTHER_LISTINGS).join(", ")}${more > 0 ? ` and ${more} more: gloom search ${symbol}` : ""}`;
-  return `${symbol} = ${name ? `${shortCompanyName(name)}, ` : ""}${chosen.exchange} (also ${also})`;
+  const named = `${others.slice(0, MAX_OTHER_LISTINGS).join(", ")}${more > 0 ? ` and ${more} more: gloom search ${symbol}` : ""}`;
+  const which = others.length === 1 ? "a different company" : "different companies";
+  return `${symbol} = ${name ? `${shortCompanyName(name)}, ` : ""}${chosen.exchange} (${which} on ${named})`;
 }
 
 // Quotes of these never name a company's listing, so they are never a choice between companies.
@@ -407,34 +429,50 @@ export function listingReadNotes(listing: Pick<ListingArg, "readAs">): string[]
   return listing.readAs ? [listing.readAs] : [];
 }
 
+/**
+ * The coin line for a bare coin ticker (SOL, ETH) a command read as a listing that is
+ * not the coin, from the quote it was read on (`notTheCoinNote`). A list, so a command can
+ * spread it into its warnings. A named listing (`ETH:ARCA`, `--exchange`) asked for that
+ * listing on purpose and gets none.
+ */
+export function coinListingNotes(
+  listing: Pick<CliListing, "symbol" | "exchange">,
+  quote: Pick<Quote, "name" | "instrumentType" | "stale" | "delisting"> | null | undefined,
+): string[] {
+  const note = listing.exchange ? null : notTheCoinNote(listing.symbol, quote);
+  return note ? [note] : [];
+}
+
 /**
  * `listingChoiceNote` for a listing a command resolved, from the quote it was
  * read on: only a bare symbol went where the data service chose. A named
  * listing whose code names several venues says which it was read as
- * (`listingReadNotes`). A list, so a command can spread it into its warnings.
+ * (`listingReadNotes`). A bare coin ticker read as another listing ends with
+ * the coin's pair (`coinListingNotes`). A list, so a command can spread it into
+ * its warnings.
  */
 export async function listingChoiceNotes(
   listing: Pick<CliListing, "symbol" | "exchange" | "saved" | "readAs">,
   deps: ListingDeps,
-  quote: Pick<Quote, "name" | "listingExchangeName" | "exchangeName" | "instrumentType"> | null | undefined,
+  quote: Pick<Quote, "name" | "listingExchangeName" | "exchangeName" | "instrumentType" | "stale" | "delisting"> | null | undefined,
   /** The venues `loadBareVenues` already started; looked up here when not given. */
   venues?: Promise<ListingVenue[]> | null,
 ): Promise<string[]> {
-  if (!isBareListing(listing)) return listingReadNotes(listing);
-  if (!quote || UNLISTED_TYPES.has(quote.instrumentType?.trim().toUpperCase() ?? "")) return [];
+  const coin = coinListingNotes(listing, quote);
+  if (!isBareListing(listing)) return [...listingReadNotes(listing), ...coin];
+  if (!quote || UNLISTED_TYPES.has(quote.instrumentType?.trim().toUpperCase() ?? "")) return coin;
   const exchange = canonicalExchange(quote.listingExchangeName || quote.exchangeName);
-  if (!exchange) return [];
+  if (!exchange) return coin;
   const listed = await (venues ?? loadBareVenues(listing, deps) ?? []);
   const note = listingChoiceNote(listing.symbol, { exchange, name: quote.name }, listed);
-  return note ? [note] : [];
+  return [...note ? [note] : [], ...coin];
 }
 
 /**
  * `listingChoiceNotes` for a command with no quote of its own to read the
  * listing from (`fn`): it loads the listing's quote, and only for a bare
  * symbol, so a named or saved listing costs nothing. A bare coin ticker read
- * as a fund (BTC, the Grayscale trust) ends with `quote`'s note naming the
- * coin's pair.
+ * as another listing (BTC, the Grayscale trust) ends with the coin's pair.
  */
 export async function quotedListingChoiceNotes(
   listing: Pick<CliListing, "symbol" | "exchange" | "saved" | "request" | "readAs">,
@@ -442,9 +480,7 @@ export async function quotedListingChoiceNotes(
 ): Promise<string[]> {
   const venues = loadBareVenues(listing, deps);
   if (!venues) return listingReadNotes(listing);
-  const quote = await loadListingQuote(deps.dataProvider, listing);
-  const coin = notTheCoinNote(listing.symbol, quote);
-  return [...await listingChoiceNotes(listing, deps, quote, venues), ...coin ? [coin] : []];
+  return listingChoiceNotes(listing, deps, await loadListingQuote(deps.dataProvider, listing), venues);
 }
 
 /**
@@ -561,31 +597,43 @@ export function futuresTryLine(symbol: string, request: ListingDataRequest): str
   return `${future.symbol} ${future.name} future${retry ? ` (try: ${retry})` : ""}`;
 }
 
+/** A venue's listing as its key names it: under its own symbol there (BP:LSE for `BP.`), else the one asked for. */
+function venueKey(symbol: string, venue: Pick<ListingVenue, "exchange" | "symbol">): string {
+  return `${venue.symbol ?? symbol}:${venue.exchange}`;
+}
+
 function describeOtherListings(
   listing: BareListing,
   { exchange, resolved, others, choose }: BareListingVenues,
   request: ListingDataRequest,
+  /** Listings just asked that had none: named as having none, never offered to try. */
+  without: readonly ListingVenue[] = [],
 ): OtherListingsMessage | null {
   const future = futuresTryLine(listing.symbol, request);
-  if (others.length === 0 && !future) return null;
+  const offered = others.filter((venue) => !without.includes(venue));
+  if (offered.length === 0 && !future && without.length === 0) return null;
   const name = resolved?.name || listing.saved?.metadata.name?.trim() || "";
-  const lines = others.slice(0, MAX_OTHER_LISTINGS).map((venue) => {
-    const key = `${listing.symbol}:${venue.exchange}`;
+  const lines = offered.slice(0, MAX_OTHER_LISTINGS).map((venue) => {
+    const key = venueKey(listing.symbol, venue);
     const retry = retryCommand(request, key);
     return `${key}${venue.name ? ` ${venue.name}` : ""}${retry ? ` (try: ${retry})` : ""}`;
   });
-  if (others.length > MAX_OTHER_LISTINGS) lines.push(`and ${others.length - MAX_OTHER_LISTINGS} more: gloom search ${listing.symbol}`);
+  if (offered.length > MAX_OTHER_LISTINGS) lines.push(`and ${offered.length - MAX_OTHER_LISTINGS} more: gloom search ${listing.symbol}`);
   if (future) lines.push(future);
-  const heading = choose ? "Listings" : "Other listings";
+  // Every other listing was asked and had nothing: they are named as such, with nothing to try.
+  const heading = choose ? "Listings" : lines.length === 0 ? `No ${request.noun} on its other listings either` : "Other listings";
+  const named = lines.length === 0 ? without : offered;
+  const details = lines.length === 0 ? `${heading}: ${without.map((venue) => venueKey(listing.symbol, venue)).join(", ")}.`
+    : lines.length === 1 ? `${heading}: ${lines[0]}` : [`${heading}:`, ...lines.map((line) => `  ${line}`)].join("\n");
   return {
     // The symbol went to no venue, so none of them is said to lack the data.
     message: choose
       ? `Choose an exchange for ${listing.symbol}.`
       : `${listing.symbol} resolved to ${name ? `${name} (${exchange})` : exchange}, which has no ${request.noun}.`,
-    details: lines.length === 1 ? `${heading}: ${lines[0]}` : [`${heading}:`, ...lines.map((line) => `  ${line}`)].join("\n"),
+    details,
     heading,
-    listings: [...others.map((venue) => `${listing.symbol}:${venue.exchange}`), ...future ? [futuresContractByCode(listing.symbol)!.symbol] : []],
-    choices: others.slice(0, MAX_OTHER_LISTINGS).map((venue) => ({ key: `${listing.symbol}:${venue.exchange}`, name: venue.name || null })),
+    listings: [...named.map((venue) => venueKey(listing.symbol, venue)), ...future ? [futuresContractByCode(listing.symbol)!.symbol] : []],
+    choices: offered.slice(0, MAX_OTHER_LISTINGS).map((venue) => ({ key: venueKey(listing.symbol, venue), name: venue.name || null })),
     choose,
   };
 }
@@ -610,27 +658,44 @@ async function otherListingsMessage(
   return venues && describeOtherListings(listing, venues, request);
 }
 
-/** The listing on one venue, as `SYM:EXCH` names it. */
-function namedListing(listing: CliListing, exchange: string): CliListing {
-  const key = `${listing.symbol}:${exchange}`;
+/** The listing on one venue, as `SYM:EXCH` names it, under the venue's own symbol when search lists one. */
+function namedListing(listing: CliListing, venue: Pick<ListingVenue, "exchange" | "symbol">): CliListing {
+  const { exchange } = venue;
+  const symbol = venue.symbol ?? listing.symbol;
+  const key = `${symbol}:${exchange}`;
   const saved = canonicalExchange(listing.saved?.metadata.exchange) === exchange ? listing.saved : null;
-  return { symbol: listing.symbol, exchange, key, saved, request: { symbol: key, exchange } };
+  return { symbol, exchange, key, saved, request: { symbol: key, exchange } };
 }
 
+/**
+ * Each listing's quote, null where it has none; `undefined` where the request
+ * itself failed, which says nothing of whether it has one.
+ */
 async function quoteListings(
   dataProvider: DataProvider,
   listings: readonly CliListing[],
   refresh: boolean,
-): Promise<Array<Quote | null>> {
+  datesChangeBasis = false,
+): Promise<Array<Quote | null | undefined>> {
   if (listings.length === 0) return [];
   const targets = listings.map((listing) => listing.request);
   if (dataProvider.getQuotesBatch) {
-    const results = await dataProvider.getQuotesBatch(targets, { forceRefresh: refresh }).catch(logFailure("cli.listing-arg", "Read listing quote batch failed", []));
-    return targets.map((target, index) => (results.find((result) => result.target === target) ?? results[index])?.quote ?? null);
+    const results = await dataProvider.getQuotesBatch(targets, { forceRefresh: refresh, ...(datesChangeBasis ? { datesChangeBasis } : {}) })
+      .catch(logFailure("cli.listing-arg", "Read listing quote batch failed", null));
+    if (!results) return targets.map(() => undefined);
+    return targets.map((target, index) => {
+      const result = results.find((entry) => entry.target === target) ?? results[index];
+      // No source quotes it, which is an answer; any other failure is none.
+      return result?.quote ?? (result && (result.error == null || isNoProviderError(result.error)) ? null : undefined);
+    });
   }
   return Promise.all(targets.map((target) => dataProvider.getQuote(target.symbol, target.exchange, {
     cacheMode: refresh ? "refresh" : "default",
-  }).catch(logFailure("cli.listing-arg", "Read listing quote failed", null))));
+    ...(datesChangeBasis ? { datesChangeBasis } : {}),
+  }).catch((error: unknown) => {
+    logFailure("cli.listing-arg", "Read listing quote failed")(error);
+    return isNoProviderError(error) ? null : undefined;
+  })));
 }
 
 export type BareListingQuote =
@@ -661,7 +726,7 @@ export async function quoteBareListing(
   listing: CliListing,
   deps: ListingDeps,
   request: ListingDataRequest,
-  { refresh = false }: { refresh?: boolean } = {},
+  { refresh = false, datesChangeBasis = false }: { refresh?: boolean; datesChangeBasis?: boolean } = {},
 ): Promise<BareListingQuote | null> {
   const venues = await bareListingVenues(listing, deps);
   if (!venues) return null;
@@ -669,17 +734,19 @@ export async function quoteBareListing(
     const other = describeOtherListings(listing, venues, request);
     return other && { kind: "missing", ...other };
   }
-  const first = [namedListing(listing, venues.exchange)];
-  const rest = venues.others.map((venue) => namedListing(listing, venue.exchange));
+  const first = [namedListing(listing, venues.resolved ?? { exchange: venues.exchange })];
+  const rest = venues.others.map((venue) => namedListing(listing, venue));
   let tried = first;
-  let quotes = await quoteListings(deps.dataProvider, first, refresh);
+  let quotes = await quoteListings(deps.dataProvider, first, refresh, datesChangeBasis);
   if (!quotes[0] && rest.length > 0) {
     tried = [...first, ...rest];
-    quotes = [...quotes, ...await quoteListings(deps.dataProvider, rest, refresh)];
+    quotes = [...quotes, ...await quoteListings(deps.dataProvider, rest, refresh, datesChangeBasis)];
   }
   const found = quotes.findIndex(Boolean);
   if (found < 0) {
-    const other = describeOtherListings(listing, venues, request);
+    // A listing just asked that had no quote is no listing to try.
+    const without = venues.others.filter((_venue, index) => quotes[index + 1] === null);
+    const other = describeOtherListings(listing, venues, request, without);
     return other && { kind: "missing", ...other };
   }
   const answer = tried[found]!;
@@ -692,7 +759,8 @@ export async function quoteBareListing(
     kind: "quoted",
     listing: answer,
     quote: quotes[found]!,
-    note: chosenListingNote(listing.symbol, answer.exchange, others, without),
+    // Under the venue's own symbol (BP:LSE for `BP.`), the note names the listing, not only its venue.
+    note: chosenListingNote(listing.symbol, answer.symbol === listing.symbol ? answer.exchange : answer.key, others, without),
   };
 }
 
@@ -703,6 +771,8 @@ export interface ReadListing {
   exchange: string;
   /** The listing's company, from its quote. */
   name: string | null;
+  /** A bare coin ticker read as a listing that is not the coin (`coinListingNotes`); null otherwise. */
+  coinNote: string | null;
 }
 
 /**
@@ -723,10 +793,14 @@ export async function readBareListing(
   const listing = await resolveCliListing(symbol, null, deps);
   if (listing.exchange) return null;
   const answer = await loadListingQuoteAnswer(deps.dataProvider, listing);
-  if (answer.quote) return { symbol: listing.symbol, exchange: listing.request.exchange, name: answer.quote.name?.trim() || null };
+  if (answer.quote) {
+    return { symbol: listing.symbol, exchange: listing.request.exchange, name: answer.quote.name?.trim() || null, coinNote: coinListingNotes(listing, answer.quote)[0] ?? null };
+  }
   if (!isNoProviderError(answer.error)) return null;
   const other = await quoteBareListing(listing, deps, request, { refresh });
-  if (other?.kind === "quoted") return { symbol: listing.symbol, exchange: other.listing.exchange, name: other.quote.name?.trim() || null };
+  if (other?.kind === "quoted") {
+    return { symbol: listing.symbol, exchange: other.listing.exchange, name: other.quote.name?.trim() || null, coinNote: coinListingNotes(listing, other.quote)[0] ?? null };
+  }
   if (other?.choose) throw new ListingArgError(other.message, other.details, other.choices);
   return null;
 }
@@ -948,6 +1022,10 @@ export async function loadSavedListingOf(
   for (const listing of listings) {
     if (found.some((entry) => entry.listing.key === listing.key)) continue;
     const ticker = await loadSavedListing(store, listing);
+    // A bare symbol's US listing comes before a row abroad saved under its bare key (SHEL, saved from SHEL.L).
+    if (ticker && !listing.exchange && savedAbroadForBareSymbol(listing.symbol, ticker)) {
+      add(listing, savedUsListingOf(listing.symbol, await store.loadAllTickers()));
+    }
     add(listing, ticker);
     // A suffixed key as typed may be saved with a venue (7203.T:JPX, GARAN.IS:XNYS): any row of that symbol.
     if (!ticker && !listing.exchange && tickerHasListingSuffix(listing.symbol)) {
@@ -1087,7 +1165,9 @@ export async function resolveCliListing(
   const terminal = named ? null : read;
   // "AAPL GP" is written as a code, with a market code no venue answers to and no company's name: one entry, never AAPL and GP.
   if (!terminal && !named) await refuseUnknownMarketCode(typed, deps);
-  let parsed = named ?? parseListingArg(raw, exchangeOption, { ...options, terminalCode: terminal });
+  // `BP.` is London's code for BP: its London line where London lists it, and `GE.` a US ticker with a stray dot.
+  const dotted = terminal || named || exchangeOption?.trim() ? null : readLondonDottedSymbol(typed);
+  let parsed = named ?? (dotted ? await londonDottedListing(dotted, deps) : parseListingArg(raw, exchangeOption, { ...options, terminalCode: terminal }));
   if (!parsed.symbol) throw new ListingArgError("Ticker symbol is required.");
   // $VIX is Schwab's code for ^VIX, unless a security trades as VIX: $AAPL is a cashtag.
   const index = named || parsed.exchange ? null : await readDollarIndexCode(raw, deps);
@@ -1115,7 +1195,9 @@ export async function resolveCliListing(
     parsed = market;
   }
   let listing = await settleSharedCode(parsed, deps);
-  const saved = await loadSavedListing(deps.store, listing) ?? (typedKey ? await loadSuffixedRow(deps.store, typedKey, listing.exchange) : null);
+  const found = await loadSavedListing(deps.store, listing) ?? (typedKey ? await loadSuffixedRow(deps.store, typedKey, listing.exchange) : null);
+  // A bare symbol is its US listing when it has one, whatever row abroad holds the bare key (SHEL saved from SHEL.L).
+  const saved = listing.exchange ? found : await savedRowOfBareSymbol(listing.symbol, found, deps);
   // A code nothing could read stays the venue it is saved on.
   const savedExchange = canonicalExchange(saved?.metadata.exchange);
   if (listing.sharedCode && savedExchange) listing = { symbol: listing.symbol, exchange: savedExchange, key: `${listing.symbol}:${savedExchange}` };
@@ -1129,6 +1211,21 @@ export async function resolveCliListing(
   };
 }
 
+/**
+ * A two-letter symbol written with London's trailing dot (`BP.`, `RR.`) as its
+ * London line, said as "Read BP. as BP:LSE.", where search lists it on LSE or
+ * its quote there says it trades. Elsewhere the dot was a slip after the
+ * ticker, dropped as a stray edge is (`GE.` is GE).
+ */
+async function londonDottedListing(dotted: NearMissListing, deps: ListingDeps): Promise<ListingArg> {
+  const london = { symbol: dotted.symbol, exchange: "LSE" };
+  const venues = await listingVenues(dotted.symbol, deps).catch(logFailure("cli.listing-arg", "Read listing venues failed", []));
+  const listed = venues.some((venue) => venue.exchange === london.exchange) || await quotedOnVenue(london, deps);
+  if (!listed) return parseListingArg(dotted.symbol);
+  const key = `${london.symbol}:${london.exchange}`;
+  return { ...parseListingArg(key), readAs: `Read ${dotted.typed} as ${key}.` };
+}
+
 /**
  * Fails a line written as a Bloomberg code whose market code no venue answers
  * to (`AAPL GP`), suggesting the code of the symbol's own listing (`AAPL
@@ -1224,17 +1321,23 @@ const ONE_WORD_NAME = /^\p{L}[\p{L}\p{N}&'’.-]*$/u;
  * for anything else, and when search names no company or is too busy to say.
  */
 export async function oneWordCompanyName(typed: string, deps: Pick<ListingDeps, "dataProvider">): Promise<ListingArg | null> {
+  const found = await findOneWordCompany(typed, deps);
+  return found ? companyListingArg(typed, found) : null;
+}
+
+/** The company `oneWordCompanyName` reads a word as, before it is read as a listing. */
+async function findOneWordCompany(typed: string, deps: Pick<ListingDeps, "dataProvider">): Promise<CompanyNameListing | null> {
   const word = typed.trim();
   if (!ONE_WORD_NAME.test(word) || knownGapMessage(word) || isMajorCoinName(word)) return null;
-  const named = await readCompanyName(word, deps, { oneWord: true }).catch((error: unknown) => {
+  const found = await findCompanyName(word, deps, { oneWord: true }).catch((error: unknown) => {
     if (!isProviderBusy(error)) throw error;
     // Intentional ignore: a busy search says nothing about the name, so the word keeps its own "Not a ticker".
     return null;
   });
-  if (!named) return null;
+  if (!found) return null;
   // The board is read only for a word that names a company, and once for the run (`primeBoardCoins`).
   if (/^[A-Za-z0-9]+$/.test(word)) await primeBoardCoins([`Not a ticker: ${word.toUpperCase()}.`]);
-  return boardCoinFor(word) ? null : named;
+  return boardCoinFor(word) ? null : found;
 }
 
 function isMajorCoinName(word: string): boolean {
@@ -1242,9 +1345,16 @@ function isMajorCoinName(word: string): boolean {
   return [...MAJOR_COIN_NAMES.values()].some((name) => name.toLowerCase() === wanted);
 }
 
+function findCompanyName(typed: string, deps: Pick<ListingDeps, "dataProvider">, options: { oneWord?: boolean } = {}): Promise<CompanyNameListing | null> {
+  return findListingOfCompanyName(deps.dataProvider, typed, { meant: true, quoted: true, ...options });
+}
+
 async function readCompanyName(typed: string, deps: Pick<ListingDeps, "dataProvider">, options: { oneWord?: boolean } = {}): Promise<ListingArg | null> {
-  const found = await findListingOfCompanyName(deps.dataProvider, typed, { meant: true, quoted: true, ...options });
-  if (!found) return null;
+  const found = await findCompanyName(typed, deps, options);
+  return found ? companyListingArg(typed, found) : null;
+}
+
+function companyListingArg(typed: string, found: CompanyNameListing): ListingArg {
   const key = `${found.symbol}:${found.exchange}`;
   // A fund or an index carrying the name asks about the company's stock: "Did you mean JPM (JPMorgan Chase & Co.)?".
   const meant = found.meant ? { symbol: found.meant.symbol, name: found.meant.name } : null;
@@ -1252,6 +1362,35 @@ async function readCompanyName(typed: string, deps: Pick<ListingDeps, "dataProvi
   return { ...parseListingArg(key), readAs: `Read "${typed.trim()}" as ${key} (${found.name}).${question}`, ...meant ? { meant } : {} };
 }
 
+/**
+ * The listing search names for a company's name typed where a ticker goes,
+ * as a sentence offers it: `PLTR (Palantir Technologies Inc.)`, a listing
+ * abroad with its venue (`SIE:XETRA (Siemens AG)`), a fund or an index that
+ * carries the name as the company's stock it means. Null when the words name
+ * no company, search is busy, or the listing found is the word itself: a
+ * real ticker is never a company's name. Never throws.
+ */
+export async function companyNameSuggestion(typed: string, deps: Pick<ListingDeps, "dataProvider">): Promise<{ symbol: string; name: string } | null> {
+  const words = typed.trim().replace(/^\$/, "");
+  if (!words) return null;
+  try {
+    const found = isCompanyNameInput(words) ? await findCompanyName(words, deps).catch(busyAsMiss) : await findOneWordCompany(words, deps);
+    const listing = found?.meant ?? found;
+    if (!listing || listing.symbol.toUpperCase() === words.toUpperCase()) return null;
+    return { symbol: isUsListingExchange(listing.exchange) ? listing.symbol : `${listing.symbol}:${listing.exchange}`, name: listing.name };
+  } catch (error) {
+    logFailure("cli.listing-arg", "Search a company name for a suggestion failed")(error);
+    return null;
+  }
+}
+
+/** A search too busy to answer is no company, as a name that matches none. */
+function busyAsMiss(error: unknown): null {
+  if (!isProviderBusy(error)) throw error;
+  // Intentional ignore: a busy search says nothing about the name, so no company is suggested.
+  return null;
+}
+
 /** `resolveCliListing` for a command: a bad exchange fails the command with its message. */
 export async function requireCliListing(
   raw: string,

package/src/cli/output-file.ts

@@ -0,0 +1,68 @@
+import { mkdir, stat, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { posix, win32 } from "path";
+
+interface OutputPathContext {
+  cwd?: string;
+  home?: string;
+  platform?: NodeJS.Platform;
+}
+
+/** `C:\Users\me\out.csv`, `C:/out.csv`, `\\server\share\out.csv`: a path only Windows reads. */
+const WINDOWS_PATH = /^(?:[A-Za-z]:[\\/]|\\\\)/;
+
+/**
+ * The absolute path `--output <path>` names, in any form a shell passes it:
+ * relative to the folder the command runs in, absolute, or under the home
+ * folder (`~/Desktop/rv.csv`, which a shell leaves as typed after
+ * `--output=`). A Windows path is read as one on Windows; anywhere else it
+ * is refused, since it would write a file named after the whole path.
+ */
+export function resolveOutputPath(raw: string, context: OutputPathContext = {}): string {
+  const platform = context.platform ?? process.platform;
+  const paths = platform === "win32" ? win32 : posix;
+  const typed = raw.trim();
+  if (!typed) throw new Error("--output needs a file to write, such as --output report.csv.");
+  if (platform !== "win32" && WINDOWS_PATH.test(typed)) {
+    throw new Error(`${typed} is a Windows path. Write a path on this computer, such as --output ~/Desktop/report.csv.`);
+  }
+  const home = context.home ?? homedir();
+  const homeRelative = /^~(?:$|[\\/])/.test(typed);
+  const expanded = homeRelative ? paths.join(home, typed.slice(1)) : typed;
+  return paths.resolve(context.cwd ?? process.cwd(), expanded);
+}
+
+function errorCode(error: unknown): string | undefined {
+  return error && typeof error === "object" && "code" in error ? String((error as { code: unknown }).code) : undefined;
+}
+
+function isFolder(path: string, paths: typeof posix): Error {
+  return new Error(`Cannot write ${path}: it is a folder. Name a file in it, such as ${paths.join(path, "report.csv")}.`);
+}
+
+/** Fails when `path` names a folder: checked before a report loads, so it stops at once. */
+export async function checkOutputPath(path: string, platform: NodeJS.Platform = process.platform): Promise<void> {
+  const existing = await stat(path).catch(() => {
+    // Intentional ignore: a path that does not exist yet is the usual case, and writing reports any real failure.
+    return null;
+  });
+  if (existing?.isDirectory()) throw isFolder(path, platform === "win32" ? win32 : posix);
+}
+
+/**
+ * Writes a command's output to `path`, creating the folders it names as
+ * `shot --output` does, and failing with what to do when it cannot.
+ */
+export async function writeOutputFile(path: string, contents: string, platform: NodeJS.Platform = process.platform): Promise<void> {
+  const paths = platform === "win32" ? win32 : posix;
+  try {
+    await mkdir(paths.dirname(path), { recursive: true });
+    await writeFile(path, contents);
+  } catch (error) {
+    const code = errorCode(error);
+    if (code === "EISDIR") throw isFolder(path, paths);
+    if (code === "EACCES" || code === "EPERM") throw new Error(`Cannot write ${path}: permission denied.`);
+    if (code === "ENOTDIR" || code === "EEXIST") throw new Error(`Cannot write ${path}: a file stands where one of its folders would be.`);
+    throw new Error(`Cannot write ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/src/cli/pane-functions/capabilities.ts

@@ -2,6 +2,7 @@ import type {
   HeadlessPaneArgumentDef,
   HeadlessPaneDefinition,
   HeadlessPaneOptionDef,
+  HeadlessPaneReference,
   PaneDef,
   PaneTemplateDef,
 } from "../../types/plugin";
@@ -26,6 +27,8 @@ export interface PaneFunctionCapability {
   screenshotReadiness: PaneFunctionScreenshotReadiness;
   dataRequirements: string[];
   limitations: string[];
+  /** Lists the catalog prints under the options (EQS's sector and industry names). */
+  reference?: HeadlessPaneReference[];
   options: PaneFunctionOptionDef[];
   /** A rendered view that refuses any option it does not declare (PaneDef.reportOptionsOnly), as a headless report does. */
   strictOptions?: boolean;