gangtise-openapi-cli 0.34.0 → 0.35.0

package/dist/src/core/indicatorMatrix.js

@@ -1,32 +1,14 @@
 import { screenerExpressionFields, screenerExpressionIsEvaluable } from "./args.js";
 import { ApiError, attachEnvelopeTraceId, ENVELOPE_TRACE_ID } from "./errors.js";
-// The EDE endpoints double-wrap on success: the shared client strips the outer
-// envelope but leaves an inner { code, status, data } around the real payload.
-// Peel that inner envelope so the list (search) / matrix (cross-section,
-// time-series) is reachable. A failure code carried only by the inner envelope
-// must still surface instead of rendering its null payload as success.
 export function unwrapIndicatorData(raw) {
     if (raw && typeof raw === "object" && !Array.isArray(raw)) {
         const record = raw;
         if ("code" in record || "status" in record) {
             const code = record.code === undefined ? undefined : String(record.code);
             const ok = record.status === true || code === "000000" || code === "0";
-            // A failure envelope may omit `data` entirely ({ code, status: false, msg })
-            // — gating on the data key would let a permission/quota error flow through
-            // as "successful" payload. Still require some envelope evidence
-            // (status/msg/data) so a non-envelope object that merely carries a `code`
-            // field can't be misread as a failure.
             if (!ok && ("status" in record || "msg" in record || "data" in record)) {
-                // Pass `record` as details: the inner envelope carries no traceId of its
-                // own, but unwrapEnvelope attached the outer one to this object and
-                // ApiError.traceId falls back to it. Without it these failures — the EDE
-                // 999999 / 130001 that most need reporting — reach the user trace-less.
                 throw new ApiError(typeof record.msg === "string" && record.msg ? record.msg : "Indicator API request failed", code, undefined, record);
             }
-            // Carry the envelope's traceId onto the inner payload. `unwrapEnvelope`
-            // attached it to THIS object, but everything downstream (the flatteners'
-            // shape guards) only ever sees `record.data` — without this hand-off those
-            // failures, exactly the ones support needs to trace, arrive trace-less.
             if (ok && "data" in record)
                 return attachEnvelopeTraceId(record.data, record[ENVELOPE_TRACE_ID] ?? record.traceId);
         }
@@ -36,12 +18,6 @@ export function unwrapIndicatorData(raw) {
 function asStringArray(value) {
     return Array.isArray(value) ? value.map((item) => String(item)) : undefined;
 }
-/** An IDENTITY axis — the security codes a row belongs to, the dates a column
- * belongs to. `String(item)` would turn a `null` into the literal `"null"` and
- * render it as a perfectly plausible label (probed 2026-08-02: `dates: [null]`
- * produced `date: "null"`, `securityCodeList: [null]` produced
- * `security: "null"`), so a fabricated identity would reach the output at exit
- * 0. Nothing here may be coerced: every entry must already be a non-empty string. */
 function asIdentityArray(data, value, key) {
     if (!Array.isArray(value))
         return undefined;
@@ -51,9 +27,6 @@ function asIdentityArray(data, value, key) {
     }
     return value;
 }
-/** Indicator metadata is an identity axis too: `--key-by code` addresses columns
- * by `code`, so an entry without one cannot be mapped back to what was asked
- * for. A non-object entry used to collapse into `{}` and surface as `col0`. */
 function asIndicatorMetaList(data, value) {
     if (!Array.isArray(value))
         return undefined;
@@ -71,11 +44,6 @@ function rowOf(values, index) {
     const row = values[index];
     return Array.isArray(row) ? row : undefined;
 }
-// Build one column header per series. Prefer the human-readable name; on a
-// duplicate name append a disambiguator so a column is never silently
-// overwritten. `reserved` pre-seeds the metadata column names, so a series
-// literally named "date" / "security" / "name" gets suffixed rather than
-// clobbering the metadata.
 function buildHeaders(bases, suffixes, reserved) {
     const used = new Set(reserved);
     const headers = [];
@@ -93,21 +61,10 @@ function buildHeaders(bases, suffixes, reserved) {
     }
     return headers;
 }
-// Column headers for a list of indicator metadata. keyBy "code" makes each
-// column its `code` (unique, and independent of the display name or the
-// server's column order) instead of the human name — required for batch
-// code→value mapping, where names collide (many indicators share a display
-// name) and the server reorders columns relative to the request. The screener
-// disambiguates by `field` instead, because there the SAME code may legitimately
-// appear twice under two variables with different parameters.
 function indicatorHeaders(indicators, keyBy, reserved) {
     const codes = indicators.map((meta) => optionalString(meta.code));
     const fields = indicators.map((meta, i) => optionalString(meta.field) ?? codes[i]);
     const bases = keyBy === "code" ? codes : indicators.map((meta) => optionalString(meta.name));
-    // On a screener payload every column carries its variable, so a repeated base
-    // can suffix ALL of its occurrences instead of leaving the first one bare.
-    // A bare `收盘价` next to `收盘价 (F2)` reads as "the" close price when it is
-    // really just whichever variable the server happened to list first.
     const screener = indicators.some((meta) => meta.field !== undefined);
     if (!screener)
         return buildHeaders(bases, fields, reserved);
@@ -115,32 +72,6 @@ function indicatorHeaders(indicators, keyBy, reserved) {
     return buildHeaders(bases.map((base, i) => (base !== undefined && repeated.has(base) ? `${base} (${fields[i] ?? i})` : base)), fields, reserved);
 }
 const CROSS_SECTION_COLUMNS = ["security", "name"];
-/** A response carrying neither securities nor indicators: the query as a whole
- * resolved to nothing. This is NOT a dropped axis, so it must not be reported as
- * partial — calling every requested code "omitted" would be false metadata, the
- * diff against the request is total by construction.
- *
- * What it MEANS changed on 2026-08-07: a genuine no-data answer (non-trading
- * date, uncovered market, future date) now comes back as a null cell with its
- * row and column intact, so an all-empty matrix no longer means "no data". It
- * now means nothing in the request RESOLVED — every security code or every
- * indicator code was unrecognised — or a parameter name is wrong. The caller's
- * stderr note says exactly that.
- *
- * The check covers every STRUCTURAL array, not just the two axis lists, because
- * accepting anything looser would let a malformed payload — `values: null`, a
- * missing `values`, or dates with no matrix — pass as "legitimately empty" and
- * exit 0, which is precisely the protocol regression this release's shape guards
- * exist to catch. Required empty: `securityCodeList`, `indicatorList`, `values`;
- * plus `dates` when present. Probed 2026-08-02 (back when this shape still meant
- * "no data"): a time-series all-empty answer is five empty arrays, a
- * cross-section one is four (it carries no `dates` key at all), hence "absent or
- * empty" rather than a flat count. The STRUCTURE is unchanged; only its meaning
- * moved — since 2026-08-07 it signals an unresolved axis, not missing data.
- *
- * `securityNameList` is deliberately NOT checked: it holds display labels, not
- * structure, so a `null` there cannot misalign anything — and rejecting it would
- * re-introduce the false-partial this function exists to prevent. */
 export function isEmptyMatrix(data) {
     if (!data || typeof data !== "object")
         return false;
@@ -151,28 +82,12 @@ export function isEmptyMatrix(data) {
         return false;
     if (!Array.isArray(d.values) || d.values.length !== 0)
         return false;
-    // `dates` is time-series only; when present it must be empty too.
     return d.dates === undefined || (Array.isArray(d.dates) && d.dates.length === 0);
 }
-/** Validate the variable bindings a screener answered with, returning the bound
- * variables that are merely missing (see below).
- *
- * The screener answers with the variable each column was requested under, and
- * that binding is the ONLY thing tying a column back to the filter it came from
- * — nothing else in the payload can catch it going wrong. A swapped or unknown
- * `field` renders as a perfectly ordinary result (probed 2026-08-02: a response
- * labelling a requested `F1` as `F9` printed a normal table at exit 0), which
- * would make every screening decision downstream unfounded.
- *
- * Every returned entry must therefore name a REQUESTED variable and carry that
- * variable's code, and no variable may appear twice. A wholly empty result binds
- * nothing and is left alone. */
 export function checkScreenerBindings(data, requested, expression) {
     if (!data || typeof data !== "object")
         return [];
     const d = data;
-    // A result with no securities matched nothing and binds nothing — the
-    // canonical empty answer, left alone.
     if (!Array.isArray(d.securityCodeList) || d.securityCodeList.length === 0)
         return [];
     const indicators = Array.isArray(d.indicatorList) ? d.indicatorList : [];
@@ -192,43 +107,13 @@ export function checkScreenerBindings(data, requested, expression) {
         }
         seen.add(field);
     }
-    // Securities came back, so the filter ran. A column vanishing is never "it got
-    // filtered out" — filtering removes securities (rows), never indicators
-    // (columns). Since 2026-08-07 a covered-but-empty indicator keeps a null
-    // column, so an absent column means the server did not resolve that indicator
-    // code at all. What that implies depends on how the expression combines terms:
-    //
-    // The answer follows the expression's BOOLEAN STRUCTURE, not the mere presence
-    // of a `||` — see screenerExpressionIsEvaluable. If no branch survives the
-    // missing columns, the rows cannot be shown to satisfy anything and the result
-    // is fatal; if some branch still could have matched, the absence proves nothing
-    // wrong and it degrades to partial.
     const missing = [...wanted.keys()].filter((field) => !seen.has(field));
     if (!screenerExpressionIsEvaluable(expression, seen)) {
         const absent = [...new Set(screenerExpressionFields(expression))].filter((field) => !seen.has(field));
         throw new ApiError(`Screener binding mismatch: the expression cannot be evaluated from what came back — ${absent.join(", ")} ${absent.length > 1 ? "have" : "has"} no column, and no branch of the expression survives without ${absent.length > 1 ? "them" : "it"}, so the rows cannot be shown to satisfy it`, undefined, undefined, data);
     }
-    // Whatever survives is an output column that went missing: information lost,
-    // correctness intact.
     return missing;
 }
-/** What the caller asked for that the response does not contain.
- *
- * The server used to drop any axis it had no DATA for, which made this a
- * coverage check. Re-probed 2026-08-08: a coverage gap is now padded with `null`
- * and keeps its row and column, down to the 1×1 case (`finc_pb_mrq` × 09992.HK,
- * `mgn_bal` × 00700.HK — null, present, alone in the request). What still
- * disappears is a code the server cannot RESOLVE: an unknown indicator code, or
- * a security code with the wrong market suffix (`AAPL.US` vanishes, `AAPL.O`
- * returns).
- *
- * So the remaining shape is the dangerous one: a misspelled code is invisible
- * otherwise — `--key-by code` batch mapping finds no key at all rather than a
- * null, and the pull quietly returns fewer rows than requested with exit code 0.
- *
- * Universe entries with no `.` are skipped — those are sector IDs, which the
- * server expands into constituents, so their absence from the response is
- * expected rather than a dropped row. */
 export function droppedFromMatrix(data, requestedSecurities, requestedIndicators) {
     const empty = { securities: [], indicators: [] };
     if (!data || typeof data !== "object")
@@ -241,11 +126,6 @@ export function droppedFromMatrix(data, requestedSecurities, requestedIndicators
         indicators: requestedIndicators.filter((code) => !returnedIndicators.has(code)),
     };
 }
-/** True only when the payload carries NONE of the EDE matrix keys — a foreign
- * shape. Nothing legitimately reaches the flatteners in that state — `indicator
- * search` prints its unwrapped list directly and `raw call` bypasses them — so
- * this is a protocol failure, not a payload to hand back: returning it would
- * print the raw envelope and exit 0, indistinguishable from success. */
 function assertMatrixPayload(data, d) {
     const bare = d.securityCodeList === undefined && d.securityNameList === undefined
         && d.indicatorList === undefined && d.dates === undefined && d.values === undefined;
@@ -258,19 +138,6 @@ function assertAxis(data, axis, key) {
         throw new ApiError(`Indicator matrix shape mismatch: the response is missing \`${key}\` or it is not an array — the response layout may have changed`, undefined, undefined, data);
     }
 }
-/** Resolve the display names for a security axis, degrading instead of failing.
- *
- * Names are consumed POSITIONALLY, so a list that does not line up cannot be
- * trusted at all: `["泡泡玛特"]` against `["600519.SH","09992.HK"]` labels 茅台's
- * series 泡泡玛特, and a `[null]` element used to render a column literally
- * headed `"null"` (both probed 2026-08-02). Neither may reach the output.
- *
- * But a name is a LABEL, not structure — `securityCodeList` already carries
- * identity, and every header falls back to the code. So an anomaly here drops
- * the names and keeps the values, rather than killing an EDE command whose
- * numbers are all correct. That is a deliberate asymmetry with the other guards
- * in this module: they protect against MISATTRIBUTED VALUES and must be fatal;
- * this one protects a caption. */
 function resolveSecurityNames(names, codes) {
     if (names === undefined || names === null)
         return undefined;
@@ -282,9 +149,6 @@ function resolveSecurityNames(names, codes) {
     return names.map((name, i) => {
         if (typeof name === "string" && name.trim() !== "")
             return name;
-        // A blank or null name is a plausible gap for one security — fall back
-        // quietly. A non-string (an object, a number) means the field changed type,
-        // which is worth saying once.
         if (typeof name !== "string" && name !== null && name !== undefined && !warned) {
             warned = true;
             process.stderr.write(`[gangtise] warning: securityNameList holds non-string entries; those columns fall back to the security code.\n`);
@@ -292,13 +156,6 @@ function resolveSecurityNames(names, codes) {
         return codes[i];
     });
 }
-/** The matrix endpoints cannot legitimately answer with a non-object payload:
- * `indicator search` never reaches the flatteners (it prints the unwrapped list
- * directly) and `raw call` bypasses them entirely, so there is no caller for
- * which `null`, an array, or a foreign object is a valid cross-section /
- * time-series / screener body. Checked here, BEFORE the envelope is discarded,
- * because a `data: null` cannot carry the non-enumerable traceId — passing the
- * envelope as details is the only way such a failure stays traceable. */
 export function requireIndicatorMatrix(raw) {
     const data = unwrapIndicatorData(raw);
     if (!data || typeof data !== "object" || Array.isArray(data)) {
@@ -311,23 +168,6 @@ function assertValuesPresent(data, values) {
         throw new ApiError(`Indicator matrix shape mismatch: the response carries axis lists but no \`values\` array — the response layout may have changed`, undefined, undefined, data);
     }
 }
-/** The matrix and its axis labels must agree on BOTH dimensions, or cells are
- * dropped or misread. The 2026-08-01 revision transposed cross-section without a
- * version marker, so a re-transpose has to fail loudly rather than silently
- * relabel columns — with the caveat that this only catches a NON-SQUARE change.
- * A 2×2 or 1×1 matrix keeps its dimensions when transposed and would still be
- * read with the axes swapped; nothing in the payload distinguishes the two.
- *
- * Row length is checked exactly, not leniently: the server pads a row with
- * `null` rather than truncating it — probed 2026-08-02 across A/HK/US, where a
- * US security missing 3 of 4 indicators still came back with a full-length row,
- * and a cross-market time series padded every security to the union of trading
- * days (each market's own holidays land as `null`). A short or long row is
- * therefore a structural change, not missing data.
- *
- * `data` rides along as ApiError details so the failure keeps the response's
- * traceId — a shape mismatch is precisely the kind of thing support needs to
- * trace, and without it the error reaches the user trace-less. */
 function assertMatrixShape(data, values, rows, rowAxis, cols, colAxis) {
     if (values.length !== rows) {
         throw new ApiError(`Indicator matrix shape mismatch: got ${values.length} value rows for ${rows} ${rowAxis} — the response layout may have changed`, undefined, undefined, data);
@@ -339,19 +179,12 @@ function assertMatrixShape(data, values, rows, rowAxis, cols, colAxis) {
         }
     }
 }
-// Cross-section (and the screener, whose payload is the same shape plus a
-// per-indicator `field`): one row per security, one column per indicator.
-// `values` is [security][indicator], so security i's value for indicator j is
-// values[i][j]. There is no row-level date any more — the query date now lives
-// in each indicator's own parameters and may legitimately differ per column.
 export function flattenCrossSection(data, keyBy = "name") {
     if (!data || typeof data !== "object" || Array.isArray(data)) {
         throw new ApiError(`Indicator API returned no matrix object (got ${data === null ? "null" : Array.isArray(data) ? "an array" : typeof data}) — the response layout may have changed`, undefined, undefined, data);
     }
     const d = data;
     assertMatrixPayload(data, d);
-    // Past this point the payload claims to be a matrix, so every axis it needs
-    // must actually be there. A `null` or absent axis is a broken response.
     const securityCode = asIdentityArray(data, d.securityCodeList, "securityCodeList");
     const indicators = asIndicatorMetaList(data, d.indicatorList);
     assertAxis(data, securityCode, "securityCodeList");
@@ -361,8 +194,6 @@ export function flattenCrossSection(data, keyBy = "name") {
     const securityName = resolveSecurityNames(d.securityNameList, securityCode);
     const headers = indicatorHeaders(indicators, keyBy, CROSS_SECTION_COLUMNS);
     const list = securityCode.map((code, i) => {
-        // Only create `name` when there IS one: an always-present `name: undefined`
-        // is invisible in JSON but renders as a real empty column in CSV/table.
         const row = securityName ? { security: code, name: securityName[i] } : { security: code };
         const cells = rowOf(d.values, i);
         for (let j = 0; j < headers.length; j++) {
@@ -372,25 +203,6 @@ export function flattenCrossSection(data, keyBy = "name") {
     });
     return { list, total: list.length };
 }
-// Time-series: one row per date. Columns are the indicators (single-security
-// case) or the securities (single-indicator case) — exactly one dimension
-// varies, per the API contract. `values` stays a 2D [series][date] matrix.
-//
-// Axis rule, in priority order:
-//  1. More than one indicator came back → multi-indicator × single-security.
-//  2. More than one security came back → single-indicator × multi-security.
-//     This is what a sector ID produces: the request carries ONE universe entry
-//     and the server expands it into N constituents, so the request count says
-//     nothing about the axis.
-//  3. Both are 1 → genuinely ambiguous, so fall back to what was REQUESTED:
-//     - a universe holding a sector ID always takes the security axis. The
-//       sector may expand to one constituent, or the rest may have been dropped
-//       for lack of data; either way the caller asked "which securities", and an
-//       indicator-named column would erase whose series this is.
-//     - otherwise the entry count decides. The server drops securities with no
-//       data at all, so a two-security request that comes back with one must
-//       still be labelled by security (probed 2026-08-02: `finc_pe_ttm` over
-//       600519.SH + 09992.HK).
 export function flattenTimeSeries(data, keyBy = "name", requestedUniverse) {
     if (!data || typeof data !== "object" || Array.isArray(data)) {
         throw new ApiError(`Indicator API returned no matrix object (got ${data === null ? "null" : Array.isArray(data) ? "an array" : typeof data}) — the response layout may have changed`, undefined, undefined, data);
@@ -405,28 +217,12 @@ export function flattenTimeSeries(data, keyBy = "name", requestedUniverse) {
     assertAxis(data, indicators, "indicatorList");
     assertValuesPresent(data, d.values);
     const securityName = resolveSecurityNames(d.securityNameList, securityCode);
-    // The API permits multi-indicator × single-security OR single-indicator ×
-    // multi-security, never both — the server rejects such a REQUEST with 100003.
-    // A RESPONSE carrying both axes plural is therefore unattributable: whichever
-    // axis becomes the columns, the other one's identity is silently discarded
-    // (probed 2026-08-02: 2×2 rendered as 收盘价/成交量 with both securities gone,
-    // and droppedFromMatrix sees nothing missing so it would not even flag).
-    // Data with only one identity axis is unattributable in the other direction:
-    // `securityCodeList: []` alongside a populated matrix leaves every row
-    // belonging to no security at all, and the row/column counts still line up so
-    // no other guard notices.
-    // Without this, dates-with-no-series still passes the later shape check (0 rows
-    // for 0 series) and emits one row per date carrying nothing but the date. A
-    // response that resolved to nothing empties `dates` too (probed 2026-08-02), so dates
-    // alongside a missing axis is always a broken response.
     if (dates.length > 0 && (securityCode.length === 0 || indicators.length === 0)) {
         throw new ApiError(`Indicator matrix shape mismatch: the time-series response carries ${dates.length} dates but ${securityCode.length} securities and ${indicators.length} indicators — the data could not be attributed`, undefined, undefined, data);
     }
     if (securityCode.length > 1 && indicators.length > 1) {
         throw new ApiError(`Indicator matrix shape mismatch: the time-series response carries ${securityCode.length} securities AND ${indicators.length} indicators, which the endpoint does not support — one of the two identities would be lost`, undefined, undefined, data);
     }
-    // A universe entry without a `.` is a sector ID — the server expands it, so
-    // neither its presence nor the entry count says anything about the axis.
     const requested = requestedUniverse === undefined ? undefined : [...new Set(requestedUniverse)];
     const hasSector = requested?.some((entry) => !entry.includes(".")) ?? false;
     const seriesAreIndicators = indicators.length > 1 ? true
@@ -435,9 +231,6 @@ export function flattenTimeSeries(data, keyBy = "name", requestedUniverse) {
                 : (requested?.length ?? securityCode.length) <= 1;
     const seriesCount = seriesAreIndicators ? indicators.length : securityCode.length;
     assertMatrixShape(data, d.values, seriesCount, seriesAreIndicators ? "indicators" : "securities", dates.length, "dates");
-    // Map over securityCode rather than securityNameList directly: a response that
-    // omits the names must still yield one header per security (falling back to
-    // the code), not zero columns.
     const headers = seriesAreIndicators
         ? indicatorHeaders(indicators, keyBy, ["date"])
         : buildHeaders(securityCode.map((code, i) => (keyBy === "code" ? code : securityName?.[i])), securityCode, ["date"]);

package/dist/src/core/normalize.js

@@ -1,24 +1,10 @@
 import { ENVELOPE_TRACE_ID, ValidationError } from "./errors.js";
-/** 信封 traceId 由 `client.ts` 挂在每个成功响应的 payload 上（非枚举 symbol）。
- * 结构异常报障没这个 id 服务端查不了，所以拍平失败时要一并带出。 */
 function traceSuffix(source) {
     if (!source || typeof source !== "object")
         return "";
     const traceId = source[ENVELOPE_TRACE_ID];
     return typeof traceId === "string" ? `（trace ${traceId}）` : "";
 }
-/** 按位置把列式响应的一行值拍平成对象。
- *
- * 上游对「fieldList 里有该接口不存在的字段名」有两套处理，实测 2026-07-24：
- * day-kline / minute-kline / fund-flow 把名和值一起丢、三大报表补 null——长度仍相等，安全；
- * 但 realtime / main-business / valuation-analysis 是**值只按有效字段返回、字段名却按请求
- * 原样回显**。长度一旦不等，按位置拍平就会把值贴到错误的字段上：realtime 传
- * ["securityCode","close","turnoverRate"]（realtime 根本没有 close）只回 2 个值，
- * 换手率 28.5573 被贴成 close，读起来就是「茅台收盘价 28.56」（真实价 1297.41）。
- * 不报错、数字看着还合理、却完全是另一个指标——静默错列必须变成显式失败。
- *
- * 文案不能一口咬定「字段名传错」：`alternative edb-data` 走同一个拍平却根本没有
- * `--field`（只有 `--indicator-id`），那里长度不等只可能是上游响应结构变了。 */
 export function zipFieldRow(fields, row, source) {
     if (row.length !== fields.length) {
         throw new ValidationError(`响应字段数与 fieldList 不匹配（fieldList ${fields.length} 项、该行返回 ${row.length} 个值）——按位置拍平会把值贴到错误的字段上，已拒绝输出。带 --field 的命令多为传了该接口不存在的字段名（上游只返回有效字段的值、字段名却按请求回显）：核对 --field 取值（如 quote realtime 没有 close，最新价是 latestPrice），不确定就不传 --field（返回全量字段最稳）。没有 --field 的命令（如 alternative edb-data）出现此错，是上游响应结构异常，请报障${traceSuffix(source)}。`);

package/dist/src/core/output.js

@@ -8,16 +8,9 @@ export function parseOutputFormat(value) {
     }
     throw new ConfigError(`Unsupported format: ${format}`);
 }
-/** Cell text for terminal-facing formats (table/markdown): newlines collapsed for
- * alignment, remaining C0/DEL/C1 control chars stripped so server data can't inject
- * terminal escape sequences into the user's terminal (U+009B is a one-byte CSI
- * that 8-bit-control terminals treat exactly like ESC[). */
 function sanitizeCell(value) {
     return value.replace(/[\r\n]+/g, " ").replace(/[\u0000-\u001f\u007f\u0080-\u009f]/g, "");
 }
-/** Terminal display width: CJK/fullwidth chars and emoji occupy 2 columns — padEnd
- * counts UTF-16 code units and misaligns every table containing Chinese text or emoji
- * (e.g. WeChat group names). */
 function displayWidth(value) {
     let width = 0;
     for (const ch of value) {
@@ -40,10 +33,6 @@ function formatScalar(value) {
     }
     return String(value);
 }
-/** Rows for a list: object rows as-is with stray null/scalar rows dropped (one bad
- * row must not degrade the whole table to index/value pairs — and the streaming CSV
- * path already skips them, so both paths agree). A list with NO object rows at all
- * (e.g. plain string codes) still renders as index/value pairs. */
 function rowsFromList(list) {
     const objectRows = list.filter((item) => Boolean(item && typeof item === "object" && !Array.isArray(item)));
     if (objectRows.length > 0)
@@ -51,11 +40,6 @@ function rowsFromList(list) {
     return list.map((item, index) => ({ index, value: item }));
 }
 function toRows(value) {
-    // A null/undefined payload means "no data", not "one row whose only column is
-    // null". Without this guard it fell through to [{ value }] and jsonl emitted
-    // {"value":null} — a phantom record that makes `wc -l` report 1. Real case:
-    // insight foreign-opinion --industry answers 200 + data:null.
-    // Scalars (0, "", false) are left alone; only the two empty values short-circuit.
     if (value === null || value === undefined) {
         return [];
     }
@@ -71,10 +55,7 @@ function toRows(value) {
     }
     return [{ value }];
 }
-// One huge cell (a 50KB brief/chat message) would otherwise force every row of
-// that column to be padded to the same width — rows × width of pure spaces.
 const MAX_CELL_DISPLAY_WIDTH = 120;
-/** Truncate a cell to the display-width cap, ellipsis included in the budget. */
 function clampCell(value) {
     if (displayWidth(value) <= MAX_CELL_DISPLAY_WIDTH)
         return value;
@@ -94,12 +75,6 @@ function renderTable(rows) {
         return "(empty)";
     }
     const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
-    // Format every cell once (formatScalar may JSON.stringify objects), sanitizing
-    // control chars so multi-line fields don't break alignment. Reuse the matrix for
-    // both width and rendering — and compute widths with reduce, NOT Math.max(...arr):
-    // spreading a per-row array overflows the call stack on large results (table is
-    // the default format, e.g. `quote day-kline --security all`). Widths and padding
-    // use displayWidth so CJK cells stay aligned.
     const headerCells = columns.map((column) => clampCell(sanitizeCell(column)));
     const matrix = rows.map((row) => columns.map((column) => clampCell(sanitizeCell(formatScalar(row[column])))));
     const widths = columns.map((_, c) => matrix.reduce((max, cells) => Math.max(max, displayWidth(cells[c])), displayWidth(headerCells[c])));
@@ -114,10 +89,6 @@ function renderMarkdown(rows) {
         return "(empty)";
     }
     const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
-    // Column names come from server data (e.g. EDE indicator display names) — escape
-    // them like cell values or a name containing | / , breaks the whole table.
-    // Backslash must go first: escaping only "|" turns a literal `\|` into `\\|`,
-    // which GFM reads as an escaped backslash + BARE pipe → an extra column.
     const mdEscape = (value) => value.replaceAll("\\", "\\\\").replaceAll("|", "\\|");
     const header = `| ${columns.map((column) => mdEscape(sanitizeCell(column))).join(" | ")} |`;
     const divider = `| ${columns.map(() => "---").join(" | ")} |`;
@@ -134,8 +105,6 @@ function renderCsv(rows) {
     return [header, ...body].join("\n");
 }
 export function renderOutput(value, format) {
-    // toRows is computed lazily per branch: json never needs it, and jsonl only
-    // falls back to it when the value isn't already a {list}/array.
     switch (format) {
         case "json":
             return JSON.stringify(value, null, 2);
@@ -154,18 +123,14 @@ export function renderOutput(value, format) {
             return renderTable(toRows(value));
     }
 }
-/** Stream large jsonl/csv output row-by-row to avoid building a full string in memory. */
 export async function streamOutputToFile(value, format, outputPath) {
     if (format !== "jsonl" && format !== "csv")
         return false;
     const list = pickList(value);
     if (!list)
         return false;
-    // Below this row count the join() approach is cheaper than per-row writes.
     if (list.length < 1000)
         return false;
-    // csv can only stream object rows; an all-scalar list has no columns — fall back
-    // to renderOutput's index/value shaping instead of writing a BOM-only file.
     let csvRows = [];
     let csvColumns = [];
     if (format === "csv") {
@@ -177,13 +142,8 @@ export async function streamOutputToFile(value, format, outputPath) {
     const { dirname } = await import("node:path");
     const { createWriteStream } = await import("node:fs");
     await fs.mkdir(dirname(outputPath), { recursive: true });
-    // Stream into a .part sibling and rename over the target only on success, so a
-    // failed re-export never destroys the previous good file.
     const partPath = `${outputPath}.part`;
     const stream = createWriteStream(partPath, { encoding: "utf8" });
-    // A stream 'error' with no listener (EACCES on open, ENOSPC mid-write) crashes the
-    // process before any write callback fires. Swallow the event here — the failure
-    // still surfaces through the write/end callbacks below.
     stream.on("error", () => { });
     try {
         if (format === "jsonl") {
@@ -192,7 +152,6 @@ export async function streamOutputToFile(value, format, outputPath) {
             }
         }
         else {
-            // BOM so Excel double-click decodes Chinese as UTF-8 instead of ANSI/GBK.
             await writeLine(stream, "\ufeff" + csvColumns.map(csvEscape).join(","));
             for (const row of csvRows) {
                 const cells = csvColumns.map((column) => csvEscape(formatScalar(row[column])));
@@ -205,13 +164,7 @@ export async function streamOutputToFile(value, format, outputPath) {
         await fs.rename(partPath, outputPath);
     }
     catch (error) {
-        // Mirror the download path: never leave a truncated file that looks complete.
-        // createWriteStream opens lazily — an early abort can reach unlink BEFORE the
-        // open() creates the file, so wait for 'close' (fd released or open aborted)
-        // or the .part would reappear right after being "removed".
         stream.destroy();
-        // Already-closed happens when the failure was the rename (stream ended fine);
-        // then 'close' has fired and waiting for it again would hang forever.
         if (!stream.closed) {
             await new Promise((resolve) => stream.once("close", resolve));
         }
@@ -220,8 +173,6 @@ export async function streamOutputToFile(value, format, outputPath) {
     }
     return true;
 }
-/** Extract a row array from a value: the array itself, or its `.list` property,
- * else null. Shared by streaming, printer's title-cache, and list detection. */
 export function pickList(value) {
     if (Array.isArray(value))
         return value;
@@ -234,9 +185,6 @@ export function pickList(value) {
 }
 function csvEscape(value) {
     let out = value;
-    // Formula-injection guard, but don't mangle legitimate numbers: a leading
-    // -/+ only needs escaping when the cell isn't a finite number (e.g. "-1+cmd"),
-    // so values like "-3.5" stay numeric for Excel/pandas.
     if (/^[=@\t\r]/.test(out) || (/^[+\-]/.test(out) && !Number.isFinite(Number(out))))
         out = "'" + out;
     if (/[",\n\r]/.test(out))
@@ -250,8 +198,6 @@ function writeLine(stream, line) {
             resolve();
             return;
         }
-        // Waiting only for 'drain' would hang forever if the stream errors instead;
-        // race the two and detach the loser so listeners don't pile up per write.
         const onDrain = () => { stream.off("error", onError); resolve(); };
         const onError = (err) => { stream.off("drain", onDrain); reject(err); };
         stream.once("drain", onDrain);
@@ -264,8 +210,6 @@ export async function saveOutputIfNeeded(content, outputPath) {
     }
     const { dirname } = await import("node:path");
     await fs.mkdir(dirname(outputPath), { recursive: true });
-    // Write to a .part sibling and rename over the target only on success, so a
-    // failed re-export/download never destroys the previous good file.
     const partPath = `${outputPath}.part`;
     try {
         if (typeof content === "string") {

package/dist/src/core/printer.js

@@ -1,13 +1,7 @@
 import { normalizeRows } from "./normalize.js";
 import { pickList, renderOutput, saveOutputIfNeeded, streamOutputToFile } from "./output.js";
 import { extractTitles, writeTitleCache } from "./titleCache.js";
-/** Rows above which renderOutput's single in-memory string risks high memory / the V8
- * max-string-length cap. Well above normal result sizes, so it only fires on huge exports. */
 const LARGE_RESULT_ROWS = 50_000;
-/** Warn when we're about to renderOutput a huge result. Called only on the paths that
- * actually render — never after streamOutputToFile streamed — so it can't misfire on a
- * genuinely streamed export, and it DOES fire on the all-scalar-csv list that streaming
- * declines (which then falls back to a full in-memory string). */
 function warnIfLargeInMemory(items, format) {
     if (items && items.length >= LARGE_RESULT_ROWS) {
         process.stderr.write(`[gangtise] note: ${items.length} rows in '${format}' is built entirely in memory; stream large exports to a file with --format jsonl --output <path> (or csv).\n`);
@@ -28,11 +22,6 @@ export async function printData(data, format, output, cache) {
             const listLen = Array.isArray(meta.list) ? meta.list.length : 0;
             process.stderr.write(`Total: ${meta.total}, showing: ${listLen}\n`);
         }
-        // Incomplete results exit with code 3: the table/csv/jsonl renderers only
-        // emit the rows, so without a distinct exit code a script or AI consumer
-        // cannot tell such an export from a clean one. `partial` means rows are
-        // missing — failed pages/shards, a row cap, or an EDE response that dropped
-        // whole securities/indicators because it did not recognise those codes.
         if (meta.partial === true) {
             process.exitCode = 3;
         }
@@ -42,22 +31,14 @@ export async function printData(data, format, output, cache) {
             process.stdout.write(`${output}\n`);
             return;
         }
-        // streamOutputToFile declined (non-stream format, or an all-scalar csv list) \u2192 we
-        // fall back to renderOutput, which builds the whole result as one string.
         warnIfLargeInMemory(items, format);
         const content = renderOutput(normalized, format);
-        // CSV files get a BOM so Excel double-click decodes Chinese as UTF-8 (stdout
-        // stays BOM-free for pipes).
         await saveOutputIfNeeded(format === "csv" ? `\ufeff${content}` : content, output);
         process.stdout.write(`${output}\n`);
         return;
     }
     warnIfLargeInMemory(items, format);
     const rendered = renderOutput(normalized, format);
-    // An empty render means "no rows at all". Appending the newline anyway would put
-    // one blank line on stdout — `wc -l` reports 1 and `while read` yields one empty
-    // record, which is exactly the phantom row the null-payload guard in toRows()
-    // removes. Table/markdown render "(empty)" so they are unaffected.
     if (rendered)
         process.stdout.write(`${rendered}\n`);
 }