gloomberb 0.17.2 → 0.17.4

package/src/plugins/builtin/research/relative-valuation-columns.ts

@@ -0,0 +1,289 @@
+import type { ScreenDefinition, ScreenMetric, ScreenRow } from "../../../api-client/equity-screener";
+import type { HeadlessPaneColumn, HeadlessPaneContext, HeadlessPaneRow } from "../../../types/headless";
+import type { TickerFinancials } from "../../../types/financials";
+import { isUsListingExchange, parsePublicTickerKey } from "../../../utils/exchanges";
+import { errorMessage } from "../../../utils/errors";
+import { formatNumber } from "../../../utils/format";
+import { fetchScreen } from "../equity-screener/client";
+import { refusedLock } from "../shared/cloud-denied";
+import { resolveHeadlessInstrument } from "../shared/headless-market-data";
+import { loadShortInterest } from "../short-interest/client";
+import { buildShortWatchRow } from "../short-interest/watch-model";
+import { analystTargetCurrency, formatAnalystPrice, recommendationTotal } from "./analyst-model";
+
+/** The columns `--columns` adds to RV's report, each read from the path its own function uses. */
+export const EXTRA_COLUMN_IDS = ["shortInterest", "nextEarnings", "target", "grossMargin", "evEbitda"] as const;
+export type ExtraColumnId = (typeof EXTRA_COLUMN_IDS)[number];
+
+const COLUMN_ALIASES: Record<string, ExtraColumnId> = {
+  shortinterest: "shortInterest", short: "shortInterest", si: "shortInterest", shortfloat: "shortInterest",
+  nextearnings: "nextEarnings", earnings: "nextEarnings", earningsdate: "nextEarnings",
+  target: "target", targets: "target", analysttarget: "target", analysts: "target", pricetarget: "target",
+  grossmargin: "grossMargin", gross: "grossMargin", gm: "grossMargin",
+  evebitda: "evEbitda", evtoebitda: "evEbitda",
+};
+
+/** `--columns`: a comma list of the fields above (or their short names), in order, as the canonical names. */
+export function normalizeExtraColumns(value: string): string {
+  const tokens = value.split(/[,\s]+/).filter(Boolean);
+  if (tokens.length === 0) throw new Error(`--columns needs one or more of: ${EXTRA_COLUMN_IDS.join(", ")}.`);
+  const ids = tokens.map((token) => {
+    const id = COLUMN_ALIASES[token.toLowerCase().replace(/[^a-z]/g, "")];
+    if (!id) throw new Error(`Unknown --columns field "${token}". Use any of: ${EXTRA_COLUMN_IDS.join(", ")}.`);
+    return id;
+  });
+  return [...new Set(ids)].join(",");
+}
+
+export function parseExtraColumns(value: unknown): ExtraColumnId[] {
+  return typeof value === "string" && value ? value.split(",").filter((id): id is ExtraColumnId => (EXTRA_COLUMN_IDS as readonly string[]).includes(id)) : [];
+}
+
+const percent = (value: unknown) => (typeof value === "number" && Number.isFinite(value) ? `${value.toFixed(2)}%` : "-");
+const text = (value: unknown) => (typeof value === "string" && value ? value : "-");
+
+/** Each added column, then (exports only) the source and as-of of its cells. */
+interface ColumnSpec {
+  columns: HeadlessPaneColumn[];
+  sourceKey: string;
+  asOfKey: string;
+  label: string;
+}
+
+const COLUMN_SPECS: Record<ExtraColumnId, ColumnSpec> = {
+  shortInterest: {
+    label: "Short % Float",
+    columns: [{ key: "shortInterestPercentFloat", header: "Short % Float", align: "right", format: percent }],
+    sourceKey: "shortInterestSource",
+    asOfKey: "shortInterestAsOf",
+  },
+  nextEarnings: {
+    label: "Next Earnings",
+    columns: [{
+      key: "nextEarningsDate", header: "Next Earnings", format: text, shrink: false,
+      // The text table says when in the day and whether the date is confirmed; exports keep them as columns.
+      textFormat: (value, row) => (typeof value === "string" && value
+        ? [value, row.nextEarningsTiming, row.nextEarningsStatus === "estimated" ? "est" : null].filter(Boolean).join(" ") : "-"),
+    }, { key: "nextEarningsTiming", header: "Next Earnings Timing", format: text }, { key: "nextEarningsStatus", header: "Next Earnings Status", format: text }],
+    sourceKey: "nextEarningsSource",
+    asOfKey: "nextEarningsAsOf",
+  },
+  target: {
+    label: "Avg Target",
+    columns: [
+      { key: "targetMean", header: "Avg Target", align: "right", unitKey: "targetCurrency",
+        format: (value, row) => (typeof value === "number" ? formatAnalystPrice(value, typeof row.targetCurrency === "string" ? row.targetCurrency : undefined) : "-") },
+      { key: "analystCount", header: "Analysts", align: "right", format: (value) => (typeof value === "number" ? String(value) : "-") },
+    ],
+    sourceKey: "targetSource",
+    asOfKey: "targetAsOf",
+  },
+  grossMargin: {
+    label: "Gross Margin",
+    columns: [{ key: "grossMarginPercent", header: "Gross Margin", align: "right", format: percent }],
+    sourceKey: "grossMarginSource",
+    asOfKey: "grossMarginAsOf",
+  },
+  evEbitda: {
+    label: "EV/EBITDA",
+    columns: [{ key: "evEbitda", header: "EV/EBITDA", align: "right", format: (value) => (typeof value === "number" ? formatNumber(value, 1) : "-") }],
+    sourceKey: "evEbitdaSource",
+    asOfKey: "evEbitdaAsOf",
+  },
+};
+
+/** The timing and status columns of Next Earnings stay out of the text table, which folds them into the date. */
+const EXPORT_ONLY_KEYS = new Set(["nextEarningsTiming", "nextEarningsStatus"]);
+
+/** The columns the added fields print as: `text` for the terminal table, `export` with each cell's source and as-of. */
+export function extraColumns(ids: readonly ExtraColumnId[]): { text: HeadlessPaneColumn[]; export: HeadlessPaneColumn[] } {
+  const specs = ids.map((id) => COLUMN_SPECS[id]);
+  return {
+    text: specs.flatMap((spec) => spec.columns.filter((column) => !EXPORT_ONLY_KEYS.has(column.key))),
+    export: specs.flatMap((spec) => [
+      ...spec.columns,
+      { key: spec.sourceKey, header: `${spec.label} source`, format: text },
+      { key: spec.asOfKey, header: `${spec.label} as of`, format: text, shrink: false },
+    ]),
+  };
+}
+
+/** Whether a symbol is a US listing, which FINRA short interest, the earnings calendar and the screener cover. */
+function usListing(symbol: string): string | null {
+  const { symbol: bare, exchange } = parsePublicTickerKey(symbol);
+  return !exchange || isUsListingExchange(exchange) ? bare.toUpperCase() : null;
+}
+
+/** A failed read of one column, as the report says it: a Pro or sign-in wall in the words its lock note uses, else why. */
+function failureMessage(label: string, error: unknown, symbol?: string): string {
+  const refused = refusedLock(error);
+  if (refused?.gate === "pro") return `${label} requires Gloom Pro.`;
+  if (refused) return `${label} needs a free Gloom sign-in.`;
+  return `${symbol ? `${symbol}: ` : ""}${label} unavailable: ${errorMessage(error)}`;
+}
+
+interface ExtraColumnsResult {
+  /** The added fields of each symbol's row, keyed by the symbol as given. */
+  fields: Map<string, HeadlessPaneRow>;
+  errors: string[];
+  notes: string[];
+}
+
+const SHORT_INTEREST_SOURCES: Record<string, string> = { finra: "FINRA", gloom: "Gloom Cloud" };
+
+/** Percent of float at the latest settlement, as `SIW` computes it, dated by that settlement. */
+async function loadShortInterestFields(symbols: readonly string[], financials: ReadonlyMap<string, TickerFinancials | null>, ctx: HeadlessPaneContext, out: ExtraColumnsResult) {
+  const label = COLUMN_SPECS.shortInterest.label;
+  await Promise.all(symbols.map(async (symbol) => {
+    const bare = usListing(symbol);
+    if (!bare) return;
+    try {
+      const result = await loadShortInterest(bare, ctx.apiClient);
+      const row = buildShortWatchRow({ symbol, records: result.records, floatShares: financials.get(symbol)?.fundamentals?.floatShares ?? null, history: null });
+      if (!row.settlementDate) return;
+      Object.assign(out.fields.get(symbol)!, {
+        shortInterestPercentFloat: row.percentFloat,
+        shortInterestSource: SHORT_INTEREST_SOURCES[result.source] ?? "FINRA",
+        shortInterestAsOf: row.settlementDate,
+      });
+    } catch (error) {
+      out.errors.push(failureMessage(label, error, symbol));
+    }
+  }));
+}
+
+/** The next report date on the earnings calendar `earnings` reads, dated by when the calendar was read. */
+async function loadNextEarningsFields(symbols: readonly string[], ctx: HeadlessPaneContext, out: ExtraColumnsResult) {
+  const label = COLUMN_SPECS.nextEarnings.label;
+  const listed = symbols.flatMap((symbol) => {
+    const bare = usListing(symbol);
+    return bare ? [{ symbol, bare }] : [];
+  });
+  if (listed.length === 0) return;
+  if (!ctx.marketData.getEarningsCalendar) {
+    out.errors.push(`${label} unavailable: the market data source has no earnings calendar.`);
+    return;
+  }
+  try {
+    const events = await ctx.marketData.getEarningsCalendar(listed.map(({ bare }) => bare));
+    const readAt = new Date().toISOString();
+    const today = readAt.slice(0, 10);
+    for (const { symbol, bare } of listed) {
+      const next = events
+        .filter((event) => event.symbol.toUpperCase() === bare && event.epsActual == null && event.earningsDate.toISOString().slice(0, 10) >= today)
+        .sort((left, right) => left.earningsDate.getTime() - right.earningsDate.getTime())[0];
+      if (!next) continue;
+      Object.assign(out.fields.get(symbol)!, {
+        nextEarningsDate: next.earningsDate.toISOString().slice(0, 10),
+        nextEarningsTiming: next.timing || null,
+        nextEarningsStatus: next.isDateEstimate === true ? "estimated" : next.isDateEstimate === false ? "confirmed" : null,
+        nextEarningsSource: "Gloom Cloud earnings calendar",
+        nextEarningsAsOf: readAt,
+      });
+    }
+  } catch (error) {
+    out.errors.push(failureMessage(label, error));
+  }
+}
+
+/** The mean analyst target and the analysts behind the latest recommendation mix, as `analyst` reads them. */
+async function loadTargetFields(symbols: readonly string[], ctx: HeadlessPaneContext, out: ExtraColumnsResult) {
+  const label = COLUMN_SPECS.target.label;
+  const read = ctx.marketData.getAnalystResearch?.bind(ctx.marketData);
+  if (!read) {
+    out.errors.push(`${label} unavailable: the market data source has no analyst research.`);
+    return;
+  }
+  await Promise.all(symbols.map(async (symbol) => {
+    try {
+      const { symbol: ticker, exchange } = await resolveHeadlessInstrument(ctx, symbol);
+      const data = await read(ticker, exchange ?? "");
+      const average = data.priceTarget?.average;
+      const count = recommendationTotal(data);
+      if (average == null && count == null) return;
+      Object.assign(out.fields.get(symbol)!, {
+        targetMean: average != null && Number.isFinite(average) ? average : null,
+        targetCurrency: analystTargetCurrency(data) ?? null,
+        analystCount: count,
+        targetSource: "Gloom Cloud analyst research",
+        targetAsOf: data.fetchedAt ?? new Date().toISOString(),
+      });
+    } catch (error) {
+      out.errors.push(failureMessage(label, error, symbol));
+    }
+  }));
+}
+
+function metricFields(metric: ScreenMetric | undefined): { value: number | null; source: string | null; asOf: string | null } | null {
+  if (!metric || metric.value == null || !Number.isFinite(metric.value) || metric.state === "unavailable") return null;
+  return { value: metric.value, source: metric.source || null, asOf: metric.asOf ?? metric.observedAt ?? null };
+}
+
+/** Gross margin and EV/EBITDA as the screener stores them, each with its own source and statement date. */
+async function loadScreenerFields(ids: readonly ExtraColumnId[], symbols: readonly string[], ctx: HeadlessPaneContext, out: ExtraColumnsResult) {
+  const wanted = ids.filter((id) => id === "grossMargin" || id === "evEbitda");
+  const listed = symbols.flatMap((symbol) => {
+    const bare = usListing(symbol);
+    return bare ? [{ symbol, bare }] : [];
+  });
+  if (wanted.length === 0 || listed.length === 0) return;
+  const definition: ScreenDefinition = {
+    version: 1,
+    criteria: [{ field: "symbol", op: "in", value: [...new Set(listed.map(({ bare }) => bare))] }],
+    sort: { field: "symbol", direction: "asc" },
+    currency: null,
+  };
+  let rows: ScreenRow[];
+  try {
+    rows = (await fetchScreen(definition, null, ctx.signal, ctx.apiClient)).rows;
+  } catch (error) {
+    out.errors.push(failureMessage(wanted.map((id) => COLUMN_SPECS[id].label).join(" and "), error));
+    return;
+  }
+  for (const { symbol, bare } of listed) {
+    const row = rows.find((candidate) => candidate.symbol.toUpperCase() === bare && isUsListingExchange(candidate.exchange));
+    if (!row) continue;
+    const fields = out.fields.get(symbol)!;
+    if (wanted.includes("grossMargin")) {
+      const gross = metricFields(row.metrics.grossMarginPercent);
+      if (gross) Object.assign(fields, { grossMarginPercent: gross.value, grossMarginSource: gross.source, grossMarginAsOf: gross.asOf });
+    }
+    if (wanted.includes("evEbitda")) {
+      const multiple = metricFields(row.metrics.evToEbitda);
+      if (multiple) Object.assign(fields, { evEbitda: multiple.value, evEbitdaSource: multiple.source, evEbitdaAsOf: multiple.asOf });
+    }
+  }
+}
+
+/** The US-only columns among `ids`, which a listing abroad leaves blank. */
+const US_ONLY: ReadonlySet<ExtraColumnId> = new Set(["shortInterest", "nextEarnings", "grossMargin", "evEbitda"]);
+
+/**
+ * The added fields for every symbol, each column read apart so one that
+ * fails (or is locked) leaves the others: short interest from FINRA's
+ * settlements, the next report date from the earnings calendar, the mean
+ * target and analyst count from analyst research, gross margin and EV/EBITDA
+ * from the screener's stored figures.
+ */
+export async function loadExtraColumns(
+  ids: readonly ExtraColumnId[],
+  symbols: readonly string[],
+  financials: ReadonlyMap<string, TickerFinancials | null>,
+  ctx: HeadlessPaneContext,
+): Promise<ExtraColumnsResult> {
+  const out: ExtraColumnsResult = { fields: new Map(symbols.map((symbol) => [symbol, {}])), errors: [], notes: [] };
+  if (ids.length === 0) return out;
+  await Promise.all([
+    ids.includes("shortInterest") ? loadShortInterestFields(symbols, financials, ctx, out) : null,
+    ids.includes("nextEarnings") ? loadNextEarningsFields(symbols, ctx, out) : null,
+    ids.includes("target") ? loadTargetFields(symbols, ctx, out) : null,
+    loadScreenerFields(ids, symbols, ctx, out),
+  ]);
+  ctx.signal.throwIfAborted();
+  const abroad = symbols.filter((symbol) => !usListing(symbol));
+  const usOnly = ids.filter((id) => US_ONLY.has(id)).map((id) => COLUMN_SPECS[id].label);
+  if (abroad.length > 0 && usOnly.length > 0) {
+    out.notes.push(`${usOnly.join(", ")} cover US listings; ${abroad.join(", ")} ${abroad.length === 1 ? "is" : "are"} left blank.`);
+  }
+  return out;
+}

