Smaller consistency items left from the audit

[productdevbook]

Split out of #439. Everything real but too small for its own issue. Each is independent; none is urgent.

API shape

Cell utilities are split between the root and hucre/xlsx. hucre/xlsx exports parseCellRef, colToLetter, cellRef, rangeRef. The root additionally exports letterToCol, parseRange, isInRange, r1c1ToA1, a1ToR1C1. Someone on hucre/xlsx who needs letterToCol has to pull a second entry point for a pure string helper. The JSON surface had exactly this disagreement and it was fixed before v1 (src/index.ts:84-89 says so); this one was missed.

Ranges are A1 strings in half the API and coordinate objects in the other half.

A1 string	{ startRow, startCol, endRow, endCol }
DataValidation.range, ConditionalRule.range, AutoFilter.range, TableDefinition.range, NamedRange.range, PageSetup.printArea, ReadOptions.range	MergeRange, copyRange(sheet, source, target), SheetImage.anchor, sparkline fields

cell-utils exports parseRange and rangeRef to convert, and both directions show up constantly in user code. There is no rule to hold in your head about which form a field wants. Accepting string | MergeRange at the boundary and normalising once would cost a few lines.

Testing infrastructure

No coverage threshold. 98.8% today, enforced by nothing — vitest.config.ts sets only exclude.

No bundle-size budget. The README compares against a competitor's ~300 KB without publishing hucre's own. Measured with rolldown: writeXlsx from the root entry is 129 KB minified / 36 KB gzipped, readXlsx 128/34, parseCsv 4.7/2.1. Worth pinning so a regression is visible.

test/parity-statement.test.ts parses src/_types.ts with a regex. Deriving beats transcribing and the intent is right, but new RegExp('export interface ' + iface + ' \\{([\\s\\S]*?)\\n\\}') breaks on any nested brace at column 0. Three other tests now use the same helper, so it is worth making sturdier — a .d.ts walk or a small TS-API script.

Correctness, minor

parseW3CDTF is new Date(value) (doc-props-reader.ts:22). hucre's own writer always emits a Z, and W3CDTF requires a zone designator on a date-time, so compliant files are fine. A non-compliant 2024-01-15T10:30:00 from another tool is parsed as local time — the #415 shape, in a third place. One Z-append guard, the way ods/reader.ts:455 already does it.

Numbers are serialised with String(value) in both the XLSX and CSV writers, so 1e21 becomes 1e+21 and 0.1 + 0.2 becomes 0.30000000000000004 (17 significant digits). Excel writes 1E+21 and caps at 15. Both are parseable; worth deciding rather than inheriting whatever V8 does.

toMarkdown escapes | but not * or _. A cell reading *not emphasis* renders as emphasis. Defensible for output the docs call terminal-only; worth a line of doc either way.

formatValue groups in threes. Since #456 the separator comes from Intl for any locale, but the grouping pattern is still fixed — so hi-IN gets 1,234,567.50 where the locale wants 12,34,567.50. Noted in the code; fixing it means reading the grouping widths from Intl too.

injectWorksheetDrawing (roundtrip.ts:1258) splices <drawing r:id="…"/> into generated XML by substring search over thirteen candidate insertion points. Safe today — the input is hucre's own output and cell text is escaped — but the worksheet writer should take a drawingRId parameter instead.

fullCalcOnLoad="1" is written unconditionally (workbook-writer.ts:147), so every workbook hucre produces forces a full recalculation and the cached formula results it just wrote are discarded. Correct given there is no formula engine; worth a line in the docs, since it makes formulaResult effectively write-only.

Diagnostics

onWarning (#462) is wired at two sites — the two measured as silent. Others could follow the same shape: an out-of-range dxfId on a conditional rule, a paper size code that is not usable, a hyperlink r:id that resolves to nothing. Each wants a test with it rather than a speculative call.

Repo

No issue or PR templates, no CODEOWNERS. Decisions about how contributions should be shaped, so left for the maintainer.

[productdevbook]

Worked through this. Every code item is done; what remains is the one thing the issue itself left for you.

Done

item	PR
Cell utilities split between root and hucre/xlsx	#482
Ranges: A1 strings vs coordinate objects	#482
No coverage threshold	#483
No bundle-size budget	#483
parity-statement.test.ts parses _types.ts with a regex	#483
parseW3CDTF is new Date(value)	#481
Numbers serialised with String(value)	#485
toMarkdown escapes `	but not*or_`
formatValue groups in threes	#481
injectWorksheetDrawing splices by substring search	#484
fullCalcOnLoad="1" written unconditionally	#481 (documented)
onWarning wired at only two sites	#486

Four things worth reporting back

The bundle-size numbers had already drifted. The README published 2.3 / 32 / 64 / 114 KB gzipped; measured, they are 3.7 / 34 / 68 / 127. Corrected, and the four scenarios now pinned in scripts/size-budget.json are exactly the four it quotes, so they cannot drift apart again.

The regex was fragile, not wrong. Measured against every interface those tests actually use, the new reader returns identical field lists — Sheet 33/33, WriteSheet 31/31, PageSetup 27/27, and so on. The value is that [\s\S]*?\n\} truncating produces a shorter list, which makes a derive-from-source test pass rather than fail, and that the new one follows extends — the exact mistake the audit made against JsonReadOptions.

The number question turned up a real defect somewhere else. String(value) in the XLSX writer is right and is staying: it is the only spelling that round-trips a double exactly, and rounding to 15 digits would turn 0.1 + 0.2 into 0.3. But the CSV writer does not do this. formatNumber expanded small magnitudes with toFixed(20), which caps at twenty decimal places — so Number.EPSILON kept five significant digits of seventeen and Number.MIN_VALUE came out as "0.0". The smallest values a caller could put in a cell read back as zero. Fixed in #485.

unresolved-dxf was in the ReadWarning union and emitted from nowhere — a code no caller could ever have received. Wired in #486, along with unresolved-hyperlink and unusable-paper-size.

Left for you, deliberately

Issue and PR templates, and CODEOWNERS. The issue says these are decisions about how contributions should be shaped and left them for the maintainer, so I have not guessed at them.

One judgement call worth flagging in case you disagree: toMarkdown now escapes _ as well as *, which makes a cell of sub_total render as sub\_total in the source. GFM does not treat intraword underscores as emphasis, so this is stricter than strictly necessary — telling _total_ from sub_total needs the flanking rules. escapeInline: false turns the whole thing off. Happy to narrow it to * alone if you would rather.