gloomberb 0.16.3 → 0.16.5

package/src/cli/result.ts

@@ -7,13 +7,16 @@ import {
   statValueWidth,
   visibleLength,
   wrapText,
+  wrapToTerminal,
   type CliStatEntry,
   type CliTableColumn,
 } from "../utils/cli-output";
 import { serializeCsv } from "../utils/csv";
 import { formatUtcTime, isEpochMilliseconds, isZonedIsoDateTime } from "../utils/utc-time";
 import { formatFreshnessLine, type ReportFreshness } from "./pane-functions/freshness";
+import { withSearchHints } from "./not-a-ticker";
 import { renderReportCsv, renderReportNdjson, type CliReportTables } from "./report-tables";
+import { windowRows, type RowWindow, type RowWindowOptions } from "./row-window";
 
 export interface CliResult<T = unknown> {
   data: T;
@@ -59,6 +62,19 @@ export interface CliResultRenderOptions<T = unknown, Row = Record<string, unknow
   summary?: (data: T) => string;
   /** Text-mode line printed first, naming what the result is about, such as the listing a symbol resolved to. */
   heading?: string;
+  /** Text-mode line printed under the rows, such as where a listing stops. Not printed with no rows: say it in `empty`. */
+  footnote?: string;
+  /** Text-mode block printed under the rows and footnote, for figures about a row that are not columns. */
+  details?: (data: T) => string;
+  /**
+   * The row key holding each row's date, which makes the rows a dated series:
+   * `--tail` keeps the newest rows whichever way the series runs, and a
+   * `--limit` that keeps the oldest says so, under the text table and as
+   * `metadata.rows` in JSON.
+   */
+  dateKey?: string;
+  /** How many rows to show when neither `--limit` nor `--tail` is given; every row when absent. */
+  defaultLimit?: number;
   /**
    * What CSV and NDJSON write instead of the rows: a report's tables as the
    * text view shows them, CSV with its `# section:` and closing `#` lines.
@@ -89,14 +105,28 @@ const KEY_ACRONYMS: Record<string, string> = {
   usd: "USD",
 };
 
-function applyLimit<T>(data: T, limit?: number): T {
-  if (!Array.isArray(data) || limit == null) return data;
-  return data.slice(0, limit) as T;
+function rowWindowOptions(options: CliGlobalOptions, renderOptions: Pick<CliResultRenderOptions, "defaultLimit">): RowWindowOptions {
+  return options.tail != null ? { tail: options.tail } : { limit: options.limit ?? renderOptions.defaultLimit };
+}
+
+function windowed<Row>(
+  rows: readonly Row[],
+  options: CliGlobalOptions,
+  renderOptions: Pick<CliResultRenderOptions, "dateKey" | "defaultLimit">,
+): RowWindow<Row> {
+  const { dateKey } = renderOptions;
+  const dateOf = dateKey ? (row: Row) => (isPlainObject(row) ? row[dateKey] : undefined) : undefined;
+  return windowRows(rows, rowWindowOptions(options, renderOptions), dateOf);
+}
+
+function asRows<T, Row>(data: T, rows?: (data: T) => Row[]): Row[] {
+  return rows ? rows(data) : (Array.isArray(data) ? data : [data]) as Row[];
 }
 
-function asRows<T, Row>(data: T, limit?: number, rows?: (data: T) => Row[]): Row[] {
-  const resolvedRows = rows ? rows(data) : (Array.isArray(data) ? data : [data]) as Row[];
-  return limit == null ? resolvedRows : resolvedRows.slice(0, limit);
+/** What JSON says about rows the window cut, under `metadata.rows`. */
+function cutMetadata(window: RowWindow<unknown>) {
+  if (window.rows.length >= window.total) return null;
+  return { shown: window.rows.length, total: window.total, kept: window.kept, ...(window.note ? { note: window.note } : {}) };
 }
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -277,6 +307,7 @@ function renderTextTable<Row extends Record<string, unknown>>(
       width: column.width,
       maxWidth: column.maxWidth,
       optional: column.optional,
+      dropPriority: column.dropPriority,
       shrink: column.shrink,
     })),
     cells.map((row) => shown.map(({ index }) => row[index]!)),
