docs: Token 计数修正 50→67 (AGENTS.md + CLAUDE.md)

docs/analysis/architecture-analysis-report-2026-06-06-1133.md

@@ -0,0 +1,266 @@
+# L Language 架构分析报告 v0.6.1 (复查)
+
+> 日期: 2026-06-06 11:33 UTC | 自动生成 | **无代码变更**
+> 上次报告基线: `031dedf` (2026-06-06 06:53 UTC, v0.6.1)
+> 当前 HEAD: `031dedf` refactor: 拆分 sema analyze_expr 为 9 个辅助函数 + 调度器
+> **结论: 自上次报告以来无任何代码变化。**
+
+---
+
+## 0. 代码变更检查
+
+```
+git diff 031dedf..HEAD → (空)
+```
+
+**零提交, 零文件变更, 零行变化。** 上次报告距今约 4.5 小时，HEAD 未移动。
+
+尽管如此，本报告通过重新同步 codegraph、逐文件行数验证、完整测试套件重跑、以及精确 Token 类型计数重新确认项目状态。发现一处数据修正: Token 类型实际为 67 种（上次报告误记为 58）。
+
+---
+
+## 1. 当前架构快照
+
+### 1.1 编译流水线
+
+```
+源码(.l) → Lexer(词法) → Parser(语法+去糖) → Sema(语义) → Codegen(LLVM IR) → Target(obj) → clang+lld 链接(.exe)
+            67 Token      25 AST 节点           类型标注       LLVMModuleRef       .o 文件        优先clang→fallback gcc
+```
+
+### 1.2 模块清单与精确行数
+
+| 模块 | 文件 | 行数 | 职责 |
+|------|------|------|------|
+| include/ | l_lang.h | 55 | TypeKind (13), SourceLoc |
+| lexer/ | lexer.c (168) + token.c (53) + .h (47+10) | 278 | 手写状态机, 67 Token |
+| ast/ | ast.c (221) + ast.h (152) | 373 | 25 种 AST + 工厂函数 |
+| parser/ | parser.c (851) + parser.h (10) | 861 | 递归下降+Pratt, 去糖逻辑 |
+| sema/ | sema.c (806) + symbol.c (148) + .h (9+63) | 1,026 | 类型推断, 9+1 函数结构 |
+| codegen/ | codegen.c (764) + target.c (30) + .h (12+15) | 821 | LLVM IR 生成 + 目标输出 |
+| driver/ | main.c (205) + error.c (46) + .h (18) | 269 | 流水线串联 + 错误报告 |
+| util/ | arena.c (39) + arena.h (13) | 52 | Bump allocator (8MB) |
+| **合计** | | **~3,735** | |
+
+### 1.3 核心类型枚举（数据修正）
+
+| 枚举 | 数量 | 来源文件 | 备注 |
+|------|------|----------|------|
+| **TokenKind** | **67** | token.h:5 | **上次报告误记为 58，已修正** |
+| TypeKind | 13 | l_lang.h:1 | i32/i64/u64/f64/bool/char/str/void/struct/enum/array/unknown/error |
+| AstNodeKind | 25 | ast.h:1 | 含 impl/method_call/array_assign/match 脱糖节点 |
+| SymbolKind | 5 | symbol.h | VAR/PARAM/FN/STRUCT/ENUM |
+
+#### Token 类型完整列表 (67 种)
+
+| 类别 | 数量 | Token |
+|------|------|-------|
+| 关键字 | 15 | `fn` `let` `var` `if` `else` `while` `for` `in` `return` `guard` `struct` `type` `enum` `extend` `match` |
+| 类型 | 8 | `i32` `i64` `u64` `f64` `bool` `char` `str` `void` |
+| 字面量 | 6 | INT_LIT FLOAT_LIT CHAR_LIT `true` `false` STR_LIT |
+| 标识符 | 2 | IDENT UNDERSCORE |
+| 算术 | 5 | `+` `-` `*` `/` `%` |
+| 比较 | 6 | `==` `!=` `<` `>` `<=` `>=` |
+| 逻辑 | 4 | `&&` `\|\|` `\|`(pipe) `!` |
+| 箭头 | 3 | `->` `to` `=>` |
+| 复合赋值 | 4 | `+=` `-=` `*=` `/=` |
+| 括号 | 4 | `(` `)` `{` `}` |
+| 方括号 | 2 | `[` `]` |
+| 其他分隔 | 4 | `,` `:` `;` `=` |
+| 特殊 | 4 | `.` `::` EOF ERROR |
+
+**关键增长点** (vs v0.1 的 40 种): `var` `guard` `struct` `type` `enum` `extend` `match` `i32` `u64` `char` CHAR_LIT STR_LIT `to` `\|`(pipe) `=>` `+=` `-=` `*=` `/=` `[` `]` `.` `::` — 共 27 种新增。
+
+---
+
+## 2. 已实现功能总览（无变化）
+
+### 2.1 版本演进路线
+
+| 版本 | 日期 | 核心功能 | Token | AST | 测试 |
+|------|------|----------|-------|-----|------|
+| v0.1 | 06-05 | 基础类型+控制流+函数 | 40 | 14 | 65 |
+| v0.2 | 06-05 | let mut + str + 复合赋值 | +4 | +1 | +? |
+| v0.3 | 06-05 | for..in range (去糖) | +2 | +1 | +2 集成 |
+| v0.4 | 06-05 | struct + 字段访问 + RAII | +5 | +4 | +3 集成 |
+| v0.5 | 06-05 | type/impl/enum/array/match | +7 | +5 | +6 集成 |
+| v0.6 | 06-05 | i32/u64/char + guard + named args + pipe + 插值 | +9 | 0 | +4 集成 |
+| v0.6.1 | 06-06 | sema analyze_expr 拆分重构 | 0 | 0 | 0 |
+
+### 2.2 P0 基础功能 (v0.1→v0.4) — 100%
+
+| # | 功能 | 版本 | 实现方式 |
+|---|------|------|----------|
+| 1 | 词法分析 + 注释跳过 | v0.1 | 手写状态机 |
+| 2 | Pratt 表达式解析 (9 级优先级) | v0.1 | 递归下降+Pratt |
+| 3 | i64/f64/bool/void 基本类型 | v0.1 | 直接 LLVM 类型映射 |
+| 4 | let 不可变变量 + 类型推断 | v0.1 | sema 从初始值推断 |
+| 5 | if/else 控制流 | v0.1 | LLVM cond_br |
+| 6 | while 循环 | v0.1 | LLVM 三 BB 循环 |
+| 7 | 函数定义+调用+递归 | v0.1 | LLVM function/call |
+| 8 | 斐波那契程序通过 | v0.1 | 递归版 fib(10) = 55 |
+| 9 | let mut + 赋值 | v0.2 | alloca+store/load |
+| 10 | str 类型 + 拼接 | v0.2 | LLVM i8* + concat helper |
+| 11 | for..in range (去糖为 while) | v0.3 | parser 去糖 |
+| 12 | 结构体声明+初始化+字段访问 | v0.4 | LLVM struct GEP |
+
+### 2.3 P1 类型与抽象 (v0.5) — 100%
+
+| # | 功能 | 实现方式 |
+|---|------|----------|
+| 13 | type 别名 (含 struct 别名) | sema 层解析, zero-codegen |
+| 14 | enum 声明 + 变体访问 | sema + codegen (i64 tag) |
+| 15 | 固定大小数组 + 索引 + 赋值 | LLVM array + GEP |
+| 16 | impl/extend 方法块 | sema mangle (receiver→struct name) |
+| 17 | match 表达式 | parser 去糖为 let+if-else 链 |
+| 18 | parse_type_expr 统一解析 | 单一函数, 消除 parser 类型标注重复 |
+
+### 2.4 P0-扩展 (v0.6) — 100%
+
+| # | 功能 | 实现方式 |
+|---|------|----------|
+| 19 | i32/u64/char 类型 + 字符字面量 | 新增 Lexer/Sema/Codegen 分支 |
+| 20 | guard 守卫语句 | parser 去糖为 if-else |
+| 21 | 命名参数 (任意顺序) | sema 重排序匹配 |
+| 22 | 管道 `\|>` | parser 去糖为嵌套调用 |
+| 23 | 字符串插值 `\(expr)` | parser 去糖为 str 拼接 |
+
+### 2.5 语法差异化 (L vs Rust)
+
+| L 语法 | Rust 对应 | 设计意图 |
+|--------|----------|----------|
+| `var` | `let mut` | 更短, 2 tokens→1 |
+| `T[N]` | `[T; N]` | C 风格数组直觉 |
+| `to` | `..` | 避免与浮点 `.` 歧义 |
+| `extend` | `impl` | 强调扩展而非实现 |
+| `guard` | 无 (Swift 灵感) | 提前返回语法糖 |
+| `\|>` | 无 (F#/Elixir 灵感) | 函数式管道 |
+| `\(expr)` | 无 (Swift 灵感) | 内联表达式求值 |
+
+---
+
+## 3. Rust 对标缺失清单
+
+### 3.1 已完成 (19 项)
+
+全部 P0 + P1 + P0-扩展功能已实现，覆盖 Rust 的基础/中级语法元素。
+
+### 3.2 P2 缺失（中期 — 预计 2-4 周）
+
+| # | 功能 | 预计工时 | 优先级 | Rust 对应 |
+|---|------|---------|--------|----------|
+| F1 | **枚举关联数据 (ADT)** | 2-3 天 | ⭐⭐⭐ | `enum Option<T> { Some(T), None }` |
+| F2 | **表达式作为值** | 2-3 天 | ⭐⭐⭐ | 块返回最后表达式 |
+| F3 | **模块系统** `mod` + `use` | 3-5 天 | ⭐⭐ | 多文件编译 + 可见性 |
+| F4 | **`if let` / `while let`** | 1-2 天 | ⭐⭐ | 模式匹配简化语法糖 |
+| F5 | **泛型 (单态化)** | 5-7 天 | ⭐⭐ | `fn<T>(x: T) → T` |
+| F6 | **trait / 接口** | 5-7 天 | ⭐⭐ | 抽象行为定义 |
+| F7 | **引用 / 切片** | 7-10 天 | ⭐ | `&T`, `&[T]` (不含 borrow check) |
+| F8 | **闭包 (lambda)** | 3-5 天 | ⭐ | `\|x\| x + 1` |
+
+### 3.3 P3 缺失（长期 — 1 个月+）
+
+| # | 功能 | 预计工时 | 备注 |
+|---|------|---------|------|
+| F9 | 所有权 + 借用检查 | 2-4 周 | borrow checker — 复杂度极高 |
+| F10 | 自举 (编译器用 L 重写) | 4-6 周 | 需要完整的标准库支持 |
+| F11 | 标准库 (io/vec/collections) | 4-8 周 | 模块系统必须先就位 |
+| F12 | 编译期执行 (const fn/constexpr) | 1-2 周 | LLVM JIT 或解释器 |
+| F13 | 错误处理 (`Result` / `?` 操作符) | 1 周 | 依赖枚举关联数据 |
+| F14 | 模式匹配解构 | 1-2 周 | 超越当前 match 的简单 if-else 去糖 |
+| F15 | 不安全的代码块 (unsafe) | 3-5 天 | 指针操作/FFI |
+
+**优先级建议**: F1 (ADT) → F2 (表达式值) → F4 (if let) → F3 (模块) → F5 (泛型) → F6 (trait)。ADT 和表达式值是最具语言表现力增益的下一步。
+
+---
+
+## 4. 代码审查（无变化, 与前次一致）
+
+### 4.1 sema analyze_expr 拆分（v0.6.1 重构）
+
+**状态**: 已完成且经验证稳定。`analyze_expr` 从 380+ 行缩减为 15 行调度器 + 9 个辅助函数。
+
+| 辅助函数 | 职责 |
+|----------|------|
+| `analyze_ident_expr` | 标识符引用类型检查 |
+| `analyze_unary_expr` | `-` `!` 类型推导 |
+| `analyze_binary_expr` | 二元运算 + 隐式提升 |
+| `analyze_call_expr` | 函数调用参数/返回值检查 |
+| `analyze_field_access` | struct 字段访问 |
+| `analyze_struct_init` | struct 字面量初始化 |
+| `analyze_enum_variant` | enum 变体初始化 |
+| `analyze_index_expr` | 数组索引访问 |
+| `analyze_method_call` | 方法调用 (extend mangle) |
+
+评估: 重构质量良好，参数签名统一，新增 AST 类型的改动范围可控。74 个 sema 测试断言全部通过。
+
+### 4.2 持续关注问题
+
+| 问题 | 位置 | 风险 |
+|------|------|------|
+| parser.c 单文件 851 行 | parser.c | 新增语法改动面大 |
+| 去糖在 parser 层, 错误消息丢失原始位置 | parser 各处 | match/guard/pipe 报错不直观 |
+| codegen.c 764 行 | codegen.c | 结构体+枚举+方法生成耦合 |
+
+---
+
+## 5. 测试覆盖（全部通过）
+
+| 测试文件 | 测试函数 | 断言 | 覆盖范围 |
+|---------|----------|------|---------|
+| test_lexer.c | 3 | 41 | 基础 token、关键字、运算符 |
+| test_parser.c | 5 | 15 | 函数解析、表达式、if/while |
+| test_sema.c | 24 | 74 | 类型错误、struct/enum/array/match/method/new_types |
+| test_codegen.c | 10 | 28 | 函数/if/while/binary/struct/enum/array/method/match |
+| **单元断言** | **42** | **158** | |
+| 集成 .l 程序 | **29** | — | 全特性端到端, 01~29 |
+| **总计** | **71** | **158+** | |
+
+**验证结果**: 全部 158 断言通过，零失败。构建零警告（`-Wall -Wextra`）。
+
+---
+
+## 6. 技术债务
+
+| # | 问题 | 严重度 | 现状 | 建议 |
+|---|------|--------|------|------|
+| 1 | parser.c 单文件 851 行 | **高** | 未变 | 拆分为 expr/stmt/decl 三个文件 |
+| 2 | 去糖无独立 pass, 错误消息受损 | **中** | 未变 | 将 parser 去糖逻辑提取为独立 desugar pass |
+| 3 | codegen.c 764 行 | 中 | 未变 | 按类型/表达式拆分 |
+| 4 | TypeKind 耦合 (改 7+ 文件) | 低 | 未变 | 用代码生成减少手动同步 |
+| 5 | AST Visitor 缺失 | 低 | 未变 | 宏驱动 visitor 生成 |
+| 6 | LLVM 22 无 mem2reg C API | 低 | 平台限制 | 等待 LLVM 23 或手写优化 pass |
+
+> 共 6 项，与上次报告一致。analyze_expr 膨胀已在 v0.6.1 解决。
+
+---
+
+## 7. 推荐开发路线图
+
+### v0.7 (短期, 2-3 天) — 语言表现力
+
+1. **枚举关联数据 (ADT)** — `enum Option { Some(i64), None }` — 解锁 Result/Option 模式
+2. **表达式作为值** — `let x = if cond { 1 } else { 2 }` — 一致性提升
+3. **`if let` 语法糖** — `if let Some(v) = opt { ... }` — 在 ADT 之后自然跟进
+
+### v0.8 (中期, 1 周) — 工程化
+
+1. **独立 desugar pass** — 解决技术债务 #2，改善 match/guard/pipe 错误消息
+2. **模块系统** — `mod` + `use` + `pub` — 多文件编译
+3. 标准库起步: `io`, `convert`, `collections/vec`
+
+### v0.9 (中期, 1-2 周) — 类型系统
+
+1. 泛型 (单态化)
+2. trait / 接口
+3. AST Visitor 宏驱动
+
+---
+
+## 8. 修正说明
+
+- **TokenKind 计数**: 上次报告 (v0.6.1) 记 58 种，实际为 **67 种**。本次通过逐行读取 token.h 精确计数修正。58 是 v0.1 报告的近似值延续。AGENTS.md 中的 "50 Token 类型" 也已过期。
+
+---
+
+*本报告由 Codex 自动生成于 2026-06-06 11:33 UTC。自上次代码基线 `031dedf` (v0.6.1) 以来零变更。构建和完整测试套件重新验证通过 (158 断言, 0 失败)。*