@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/charts/table-data.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Numeric reading of GFM table cells and columns, the input to
+ * {@link planChart}: what number a cell holds (in base units, with its
+ * dimension and annotations) and which role each column plays — a measure to
+ * plot, a category label, an ordered x axis, or a row index to ignore.
+ *
+ * Cells are model-written prose, not CSV: `~1,400`, `**4** ✅`, `17 (21.5%)`,
+ * `24–72 h`, `12 → 15`, `5/8`, `1m 56s`, `TIMEOUT`. The reader keeps the first
+ * number and its unit and classifies the rest, so a column of mostly clean
+ * numbers survives a few annotated or sentinel cells.
+ */
+/** What a number measures; values of one dimension share an axis after unit normalization. */
+export type Dimension = "count" | "percent" | "duration" | "bytes" | "currency" | "ratio" | "fraction" | "rate";
+/**
+ * How cleanly a cell reads as its number: bare (`12 ms`), with a short note
+ * (`17 (21.5%)`, `16 pass`), a range (`24–72 h`), a transition (`12 → 15`), a
+ * fraction (`5/8`), or a number leading prose (`~1,400w, nearly ready`).
+ */
+export type CellFit = "pure" | "note" | "range" | "arrow" | "fraction" | "prose";
+/** A cell that reads as a number. */
+export interface NumberCell {
+    readonly kind: "number";
+    /** Value in base units: seconds, bytes, a plain count, percent points. */
+    readonly value: number;
+    readonly dim: Dimension;
+    /** Unit or currency symbol as written (`ms`, `KiB`, `$`, `tok/s`); empty for bare numbers. */
+    readonly unit: string;
+    readonly fit: CellFit;
+    /** Written as an estimate or bound (`~`, `≈`, `<`, `≥`). */
+    readonly approx: boolean;
+    /** Written with an explicit sign (`+12%`, `-3`). */
+    readonly signed: boolean;
+    /** The cell was bolded: models bold the value they want noticed. */
+    readonly emphasis: boolean;
+    /** The cell text without Markdown decoration. */
+    readonly text: string;
+    /** The number as written, with approximation, sign, currency and unit (`~$250`, `12.5 ms`, `24–72 h`). */
+    readonly figure: string;
+    /** `a → b`: `b`, in the same base units. */
+    readonly to?: number;
+    /** `a → b`: `b` as written. */
+    readonly toFigure?: string;
+    /** `a–b`: `b`, in the same base units. */
+    readonly upper?: number;
+    /**
+     * `a/b`: `b`. {@link analyzeTable} reads a score (`12/12`, `154/160`, a mean
+     * like `0.6/4`) as the percent of `b` reached, unless its column also holds a
+     * plain fraction; a pair (`85 / 147` under `Edit / read calls`) keeps `a`.
+     */
+    readonly denominator?: number;
+    /**
+     * `a ± e` (`3.67s ± 0.69`, `~404ms ± 60`, `$0.72 (±0.16)`): `e`, in the same base units — the
+     * spread the table states around the value; {@link figure} then writes both (`3.67s ± 0.69`).
+     */
+    readonly error?: number;
+    /**
+     * A slash list of measurements in one unit (`79 / 124 µs`, `1,864 ms /
+     * 2,678 ms`, `**675ms** / 680ms`): every listed value, the first included,
+     * in base units, 2–4 of them. `value` is the first.
+     */
+    readonly values?: readonly number[];
+}
+/** A cell that is not a quantity. */
+export interface OtherCell {
+    readonly kind: "missing" | "date" | "time" | "version" | "id" | "text";
+    readonly text: string;
+    readonly emphasis: boolean;
+}
+export type Cell = NumberCell | OtherCell;
+/**
+ * What a column contributes to a chart: `measure` values to plot, `label`
+ * category names, `temporal` dates or times, `sequence` an ordered step
+ * (`Run`, `Day`, `Workers`), `index` a row number or identifier never plotted.
+ */
+export type ColumnRole = "measure" | "label" | "temporal" | "sequence" | "index";
+export interface TableColumn {
+    readonly index: number;
+    /** Header text without Markdown decoration. */
+    readonly header: string;
+    readonly role: ColumnRole;
+    readonly cells: readonly Cell[];
+    /** Dominant dimension of the numeric cells. */
+    readonly dim: Dimension | undefined;
+    /** Representative unit of the dominant dimension (`$`, `tok/s`); empty when bare. */
+    readonly unit: string;
+    /** Numeric cells disagree on dimension (a metric-per-row table). */
+    readonly mixed: boolean;
+    /** Numeric cells are mostly scores out of a total (`12/12`), read as percent of it. */
+    readonly scores: boolean;
+    /**
+     * Per row, the status its cell leads with ({@link cellStatus}), when most
+     * of the column's cells lead with one: a pass/fail or progress column.
+     */
+    readonly statuses?: readonly (Status | undefined)[];
+    /** Every numeric data cell holds the same value: an echoed setting, not a measure. */
+    readonly constant: boolean;
+    /** Share of numeric cells written with an explicit sign. */
+    readonly signedShare: number;
+    /** Share of numeric cells written as `a → b`. */
+    readonly arrowShare: number;
+    /**
+     * Index of the measure column this one restates, read from the values: a
+     * proportional copy (`pass` 33/38 beside `pass%` 87%, `Samples` beside `% of
+     * Total`, `Leverage vs $200` beside the cost) or a running total of it
+     * (`Offset` summing `Verts`). Such a column is never a measure of its own.
+     */
+    readonly restates?: number;
+}
+/**
+ * Measure columns that add up, read from the values: leaf `parts` summing to
+ * `whole` in every row (`Cached + Uncached input = Input`, `Input + Output =
+ * Total` → parts Cached, Uncached input, Output of Total), or — when not
+ * `exact` — parts falling within a `Total` column, the rest unlisted (`New +
+ * Edited ≤ Prose total`).
+ */
+export interface Composition {
+    /** Column the parts make up; absent when only a judge says the parts form a whole. */
+    readonly whole: number | undefined;
+    /** Leaf part columns, in table order. */
+    readonly parts: readonly number[];
+    /** The parts sum to the whole within the written precision in every row. */
+    readonly exact: boolean;
+}
+/** A table read for charting. */
+export interface TableAnalysis {
+    readonly columns: readonly TableColumn[];
+    /**
+     * Category labels: the first text or temporal column not made only of codes
+     * (`#2233`, `00`), else the first text column, else a sequence or index column.
+     */
+    readonly label: TableColumn | undefined;
+    /** Plottable measure columns, constant ones excluded. */
+    readonly measures: readonly TableColumn[];
+    /** Data rows, in table order, without total/summary rows. */
+    readonly rows: readonly number[];
+    /** Total/summary rows (`Total`, `Average`, …), kept out of the scale. */
+    readonly totals: readonly number[];
+    /** Measure columns adding up to a whole, when the values show it. */
+    readonly composition?: Composition;
+}
+/**
+ * What a status cell (`ok`, `FAIL`, `pending`, ✅) says about its row: `good`
+ * passed or landed, `bad` failed or broke, `warn` partly or flaky, `pending`
+ * not settled yet.
+ */
+export type Status = "good" | "bad" | "warn" | "pending";
+/**
+ * The status a cell's text leads with (`FAIL`, `✓ via mmdc`, `**pending**`,
+ * `1 ok`), or `undefined` for any other text. A count before the word
+ * (`3 ok`) still reads as the word's status.
+ */
+export declare function cellStatus(text: string): Status | undefined;
+/**
+ * Strip inline Markdown from a cell: links keep their text; bold, italics,
+ * strikethrough, code spans and `<br>` keep their content.
+ */
+export declare function plainCell(markdown: string): {
+    text: string;
+    emphasis: boolean;
+};
+/** Parse the first number of a (Markdown) cell, or classify why it is not one. */
+export declare function parseCell(markdown: string): Cell;
+/** Read a table's columns and rows for charting. Cells are the raw Markdown of each cell. */
+export declare function analyzeTable(header: readonly string[], rows: readonly (readonly string[])[]): TableAnalysis;
+/**
+ * Half the last written digit of `cell`, in base units (`6,313k` → 500,
+ * `38.5%` → 0.05): how far its value may sit from the exact quantity it
+ * rounds. A score (`33/38` read as percent) and a whole count written in full
+ * (`46`, `1,980`) are exact.
+ */
+export declare function writtenSlack(cell: NumberCell): number;
+/** Strictly increasing or strictly decreasing. */
+export declare function isMonotonic(values: readonly number[]): boolean;
+/** Whether `cell` reads as a number. */
+export declare function isNumber(cell: Cell | undefined): cell is NumberCell;