package/src/plugins/builtin/research/relative-valuation-currency.ts

@@ -0,0 +1,164 @@
+import type { HeadlessPaneContext } from "../../../types/headless";
+import { MarketDataCoordinator, resolveEntryValue } from "../../../market-data/coordinator";
+import { fxLegForCurrency } from "../../../market-data/coordinator/fx-legs";
+import { resolveCurrencyUnit } from "../../../utils/currency-units";
+import { errorMessage } from "../../../utils/errors";
+
+/** One currency's US dollar rate, as the app's FX rates serve it: USD per unit, and when it was observed. */
+export interface UsdRate {
+  rate: number;
+  /** The source's observation time; null when it states none. */
+  asOf: string | null;
+  /** When the rate was read, said in place of an observation time the source does not state. */
+  retrievedAt?: string | null;
+}
+
+/** A rate a market cap was converted at: `to` per `from`, and the older of its two legs' observation times. */
+export interface CapConversion {
+  from: string;
+  to: string;
+  rate: number;
+  asOf: string | null;
+  /** When the rate was read, for a rate whose source states no observation time. */
+  retrievedAt: string | null;
+}
+
+type CapRow = { symbol: string; marketCap: number | null; marketCapCurrency: string | null };
+
+export type ConvertedCapRow<Row extends CapRow> = Row & {
+  /** The cap as the source served it, and its currency, when it was converted. */
+  marketCapNative?: number;
+  marketCapNativeCurrency?: string;
+};
+
+const usable = (rate: number | undefined): rate is number => rate != null && Number.isFinite(rate) && rate > 0;
+
+function olderOf(left: string | null, right: string | null): string | null {
+  if (!left || !right) return left ?? right;
+  return Date.parse(left) <= Date.parse(right) ? left : right;
+}
+
+/**
+ * Every row's market cap in `target`, through each currency's US dollar
+ * rate (a pence cap is first made pounds). A row already in `target`, or
+ * with no cap, stays as it is. A currency with no usable rate leaves its
+ * rows in their own currency and is listed in `unconverted`, so the table
+ * never mixes a guess in.
+ */
+export function convertMarketCaps<Row extends CapRow>(
+  rows: readonly Row[],
+  target: string,
+  rates: ReadonlyMap<string, UsdRate>,
+): { rows: Array<ConvertedCapRow<Row>>; conversions: CapConversion[]; unconverted: Array<{ currency: string; symbols: string[] }> } {
+  const usd = (currency: string): UsdRate | undefined => (currency === "USD" ? { rate: 1, asOf: null } : rates.get(currency));
+  const conversions = new Map<string, CapConversion>();
+  const unconverted = new Map<string, string[]>();
+  const converted = rows.map((row): ConvertedCapRow<Row> => {
+    if (row.marketCap == null || !row.marketCapCurrency || row.marketCapCurrency === target) return row;
+    const unit = resolveCurrencyUnit(row.marketCapCurrency);
+    let rate = 1;
+    if (unit.currency !== target) {
+      const from = usd(unit.currency);
+      const to = usd(target);
+      if (!from || !to || !usable(from.rate) || !usable(to.rate)) {
+        unconverted.set(row.marketCapCurrency, [...unconverted.get(row.marketCapCurrency) ?? [], row.symbol]);
+        return row;
+      }
+      rate = from.rate / to.rate;
+      if (!conversions.has(unit.currency)) {
+        conversions.set(unit.currency, {
+          from: unit.currency, to: target, rate, asOf: olderOf(from.asOf, to.asOf), retrievedAt: olderOf(from.retrievedAt ?? null, to.retrievedAt ?? null),
+        });
+      }
+    }
+    return {
+      ...row,
+      marketCap: row.marketCap / unit.divisor * rate,
+      marketCapCurrency: target,
+      marketCapNative: row.marketCap,
+      marketCapNativeCurrency: row.marketCapCurrency,
+    };
+  });
+  return {
+    rows: converted,
+    conversions: [...conversions.values()],
+    unconverted: [...unconverted].map(([currency, symbols]) => ({ currency, symbols })),
+  };
+}
+
+/** A rate as a dealer quotes it: `EUR/USD 1.1612`, `USD/JPY 151.20`; a cross of two other currencies as `from/to`. */
+export function conversionPairText({ from, to, rate }: Pick<CapConversion, "from" | "to" | "rate">): string {
+  const figure = (value: number) => value.toPrecision(5);
+  if (from !== "USD" && to !== "USD") return `${from}/${to} ${figure(rate)}`;
+  const other = to === "USD" ? from : to;
+  const usdPerOther = to === "USD" ? rate : 1 / rate;
+  const perDollar = fxLegForCurrency(other)?.invert ?? true;
+  return perDollar ? `USD/${other} ${figure(1 / usdPerOther)}` : `${other}/USD ${figure(usdPerOther)}`;
+}
+
+/** `2026-10-13 21:00 UTC`, or `2026-10-13` for a date. */
+function rateTimeText(asOf: string): string {
+  const time = Date.parse(asOf);
+  if (!Number.isFinite(time)) return asOf;
+  return /^\d{4}-\d{2}-\d{2}$/.test(asOf) ? asOf : `${new Date(time).toISOString().slice(0, 16).replace("T", " ")} UTC`;
+}
+
+/**
+ * The status line's note naming each rate and its date:
+ * `market caps in USD at EUR/USD 1.1612 (2026-10-13 21:00 UTC)`.
+ */
+export function conversionNote(target: string, conversions: readonly CapConversion[]): string | null {
+  if (conversions.length === 0) return null;
+  const rates = conversions.map((conversion) => `${conversionPairText(conversion)} (${conversion.asOf ? rateTimeText(conversion.asOf)
+    : conversion.retrievedAt ? `retrieved ${rateTimeText(conversion.retrievedAt)}` : "time not stated"})`);
+  return `market caps in ${target} at ${rates.join(", ")}`;
+}
+
+/**
+ * The US dollar rate of each currency through the app's FX path (the market
+ * data coordinator's `loadFxRate`, which converted totals read), a pence code
+ * as its pound. A currency whose rate fails is listed in `failed` with why.
+ */
+export async function loadFxLegs(
+  currencies: readonly string[],
+  ctx: Pick<HeadlessPaneContext, "marketData">,
+): Promise<{ legs: Map<string, UsdRate>; failed: Array<{ currency: string; reason: string }> }> {
+  const wanted = [...new Set(currencies.map((currency) => resolveCurrencyUnit(currency).currency).filter((currency) => currency && currency !== "USD"))];
+  const legs = new Map<string, UsdRate>();
+  const failed: Array<{ currency: string; reason: string }> = [];
+  if (wanted.length === 0) return { legs, failed };
+  const coordinator = new MarketDataCoordinator(ctx.marketData);
+  try {
+    await Promise.all(wanted.map(async (currency) => {
+      try {
+        const entry = await coordinator.loadFxRate(currency);
+        const rate = resolveEntryValue(entry);
+        if (!usable(rate ?? undefined)) throw new Error(entry.error?.message ?? "no usable rate");
+        const time = (value: number | null | undefined) => (value != null && Number.isFinite(value) ? new Date(value).toISOString() : null);
+        legs.set(currency, { rate: rate!, asOf: time(entry.asOf), retrievedAt: time(entry.fetchedAt) });
+      } catch (error) {
+        failed.push({ currency, reason: errorMessage(error) });
+      }
+    }));
+  } finally {
+    coordinator.destroy();
+  }
+  return { legs, failed };
+}
+
+const CURRENCY_CODE = /^[A-Z]{3}$/;
+
+/** `--currency`: a three-letter code the runtime knows, upper-cased. */
+export function normalizeCapCurrency(value: string): string {
+  const code = value.trim().toUpperCase();
+  let known: readonly string[] = [];
+  try {
+    known = Intl.supportedValuesOf("currency");
+  } catch {
+    // An older runtime lists none; the shape check stands alone.
+  }
+  if (!CURRENCY_CODE.test(code) || (known.length > 0 && !known.includes(code))) {
+    throw new Error(`Invalid --currency value "${value}". Use a three-letter currency code such as USD or EUR.`);
+  }
+  return code;
+}

