Document conversion internals and limits

docs/architecture.md

@@ -12,17 +12,22 @@
 - table -> structured
 - table -> table
 
-## Format Adapters
+## Source Layout
 
-各形式の処理は `cmd/dataxl/main.go` の以下の関数に集約しています。
+実装は `cmd/dataxl` package内で責務別に分割しています。
 
-- `parseStructured`
-- `encodeStructured`
-- `parseTable`
-- `encodeTable`
+- `main.go`: CLI option、stdin/stdout、ファイル入出力
+- `conversion.go`: 変換経路の選択、形式名の正規化・推定
+- `structured.go`: JSON/YAML/TOML adapter
+- `table.go`: CSV/TSV/XLSX adapter、table model、flatten
+- `path.go`: セル値の型推定、列パスのparse、unflatten
 
-現在はCLIが小さいため単一ファイルに置いています。形式やオプションが増えたら、
-`internal/format` や `internal/table` へ分割する余地があります。
+`convert` はファイル入出力から独立しているため、CLIを経由せず変換matrixをテストできます。
+形式固有処理は `parseStructured` / `encodeStructured` または
+`parseTable` / `encodeTable` に閉じ込めます。
+
+現状は単一commandだけが利用するため同じpackageに置いています。別commandやlibrary APIから
+再利用する段階になったら、安定させたい境界を見極めたうえで `internal` packageへ移します。
 
 ## Table Model
 
@@ -79,6 +84,21 @@ items[0].sku
 - 小数または指数表記: float64
 - その他: string
 
+ゼロ埋め整数は、IDやコードを壊さないためstringとして保持します。複数列が同じパスで
+異なる中間型を要求する場合は、先に構築された値を後続列で上書きしません。
+
+### Path grammar
+
+現在の列パスは次の要素を扱います。
+
+```text
+path  = key, { ".", key | "[", index, "]" };
+index = digit, { digit };
+```
+
+実例は `user.name`、`items[0].sku`、`orders[0].items[1].qty` です。
+区切り文字を含むmap keyのescapeは未対応です。
+
 ## TOML Output
 
 TOMLはトップレベル配列を直接表せないため、表からTOMLへ出力する場合など、
@@ -91,3 +111,9 @@ TOMLはトップレベル配列を直接表せないため、表からTOMLへ出
 - `github.com/BurntSushi/toml`: TOML読み書き
 
 Go 1.24以上を前提にしています。
+
+## Error handling
+
+- 未対応形式、decode失敗、workbook/sheet操作失敗は呼び出し元へerrorを返します。
+- path復元中の型競合は既存値を保護するため、その列の適用を中止します。
+- XLSXのstyle・pane設定も通常の変換errorとして扱い、不完全なworkbookを成功扱いしません。

docs/development.md

@@ -51,6 +51,11 @@ The current tests cover:
 - YAML -> TSV flattening
 - TSV -> JSON path restoration
 - JSON -> XLSX -> JSON round trip
+- structured -> structured conversion without CLI/file I/O
+- extension normalization and format inference
+- ragged table row padding
+- conservative cell type inference, including zero-padded identifiers
+- conflicting unflatten paths
 
 When adding a new format or path rule, add tests around both directions where
 possible.
@@ -96,3 +101,6 @@ go install git.rumginger.org/agent/dataxl/cmd/dataxl@v0.1.0
 - Preserve headers as the contract between spreadsheet data and structured data.
 - Prefer explicit errors over silent best-effort conversion when a format is unsupported.
 - Keep dependencies small unless a format needs a mature parser/writer.
+- Keep CLI/file I/O in `main.go`; conversion behavior should remain testable through `convert`.
+- Keep format-specific behavior in its structured or table adapter.
+- Document round-trip limitations when a representation cannot preserve a value exactly.