token-goat 2.9.13 → 2.9.15

package/dist/token-goat-chunk-NU7TLMQK.mjs

@@ -0,0 +1,585 @@
+import { createRequire as __cjsRequire } from 'node:module';
+const require = __cjsRequire(import.meta.url);
+import {
+  queryCsv,
+  quoteCsvCell
+} from "./token-goat-chunk-YKG35VHC.mjs";
+import {
+  NotAnOfficeDocumentError,
+  assertOoxmlWithinDeadline,
+  decodeZipEntry,
+  ooxmlPartBudget,
+  ooxmlWorkDeadline,
+  parseOoxmlPart,
+  readOoxmlZip
+} from "./token-goat-chunk-MZDIJJ3R.mjs";
+import {
+  DocumentRefusedError
+} from "./token-goat-chunk-Y4AFKTHK.mjs";
+import {
+  displaySafeText
+} from "./token-goat-chunk-ERTXEKB6.mjs";
+import {
+  init_define_import_meta_env
+} from "./token-goat-chunk-A37V4PBF.mjs";
+
+// src/xlsx_extract.ts
+init_define_import_meta_env();
+
+// src/xlsx_reader.ts
+init_define_import_meta_env();
+var EMPTY_CELL = Object.freeze({ value: null, text: "" });
+function asArray(val) {
+  if (val === void 0 || val === null) return [];
+  if (Array.isArray(val)) return val.filter((v) => v !== null && typeof v === "object");
+  if (typeof val === "object") return [val];
+  return [];
+}
+function textOf(node) {
+  if (node === void 0 || node === null) return "";
+  if (typeof node === "string") return node;
+  if (typeof node === "number" || typeof node === "boolean") return String(node);
+  if (Array.isArray(node)) return node.map(textOf).join("");
+  const t = node["#text"];
+  return t === void 0 ? "" : String(t);
+}
+function attr(node, name) {
+  if (node === void 0) return void 0;
+  const v = node[`@_${name}`];
+  return v === void 0 || v === null ? void 0 : String(v);
+}
+function isTruthyAttr(v) {
+  return v === "1" || v === "true";
+}
+function refToColumn(ref) {
+  let n = 0;
+  for (const ch of ref) {
+    const code = ch.toUpperCase().charCodeAt(0);
+    if (code < 65 || code > 90) break;
+    n = n * 26 + (code - 64);
+  }
+  return n;
+}
+function refToRow(ref) {
+  const m = /(\d+)\s*$/.exec(ref);
+  return m ? parseInt(m[1], 10) : 0;
+}
+var BUILTIN_DATE_FORMAT_IDS = /* @__PURE__ */ new Set([14, 15, 16, 17, 18, 19, 20, 21, 22, 45, 46, 47]);
+function formatCodeIsDate(formatCode) {
+  const stripped = formatCode.replace(/"[^"]*"/g, "").replace(/\[[^\]]*\]/g, "").replace(/\\./g, "");
+  return /[ymdhs]/i.test(stripped);
+}
+function serialToDate(serial, date1904) {
+  if (date1904) return new Date(Date.UTC(1904, 0, 1) + Math.round(serial * 864e5));
+  const adjusted = serial >= 61 ? serial - 1 : serial;
+  return new Date(Date.UTC(1899, 11, 31) + Math.round(adjusted * 864e5));
+}
+function numberToText(n) {
+  return String(n);
+}
+function parseStyles(xml, parsed) {
+  if (xml === null || parsed === null || typeof parsed !== "object") return { dateStyles: [] };
+  const sheet = parsed["styleSheet"];
+  if (sheet === void 0 || sheet === null || typeof sheet !== "object") return { dateStyles: [] };
+  const root = sheet;
+  const customDateFormats = /* @__PURE__ */ new Set();
+  for (const fmt of asArray(root["numFmts"]?.["numFmt"])) {
+    const id = Number(attr(fmt, "numFmtId"));
+    const code = attr(fmt, "formatCode");
+    if (Number.isFinite(id) && code !== void 0 && formatCodeIsDate(code)) customDateFormats.add(id);
+  }
+  const dateStyles = [];
+  for (const xf of asArray(root["cellXfs"]?.["xf"])) {
+    const id = Number(attr(xf, "numFmtId") ?? "0");
+    dateStyles.push(Number.isFinite(id) && (BUILTIN_DATE_FORMAT_IDS.has(id) || customDateFormats.has(id)));
+  }
+  return { dateStyles };
+}
+function parseSharedStrings(parsed) {
+  if (parsed === null || typeof parsed !== "object") return [];
+  const sst = parsed["sst"];
+  if (sst === void 0 || sst === null || typeof sst !== "object") return [];
+  return asArray(sst["si"]).map((si) => {
+    if (si["t"] !== void 0) return textOf(si["t"]);
+    const runs = asArray(si["r"]);
+    if (runs.length > 0) return runs.map((r) => textOf(r["t"])).join("");
+    return "";
+  });
+}
+function parseWorkbookRels(parsed) {
+  const out = /* @__PURE__ */ new Map();
+  if (parsed === null || typeof parsed !== "object") return out;
+  const rels = parsed["Relationships"];
+  if (rels === void 0 || rels === null || typeof rels !== "object") return out;
+  for (const rel of asArray(rels["Relationship"])) {
+    const id = attr(rel, "Id");
+    const target = attr(rel, "Target");
+    if (id === void 0 || target === void 0) continue;
+    const normalized = target.startsWith("/") ? target.slice(1) : `xl/${target.replace(/^\.\//, "")}`;
+    out.set(id, normalized);
+  }
+  return out;
+}
+function buildCell(c, shared, styles, date1904) {
+  const type = attr(c, "t") ?? "n";
+  const styleIdx = Number(attr(c, "s") ?? "-1");
+  const isDateStyle = Number.isInteger(styleIdx) && styleIdx >= 0 && styles.dateStyles[styleIdx] === true;
+  const hasV = c["v"] !== void 0;
+  const hasIs = c["is"] !== void 0;
+  const fNode = c["f"];
+  const formula = fNode === void 0 ? "" : textOf(fNode);
+  if (!hasV && !hasIs && formula === "") return null;
+  let raw;
+  let text;
+  if (type === "s") {
+    const idx = Number(textOf(c["v"]));
+    const s = Number.isInteger(idx) ? shared[idx] ?? "" : "";
+    raw = s;
+    text = s;
+  } else if (type === "inlineStr") {
+    const isNode = c["is"];
+    const s = isNode !== void 0 && isNode !== null && typeof isNode === "object" ? (() => {
+      const node = isNode;
+      if (node["t"] !== void 0) return textOf(node["t"]);
+      return asArray(node["r"]).map((r) => textOf(r["t"])).join("");
+    })() : textOf(isNode);
+    raw = s;
+    text = s;
+  } else if (type === "str") {
+    const s = textOf(c["v"]);
+    raw = s;
+    text = s;
+  } else if (type === "b") {
+    const b = textOf(c["v"]).trim() === "1";
+    raw = b;
+    text = b ? "TRUE" : "FALSE";
+  } else if (type === "e") {
+    const e = textOf(c["v"]);
+    raw = { error: e };
+    text = e;
+  } else {
+    const n = Number(textOf(c["v"]));
+    if (!Number.isFinite(n)) {
+      raw = null;
+      text = "";
+    } else if (isDateStyle) {
+      const d = serialToDate(n, date1904);
+      raw = d;
+      text = d.toISOString();
+    } else {
+      raw = n;
+      text = numberToText(n);
+    }
+  }
+  if (formula !== "") return { value: { formula, result: raw }, text, formula };
+  return { value: raw, text };
+}
+function parseSheet(parsed, shared, styles, date1904) {
+  const cells = /* @__PURE__ */ new Map();
+  let rowCount = 0;
+  let columnCount = 0;
+  let populatedRows = 0;
+  if (parsed === null || typeof parsed !== "object") return { cells, rowCount, columnCount, populatedRows };
+  const ws = parsed["worksheet"];
+  if (ws === void 0 || ws === null || typeof ws !== "object") return { cells, rowCount, columnCount, populatedRows };
+  const sheetData = ws["sheetData"];
+  if (sheetData === void 0 || sheetData === null || typeof sheetData !== "object") {
+    return { cells, rowCount, columnCount, populatedRows };
+  }
+  let fallbackRow = 0;
+  for (const row of asArray(sheetData["row"])) {
+    const declaredRow = Number(attr(row, "r"));
+    const rowIdx = Number.isInteger(declaredRow) && declaredRow > 0 ? declaredRow : fallbackRow + 1;
+    fallbackRow = rowIdx;
+    let fallbackCol = 0;
+    const rowCells = /* @__PURE__ */ new Map();
+    for (const c of asArray(row["c"])) {
+      const ref = attr(c, "r");
+      const declaredCol = ref === void 0 ? 0 : refToColumn(ref);
+      const colIdx = declaredCol > 0 ? declaredCol : fallbackCol + 1;
+      fallbackCol = colIdx;
+      const cell = buildCell(c, shared, styles, date1904);
+      if (cell === null) continue;
+      rowCells.set(colIdx, cell);
+      if (colIdx > columnCount) columnCount = colIdx;
+    }
+    if (rowCells.size === 0) continue;
+    cells.set(rowIdx, rowCells);
+    populatedRows++;
+    if (rowIdx > rowCount) rowCount = rowIdx;
+  }
+  return { cells, rowCount, columnCount, populatedRows };
+}
+function makeWorksheet(name, data) {
+  function getRow(r) {
+    const rowCells = data.cells.get(r);
+    return {
+      get values() {
+        const out = [];
+        if (rowCells !== void 0) for (const [col, cell] of rowCells) out[col] = cell.value;
+        return out;
+      },
+      eachCell(opts, cb) {
+        if (opts.includeEmpty) {
+          let maxCol = 0;
+          if (rowCells !== void 0) {
+            for (const c of rowCells.keys()) if (c > maxCol) maxCol = c;
+          }
+          for (let c = 1; c <= maxCol; c++) cb(rowCells?.get(c) ?? EMPTY_CELL, c);
+          return;
+        }
+        if (rowCells === void 0) return;
+        for (const col of [...rowCells.keys()].sort((a, b) => a - b)) cb(rowCells.get(col), col);
+      }
+    };
+  }
+  return {
+    name,
+    rowCount: data.rowCount,
+    columnCount: data.columnCount,
+    actualRowCount: data.populatedRows,
+    getRow,
+    getCell(addr) {
+      return data.cells.get(refToRow(addr))?.get(refToColumn(addr)) ?? EMPTY_CELL;
+    }
+  };
+}
+async function readXlsxWorkbook(filePath, deadline = ooxmlWorkDeadline()) {
+  const entries = await readOoxmlZip(filePath, ".xlsx");
+  const budget = ooxmlPartBudget();
+  const workbookXml = decodeZipEntry(entries, "xl/workbook.xml", budget);
+  if (workbookXml === null) throw new NotAnOfficeDocumentError(`not a valid .xlsx file: ${filePath}`);
+  const workbookRoot = await parseOoxmlPart(workbookXml);
+  const wbNode = workbookRoot?.["workbook"];
+  if (wbNode === void 0 || wbNode === null || typeof wbNode !== "object") {
+    throw new NotAnOfficeDocumentError(`not a valid .xlsx file: ${filePath}`);
+  }
+  const wb = wbNode;
+  const date1904 = isTruthyAttr(attr(wb["workbookPr"], "date1904"));
+  const relsXml = decodeZipEntry(entries, "xl/_rels/workbook.xml.rels", budget);
+  const rels = parseWorkbookRels(relsXml === null ? null : await parseOoxmlPart(relsXml));
+  const sharedXml = decodeZipEntry(entries, "xl/sharedStrings.xml", budget);
+  const shared = sharedXml === null ? [] : parseSharedStrings(await parseOoxmlPart(sharedXml));
+  const stylesXml = decodeZipEntry(entries, "xl/styles.xml", budget);
+  const styles = parseStyles(stylesXml, stylesXml === null ? null : await parseOoxmlPart(stylesXml));
+  const worksheets = [];
+  const parsedByPart = /* @__PURE__ */ new Map();
+  for (const sheet of asArray(wb["sheets"]?.["sheet"])) {
+    const name = attr(sheet, "name") ?? "";
+    const rid = attr(sheet, "r:id") ?? attr(sheet, "relationshipId");
+    const partPath = rid === void 0 ? void 0 : rels.get(rid);
+    const cached = partPath === void 0 ? void 0 : parsedByPart.get(partPath);
+    if (cached !== void 0) {
+      worksheets.push(makeWorksheet(name, cached));
+      continue;
+    }
+    assertOoxmlWithinDeadline(deadline, "Narrow the read to specific sheets with xlsx-head, or use a smaller workbook.");
+    const sheetXml = partPath === void 0 ? null : decodeZipEntry(entries, partPath, budget);
+    const data = sheetXml === null ? { cells: /* @__PURE__ */ new Map(), rowCount: 0, columnCount: 0, populatedRows: 0 } : parseSheet(await parseOoxmlPart(sheetXml), shared, styles, date1904);
+    if (partPath !== void 0) parsedByPart.set(partPath, data);
+    worksheets.push(makeWorksheet(name, data));
+  }
+  return {
+    worksheets,
+    getWorksheet: (name) => worksheets.find((ws) => ws.name === name)
+  };
+}
+
+// src/xlsx_extract.ts
+var loadWorkbook = readXlsxWorkbook;
+function requireSheet(wb, sheetName) {
+  if (sheetName !== void 0 && sheetName.trim() !== "") {
+    const ws = wb.getWorksheet(sheetName);
+    if (ws === void 0) {
+      throw new Error(`unknown sheet: ${sheetName} (available: ${wb.worksheets.map((s) => s.name).join(", ")})`);
+    }
+    return ws;
+  }
+  const first = wb.worksheets[0];
+  if (first === void 0) {
+    throw new Error("workbook contains no worksheets");
+  }
+  return first;
+}
+var MAX_XLSX_SCAN_CELLS = 2e7;
+var XlsxScanTooLargeError = class extends DocumentRefusedError {
+  constructor(extent, cells, hint) {
+    super(`${extent} (${cells.toLocaleString()} cells), over the ${MAX_XLSX_SCAN_CELLS.toLocaleString()}-cell scan limit; ${hint}`, "XlsxScanTooLargeError");
+  }
+};
+function assertCellCount(cells, extent, hint) {
+  if (cells > MAX_XLSX_SCAN_CELLS) throw new XlsxScanTooLargeError(extent, cells, hint);
+}
+function assertScannableExtent(ws) {
+  assertCellCount(
+    (ws.rowCount || 0) * (ws.columnCount || 0),
+    `sheet "${ws.name}" declares a used range of ${ws.rowCount} rows x ${ws.columnCount} cols`,
+    "read a bounded range with xlsx-range --range"
+  );
+}
+function colLettersToIndex(letters) {
+  let n = 0;
+  for (const ch of letters.toUpperCase()) n = n * 26 + (ch.charCodeAt(0) - 64);
+  return n;
+}
+function indexToColLetters(idx) {
+  let n = idx;
+  let s = "";
+  while (n > 0) {
+    const rem = (n - 1) % 26;
+    s = String.fromCharCode(65 + rem) + s;
+    n = Math.floor((n - 1) / 26);
+  }
+  return s;
+}
+function decodeCellRef(ref) {
+  const m = /^([A-Za-z]+)(\d+)$/.exec(ref.trim());
+  if (!m) throw new Error(`invalid cell reference: ${ref}`);
+  return { c: colLettersToIndex(m[1]), r: parseInt(m[2], 10) };
+}
+function decodeRange(ref) {
+  const parts = ref.split(":");
+  const startRef = parts[0] !== void 0 && parts[0] !== "" ? parts[0] : ref;
+  const endRef = parts[1] !== void 0 && parts[1] !== "" ? parts[1] : startRef;
+  const start = decodeCellRef(startRef);
+  const end = decodeCellRef(endRef);
+  return {
+    s: { r: Math.min(start.r, end.r), c: Math.min(start.c, end.c) },
+    e: { r: Math.max(start.r, end.r), c: Math.max(start.c, end.c) }
+  };
+}
+function encodeCell(cell) {
+  return `${indexToColLetters(cell.c)}${cell.r}`;
+}
+function formatDateCell(d) {
+  const isDateOnly = d.getUTCHours() === 0 && d.getUTCMinutes() === 0 && d.getUTCSeconds() === 0 && d.getUTCMilliseconds() === 0;
+  return isDateOnly ? d.toISOString().slice(0, 10) : d.toISOString();
+}
+function cellText(cell) {
+  if (cell.value === null || cell.value === void 0) return "";
+  if (cell.value instanceof Date) return formatDateCell(cell.value);
+  const v = cell.value;
+  if (typeof v === "object" && v !== null) {
+    const obj = v;
+    if (Array.isArray(obj.richText)) return obj.richText.map((t) => t.text).join("");
+    if (typeof obj.error === "string") return obj.error;
+    if (obj.result !== void 0) {
+      if (obj.result instanceof Date) return formatDateCell(obj.result);
+      if (typeof obj.result === "object" && obj.result !== null && typeof obj.result.error === "string") {
+        return obj.result.error;
+      }
+      return String(obj.result);
+    }
+    if (obj.text !== void 0) return String(obj.text);
+  }
+  return cell.text !== "" ? cell.text : String(cell.value);
+}
+function cellFormula(cell) {
+  const v = cell.value;
+  if (typeof v === "object" && v !== null) {
+    const obj = v;
+    if (typeof obj.formula === "string") return obj.formula;
+  }
+  return void 0;
+}
+function usedRange(ws) {
+  assertScannableExtent(ws);
+  let maxCol = 0;
+  const rowCount = ws.rowCount || 0;
+  for (let r = 1; r <= rowCount; r++) {
+    const row = ws.getRow(r);
+    row.eachCell({ includeEmpty: false }, (_cell, colNumber) => {
+      if (colNumber > maxCol) maxCol = colNumber;
+    });
+  }
+  const rows = rowCount;
+  const cols = maxCol;
+  if (rows === 0 || cols === 0) {
+    return { ref: "(empty)", rows: 0, cols: 0 };
+  }
+  return { ref: `A1:${indexToColLetters(cols)}${rows}`, rows, cols };
+}
+async function listSheets(filePath, deadline = ooxmlWorkDeadline()) {
+  const wb = await loadWorkbook(filePath, deadline);
+  return wb.worksheets.map((ws) => {
+    assertOoxmlWithinDeadline(deadline, "Narrow the read to specific sheets with xlsx-head, or use a smaller workbook.");
+    const { ref, rows, cols } = usedRange(ws);
+    return { name: ws.name, ref, rows, cols };
+  });
+}
+function headSheetFromWorksheet(ws, rows, columns) {
+  assertScannableExtent(ws);
+  const rowCount = ws.rowCount || 0;
+  const sheetCols = ws.columnCount || 0;
+  const scanRows = Math.min(rowCount, rows + 1);
+  const aoa = [];
+  for (let r = 1; r <= scanRows; r++) {
+    const rowVals = [];
+    for (let c = 1; c <= sheetCols; c++) {
+      rowVals.push(cellText(ws.getCell(encodeCell({ r, c }))));
+    }
+    aoa.push(rowVals);
+  }
+  let header = Array.from({ length: sheetCols }, (_, i) => String(aoa[0]?.[i] ?? ""));
+  let dataRows = aoa.slice(1, 1 + rows).map(
+    (r) => Array.from({ length: sheetCols }, (_, i) => String(r[i] ?? ""))
+  );
+  if (columns !== void 0 && columns.length > 0) {
+    const normCols = columns.map((c) => c.trim()).filter(Boolean);
+    const selectedIndices = [];
+    for (const req of normCols) {
+      let idx = header.findIndex((h) => h === req);
+      if (idx === -1) {
+        idx = header.findIndex((h) => h.toLowerCase() === req.toLowerCase());
+      }
+      if (idx === -1 && /^[A-Za-z]+$/.test(req)) {
+        const colNum = colLettersToIndex(req);
+        if (colNum >= 1 && colNum <= sheetCols) {
+          idx = colNum - 1;
+        }
+      }
+      if (idx !== -1 && !selectedIndices.includes(idx)) {
+        selectedIndices.push(idx);
+      } else if (idx === -1) {
+        throw new Error(`unknown column: ${req} (available: ${header.filter(Boolean).join(", ")})`);
+      }
+    }
+    header = selectedIndices.map((i) => header[i] ?? "");
+    dataRows = dataRows.map((r) => selectedIndices.map((i) => r[i] ?? ""));
+  }
+  const lines = [header.map(quoteCsvCell).join(",")];
+  for (const r of dataRows) lines.push(r.map(quoteCsvCell).join(","));
+  if (rowCount - 1 > dataRows.length) {
+    lines.push(`...(${rowCount - 1 - dataRows.length} more rows elided; use --rows to see more, or xlsx-query for filtering)`);
+  }
+  return lines.join("\n");
+}
+async function headSheet(filePath, sheetName, rows = 20, columns) {
+  const wb = await loadWorkbook(filePath);
+  const ws = requireSheet(wb, sheetName);
+  return headSheetFromWorksheet(ws, rows, columns);
+}
+async function allSheetsHeadText(filePath, rows, deadline = ooxmlWorkDeadline()) {
+  const wb = await loadWorkbook(filePath, deadline);
+  const sheetTexts = [];
+  for (const ws of wb.worksheets) {
+    assertOoxmlWithinDeadline(deadline, "Narrow the read to specific sheets with xlsx-head, or use a smaller workbook.");
+    sheetTexts.push(`# Sheet: ${ws.name}
+${headSheetFromWorksheet(ws, rows)}`);
+  }
+  return sheetTexts.join("\n\n");
+}
+async function rangeSheet(filePath, sheetName, rangeSpec, showFormulas) {
+  const wb = await loadWorkbook(filePath);
+  const ws = requireSheet(wb, sheetName);
+  const range = decodeRange(rangeSpec);
+  const rangeRows = range.e.r - range.s.r + 1;
+  const rangeCols = range.e.c - range.s.c + 1;
+  assertCellCount(rangeRows * rangeCols, `range ${rangeSpec} covers ${rangeRows} rows x ${rangeCols} cols`, "ask for a smaller --range");
+  const rowsOut = [];
+  for (let r = range.s.r; r <= range.e.r; r++) {
+    const rowOut = [];
+    for (let c = range.s.c; c <= range.e.c; c++) {
+      const addr = encodeCell({ r, c });
+      const cell = ws.getCell(addr);
+      if (showFormulas && cellFormula(cell) !== void 0) {
+        rowOut.push(`=${cellFormula(cell)}`);
+      } else {
+        rowOut.push(cellText(cell));
+      }
+    }
+    rowsOut.push(rowOut);
+  }
+  const colLabels = rowsOut[0]?.map((_, i) => indexToColLetters(range.s.c + i)) ?? [];
+  return { header: colLabels, rows: rowsOut };
+}
+function formatXlsxRange(result) {
+  const lines = [result.header.map(quoteCsvCell).join(",")];
+  for (const r of result.rows) lines.push(r.map(quoteCsvCell).join(","));
+  return lines.join("\n");
+}
+async function sheetToCsv(ws) {
+  const rowCount = ws.rowCount || 0;
+  const { cols: sheetCols } = usedRange(ws);
+  const lines = [];
+  for (let r = 1; r <= rowCount; r++) {
+    const vals = [];
+    for (let c = 1; c <= sheetCols; c++) {
+      vals.push(cellText(ws.getCell(encodeCell({ r, c }))));
+    }
+    lines.push(vals.map(quoteCsvCell).join(","));
+  }
+  return lines.join("\n");
+}
+async function querySheet(filePath, sheetName, opts) {
+  const wb = await loadWorkbook(filePath);
+  const ws = requireSheet(wb, sheetName);
+  const csvText = await sheetToCsv(ws);
+  return queryCsv(csvText, opts);
+}
+async function xlsxColumns(filePath, sheetName, sampleLimit = 100) {
+  const wb = await loadWorkbook(filePath);
+  const ws = requireSheet(wb, sheetName);
+  assertScannableExtent(ws);
+  const rowCount = ws.rowCount || 0;
+  const { cols: sheetCols } = usedRange(ws);
+  if (rowCount === 0 || sheetCols === 0) {
+    return { sheetName: ws.name, totalSheetRows: 0, sampleRows: 0, columns: [] };
+  }
+  const sampleRows = Math.min(Math.max(1, sampleLimit), Math.max(1, rowCount - 1));
+  const headers = [];
+  for (let c = 1; c <= sheetCols; c++) {
+    const val = cellText(ws.getCell(encodeCell({ r: 1, c })));
+    headers.push(val || `(col ${indexToColLetters(c)})`);
+  }
+  const colSummaries = headers.map((name, i) => ({
+    letter: indexToColLetters(i + 1),
+    name,
+    index: i + 1,
+    nonEmptyRows: 0,
+    sampleRows,
+    sampleValues: []
+  }));
+  for (let r = 2; r <= 1 + sampleRows; r++) {
+    for (let c = 1; c <= sheetCols; c++) {
+      const txt = cellText(ws.getCell(encodeCell({ r, c })));
+      if (txt !== "") {
+        const summary = colSummaries[c - 1];
+        summary.nonEmptyRows++;
+        if (summary.sampleValues.length < 3 && !summary.sampleValues.includes(txt)) {
+          summary.sampleValues.push(txt);
+        }
+      }
+    }
+  }
+  return {
+    sheetName: ws.name,
+    totalSheetRows: Math.max(0, rowCount - 1),
+    sampleRows,
+    columns: colSummaries
+  };
+}
+function formatXlsxColumns(result) {
+  if (result.columns.length === 0) return `Sheet "${displaySafeText(result.sheetName)}" is empty`;
+  const lines = [
+    `Sheet: ${displaySafeText(result.sheetName)} (${result.totalSheetRows} data rows, ${result.columns.length} columns; sampled first ${result.sampleRows} rows)`
+  ];
+  for (const c of result.columns) {
+    const pct = result.sampleRows > 0 ? Math.round(c.nonEmptyRows / c.sampleRows * 100) : 0;
+    const samples = c.sampleValues.length > 0 ? ` (e.g. ${c.sampleValues.map((v) => JSON.stringify(v.length > 30 ? v.slice(0, 27) + "..." : v)).join(", ")})` : " (all empty)";
+    lines.push(`  ${c.letter.padEnd(4)} ${displaySafeText(c.name).padEnd(25)} ${c.nonEmptyRows}/${c.sampleRows} (${pct}%)${samples}`);
+  }
+  return lines.join("\n");
+}
+
+export {
+  XlsxScanTooLargeError,
+  listSheets,
+  headSheet,
+  allSheetsHeadText,
+  rangeSheet,
+  formatXlsxRange,
+  querySheet,
+  xlsxColumns,
+  formatXlsxColumns
+};