package/src/plugins/builtin/research/relative-valuation-headless.ts

@@ -1,11 +1,16 @@
 import { formatPriceEarnings, NOT_MEANINGFUL, PRICE_EARNINGS_NOTICE } from "../../../utils/price-earnings";
-import type { HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/headless";
+import type { HeadlessPaneColumn, HeadlessPaneContext, HeadlessPaneDefinition } from "../../../types/headless";
 import { EXTENDED_SESSION_LABELS, type ExtendedSession } from "../../../market-data/market/status";
 import { formatCompact, formatCurrency, formatLevelPercent, formatNumber, formatPercent, formatPercentRaw } from "../../../utils/format";
 import { loadHeadlessFinancials, loadHeadlessSymbols } from "../shared/headless-market-data";
 import { quoteFreshnessFields } from "../shared/report-freshness";
 import { RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE, RELATIVE_VALUATION_STALE_QUOTE_NOTICE, relativeValuationValues } from "./relative-valuation-model";
 import { paneSchemas } from "./headless-schema";
+import { isRecord } from "../../../utils/guards";
+import { resolveCurrencyUnit } from "../../../utils/currency-units";
+import { pickPeers, peerMethodTitle, type PeerSelection } from "./relative-valuation-peers";
+import { extraColumns, loadExtraColumns, parseExtraColumns } from "./relative-valuation-columns";
+import { conversionNote, convertMarketCaps, loadFxLegs } from "./relative-valuation-currency";
 
 const price = (value: unknown, row: Record<string, unknown>) => (
   value == null || !row.currency ? "-" : formatCurrency(Number(value), String(row.currency))
@@ -46,7 +51,9 @@ const VALUATION_COLUMNS: HeadlessPaneColumn[] = [
   })),
   ...[["evSales", "EV/S"]].map(([key, header]) => ({
     key: key!, header: header!, align: "right" as const,
-    format: (value: unknown) => value == null ? "-" : formatNumber(Number(value), 1),
+    // A withdrawn EV says so rather than leaving a bare dash; the note under the table says why.
+    format: (value: unknown, row: Record<string, unknown>) => value != null ? formatNumber(Number(value), 1)
+      : row.evSalesUnavailable ? "EV unavailable" : "-",
   })),
   ...[["fcfYield", "FCF Yield"], ["revenueGrowth", "Quarter Revenue YoY"], ["operatingMargin", "TTM Op Margin"]].map(([key, header]) => ({
     key: key!, header: header!, align: "right" as const,
@@ -54,36 +61,112 @@ const VALUATION_COLUMNS: HeadlessPaneColumn[] = [
   })),
 ];
 
