Harden CI and release artifacts

README.md

@@ -18,7 +18,7 @@ TSVへ変換したり、Excelからコピーした表を再び構造化データ
 
 ## インストール
 
-Go 1.24以上が必要です。
+Go 1.25以上が必要です。
 
 ```sh
 go install git.rumginger.org/agent/dataxl/cmd/dataxl@latest
@@ -114,9 +114,13 @@ map/arrayを復元します。
 列パスは `.` でmapのキー、`[n]` で0始まりの配列indexを表します。たとえば
 `orders[0].items[1].sku` は、最初の注文に含まれる2番目の商品の `sku` です。
 
-同じ行に `user` と `user.name` のような競合する列がある場合、先に読み込まれた
-値を保持し、後続列で型を上書きしません。曖昧な復元を避けるため、親要素と子要素を
-同時に列として置かないでください。
+`.`、`[`、`]` を含むmapキーや空のmapキーはJSON文字列を使ったbracket記法で
+表します。たとえば `{"build.target": {"x[y]": 1}}` は
+`["build.target"]["x[y]"]` という列名になります。
+
+同じ行に `user` と `user.name` のような競合する列がある場合や、同名ヘッダーが
+複数ある場合はエラーにします。どちらかの値だけを採用して正常終了することは
+ありません。
 
 ## セル値の型推定
 
@@ -129,7 +133,22 @@ CSV、TSV、XLSXから構造化形式へ戻す際は、セル文字列を次の
 - それ以外は文字列
 
 郵便番号や商品コードを想定し、`00123` や `-01` のようなゼロ埋め値は文字列のまま
-保持します。日付、時刻、`null` は自動推定しません。
+保持します。セルの前後空白も文字列の一部として保持し、` 42 ` のような値を数値に
+変換しません。日付、時刻、`null` は自動推定しません。
+
+## データ欠落を防ぐ検証
+
+- JSON入力はUTF-8として検証し、1つの値と後続空白だけを許可します。2つ目の値、
+  不正な後続データ、object内の重複キーは、値を置換・無視せずエラーにします。
+- YAML streamに複数文書がある場合は、順序を保った配列としてすべて変換します。
+- UTF-8 BOM付きCSV/TSVでは先頭のBOMをencoding markerとして除去します。
+- CSV/TSVはUTF-8として検証し、ヘッダーより列数が多い行をエラーにします。
+- 空ヘッダー列に値がある場合、重複ヘッダー、復元時に型が競合する列パスは
+  エラーにします。
+- scalar fieldを1つも持たないrecordは表で表現できないため、空行へ変換して
+  record数を失う代わりにエラーにします。空のrecord listは空の表へ変換できます。
+- `rows`、`records`、`items` を行配列として展開するのは、それがオブジェクト唯一の
+  キーである場合だけです。同階層のmetadataを破棄しません。
 
 ## CLIオプション
 
@@ -139,6 +158,7 @@ CSV、TSV、XLSXから構造化形式へ戻す際は、セル文字列を次の
 - `-to`: 出力形式。`json`, `yaml`, `toml`, `csv`, `tsv`, `xlsx`。
 - `-sheet`: XLSXの読み書きに使うシート名。既定値は `Sheet1`。
 - `-pretty`: JSONなどの構造化出力を整形するか。既定値は `true`。
+- `-version`: バージョンを表示して終了します。
 
 ## 現在の制約
 
@@ -146,7 +166,9 @@ CSV、TSV、XLSXから構造化形式へ戻す際は、セル文字列を次の
 - XLSXは指定した1シートのみ読み書きします。
 - セル値の型推定は、空文字、真偽値、整数、小数、文字列の範囲です。
 - 空のmap/arrayは表側で `{}` / `[]` と表示されますが、逆変換時は文字列になります。
-- mapキーに `.`、`[`、`]` を含む場合のescape記法は未対応です。
+- structured形式の `null` と表形式の空文字は同じ空セルになります。
+- top-level scalarやscalar配列は表側で `value` 列を使うため、逆変換時は
+  `value` キーを持つレコードになります。
 - 複雑なExcel書式や数式の保持は目的外です。
 
 ## 開発者向け情報