agent-todo.md

Agent TODOs (Excelize parity)

This file tracks incremental parity work vs the vendored Excelize snapshot in excelize/.

References:

• Human-written gap summary: docs/excelize-parity.md
• Generated (names-only) report: docs/excelize-parity-generated.md (regen via python3 scripts/excelize_parity_report.py --out docs/excelize-parity-generated.md)

Workflow (per item)

1. Add/extend MoonBit API (+ docs if needed)
2. Add focused tests (prefer snapshots via inspect)
3. Run moon info && moon fmt
4. Run moon test (use moon test --update if snapshots legitimately change)
5. Commit with a detailed message and push to origin/main

Feature worklist

Codex deep-audit gaps (2026-07-03)

Verified gaps vs .repos/excelize found by a codex CLI cross-audit; the well-scoped ones were fixed on feat/excelize-parity-gaps. Remaining:

• Typed cell values: Workbook::set_cell_time / set_cell_duration + time_to_excel_date (feat/excelize-parity-round2)
• Stream writer typed rows: StreamWriter::new_time_cell / new_duration_cell (feat/excelize-parity-round2); nil/blank stream cells skip via StreamCell::new_blank() (feat/parity-round3)
• Default charset transcoding: built-in Windows-1252/Latin-1/ASCII and UTF-16 (BOM-aware) decoding, WHATWG/Go label folding (feat/charset-transcoding); multi-byte CJK still needs the hook
• GetPictures embedded cell images: WPS DISPIMG, modern rich-value Place-in-cell (_rvRel:LocalImageIdentifier), and IMAGE() web images via xl/richData/* + metadata.xml (feat/embedded-cell-pictures)
• SECURITY: encryption salts were fully deterministic (ChaCha8 fixed default seed); now time-seeded per process + set_random_source hook for crypto-grade entropy (feat/excelize-parity-round2). Built-in fallback is still not a CSPRNG.
• RC4-style standard encryption verifier layout accepted (non-AES AlgID -> 20-byte verifier hash, decryption stays SHA-1 + AES-ECB exactly like Go) (feat/rc4-standard-layout)
• Chart Fill semantics: ChartFill override (typ/pattern/color/ shading/transparency) on all fill-bearing chart elements, faithful to drawShapeFill (feat/parity-round3)
• LEFTB/RIGHTB/MIDB/REPLACEB unified on Excel DBCS byte semantics via a shared dbcs_byte_range helper, no more mojibake (feat/parity-round3)
• culture_info now resolves language builtin numFmt IDs 27-36/50-62/ 67-81 for en-US/ja-JP/ko-KR/zh-CN/zh-TW (feat/culture-num-fmt); era codes with [$-404]/[$-411] locale tokens still pass through raw
• Hyperlinks with both r:id and location now keep the fragment (Hyperlink.location field), match both filters, and survive write roundtrips (fix/hyperlink-location-fidelity)

Fixed in this pass: get_hyperlink_cells, get_sheet_protection, ChartAxis drop_lines/high_low_lines, public ChartLineType with Solid scheme-color emission, public PivotTableField options + dataField numFmtId/subtotal normalization/255-unit name truncation, NaN/Inf cell values written as strings.

Maintenance / Cleanup

• Remove moon check warnings + deprecated slice usage (commit 4a75627)
• Coverage: raise zip/ package coverage to ≥95% (now 705/738 ≈ 95.53%)
• Coverage: raise xlsx/ package coverage materially (currently 25277/31302 ≈ 80.75%; 95–98% is a large effort)
• Coverage: decide how to treat cmd/main fn main (currently un-coverable by tests)
• Coverage: audit unreachable branches in zip/ + crypto/ (some checks appear dead without whitebox access)
• Package-by-package readability/perf pass (start with zip/, then ooxml/, then crypto/)
• Target support: confirm --target wasm compatibility (currently moon check --target all fails due to missing @async/fs/@process APIs in dependencies)

Styles / formatting

• Expand xlsx.Style beyond number formats (Font/Fill/Border/Alignment/Protection parity with Excelize Style in excelize/xmlStyles.go)
  • Font (cell styles + conditional styles)
  • Fill (pattern/solid + conditional fill)
  • Border (basic left/right/top/bottom + conditional border)
  • Alignment (basic + conditional alignment)
  • Protection (locked/hidden + conditional protection)

Charts

• Add high-level chart builder types (partial parity with Excelize Chart* types in excelize/xmlChart.go / excelize/chart.go)

Drawings: pictures & shapes

• Add picture name / alt_text options (partial parity with Excelize GraphicOptions in excelize/xmlDrawing.go)
• Add picture lock-aspect option (partial GraphicOptions parity)
• Follow-up: picture positioning (oneCell/twoCell/absolute) (more GraphicOptions parity)
• Follow-up: picture autofit options (AutoFit / AutoFitIgnoreAspect) (more GraphicOptions parity)
• Follow-up: picture PrintObject / Locked flags (writes xdr:clientData attrs) (more GraphicOptions parity)
• Expand xlsx.Shape to support size/fill/line/rich text paragraphs (Excelize Shape/ShapeLine in excelize/xmlDrawing.go)
  • Size (width/height + scale) and basic rich-text paragraphs
  • Solid fill (color + transparency) and line (color + width)
  • Name/alt text + xdr:clientData flags
  • Positioning (oneCell/twoCell/absolute)

Sparklines

• Add SparklineOptions basic parity (style presets, markers/high/low/first/last/negative, axis, reverse, seriesColor) and round-trip via SparklineGroupOptions
• Follow-ups: date axis, hidden, weight, manual min/max, empty cell modes (Excelize SparklineOptions in excelize/xmlWorksheet.go)

Pivot tables & slicers

• Add PivotTableOptions builder (Excelize PivotTableOptions in excelize/pivotTable.go)
• Add SlicerOptions builder (Excelize SlicerOptions in excelize/slicer.go)

Cells: formula/hyperlink opts

• Add FormulaOpts parity where meaningful (Excelize FormulaOpts in excelize/cell.go)
• Add HyperlinkOpts-like API for richer hyperlinks (Excelize HyperlinkOpts in excelize/cell.go)

Conditional formatting

• Add higher-level ConditionalFormatOptions parity (Excelize ConditionalFormatOptions in excelize/xmlWorksheet.go)
• Read x14 conditional formatting from worksheet extLst (iconSet + dataBar advanced props) and expose via get_conditional_formats
• Write x14 data bar advanced props (direction/solid/border) with deterministic <x14:id> linkage
• Match Excelize SetConditionalFormat range normalization for reversed/row/col refs (A2:A1,B:B,2:2 -> A2:A1 B1:B1048576 A2:XFD2)

Tables

• Expand xlsx.Table options (row/col stripes, first/last column emphasis, etc.) (Excelize Table in excelize/table.go / excelize/xmlTable.go)

Follow-ups (known remaining differences)

• Expand RichTextFont toward Excelize Font parity (strike/shadow/vertAlign/etc.)
• Audit/expand style long-tail options and add round-trip tests
  • Style Font long-tail tags (strike/outline/shadow/condense/extend/charset/family/scheme/vertAlign)
  • Style Border diagonalUp/diagonalDown (+ optional vertical/horizontal)
  • Style Fill transparency (ARGB alpha) + round-trip tests
  • Style theme/indexed colors + tint (Font/Fill)
• Audit/expand chart option coverage (typed model vs raw OOXML fallbacks)
  • Support more basic chart types (stacked col/bar, area, pie, doughnut, radar, scatter, bubble)
  • Emit axis titles/gridlines/numFmt/tickLblPos + dispBlanksAs + bar gapWidth/overlap
  • Add stock chart support (high-low-close, open-high-low-close)
  • Add 3D chart support (pie3D/line3D/area3D/col3D/bar3D/surface, etc.)
  • Add deeper series styling options (fill/line/marker/data labels/data points)

Next parity audit targets (deeper / long-tail)

Charts (long-tail)

• Doughnut chart holeSize option
• Bubble chart bubbleScale option
• Plot-area data label flags (showCatName/showSerName/showPercent/showLeaderLines/showBubbleSize)
• Axis font + alignment parity (ChartAxis)
• Title rich text parity (Chart title/axis title runs)
• Series fill/marker fill+border parity (ChartSeries/ChartMarker/ChartLine)

Charts (struct parity next)

• Omit legend element when legend.position == "none"
• Legend font parity (ChartLegend.font -> <c:txPr>)
• Plot-area fill parity (ChartPlotArea.Fill solid fill at least)
• Plot-area data table parity (ShowDataTable / ShowDataTableKeys)
• Data label model parity (ChartDataLabel alignment/font/fill)
• Chart border/fill parity (chart-level <c:spPr>/<c:txPr>)
• OfPie split position (ChartPlotArea.SecondPlotValues -> <c:splitPos>)

Rich text (long-tail)

• Rich text run color theme/indexed/tint (RichTextFont.color_theme/color_indexed/color_tint)

Shapes (long-tail)

• Shape macro attribute (Shape.macro_name -> xdr:cNvPr macro="...")

Parity audit (field-level, follow-ups)

These are discovered via python3 scripts/excelize_struct_field_parity.py and manual review.

Pivot tables

• Pivot table definition option attrs (grand totals/drill/autofmt/etc.) + rowItems/colItems parity (partial Excelize PivotTableOptions)
• Pivot field options parity (compact/outline/showAll/insertBlankRow/defaultSubtotal + proper <items>)

Sparklines

• Sparkline per-color parity on SparklineOptions (negative/markers/first/last/high/low colors) or unify via SparklineGroupOptions

Styles

• Number format long-tail parity (Excelize Style.DecimalPlaces, Style.NegRed, Style.CustomNumFmt vs MoonBit NumberFormat)

Deep parity audit (behavior-level)

These are behavior/interop differences not well-captured by API-name parity or struct-field parity scripts.

Pictures / images

• Parse image dimensions for more formats (bmp/tiff/ico) for correct EMU sizing
• Parse SVG dimensions (width/height/viewBox) for correct EMU sizing
• Parse metafile dimensions (emf/wmf) for correct EMU sizing
• Compressed metafiles (emz/wmz): gzip-decompress + sizing parity

Formula evaluation

• Formula function-name parity vs Excelize (python3 scripts/excelize_formula_parity.py)

Form controls (VML)

• Parse + round-trip basic form controls (macro/cellLink/checked) via xl/drawings/vmlDrawing*.vml
• FormControl sizing parity (width/height + anchor calculation)
• FormControl option parity (current/min/max/inc/page/horizontally, etc.)
• FormControl rich text paragraphs parity (Paragraph -> VML <font> runs)
• FormControl VML presets parity (fill/stroke + common <x:ClientData> defaults)

Next parity audit (long-tail)

These are larger-scope items where Excelize exposes many knobs and mbtexcel may still be a subset. Tackle one item at a time and add focused tests.

Drawings / anchors

• Two-cell/absolute anchors compute correct <xdr:to> cell (not same-cell with huge offsets) for charts/images/shapes (Excelize uses twoCellAnchor for charts by default)

Charts

• Chart options long-tail parity audit (Excelize Chart/Chart* options vs mbtexcel chart model)
• Combo charts (basic CatAx/ValAx + optional secondary Y axis) (Excelize AddChart(..., combo ...*Chart) / AddChartSheet(..., combo ...*Chart))
• Combo charts (axis-model long-tail): scatter/bubble mixes (basic)
• Combo charts (axis-model long-tail): dateAx/stock mixes and other edge cases

Styles

• Style model long-tail parity audit (rare font/fill/border/alignment/protection tags and edge cases)
  • Gradient cell fills (Fill::gradient, Fill.typ == "gradient", Fill.shading 0..16)
  • Gradient conditional fills (dxfs <dxf><fill><gradientFill .../></fill></dxf>)
  • Round-trip theme/indexed colors (xl/theme/theme1.xml, xl/styles.xml <indexedColors>)
  • Round-trip <colors><mruColors> (read + write preserve)
  • Preserve full theme XML on write (round-trip xl/theme/theme1.xml beyond just extracted colors)
  • Round-trip <styleSheet><extLst> (read + write preserve)
  • Round-trip <tableStyles> default styles (defaultTableStyle/defaultPivotStyle attrs)