gloomberb 0.16.6 → 0.17.0

package/src/cli/commands/ticker.ts

@@ -34,6 +34,7 @@ import { futuresContractLines, futuresSettleText, isFuturesInstrument, loadFutur
 import type { AppConfig } from "../../types/config";
 import type { FinancialStatement, Quote, TickerFinancials } from "../../types/financials";
 import { quoteTradingDay } from "../../market-data/quotes/day-range";
+import { atRegularSessionPrice } from "../../market-data/quotes/regular-session-valuation";
 import { computeTickerPriceReturns } from "../../market-data/ticker-price-returns";
 import { instrumentTypeLabel, isCryptoVenuePerpetual, resolveTickerInstrumentKind } from "../../tickers/instrument-kind";
 import type { SecFilingItem } from "../../types/data-provider";
@@ -324,6 +325,8 @@ interface FundamentalsMetric {
   text: string;
   value?: number | string | null;
   unit?: string;
+  /** A figure the text prints inside another line, which CSV gives a row of its own. */
+  exportOnly?: boolean;
 }
 
 type MetricFigure = Omit<FundamentalsMetric, "label">;
@@ -395,7 +398,7 @@ function fundamentalsMetrics(
 }
 
 function metricLines(metrics: readonly FundamentalsMetric[]): Array<[string, string]> {
-  return metrics.map((metric) => [metric.label, metric.text]);
+  return metrics.filter((metric) => !metric.exportOnly).map((metric) => [metric.label, metric.text]);
 }
 
 const TRAILING_MONEY_METRICS = new Set(["EPS (TTM)", "Revenue (TTM)", "Net Income (TTM)", "Operating Cash Flow (TTM)", "Free Cash Flow (TTM)"]);
@@ -437,8 +440,53 @@ function fundFactsNote(
   return !exchange || isUsListingExchange(exchange) ? `${note}; try fn SEC ${symbol}.` : `${note}.`;
 }
 
-/** The lines `fundamentals` or `valuation` reports, the ones with a value. */
-function fundamentalsReportMetrics(financials: FundamentalsReportData, view: "fundamentals" | "valuation"): FundamentalsMetric[] {
+/**
+ * The price a valuation is measured at, as `quote` and `ticker` read it: Last
+ * and Change are the regular session (after the close, its close and that
+ * close's move), and a pre-market, after-hours or overnight print is a line
+ * of its own, measured from that close.
+ */
+function valuationPriceMetrics(financials: FundamentalsReportData): FundamentalsMetric[] {
+  const quote = financials.quote;
+  const session = getRegularSessionDisplay(quote);
+  if (!quote || !session) return [];
+  const options = withCurrencyMinorDigits(quoteFormatOptions(quote, undefined, financials.quoteMetadata?.instrumentType), quote.currency);
+  const price = (value: number) => formatMarketPriceWithCurrency(value, quote.currency, options);
+  const extended = getExtendedSessionDisplay(quote);
+  const extendedLabel = extended ? EXTENDED_SESSION_LABELS[extended.session] : "";
+  return [
+    { label: "Last", text: price(session.price), value: session.price, unit: quote.currency },
+    session.changePercent != null && Number.isFinite(session.changePercent)
+      ? {
+        label: "Change",
+        text: colorBySign(`${formatMarketChangeWithCurrency(session.change, quote.currency, options, session.price)} (${formatPercentRaw(session.changePercent)})`, session.change),
+        value: session.changePercent,
+        unit: "%",
+      }
+      : { label: "Change", text: "—" },
+    ...extended ? [
+      {
+        label: extendedLabel,
+        // "mid" when the overnight price is the session's bid and ask midpoint, as `quote` marks it.
+        text: colorBySign(`${price(extended.price)}${extended.mark ? " mid" : ""}${extended.changePercent != null ? ` (${formatPercentRaw(extended.changePercent)})` : ""}`, extended.change),
+        value: extended.price,
+        unit: quote.currency,
+      },
+      extended.changePercent != null
+        ? { label: `${extendedLabel} Change`, text: formatPercentRaw(extended.changePercent), value: extended.changePercent, unit: "%", exportOnly: true }
+        : { label: `${extendedLabel} Change`, text: "—" },
+    ] : [],
+  ];
+}
+
+/**
+ * The lines `fundamentals` or `valuation` reports, the ones with a value.
+ * Market cap, the P/E multiples and the dividend yield are measured at the
+ * regular session price (atRegularSessionPrice), which `valuation` names in
+ * its first lines.
+ */
+function fundamentalsReportMetrics(snapshot: FundamentalsReportData, view: "fundamentals" | "valuation"): FundamentalsMetric[] {
+  const financials = atRegularSessionPrice(snapshot);
   const quote = financials.quote;
   const fundamentals = financials.fundamentals;
   const capitalization = selectMarketCapitalization(quote, fundamentals);
@@ -446,9 +494,10 @@ function fundamentalsReportMetrics(financials: FundamentalsReportData, view: "fu
     ? { text: `${formatCompact(capitalization.value)} ${capitalization.currency}`, value: capitalization.value, unit: capitalization.currency }
     : { text: "—" };
   const metrics = fundamentalsMetrics(quote, fundamentals, financials.profile, marketCap, computeTickerPriceReturns(financials), fundamentalsCurrency(financials));
-  return (view === "valuation"
-    ? metrics.filter(({ label }) => VALUATION_METRICS.has(label) || label.startsWith("Dividend Yield"))
-    : metrics).filter((metric) => metric.text !== "—");
+  if (view === "fundamentals") return metrics.filter((metric) => metric.text !== "—");
+  const valuation = metrics.filter(({ label, text }) => (VALUATION_METRICS.has(label) || label.startsWith("Dividend Yield")) && text !== "—");
+  // A listing with no valuation (a fund) says so rather than printing its price alone.
+  return valuation.length === 0 ? [] : [...valuationPriceMetrics(financials).filter((metric) => metric.text !== "—"), ...valuation];
 }
 
 /** Text for `gloomberb fundamentals` and `gloomberb valuation`: the ticker report's fundamentals without the rest. */
@@ -616,7 +665,9 @@ export async function buildTickerReport({
     lines.push(cliStyles.muted(membershipParts.join(METADATA_SEPARATOR)));
   }
 
-  const capitalization = selectMarketCapitalization(quote, fundamentals);
+  // Market cap and the multiples are measured at the regular session price the Quote section heads with.
+  const priced = atRegularSessionPrice(financials);
+  const capitalization = selectMarketCapitalization(priced.quote, priced.fundamentals);
   const convertedMarketCap = capitalization ? await toBase(capitalization.value, capitalization.currency) : Number.NaN;
   const marketCapText = capitalization
     ? Number.isFinite(convertedMarketCap)
@@ -624,7 +675,7 @@ export async function buildTickerReport({
       : `${formatCompact(capitalization.value)} ${capitalization.currency}`
     : "—";
   // Shown in the same currency as the market cap, so the two can be compared.
-  const enterpriseValue = reportedEnterpriseValue(fundamentals);
+  const enterpriseValue = reportedEnterpriseValue(priced.fundamentals);
   const evCurrency = enterpriseValueCurrency(quote, fundamentals);
   // A minor unit such as GBp stays as reported: the converter would read it as the major currency.
   const convertedEnterpriseValue = enterpriseValue != null && evCurrency && /^[A-Z]{3}$/.test(evCurrency)
@@ -672,7 +723,7 @@ export async function buildTickerReport({
     ]);
   }
 
-  const metrics = fundamentalsMetrics(quote, fundamentals, profile, { text: marketCapText }, priceReturns, fundamentalsCurrency(financials), { text: enterpriseValueText });
+  const metrics = fundamentalsMetrics(quote, priced.fundamentals, profile, { text: marketCapText }, priceReturns, fundamentalsCurrency(financials), { text: enterpriseValueText });
   const beforeFundamentals = lines.length;
   appendMetricSection(lines, "Fundamentals", metricLines(metrics));
   for (const note of trailingConversionNotes(fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
@@ -759,6 +810,8 @@ function buildTickerStructuredData({
   const quote = financials.quote;
   const priceReturns = computeTickerPriceReturns(financials, tickerFile?.metadata.assetCategory);
   const identity = listingIdentity(listing, quote);
+  // Market cap and the multiples at the regular session price, as the text report gives them.
+  const priced = atRegularSessionPrice(financials);
   return {
     symbol,
     listing: { symbol: identity.symbol, exchange: identity.exchange || null, name: identity.name },
@@ -770,7 +823,7 @@ function buildTickerStructuredData({
       ...getQuoteSessionFields(quote),
       priceBasis: quote.priceBasis ?? null,
       currency: quote.currency,
-      marketCap: quote.marketCap ?? null,
+      marketCap: priced.quote?.marketCap ?? null,
       volume: quote.volume ?? null,
       exchangeName: quote.exchangeName ?? "",
       fullExchangeName: quote.fullExchangeName ?? "",
@@ -794,7 +847,7 @@ function buildTickerStructuredData({
       positions: tickerFile.metadata.positions,
     } : null,
     fundamentals: financials.fundamentals || priceReturns.return1Y != null || priceReturns.return3Y != null ? exportedFundamentals({
-      ...financials.fundamentals,
+      ...priced.fundamentals,
       ...priceReturns,
     }) : undefined,
     profile: financials.profile,

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

@@ -0,0 +1,114 @@
+import { existsSync } from "fs";
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { buildViewBundle, electrobunViewPath, readViewStylesheet } from "../renderers/dom/build-assets";
+
+/**
+ * The page `shot` and rendered `fn` reports draw a pane in: the view bundle,
+ * the chunks it loads later (the world map's land, the docs) and the
+ * stylesheet, by path under the page's root. What changes per capture, the
+ * pane and its data, goes in the page's HTML instead (desktop-pane-shot.ts).
+ *
+ * A source checkout builds these on first use. The release binary has no
+ * sources to build from, so scripts/build.ts builds them once, packs them
+ * with `packShotView` and embeds the archive, which its entry hands to
+ * `usePrebuiltShotView` before the CLI starts. The desktop app ships the same
+ * archive alongside its CLI entry rather than embedding it in an executable.
+ */
+export type ShotViewFiles = ReadonlyMap<string, string>;
+
+const SHOT_VIEW_ENTRY = "cli-pane-shot-entry.tsx";
+/** The bundle the page loads, named after its entry. */
+export const SHOT_VIEW_SCRIPT = "cli-pane-shot-entry.js";
+export const SHOT_VIEW_STYLESHEET = "styles.css";
+export const SHOT_VIEW_ARCHIVE = "shot-view.json.gz";
+
+const MISSING_VIEW_MESSAGE = "This copy of Gloomberb cannot draw panes: it was built without the page they are drawn in. "
+  + "Reinstall or update Gloomberb. The standalone gloomberb binary "
+  + "(https://github.com/gloom-sh/gloomberb/releases/latest) also includes it.";
+
+let prebuiltArchive: string | null = null;
+let loading: Promise<ShotViewFiles> | null = null;
+
+/** Builds the page's files into `outdir`, for a capture or for scripts/build.ts to embed. */
+export async function buildShotView(outdir: string, apiUrl: string): Promise<void> {
+  await buildViewBundle({
+    entrypoint: electrobunViewPath(SHOT_VIEW_ENTRY),
+    outdir,
+    sourcemap: "none",
+    // The page has no `process`, so the cloud endpoint is baked in.
+    define: { __GLOOMBERB_API_URL__: JSON.stringify(apiUrl) },
+    aliasRules: [
+      ["backend-rpc", "native-stubs/backend-rpc.ts"],
+    ],
+    failureMessage: "Failed to build desktop pane screenshot renderer.",
+    missingEntryMessage: "Desktop pane screenshot build did not produce a JavaScript entrypoint.",
+  });
+  await Bun.write(join(outdir, SHOT_VIEW_STYLESHEET), await readViewStylesheet());
+}
+
+async function readShotViewDir(dir: string): Promise<Map<string, string>> {
+  const files = new Map<string, string>();
+  for await (const path of new Bun.Glob("**/*").scan({ cwd: dir })) {
+    files.set(path.replaceAll("\\", "/"), await Bun.file(join(dir, path)).text());
+  }
+  return files;
+}
+
+/** The files `buildShotView` wrote, as one gzipped JSON object of path to text. */
+export async function packShotView(dir: string): Promise<Uint8Array> {
+  const json = JSON.stringify(Object.fromEntries(await readShotViewDir(dir)));
+  return Bun.gzipSync(new TextEncoder().encode(json), { level: 9 });
+}
+
+/**
+ * Serve the page from the archive at `archivePath` rather than building it.
+ * @knipignore Called by the entry scripts/build.ts writes for the release binary.
+ */
+export function usePrebuiltShotView(archivePath: string): void {
+  prebuiltArchive = archivePath;
+  loading = null;
+}
+
+/** The page's files, read or built once per process. */
+export function loadShotView(): Promise<ShotViewFiles> {
+  loading ??= (prebuiltArchive ? unpackShotView(prebuiltArchive) : buildShotViewFromSource()).catch((error: unknown) => {
+    loading = null;
+    throw error;
+  });
+  return loading;
+}
+
+async function unpackShotView(archivePath: string): Promise<ShotViewFiles> {
+  const file = Bun.file(archivePath);
+  if (!(await file.exists())) throw new Error(MISSING_VIEW_MESSAGE);
+  const json = new TextDecoder().decode(Bun.gunzipSync(await file.bytes()));
+  return completeShotView(new Map(Object.entries(JSON.parse(json) as Record<string, string>)));
+}
+
+async function buildShotViewFromSource(): Promise<ShotViewFiles> {
+  // A bundle of the CLI without its sources, and without the page embedded.
+  if (!existsSync(electrobunViewPath(SHOT_VIEW_ENTRY))) throw new Error(MISSING_VIEW_MESSAGE);
+  const dir = await mkdtemp(join(tmpdir(), "gloom-pane-shot-view-"));
+  try {
+    await buildShotView(dir, process.env.GLOOMBERB_API_URL ?? "");
+    return completeShotView(await readShotViewDir(dir));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The page's files, once every file it needs is there: the bundle, the
+ * stylesheet, and each chunk the bundle loads by path (`import("./x.chunk.js")`,
+ * see build-assets.ts), which a pane would otherwise only miss when it draws.
+ */
+function completeShotView(files: Map<string, string>): ShotViewFiles {
+  const script = files.get(SHOT_VIEW_SCRIPT);
+  if (script === undefined || !files.has(SHOT_VIEW_STYLESHEET)) throw new Error(MISSING_VIEW_MESSAGE);
+  for (const [, chunk] of script.matchAll(/["']\.\/([\w./-]+\.chunk\.js)["']/g)) {
+    if (!files.has(chunk!)) throw new Error(MISSING_VIEW_MESSAGE);
+  }
+  return files;
+}

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

@@ -1,7 +1,7 @@
 import type { TapeCapture } from "../plugins/builtin/time-sales/snapshot-client";
 import { mkdir, mkdtemp, rm, writeFile } from "fs/promises";
 import { tmpdir } from "os";
-import { join, resolve, sep } from "path";
+import { join } from "path";
 import { encodeRpcValue } from "../renderers/electrobun/shared/rpc-codec";
 import type { AppConfig } from "../types/config";
 import type { ChartResolutionResult } from "../time-series/types";
@@ -21,10 +21,8 @@ import { readVisibleKeyValues } from "./visible-key-values";
 import { scrollTruncationReasons } from "./scroll-truncation";
 import { SHOT_API_PROXY_PREFIX, SHOT_HTTP_BRIDGE_PATH, SHOT_MARKET_BRIDGE_PATH } from "./desktop-pane-shot-routes";
 import { SESSION_COOKIE_NAMES } from "../api-client/session-cookie";
-import {
-  electrobunViewPath,
-  writeElectrobunViewPage,
-} from "../renderers/dom/build-assets";
+import { renderElectrobunViewHtml } from "../renderers/dom/build-assets";
+import { loadShotView, SHOT_VIEW_SCRIPT, SHOT_VIEW_STYLESHEET, type ShotViewFiles } from "./desktop-pane-shot-view";
 import { errorMessage } from "../utils/errors";
 
 export interface DesktopPaneShotIntradayHistory {
@@ -208,14 +206,12 @@ export async function renderDesktopPaneScreenshot(
   apiProxy: DesktopPaneShotApiProxy,
   options: { captureImage?: boolean; bridge?: DesktopPaneShotBridge; statusLine?: ShotStatusLine } = {},
 ): Promise<DesktopPaneShotRenderResult> {
+  const chrome = await findChromeExecutable();
+  const view = await loadShotView();
   const tempDir = await mkdtemp(join(tmpdir(), "gloom-pane-shot-"));
   let server: ReturnType<typeof Bun.serve> | null = null;
   try {
-    const outdir = join(tempDir, "assets");
-    await mkdir(outdir, { recursive: true });
-    await buildShotPage(outdir, payload);
-    server = serveShotPage(outdir, apiProxy, options.bridge ?? null);
-    const chrome = await findChromeExecutable();
+    server = serveShotPage(view, shotPageHtml(view, payload), apiProxy, options.bridge ?? null);
     return await capturePageScreenshot({
       chrome,
       url: new URL("/", server.url).href,
@@ -234,16 +230,12 @@ export async function renderDesktopPaneScreenshot(
   }
 }
 
-async function buildShotPage(outdir: string, payload: DesktopPaneShotPayload): Promise<string> {
+/** The page for one capture: the shared view, with this capture's pane and data in its bootstrap script. */
+function shotPageHtml(view: ShotViewFiles, payload: DesktopPaneShotPayload): string {
   const payloadJson = JSON.stringify(encodeRpcValue(payload)).replace(/</g, "\\u003c");
-  return writeElectrobunViewPage({
-    entrypoint: electrobunViewPath("cli-pane-shot-entry.tsx"),
-    outdir,
-    aliasRules: [
-      ["backend-rpc", "native-stubs/backend-rpc.ts"],
-    ],
-    failureMessage: "Failed to build desktop pane screenshot renderer.",
-    missingEntryMessage: "Desktop pane screenshot build did not produce a JavaScript entrypoint.",
+  return renderElectrobunViewHtml({
+    stylesheet: view.get(SHOT_VIEW_STYLESHEET) ?? "",
+    entrySrc: `./${SHOT_VIEW_SCRIPT}`,
     title: "Gloomberb Pane Shot",
     loadingText: "Rendering pane...",
     bootstrapScript: `
@@ -275,11 +267,11 @@ async function buildShotPage(outdir: string, payload: DesktopPaneShotPayload): P
 }
 
 function serveShotPage(
-  outdir: string,
+  view: ShotViewFiles,
+  html: string,
   apiProxy: DesktopPaneShotApiProxy,
   bridge: DesktopPaneShotBridge | null,
 ): ReturnType<typeof Bun.serve> {
-  const staticRoot = resolve(outdir);
   return Bun.serve({
     hostname: "127.0.0.1",
     port: 0,
@@ -295,7 +287,7 @@ function serveShotPage(
       if (url.pathname === SHOT_HTTP_BRIDGE_PATH) {
         return runShotHttpBridge(request, bridge);
       }
-      return serveShotAsset(url, staticRoot);
+      return serveShotAsset(url, view, html);
     },
   });
 }
@@ -330,21 +322,22 @@ async function runShotHttpBridge(
   }
 }
 
-async function serveShotAsset(url: URL, staticRoot: string): Promise<Response> {
+function serveShotAsset(url: URL, view: ShotViewFiles, html: string): Response {
   let pathname: string;
   try {
     pathname = decodeURIComponent(url.pathname);
   } catch {
     return new Response("Bad request", { status: 400 });
   }
-  const relativePath = pathname === "/" ? "index.html" : pathname.replace(/^\/+/, "");
-  const filePath = resolve(staticRoot, relativePath);
-  if (filePath !== staticRoot && !filePath.startsWith(`${staticRoot}${sep}`)) {
-    return new Response("Not found", { status: 404 });
+  if (pathname === "/" || pathname === "/index.html") {
+    return new Response(html, { headers: { "Content-Type": "text/html; charset=utf-8" } });
   }
-  const file = Bun.file(filePath);
-  if (!(await file.exists())) return new Response("Not found", { status: 404 });
-  return new Response(file);
+  const path = pathname.replace(/^\/+/, "");
+  const body = view.get(path);
+  if (body === undefined) return new Response("Not found", { status: 404 });
+  // A module script is only run when served as JavaScript.
+  const type = path.endsWith(".js") ? "text/javascript" : path.endsWith(".css") ? "text/css" : "text/plain";
+  return new Response(body, { headers: { "Content-Type": `${type}; charset=utf-8` } });
 }
 
 async function proxyShotApiRequest(
@@ -427,15 +420,21 @@ async function findChromeExecutable(): Promise<string> {
     "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
     "/Applications/Chromium.app/Contents/MacOS/Chromium",
     Bun.which("google-chrome"),
+    Bun.which("google-chrome-stable"),
     Bun.which("chromium"),
     Bun.which("chromium-browser"),
+    // Windows installs Chrome outside PATH, per machine or per user.
+    ...["PROGRAMFILES", "PROGRAMFILES(X86)", "LOCALAPPDATA"].map((name) => {
+      const dir = process.env[name];
+      return dir ? join(dir, "Google", "Chrome", "Application", "chrome.exe") : null;
+    }),
   ].filter((value): value is string => !!value);
 
   for (const candidate of candidates) {
     const file = Bun.file(candidate);
     if (await file.exists()) return candidate;
   }
-  throw new Error("Could not find Chrome or Chromium to render the desktop pane screenshot.");
+  throw new Error("Drawing a pane needs Google Chrome or Chromium, and neither was found. Install one, or set CHROME_PATH to its executable.");
 }
 
 async function capturePageScreenshot({

package/src/cli/entry.ts

@@ -11,9 +11,11 @@ import {
   OPEN_TUI_NATIVE_SMOKE_COMMAND,
   OPEN_TUI_RUNTIME_SMOKE_COMMAND,
   PLUGIN_HOST_SMOKE_COMMAND,
+  SHOT_VIEW_SMOKE_COMMAND,
   smokeOpenTuiNative,
   smokeOpenTuiRuntime,
   smokePluginHost,
+  smokeShotView,
 } from "./native-smoke";
 
 async function launchOpenTuiApp(cliLaunchRequest: CliLaunchRequest | null = null): Promise<void> {
@@ -51,6 +53,11 @@ export async function runCliEntrypoint(rawArgs = process.argv.slice(2)): Promise
     process.exit(0);
   }
 
+  if (command === SHOT_VIEW_SMOKE_COMMAND) {
+    await smokeShotView();
+    process.exit(0);
+  }
+
   if (!command || ((command === "launch-ui" || command === "ui") && !rawArgs.some(isCliHelpFlag))) {
     await launchOpenTuiApp();
     return;

package/src/cli/export-source.ts

@@ -2,6 +2,8 @@
  * Where exported data comes from, said the same way by every command that
  * writes CSV or JSON, so an export can go in an audit file as it is: CSV ends
  * with `#` lines and JSON carries a `source` object with the same fields.
+ * CSV and NDJSON rows also end with five fixed columns naming what each row
+ * is (`EXPORT_IDENTITY_COLUMNS`).
  */
 import { formatFreshnessLine, type ReportFreshness } from "./pane-functions/freshness";
 
@@ -38,6 +40,47 @@ export function exportSource(freshness: ReportFreshness): ExportSource {
   };
 }
 
+/**
+ * The columns every row of an export that ends with these lines carries,
+ * last and in this order, so a row says what it is after `head`, a filter or
+ * concatenating files: what was asked for, the unit of its values, the bar
+ * interval or observation frequency served, and the source and as-of date the
+ * closing lines give.
+ */
+export const EXPORT_IDENTITY_COLUMNS = ["symbol_or_series", "currency_or_unit", "interval", "source", "as_of"] as const;
+
+/** What a command knows about the rows it exports; source and as-of come from its freshness. */
+export interface ExportIdentity {
+  /** The symbol or series ID asked for: `USDZAR=X`, `SAN:EPA`, `DEXSFUS`. */
+  symbolOrSeries?: string | null;
+  /** The currency or unit the values are in: `ZAR`, `USD`, `bp`, `pct`, `index points`. */
+  currencyOrUnit?: string | null;
+  /** The bar interval or observation frequency actually returned: `1d`, `1mo`, `daily`, `monthly`. */
+  interval?: string | null;
+}
+
+/**
+ * The five cells of `EXPORT_IDENTITY_COLUMNS` for a row: blank where the
+ * command cannot say, and `as_of` the observation date of the closing lines,
+ * blank when they read `not published`.
+ */
+export function exportIdentityCells(freshness: ReportFreshness, identity: ExportIdentity = {}): string[] {
+  const source = exportSource(freshness);
+  return [
+    identity.symbolOrSeries?.trim() ?? "",
+    identity.currencyOrUnit?.trim() ?? "",
+    identity.interval?.trim() ?? "",
+    source.name,
+    source.observationDate ?? "",
+  ];
+}
+
+/** The same five as fields of an NDJSON row, null where blank. */
+export function exportIdentityFields(freshness: ReportFreshness, identity: ExportIdentity = {}): Record<string, string | null> {
+  const cells = exportIdentityCells(freshness, identity);
+  return Object.fromEntries(EXPORT_IDENTITY_COLUMNS.map((column, index) => [column, cells[index] || null]));
+}
+
 /**
  * The lines an export ends with: the source line the text report ends with,
  * then the publisher, observation date (the newest; the oldest follows when

package/src/cli/freshness.ts

@@ -60,9 +60,9 @@ function latestReportedPeriod(financials: Pick<TickerFinancials, "annualStatemen
 }
 
 /**
- * Fundamentals and valuation: reported figures, not a feed. Dated by when the
- * statistics block was observed, with the newest statement period they run
- * through named in the status; stale only when the block says so.
+ * Fundamentals: reported figures, not a feed. Dated by when the statistics
+ * block was observed, with the newest statement period they run through
+ * named in the status; stale only when the block says so.
  */
 export function fundamentalsFreshness(financials: TickerFinancials, now = Date.now()): ReportFreshness {
   const fundamentals = financials.fundamentals;
@@ -73,3 +73,18 @@ export function fundamentalsFreshness(financials: TickerFinancials, now = Date.n
     asOf: fundamentals?.fetchedAt ?? null,
   }, { stale: fundamentals?.stale === true }, now)!;
 }
+
+/**
+ * Valuation: market cap, multiples and yields measured at the quote's regular
+ * session price, beside the reported figures they divide. Dated by the quote,
+ * as `quote` dates it (after the close, its trading day's close), with the
+ * statement period the reported figures run through after the status. Stale
+ * fundamentals were measured at some older price, so they date it as
+ * `fundamentals` does; so does a missing quote.
+ */
+export function valuationFreshness(financials: TickerFinancials, now = Date.now()): ReportFreshness {
+  const quote = financials.quote;
+  if (!quote || financials.fundamentals?.stale === true) return fundamentalsFreshness(financials, now);
+  const period = latestReportedPeriod(financials);
+  return rowsFreshness([quoteObservation(quote, now)], period ? { note: `reported through ${period}` } : undefined, undefined, now)!;
+}

package/src/cli/glossary.ts

@@ -336,6 +336,23 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     shown: ["Drift"],
     definition: "The plain difference between two percentages. A 22% weight against a 20% target is 2pp over it, not 10%.",
   },
+  // Financial statements and ratios (FA).
+  {
+    term: "EBITDA", aliases: ["earnings before interest taxes depreciation and amortization", "ebitda ttm"], functions: ["FA"],
+    definition: "Earnings before interest, taxes, depreciation and amortization: operating income with depreciation and amortization "
+      + "added back, a rough measure of the cash a business earns before paying for its capital and its debt.",
+  },
+  {
+    term: "Net debt", aliases: ["net debt/ebitda", "net debt to ebitda", "net leverage"], functions: ["FA"], shown: ["Net Debt"],
+    definition: "Total debt less cash and short-term investments. Negative means more cash than debt. "
+      + "Net debt / EBITDA is how many years of EBITDA would repay it; FA divides by a year of EBITDA, the trailing four quarters in a quarterly column.",
+  },
+  {
+    term: "TTM", aliases: ["trailing twelve months", "trailing 12 months", "trailing four quarters", "ltm", "last twelve months"],
+    functions: ["FA"],
+    definition: "Trailing twelve months: the four latest quarters added up, a year that ends with the latest quarter rather than the fiscal year. "
+      + "FA's quarterly leverage ratios read their flows over it, and show < 4 quarters when fewer are on file.",
+  },
   // Funds (ETF). Named in what ETF says it cannot show yet.
   {
     term: "NAV", aliases: ["net asset value", "nav per share", "net asset value per share"], functions: ["ETF"],