+/** Peers `--peers` chose, as the expansion left them in the settings or the load picked them. */
+function peerSelectionOf(value: unknown, symbols: readonly string[]): PeerSelection | null {
+  if (!isRecord(value) || typeof value.subject !== "string" || !Array.isArray(value.peers)) return null;
+  const selection = value as unknown as PeerSelection;
+  const expected = [selection.subject, ...selection.peers];
+  return expected.length === symbols.length && expected.every((symbol, index) => symbol.toUpperCase() === symbols[index]?.toUpperCase())
+    ? selection : null;
+}
+
+/** The peers of the one symbol `--peers` was given; several symbols are already a peer list. */
+async function choosePeers(symbols: readonly string[], ctx: HeadlessPaneContext): Promise<PeerSelection> {
+  if (symbols.length !== 1) {
+    throw new Error(`--peers picks the peers of one symbol, such as RV ${symbols[0] ?? "DUOL"} --peers; with several symbols, leave it out.`);
+  }
+  const subject = symbols[0]!;
+  return pickPeers(subject, await loadHeadlessFinancials(ctx, subject).catch(() => null), ctx);
+}
+
+const PEER_SELECTION_SETTING = "peerSelection";
+
 export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
   ...paneSchemas["relative-valuation-pane"],
+  freshness: { datesEachVenue: true },
   shape: "rows",