@@ -310,7 +341,7 @@ function overflowsTerminal<Row extends Record<string, unknown>>(rows: Row[]): bo
 
 /** The closing source, as-of and status line of a text result, for output printed without `printResult`. */
 export function cliFreshnessFooter(freshness: ReportFreshness): string {
-  return cliStyles.muted(formatFreshnessLine(freshness));
+  return cliStyles.muted(wrapToTerminal(formatFreshnessLine(freshness)));
 }
 
 export function serializeCliResult<T, Row extends Record<string, unknown> = Record<string, unknown>>(
@@ -321,11 +352,13 @@ export function serializeCliResult<T, Row extends Record<string, unknown> = Reco
   const { freshness, ...rest } = result;
   if (options.format === "json") {
     const columns = serializeColumns(renderOptions.columns);
+    const window = Array.isArray(result.data) ? windowed(result.data as unknown[], options, renderOptions) : null;
+    const cut = window ? cutMetadata(window) : null;
     const envelope: CliResultJsonEnvelope<T> = {
       ok: true,
       ...rest,
-      ...(freshness ? { metadata: { ...rest.metadata, freshness } } : {}),
-      data: applyLimit(result.data, options.limit),
+      ...(freshness || cut ? { metadata: { ...rest.metadata, ...(freshness ? { freshness } : {}), ...(cut ? { rows: cut } : {}) } } : {}),
+      data: window ? window.rows as T : result.data,
       ...(columns?.length ? { columns } : {}),
     };
     return JSON.stringify(envelope, null, 2);
@@ -342,7 +375,8 @@ function serializeCliRows<T, Row extends Record<string, unknown>>(
 ): string {
   if (renderOptions.tables && options.format === "csv") return renderReportCsv(renderOptions.tables);
   if (renderOptions.tables && options.format === "ndjson") return renderReportNdjson(renderOptions.tables);
-  const rows = asRows(result.data, options.limit, renderOptions.rows);
+  const window = windowed(asRows(result.data, renderOptions.rows), options, renderOptions);
+  const rows = window.rows;
   if (options.format === "ndjson") {
     return rows.map((row) => JSON.stringify(row)).join("\n");
   }
@@ -357,7 +391,10 @@ function serializeCliRows<T, Row extends Record<string, unknown>>(
   if (rows.length === 0) {
     return withHeading(summary || cliStyles.muted(renderOptions.empty ?? "No results."));
   }
-  const body = renderTextRows(rows as Row[], result.data, renderOptions);
+  const table = renderTextRows(rows as Row[], result.data, renderOptions);
+  const notes = [window.note, renderOptions.footnote].filter((note): note is string => !!note);
+  const details = renderOptions.details?.(result.data) ?? "";
+  const body = [table, ...notes.map((note) => cliStyles.muted(note)), ...details ? ["", details] : []].join("\n");
   return withHeading(summary ? `${summary}\n\n${body}` : body);
 }
 
@@ -382,9 +419,12 @@ export function printCliResult<T, Row extends Record<string, unknown> = Record<s
   result: CliResult<T>,
   options: CliGlobalOptions,
   renderOptions: CliResultRenderOptions<T, Row> = {},
+  args: readonly string[] = [],
 ): void {
   if (options.quiet && options.format === "text") return;
-  const output = serializeCliResult(result, options, renderOptions);
+  // JSON keeps the router's own words; everything else is for a person, so a "Not a ticker" gets its hint.
+  const hinted = (text: string) => options.format === "json" ? text : withSearchHints(text, args);
+  const output = hinted(serializeCliResult(result, options, renderOptions));
   // Bun's console writer can truncate a large pipe write after stdout has been
   // initialized. The stream queues the remaining bytes until the reader drains.
   if (output) process.stdout.write(`${output}\n`);
@@ -392,7 +432,7 @@ export function printCliResult<T, Row extends Record<string, unknown> = Record<s
   // rows, so a warning goes to stderr, out of a file the rows are piped into.
   if (options.format !== "json" && !options.quiet) {
     for (const warning of result.warnings ?? []) {
-      console.error(`${cliStyles.warning("warning:")} ${warning}`);
+      console.error(`${cliStyles.warning("warning:")} ${hinted(warning)}`);
     }
   }
 }

package/src/cli/row-window.ts

@@ -0,0 +1,76 @@
+/**
+ * Which rows `--limit` and `--tail` keep, for every command that prints a
+ * list. `--limit n` keeps the first n rows as printed. `--tail n` keeps the
+ * newest n rows of a dated series, whichever way it runs (the first n of a
+ * newest-first series, the last n of an oldest-first one), and the last n of
+ * any other list. The kept rows stay in their printed order.
+ */
+export interface RowWindowOptions {
+  limit?: number;
+  tail?: number;
+}
+
+export interface RowWindow<Row> {
+  rows: Row[];
+  /** How many rows there were before the cut. */
+  total: number;
+  /** The end of a dated series the cut kept; null when nothing was cut or the rows are not a dated series. */
+  kept: "oldest" | "newest" | null;
+  /**
+   * Said when `--limit` cut an oldest-first series, which reads as the latest
+   * rows but is the earliest: "showing the oldest 2 of 252 rows; --tail 2 for
+   * the latest". Null otherwise.
+   */
+  note: string | null;
+}
+
+function timeOf(value: unknown): number | null {
+  if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.getTime() : null;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value !== "string" || !value.trim()) return null;
+  const time = Date.parse(value);
+  return Number.isFinite(time) ? time : null;
+}
+
+function firstTime<Row>(rows: readonly Row[], dateOf: (row: Row) => unknown, fromEnd: boolean): number | null {
+  for (let step = 0; step < rows.length; step += 1) {
+    const time = timeOf(dateOf(rows[fromEnd ? rows.length - 1 - step : step]!));
+    if (time != null) return time;
+  }
+  return null;
+}
+
+/** Which way a dated series runs, from its first and last dated rows; null when it is undated or spans one instant. */
+function seriesOrder<Row>(rows: readonly Row[], dateOf: (row: Row) => unknown): "ascending" | "descending" | null {
+  const first = firstTime(rows, dateOf, false);
+  const last = firstTime(rows, dateOf, true);
+  if (first == null || last == null || first === last) return null;
+  return first < last ? "ascending" : "descending";
+}
+
+/** The rows `options` keep. `dateOf` reads a row's date, which makes the rows a dated series. */
+export function windowRows<Row>(
+  rows: readonly Row[],
+  options: RowWindowOptions,
+  dateOf?: (row: Row) => unknown,
+): RowWindow<Row> {
+  const total = rows.length;
+  const count = options.tail ?? options.limit;
+  if (count == null || count >= total) return { rows: [...rows], total, kept: null, note: null };
+  const order = dateOf ? seriesOrder(rows, dateOf) : null;
+  if (options.tail != null) {
+    return {
+      rows: order === "descending" ? rows.slice(0, count) : rows.slice(total - count),
+      total,
+      kept: order ? "newest" : null,
+      note: null,
+    };
+  }
+  const kept = order === "ascending" ? "oldest" : order === "descending" ? "newest" : null;
+  return {
+    rows: rows.slice(0, count),
+    total,
+    kept,
+    note: kept === "oldest" ? `showing the oldest ${count} of ${total} rows; --tail ${count} for the latest` : null,
+  };
+}

package/src/cli/scroll-truncation.ts

@@ -0,0 +1,34 @@
+/** A scrolling box as the page measures it. */
+export interface ScrollBoxMetrics {
+  scrollTop: number;
+  scrollHeight: number;
+  clientHeight: number;
+  scrollLeft: number;
+  scrollWidth: number;
+  clientWidth: number;
+  /** The box draws a scrollbar on that axis, which says it overflows even when the measures cannot. */
+  scrollbarY: boolean;
+  scrollbarX: boolean;
+}
+
+/**
+ * What a capture leaves out of a scrolling box, naming the side: a chain
+ * centred on the money is cut above and below, a list at its top only below.
+ * Self-contained so the screenshot runner can evaluate it in the browser.
+ */
+export function scrollTruncationReasons(box: ScrollBoxMetrics): string[] {
+  const reasons: string[] = [];
+  const cut = (offset: number, content: number, viewport: number, flagged: boolean, noun: string, sides: readonly [string, string, string, string]) => {
+    if (!flagged && !(content > viewport + 1)) return;
+    // One pixel either way is subpixel layout, not a hidden row.
+    const before = offset > 1;
+    const after = offset + viewport < content - 1;
+    // A drawn scrollbar over content that measures as fitting (a list that loads more) cannot say which side.
+    reasons.push(before || after
+      ? `${noun} ${before && after ? sides[2] : before ? sides[0] : sides[1]} the rendered viewport are cut`
+      : `${noun} ${sides[3]} the rendered viewport may be cut`);
+  };
+  cut(box.scrollTop, box.scrollHeight, box.clientHeight, box.scrollbarY, "rows", ["above", "below", "above and below", "above or below"]);
+  cut(box.scrollLeft, box.scrollWidth, box.clientWidth, box.scrollbarX, "columns", ["left of", "right of", "left and right of", "left or right of"]);
+  return reasons;
+}

package/src/cli/staged-tickers.ts

@@ -0,0 +1,52 @@
+import type { TickerRepository } from "../data/ticker-repository";
+import type { TickerMetadata, TickerRecord } from "../types/ticker";
+
+type TickerSource = Pick<TickerRepository, "loadTicker" | "loadAllTickers" | "saveTicker"> & Partial<Pick<TickerRepository, "saveTickers">>;
+
+/**
+ * A ticker store that keeps a command's changes in memory until `commit`,
+ * which saves them in one write. A command that adds hundreds of symbols reads
+ * its own changes back while it works and writes once at the end, so the app
+ * sharing the database is never held up by a write per symbol.
+ */
+export class StagedTickerRepository {
+  private readonly staged = new Map<string, TickerRecord>();
+  private saved: Promise<TickerRecord[]> | null = null;
+
+  constructor(private readonly base: TickerSource) {}
+
+  async loadTicker(symbol: string): Promise<TickerRecord | null> {
+    return this.staged.get(symbol) ?? await this.base.loadTicker(symbol);
+  }
+
+  async loadAllTickers(): Promise<TickerRecord[]> {
+    this.saved ??= this.base.loadAllTickers();
+    const merged = new Map((await this.saved).map((ticker) => [ticker.metadata.ticker, ticker] as const));
+    for (const [symbol, ticker] of this.staged) merged.set(symbol, ticker);
+    return [...merged.values()];
+  }
+
+  async saveTicker(ticker: TickerRecord): Promise<void> {
+    this.staged.set(ticker.metadata.ticker, ticker);
+  }
+
+  async createTicker(metadata: TickerMetadata): Promise<TickerRecord> {
+    const ticker: TickerRecord = { metadata };
+    await this.saveTicker(ticker);
+    return ticker;
+  }
+
+  async deleteTicker(): Promise<void> {
+    throw new Error("A staged ticker store does not delete tickers.");
+  }
+
+  /** Writes every staged ticker at once. */
+  async commit(): Promise<void> {
+    const tickers = [...this.staged.values()];
+    if (tickers.length === 0) return;
+    if (this.base.saveTickers) await this.base.saveTickers(tickers);
+    else for (const ticker of tickers) await this.base.saveTicker(ticker);
+    this.staged.clear();
+    this.saved = null;
+  }
+}

package/src/cli/symbol-args.ts

@@ -0,0 +1,9 @@
+/**
+ * Symbols given as command arguments, each of which may hold several split by
+ * commas, semicolons, spaces, tabs or newlines (a pasted list), with the blanks
+ * dropped and the typed case kept. Every command that takes a symbol list splits
+ * its arguments here, and `not-a-ticker` reads the typed spelling back from them.
+ */
+export function splitSymbolArgs(args: readonly string[]): string[] {
+  return args.flatMap((arg) => arg.replace(/^\uFEFF/, "").split(/[\s,;]+/)).filter(Boolean);
+}

package/src/cli/symbol-list.ts

@@ -0,0 +1,172 @@
+import { readFile } from "fs/promises";
+import { fstatSync } from "fs";
+import { splitSymbolArgs } from "./symbol-args";
+
+/** Header cells that name a spreadsheet's symbol column, compared without case, spaces or punctuation. */
+const SYMBOL_HEADERS = new Set(["symbol", "symbols", "ticker", "tickers", "code", "stockcode", "securitycode", "instrument"]);
+
+/** One symbol as it can be typed: AAPL, $nvda, TTF.AS, SAN:EPA, BRK-B, 7203.T, ^GSPC, ES=F. */
+const SYMBOL_TOKEN = /^\$?[\p{L}\p{N}^][\p{L}\p{N}.:\-^=/&]{0,23}$/u;
+/** A plain number: a price, a weight or a share count in a spreadsheet's other columns. */
+const NUMBER_CELL = /^[+-]?(?:\d{1,3}(?:,\d{3})+|\d*)(?:\.\d+)?%?$/;
+
+function headerKey(cell: string): string {
+  return cell.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+}
+
+function isComment(cell: string): boolean {
+  return cell.startsWith("#") || cell.startsWith("//");
+}
+
+/** The delimiter of the first data line: tab, comma or semicolon, or null for a list split by spaces. */
+function detectDelimiter(lines: readonly string[]): string | null {
+  const first = lines.find((line) => line.trim() && !isComment(line.trim()));
+  if (!first) return null;
+  const unquoted = first.replace(/"[^"]*"/g, "");
+  for (const delimiter of ["\t", ",", ";"]) {
+    if (unquoted.includes(delimiter)) return delimiter;
+  }
+  return null;
+}
+
+/** RFC 4180 records: a quoted cell may hold the delimiter, a newline and doubled quotes. */
+function parseDelimited(text: string, delimiter: string): string[][] {
+  const records: string[][] = [];
+  let record: string[] = [];
+  let cell = "";
+  let quoted = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index]!;
+    if (quoted) {
+      if (char === "\"" && text[index + 1] === "\"") {
+        cell += "\"";
+        index += 1;
+      } else if (char === "\"") {
+        quoted = false;
+      } else {
+        cell += char;
+      }
+      continue;
+    }
+    if (char === "\"" && !cell.trim()) {
+      quoted = true;
+      cell = "";
+    } else if (char === delimiter) {
+      record.push(cell);
+      cell = "";
+    } else if (char === "\n") {
+      record.push(cell);
+      records.push(record);
+      record = [];
+      cell = "";
+    } else {
+      cell += char;
+    }
+  }
+  if (cell || record.length > 0) {
+    record.push(cell);
+    records.push(record);
+  }
+  return records.map((cells) => cells.map((value) => value.trim()));
+}
+
+function looksLikeSymbol(cell: string): boolean {
+  return SYMBOL_TOKEN.test(cell) && !(NUMBER_CELL.test(cell) && /[.,%]/.test(cell));
+}
+
+/**
+ * The symbols in a file or piped text, in order. A spreadsheet export reads
+ * from the column its header names (Symbol, Ticker, Code), or else its first
+ * column; a list split by commas, spaces or newlines gives every entry. A byte
+ * order mark, Windows line ends, blank lines and lines starting with # or //
+ * are ignored.
+ */
+export function parseSymbolText(text: string): string[] {
+  const normalized = text.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+  const lines = normalized.split("\n");
+  const delimiter = detectDelimiter(lines);
+  const records = (delimiter ? parseDelimited(normalized, delimiter) : lines.map((line) => line.trim().split(/\s+/)))
+    .filter((cells) => cells.some(Boolean) && !isComment(cells[0] ?? ""));
+  if (records.length === 0) return [];
+  const header = records[0]!.map(headerKey);
+  const exact = header.findIndex((cell) => SYMBOL_HEADERS.has(cell));
+  const column = exact >= 0 ? exact : header.findIndex((cell) => cell.includes("symbol") || cell.includes("ticker"));
+  if (column >= 0) return records.slice(1).map((cells) => cells[column] ?? "").filter(Boolean);
+  // Without a header, symbols laid out across columns are all symbols; a
+  // table with names, prices or weights beside them is read by its first column.
+  const grid = records.every((cells) => cells.every((cell, index) => !cell || (looksLikeSymbol(cell) && (index === 0 || !NUMBER_CELL.test(cell)))));
+  return grid ? records.flat().filter(Boolean) : records.map((cells) => cells[0] ?? "").filter(Boolean);
+}
+
+/** How a symbol is compared for repeats: AAPL, aapl and $AAPL are one. */
+export function symbolInputKey(symbol: string): string {
+  return symbol.trim().replace(/^\$/, "").toUpperCase();
+}
+
+/** The symbols without repeats, first spelling kept, and how many repeats were dropped. */
+function uniqueSymbols(symbols: readonly string[]): { symbols: string[]; repeated: number } {
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const symbol of symbols) {
+    const key = symbolInputKey(symbol);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    unique.push(symbol.trim());
+  }
+  return { symbols: unique, repeated: symbols.filter((symbol) => symbolInputKey(symbol)).length - unique.length };
+}
+
+/** Whether standard input is a pipe or a file rather than a terminal, so a command may read its list from it. */
+function stdinIsPiped(): boolean {
+  try {
+    const stats = fstatSync(0);
+    return stats.isFIFO() || stats.isFile();
+  } catch {
+    return false;
+  }
+}
+
+export interface SymbolListSource {
+  /** The arguments after the list name, symbols and `-` for standard input. */
+  args: readonly string[];
+  /** `--file <path>`. */
+  file?: string;
+  /** Reads standard input; injected so tests never block on it. */
+  readStdin?: () => Promise<string>;
+  /** Whether standard input was piped in, so a command given no symbols reads it. */
+  stdinPiped?: boolean;
+}
+
+export class SymbolListError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SymbolListError";
+  }
+}
+
+/**
+ * The symbols a command was given: as arguments, from `--file`, and from
+ * standard input when an argument is `-` or nothing else was given and input
+ * is piped in. Repeats are dropped.
+ */
+export async function readSymbolList(source: SymbolListSource): Promise<{ symbols: string[]; repeated: number }> {
+  const readStdin = source.readStdin ?? (() => Bun.stdin.text());
+  const wantsStdin = source.args.includes("-") || source.file === "-";
+  const typed = splitSymbolArgs(source.args.filter((arg) => arg !== "-"));
+  const collected = [...typed];
+  if (source.file != null && source.file !== "-") {
+    if (!source.file.trim() || source.file.startsWith("--")) throw new SymbolListError("--file needs a path, such as --file symbols.csv.");
+    let text: string;
+    try {
+      text = await readFile(source.file, "utf-8");
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      throw new SymbolListError(code === "ENOENT" ? `No file at ${source.file}.` : `Could not read ${source.file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    collected.push(...parseSymbolText(text));
+  }
+  if (wantsStdin || (typed.length === 0 && source.file == null && (source.stdinPiped ?? stdinIsPiped()))) {
+    collected.push(...parseSymbolText(await readStdin()));
+  }
+  return uniqueSymbols(collected);
+}