kenaz 0.3.21 → 0.3.23

package/core/dev/design/matrix_format_SYNTAX_BNF.md

@@ -1,754 +0,0 @@
-# .matrix 格式 EBNF 語法定義
-
-> **版本**: 1.0.0
-> **日期**: 2026-02-08
-> **標準**: Extended Backus-Naur Form (EBNF)
-> **狀態**: 正式規範
-
----
-
-## 📋 概述
-
-本文檔定義 .matrix 格式的正式語法規則,使用 EBNF 標準表示。此語法定義將作為 Parser 實作的標準參考。
-
----
-
-## 🔤 EBNF 記號說明
-
-| 記號 | 意義 | 範例 |
-|------|------|------|
-| `=` | 定義 | `rule = expression` |
-| `,` | 連接(依序出現) | `A, B` |
-| `\|` | 選擇(擇一) | `A \| B` |
-| `( )` | 分組 | `(A \| B), C` |
-| `[ ]` | 可選(0或1次) | `[A]` |
-| `{ }` | 重複(0或多次) | `{A}` |
-| `" "` | 終端符號(字面值) | `"@meta"` |
-| `' '` | 終端符號(字面值) | `'|'` |
-| `(* *)` | 註釋 | `(* comment *)` |
-| `-` | 排除 | `A - B` (A 但不包含 B) |
-
----
-
-## 🏗️ 完整語法定義
-
-### 頂層結構
-
-```ebnf
-(* .matrix 文件根結構 *)
-matrix_file =
-    [ comment_line ] ,
-    meta_section ,
-    index_section ,
-    data_section ;
-
-comment_line =
-    "#" , { any_character - newline } , newline ;
-
-newline =
-    "\n" | "\r\n" ;
-```
-
----
-
-## 📊 @meta 層語法
-
-### Meta Section 結構
-
-```ebnf
-(* @meta 層：文件元數據 *)
-meta_section =
-    "@meta" , ws , "|" , meta_fields , "|" , newline ;
-
-meta_fields =
-    meta_field , { "|" , meta_field } ;
-
-meta_field =
-    meta_key , "=" , meta_value ;
-
-meta_key =
-    "v"       (* version *)
-  | "c"       (* category *)
-  | "t"       (* timestamp *)
-  | "r"       (* range *)
-  | "proj"    (* project *)
-  | identifier ;
-
-meta_value =
-    version_string
-  | category_string
-  | timestamp_string
-  | identifier
-  | text_value ;
-```
-
-### Meta 值類型
-
-```ebnf
-(* 版本號格式 *)
-version_string =
-    digit , "." , digit , [ "." , digit ] ;
-
-(* 分類字符串 *)
-category_string =
-    letter , { letter | "-" | "_" } ;
-
-(* 時間戳格式 *)
-timestamp_string =
-    short_date , [ "-" , short_time ] ;
-
-short_date =
-    year_short , month_digit , day_digit ;
-    (* 範例: 260207 → 2026-02-07 *)
-
-year_short =
-    digit , digit ;  (* YY *)
-
-month_digit =
-    digit , digit ;  (* MM *)
-
-day_digit =
-    digit , digit ;  (* DD *)
-
-short_time =
-    hour_digit , minute_digit ;
-
-hour_digit =
-    digit , digit ;  (* HH *)
-
-minute_digit =
-    digit , digit ;  (* MM *)
-```
-
-**範例**:
-```
-@meta |v=1.0|c=project-status|t=260207-0530|proj=KenazAI|
-```
-
----
-
-## 📇 @index 層語法
-
-### Index Section 結構
-
-```ebnf
-(* @index 層：快速查詢索引 *)
-index_section =
-    "@index" , ws , "|" , index_fields , "|" , newline ;
-
-index_fields =
-    index_field , { "|" , index_field } ;
-
-index_field =
-    index_key , "=" , index_value ;
-
-index_key =
-    "ty"      (* type *)
-  | "tot"     (* total *)
-  | "c"       (* completed *)
-  | "p"       (* in_progress *)
-  | "b"       (* blocked *)
-  | "d"       (* date *)
-  | "e"       (* entries *)
-  | "cat"     (* category *)
-  | "act"     (* active *)
-  | "upd"     (* updated *)
-  | identifier ;
-
-index_value =
-    number_value
-  | status_code
-  | date_list
-  | category_list
-  | text_value ;
-```
-
-### Index 值類型
-
-```ebnf
-(* 數字值 *)
-number_value =
-    [ "-" ] , digit , { digit } , [ "." , digit , { digit } ] ;
-
-(* 日期列表 *)
-date_list =
-    short_date , { "," , short_date } ;
-
-(* 分類列表 *)
-category_list =
-    identifier , { "," , identifier } ;
-
-(* 狀態代碼 *)
-status_code =
-    "C" | "P" | "D" | "B" | "0" | "1" ;
-```
-
-**範例**:
-```
-@index |tot=123|c=100|p=15|b=8|act=1|upd=260207|
-@index |d=260207,260206,260205|e=25|cat=dev,bug,feat,doc|
-```
-
----
-
-## 💾 @data 層語法
-
-### Data Section 結構
-
-```ebnf
-(* @data 層：實際數據內容 *)
-data_section =
-    "@data" , newline ,
-    { data_line } ;
-
-data_line =
-    record_id , "|" , data_fields , "|" , newline ;
-
-record_id =
-    identifier ;
-
-data_fields =
-    data_field , { "|" , data_field } ;
-
-data_field =
-    field_key , "=" , field_value ;
-```
-
-### Data 鍵名
-
-```ebnf
-(* 欄位鍵名（縮寫） *)
-field_key =
-    (* 狀態與優先級 *)
-    "st"      (* status *)
-  | "p"       (* priority *)
-
-    (* 時間相關 *)
-  | "t"       (* time *)
-  | "ct"      (* created_at *)
-  | "ut"      (* updated_at *)
-  | "dur"     (* duration *)
-
-    (* 識別與關係 *)
-  | "i"       (* id *)
-  | "ty"      (* type *)
-  | "ag"      (* agent_type *)
-  | "dep"     (* dependencies *)
-  | "blk"     (* blocked_by *)
-
-    (* 內容 *)
-  | "d"       (* description *)
-  | "desc"    (* description (long) *)
-  | "note"    (* note *)
-  | "cat"     (* category *)
-
-    (* 數值 *)
-  | "c"       (* count *)
-  | "tot"     (* total *)
-  | "est"     (* estimated *)
-  | "act"     (* actual *)
-  | "succ"    (* success_rate *)
-
-    (* 擴展 *)
-  | identifier ;
-```
-
-### Data 值類型
-
-```ebnf
-(* 欄位值 *)
-field_value =
-    status_value
-  | priority_value
-  | duration_value
-  | timestamp_value
-  | list_value
-  | task_group
-  | text_value
-  | number_value
-  | boolean_value ;
-
-(* 狀態值 *)
-status_value =
-    "C"       (* completed *)
-  | "P"       (* in_progress *)
-  | "D"       (* pending *)
-  | "B"       (* blocked *)
-  | "X"       (* cancelled *)
-  | "R"       (* review *)
-  | "T"       (* testing *) ;
-
-(* 優先級值 *)
-priority_value =
-    "0"       (* P0 - highest *)
-  | "1"       (* P1 *)
-  | "2"       (* P2 *)
-  | "3"       (* P3 - lowest *) ;
-
-(* 時長值 *)
-duration_value =
-    number_value , time_unit ;
-
-time_unit =
-    "s"       (* seconds *)
-  | "m"       (* minutes *)
-  | "h"       (* hours *)
-  | "d"       (* days *)
-  | "w"       (* weeks *) ;
-
-(* 列表值 *)
-list_value =
-    identifier , { "," , identifier } ;
-
-(* 任務組（分號分隔的複雜結構） *)
-task_group =
-    task_item , { ";" , task_item } ;
-
-task_item =
-    identifier , { "," , sub_field } ;
-
-sub_field =
-    field_key , "=" , field_value ;
-
-(* 布林值 *)
-boolean_value =
-    "0" | "1" | "true" | "false" ;
-
-(* 文本值 *)
-text_value =
-    { any_character - ( "|" | newline ) } ;
-```
-
-**範例**:
-```
-@data
-T121|st=C|p=0|dur=135m|ct=260206-1430|desc=API integration|
-T122|st=C|p=1|dur=90m|ct=260206-1500|desc=UI refactoring|
-260207|dev|T123,st=P,dur=45m;T124,st=P,dur=60m|note=DB migration in progress|
-```
-
----
-
-## 🔤 基本詞法單元
-
-### 標識符與字符
-
-```ebnf
-(* 標識符 *)
-identifier =
-    letter , { letter | digit | "_" | "-" } ;
-
-(* 字母 *)
-letter =
-    uppercase_letter | lowercase_letter ;
-
-uppercase_letter =
-    "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J"
-  | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T"
-  | "U" | "V" | "W" | "X" | "Y" | "Z" ;
-
-lowercase_letter =
-    "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j"
-  | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t"
-  | "u" | "v" | "w" | "x" | "y" | "z" ;
-
-(* 數字 *)
-digit =
-    "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
-
-(* 空白字符 *)
-ws =
-    " " | "\t" ;
-
-(* 任意字符（不含特殊符號） *)
-any_character =
-    letter | digit | symbol | ws ;
-
-symbol =
-    "!" | "@" | "#" | "$" | "%" | "^" | "&" | "*" | "(" | ")"
-  | "-" | "+" | "=" | "[" | "]" | "{" | "}" | ";" | ":"
-  | "'" | "\"" | "," | "." | "/" | "?" | "<" | ">" | "~" | "`" ;
-```
-
----
-
-## 📐 語法樹範例
-
-### 範例 1：最小 .matrix 文件
-
-**原始**:
-```
-# .matrix v1.0
-@meta |v=1.0|c=test|t=260208|
-@index |tot=1|
-@data
-T1|st=C|
-```
-
-**語法樹**:
-```
-matrix_file
-├── comment_line
-│   └── "# .matrix v1.0"
-├── meta_section
-│   ├── "@meta"
-│   └── meta_fields
-│       ├── meta_field: v=1.0
-│       ├── meta_field: c=test
-│       └── meta_field: t=260208
-├── index_section
-│   ├── "@index"
-│   └── index_fields
-│       └── index_field: tot=1
-└── data_section
-    ├── "@data"
-    └── data_line
-        ├── record_id: T1
-        └── data_fields
-            └── data_field: st=C
-```
-
-### 範例 2：複雜任務記錄
-
-**原始**:
-```
-@data
-T123|st=P|p=0|dur=45m|ct=260207-0900|desc=DB migration|dep=T120,T121|
-```
-
-**語法樹**:
-```
-data_line
-├── record_id: "T123"
-└── data_fields
-    ├── data_field
-    │   ├── field_key: "st"
-    │   └── field_value: status_value("P")
-    ├── data_field
-    │   ├── field_key: "p"
-    │   └── field_value: priority_value("0")
-    ├── data_field
-    │   ├── field_key: "dur"
-    │   └── field_value: duration_value("45m")
-    ├── data_field
-    │   ├── field_key: "ct"
-    │   └── field_value: timestamp_value("260207-0900")
-    ├── data_field
-    │   ├── field_key: "desc"
-    │   └── field_value: text_value("DB migration")
-    └── data_field
-        ├── field_key: "dep"
-        └── field_value: list_value("T120,T121")
-```
-
-### 範例 3：記憶系統記錄
-
-**原始**:
-```
-@data
-260207|dev|T123,st=P,dur=45m;T124,st=P,dur=60m|note=DB migration in progress|
-```
-
-**語法樹**:
-```
-data_line
-├── record_id: "260207"
-└── data_fields
-    ├── data_field
-    │   ├── field_key: (implicit type)
-    │   └── field_value: identifier("dev")
-    ├── data_field
-    │   ├── field_key: (implicit tasks)
-    │   └── field_value: task_group
-    │       ├── task_item
-    │       │   ├── identifier: "T123"
-    │       │   ├── sub_field: st=P
-    │       │   └── sub_field: dur=45m
-    │       └── task_item
-    │           ├── identifier: "T124"
-    │           ├── sub_field: st=P
-    │           └── sub_field: dur=60m
-    └── data_field
-        ├── field_key: "note"
-        └── field_value: text_value("DB migration in progress")
-```
-
----
-
-## ⚙️ 解析規則
-
-### 優先級順序
-
-| 優先級 | 元素 | 說明 |
-|-------|------|------|
-| 1 | `comment_line` | 以 `#` 開頭的註釋行 |
-| 2 | `@meta` | 文件元數據（必須） |
-| 3 | `@index` | 索引層（必須） |
-| 4 | `@data` | 數據層（可選） |
-
-### 解析步驟
-
-1. **詞法分析**（Tokenization）
-   - 識別分隔符: `|`, `=`, `,`, `;`
-   - 識別保留字: `@meta`, `@index`, `@data`
-   - 識別標識符、數字、字符串
-
-2. **語法分析**（Parsing）
-   - 驗證三層結構順序
-   - 驗證各層語法規則
-   - 建立抽象語法樹（AST）
-
-3. **語義分析**（Semantic Analysis）
-   - 驗證欄位鍵名合法性
-   - 驗證值類型匹配
-   - 驗證引用完整性（dep, blk）
-
-4. **建立數據模型**（Model Building）
-   - 轉換為內部數據結構
-   - 建立索引映射
-   - 準備查詢接口
-
----
-
-## 🔒 約束規則
-
-### 必須性約束
-
-```ebnf
-(* 必須包含的元素 *)
-required_elements =
-    meta_section ,
-    index_section ;
-
-(* @data 層可選 *)
-optional_elements =
-    data_section ;
-```
-
-### 唯一性約束
-
-- **@meta 層**: 必須唯一,只能出現一次
-- **@index 層**: 必須唯一,只能出現一次
-- **@data 層**: 最多一次
-- **record_id**: 在 @data 層內必須唯一
-
-### 順序約束
-
-- **層級順序**: `@meta` → `@index` → `@data`（強制順序）
-- **欄位順序**: 無強制要求（但建議保持一致）
-
-### 數值約束
-
-```ebnf
-(* 版本號約束 *)
-version_constraint =
-    major_version = 1 ,
-    minor_version >= 0 ;
-
-(* 時間戳約束 *)
-timestamp_constraint =
-    year_short: 00..99 ,
-    month_digit: 01..12 ,
-    day_digit: 01..31 ,
-    hour_digit: 00..23 ,
-    minute_digit: 00..59 ;
-
-(* 優先級約束 *)
-priority_constraint =
-    priority_value IN { "0", "1", "2", "3" } ;
-```
-
----
-
-## ❌ 錯誤處理
-
-### 語法錯誤類型
-
-| 錯誤代碼 | 錯誤類型 | 範例 | 處理方式 |
-|---------|---------|------|---------|
-| E001 | 缺少必要層級 | 缺少 @meta | 拒絕解析 |
-| E002 | 層級順序錯誤 | @data 在 @meta 之前 | 拒絕解析 |
-| E003 | 分隔符錯誤 | 缺少 `\|` | 拒絕解析 |
-| E004 | 欄位格式錯誤 | `st:C`（應為 `st=C`） | 拒絕解析 |
-| E005 | 值類型錯誤 | `p=High`（應為 `p=0`） | 警告,嘗試修正 |
-| E006 | 時間戳格式錯誤 | `t=2026-02-07`（應為 `t=260207`） | 警告,嘗試修正 |
-| E007 | 重複 record_id | 兩個 `T123` | 拒絕解析 |
-| E008 | 未知欄位鍵名 | `unknown=value` | 警告,保留 |
-
-### 錯誤訊息格式
-
-```
-Error [E001]: Missing required section '@meta'
-  at line 1, column 1
-
-  Expected:
-    # .matrix v1.0
-    @meta |v=1.0|c=...|
-
-  Got:
-    @index |tot=123|
-```
-
----
-
-## ✅ 驗證器實作指南
-
-### 驗證步驟
-
-```python
-def validate_matrix_file(content: str) -> ValidationResult:
-    """
-    驗證 .matrix 文件語法
-    """
-    # Step 1: 詞法驗證
-    tokens = tokenize(content)
-    if not tokens:
-        return ValidationResult(False, "E000: Empty file")
-
-    # Step 2: 結構驗證
-    if not has_meta_section(tokens):
-        return ValidationResult(False, "E001: Missing @meta section")
-
-    if not has_index_section(tokens):
-        return ValidationResult(False, "E001: Missing @index section")
-
-    # Step 3: 順序驗證
-    if not check_section_order(tokens):
-        return ValidationResult(False, "E002: Invalid section order")
-
-    # Step 4: 語法驗證
-    ast = parse_tokens(tokens)
-    if not ast:
-        return ValidationResult(False, "E003: Syntax error")
-
-    # Step 5: 語義驗證
-    semantic_errors = validate_semantics(ast)
-    if semantic_errors:
-        return ValidationResult(False, semantic_errors)
-
-    return ValidationResult(True, "Valid .matrix file")
-```
-
-### Parser 實作建議
-
-1. **使用遞歸下降解析器**（Recursive Descent Parser）
-   - 簡單直觀
-   - 易於實作錯誤恢復
-   - 適合 .matrix 的簡單語法
-
-2. **建立明確的 AST 節點類型**
-   ```python
-   class MatrixFile:
-       meta: MetaSection
-       index: IndexSection
-       data: Optional[DataSection]
-
-   class MetaSection:
-       fields: Dict[str, str]
-
-   class IndexSection:
-       fields: Dict[str, Any]
-
-   class DataSection:
-       records: List[DataRecord]
-
-   class DataRecord:
-       id: str
-       fields: Dict[str, Any]
-   ```
-
-3. **提供友善的錯誤訊息**
-   - 明確的錯誤位置（行號、列號）
-   - 預期與實際的對比
-   - 修正建議
-
----
-
-## 🧪 測試案例
-
-### 正向測試（Valid）
-
-```
-# Test 1: 最小有效文件
-@meta |v=1.0|c=test|
-@index |tot=0|
-```
-
-```
-# Test 2: 包含所有層級
-# .matrix v1.0
-@meta |v=1.0|c=test|t=260208|
-@index |tot=1|c=1|
-@data
-T1|st=C|p=0|
-```
-
-```
-# Test 3: 複雜數據結構
-@meta |v=1.0|c=memory|t=260208|r=7d|
-@index |d=260208,260207|e=10|cat=dev,bug|
-@data
-260208|dev|T1,st=P,dur=30m;T2,st=C,dur=45m|note=Daily work|
-260207|bug|T3,st=B,blk=REVIEW|note=Blocked issue|
-```
-
-### 負向測試（Invalid）
-
-```
-# Test 4: 缺少 @meta（應拒絕）
-@index |tot=1|
-@data
-T1|st=C|
-```
-
-```
-# Test 5: 順序錯誤（應拒絕）
-@data
-T1|st=C|
-@meta |v=1.0|c=test|
-@index |tot=1|
-```
-
-```
-# Test 6: 分隔符錯誤（應拒絕）
-@meta |v=1.0|c=test
-@index |tot=1|
-```
-
-```
-# Test 7: 欄位格式錯誤（應拒絕）
-@data
-T1|st:C|p:0|
-```
-
----
-
-## 📚 參考資源
-
-### EBNF 標準
-
-- **ISO/IEC 14977:1996** - Information technology — Syntactic metalanguage — Extended BNF
-- **W3C EBNF Notation** - https://www.w3.org/TR/REC-xml/#sec-notation
-
-### 相關文檔
-
-- **格式規格**: `matrix_format_DESIGN_SPEC.md`
-- **縮寫映射表**: `matrix_format_ABBREVIATIONS.md`
-- **Token 對比**: `matrix_format_TOKEN_COMPARISON.md`
-- **範例文件**: `matrix_format_EXAMPLE_*.matrix`
-
----
-
-## 🔄 版本歷史
-
-| 版本 | 日期 | 變更內容 |
-|------|------|---------|
-| 1.0.0 | 2026-02-08 | 初始版本 - 完整 EBNF 定義 |
-
----
-
-**文檔版本**: 1.0.0
-**最後更新**: 2026-02-08
-**維護者**: Developer Team
-**Feature ID**: F-015
-**Task ID**: TASK_139