-  describe: ({ symbols }) => `Relative Valuation | ${symbols.join(", ")}`,
+  describe: ({ symbols }, result) => {
+    const selection = peerSelectionOf(result?.metadata?.peerSelection, result?.symbols ?? symbols);
+    return selection
+      ? `Relative Valuation | ${selection.subject} and ${peerMethodTitle(selection)}`
+      : `Relative Valuation | ${(result?.symbols ?? symbols).join(", ")}`;
+  },
   columns: [...QUOTE_COLUMNS, ...VALUATION_COLUMNS],
-  async load({ symbols }, ctx) {
+  async expandArgument(args, ctx) {
+    if (args.options.peers !== true) return null;
+    const selection = await choosePeers(args.symbols, ctx);
+    return {
+      argument: [selection.subject, ...selection.peers].join(", "),
+      settings: { [PEER_SELECTION_SETTING]: selection },
+      title: `RV ${selection.subject} + ${peerMethodTitle(selection, { automatic: true })}`,
+    };
+  },
+  async load(args, ctx) {
+    // --peers picked in advance (fn and shot) reads the same peers; any other caller picks them here.
+    const preset = args.options.peers === true ? peerSelectionOf(ctx.settings?.[PEER_SELECTION_SETTING], args.symbols) : null;
+    const selection = args.options.peers === true ? preset ?? await choosePeers(args.symbols, ctx) : null;
+    const symbols = selection ? [selection.subject, ...selection.peers] : args.symbols;
     const loaded = await loadHeadlessSymbols(symbols, ctx, (symbol) => loadHeadlessFinancials(ctx, symbol));
-    const rows = loaded.entries.map(({ symbol, data }) => ({ symbol, ...relativeValuationValues(data), ...quoteFreshnessFields(data?.quote) }));
-    const unavailableSymbols = [...loaded.unavailableSymbols, ...rows.filter((row) => ![
+    const baseRows = loaded.entries.map(({ symbol, data }) => ({ symbol, ...relativeValuationValues(data), ...quoteFreshnessFields(data?.quote) }));
+    const unavailableSymbols = [...loaded.unavailableSymbols, ...baseRows.filter((row) => ![
       row.marketCap, row.trailingPE, row.forwardPE, row.evSales, row.fcfYield, row.revenueGrowth, row.operatingMargin,
     ].some((value) => value != null)).map(({ symbol }) => symbol)];
-    const staleSymbols = rows.filter((row) => row.quoteStale).map((row) => row.symbol);
-    const staleFundamentalsSymbols = rows.filter((row) => row.fundamentalsProvenance?.stale).map((row) => row.symbol);
+    const staleSymbols = baseRows.filter((row) => row.quoteStale).map((row) => row.symbol);
+    const staleFundamentalsSymbols = baseRows.filter((row) => row.fundamentalsProvenance?.stale).map((row) => row.symbol);
+
+    // --currency: every cap in one currency, at the rates the app converts with.
+    const capCurrency = typeof args.options.currency === "string" ? args.options.currency : null;
+    const fx = capCurrency ? await loadFxLegs([capCurrency, ...baseRows.flatMap((row) => row.marketCapCurrency ?? [])], ctx) : null;
+    const converted = capCurrency && fx ? convertMarketCaps(baseRows, capCurrency, fx.legs) : null;
+    const capRows = converted?.rows ?? baseRows;
+
+    // --columns: each added column read from the path its own function uses.
+    const extraIds = parseExtraColumns(args.options.columns);
+    const financials = new Map(loaded.entries.map(({ symbol, data }) => [symbol, data] as const));
+    const extra = await loadExtraColumns(extraIds, capRows.map((row) => row.symbol), financials, ctx);
+    const rows = capRows.map((row) => ({ ...row, ...extra.fields.get(row.symbol) }));
+
     const errors = [...loaded.errors,
       ...staleSymbols.map((symbol) => `${symbol}: ${RELATIVE_VALUATION_STALE_QUOTE_NOTICE}`),
       ...staleFundamentalsSymbols.map((symbol) => `${symbol}: ${RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE}`),
+      ...extra.errors,
+    ];
+    const warnings = converted?.unconverted.map(({ currency, symbols: left }) => {
+      const reason = fx?.failed.find((failure) => failure.currency === resolveCurrencyUnit(currency).currency)?.reason;
+      return `No ${currency} rate${reason ? ` (${reason})` : ""}: ${left.join(", ")} ${left.length === 1 ? "keeps its" : "keep their"} market cap in ${currency}.`;
+    }) ?? [];
+    const conversionText = capCurrency && converted ? conversionNote(capCurrency, converted.conversions) : null;
+    const notes = [
+      ...selection ? [`Peers chosen automatically: ${selection.basis}. To choose your own: gloomberb fn RV ${selection.subject} <tickers>.`] : [],
+      ...extra.notes,
     ];
     // Last and Chg% are the regular session; an extended print gets a column only when a peer has one.
     const extendedSessions = (["PRE", "POST", "OVERNIGHT"] as const).filter((session) => rows.some((row) => row.extendedSession === session));
+    const columns = [...QUOTE_COLUMNS, ...extendedSessions.map(extendedColumn), ...VALUATION_COLUMNS];
+    const added = extraIds.length > 0 ? extraColumns(extraIds) : null;
     return {
       rows, unavailableSymbols, errors, complete: unavailableSymbols.length === 0 && errors.length === 0,
-      ...(extendedSessions.length > 0 ? { columns: [...QUOTE_COLUMNS, ...extendedSessions.map(extendedColumn), ...VALUATION_COLUMNS] } : {}),
+      ...(selection ? { symbols } : {}),
+      ...(added ? { columns: [...columns, ...added.export], textColumns: [...columns, ...added.text] }
+        : extendedSessions.length > 0 ? { columns } : {}),
+      ...(notes.length > 0 ? { notes } : {}),
+      ...(warnings.length > 0 ? { warnings } : {}),
+      ...(conversionText ? { freshness: { note: conversionText } } : {}),
       metadata: {
         staleSymbols,
         staleFundamentalsSymbols,
+        ...(selection ? { peerSelection: selection } : {}),
+        ...(converted && capCurrency ? { marketCapConversion: { currency: capCurrency, rates: converted.conversions,
+          basis: "marketCap is converted into the asked currency at each currency's US dollar rate, the rate the app's converted totals use; marketCapNative and marketCapNativeCurrency keep the cap as served." } } : {}),
+        ...(extraIds.length > 0 ? { addedColumnsBasis: "Each added column keeps its own source and as-of beside it: short interest at its FINRA settlement date, analyst targets at retrieval, the next earnings date at the calendar's retrieval, gross margin and EV/EBITDA at the screener's statement date." } : {}),
         quoteBasis: "Stale quote fields are excluded from comparison; reportedQuote retains the rejected observation and quoteAsOf retains its source timestamp.",
         priceBasis: "price, change and changePercent are the regular session: after the close, its close and that close's move. A pre-market, after-hours or overnight print is in extendedPrice, extendedChange and extendedChangePercent, measured from that close (extendedMark when it is a bid and ask midpoint). marketCap, the P/E multiples, evSales (through the equity part of the enterprise value) and fcfYield are measured at that regular session price.",
         fundamentalsBasis: "Provider multiples and operating metrics retain independent fundamentalsProvenance. Retrieval time does not establish the valuation date.",
-        notices: rows.some((row) => Object.keys(row.notMeaningful).length > 0
-          || Object.values(row.reportedMultiples).some((value) => value != null && value <= 0)) ? [PRICE_EARNINGS_NOTICE] : [],
+        notices: [
+          ...rows.some((row) => Object.keys(row.notMeaningful).length > 0
+            || Object.values(row.reportedMultiples).some((value) => value != null && value <= 0)) ? [PRICE_EARNINGS_NOTICE] : [],
+          ...rows.flatMap((row) => row.evSalesUnavailable ? [`${row.symbol}: ${row.evSalesUnavailable}`] : []),
+        ],
         multipleBasis: "Comparable P/E fields require a positive finite multiple over positive EPS; notMeaningful says why one is null, and reportedMultiples preserves the finite provider values.",
         marketCapBasis: "Market caps retain their own currency and source. Fundamentals retrieval time is not a valuation date; quote timestamps do not date fallback caps.",
       },

package/src/plugins/builtin/research/relative-valuation-model.ts

@@ -1,6 +1,6 @@
 import { comparablePriceEarnings, notMeaningfulMultiples } from "../../../utils/price-earnings";
 import { selectMarketCapitalization } from "../../../utils/market-capitalization";
-import { reportedEnterpriseValue } from "../../../utils/fundamentals";
+import { enterpriseValueReconciliationNote, enterpriseValueWithdrawn, reportedEnterpriseValue } from "../../../utils/fundamentals";
 import { getExtendedSessionDisplay, getQuoteSessionFields } from "../../../market-data/market/status";
 import { atRegularSessionPrice, movePriceDerivedFigures } from "../../../market-data/quotes/regular-session-valuation";
 import type { Quote, TickerFinancials } from "../../../types/financials";
@@ -70,6 +70,9 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
         ? fundamentals.enterpriseToRevenue
         : enterpriseValue != null && fundamentals?.revenue != null && fundamentals.revenue > 0
           ? enterpriseValue / fundamentals.revenue : null,
+    /** Why EV/S is missing when the provider's EV was withdrawn, as `valuation` says it; null otherwise. */
+    evSalesUnavailable: enterpriseValueWithdrawn(fundamentals)
+      ? enterpriseValueReconciliationNote(fundamentals) ?? "EV unavailable." : null,
     fcfYield: capitalization && fundamentals?.financialCurrency === capitalization.currency
       && fundamentals.freeCashFlow != null && Number.isFinite(fundamentals.freeCashFlow) && capitalization.value > 0
       ? fundamentals.freeCashFlow / capitalization.value : null,