## Gonidium 配置与设置

本文档说明 Gonidium 的配置体系设计，主要面向：

- 项目级配置文件 `gonidium.toml`
- 未来的用户级全局配置 `config.toml`

### 总体原则

- **语言语义稳定**：解析 / 类型提升 / 优化规则本身不通过配置改变，仅工具行为可配置。
- **项目优先**：项目内的 `gonidium.toml` 优先级高于全局配置。
- **TOML 格式**：与 `Cargo.toml`、`pyproject.toml` 一致，易读易写。

### 项目级配置：`gonidium.toml`

放在项目根目录，例如：

```text
my-project/
  gonidium.toml
  ...
```

推荐的基本结构如下（v1 设计）：

```toml
[repl]
# 是否在 REPL 中默认开启优化（对应 ReplConfig.opt_enabled）
opt_enabled = true

# 是否在表达式行输出 “expr @ dtype”
print_simplified_expr = true

# header 中显示的最近局部变量个数上限
header_locals_limit = 5

[optimization]
# 优化模式：conservative（保持 IEEE 754 舍入语义）或 aggressive（允许重结合等，常量链可折叠）
mode = "conservative"
# 是否在加减/乘除链中折叠相邻常量（如 (x+1)+2 → x+3）。不填则随 mode：aggressive 时为 true，conservative 时为 false
# const_chain_fold = true

[diagnostics]
# 使用 DiagCode::short_code()（如 "P001", "L007"）来按严重级别分组
allow   = ["L007"]
info    = ["O001"]
warning = ["L008", "L009", "L010", "O002"]
error   = ["P001", "P002", "P003", "P004", "L001", "L002", "L003", "L004", "L005", "L006"]

[backend.python]
function_name = "kernel"
module_doc = "Generated by Gonidium"

[backend.rust]
function_name = "kernel"
module_doc = "Generated by Gonidium"
```

#### `[repl]`

- **`opt_enabled: bool`**
  控制 REPL 是否默认走优化流水线（`optimize_with_info`），等价于 REPL 版本的 `--no-opt` 开关。

- **`print_simplified_expr: bool`**
  控制对无法立即求值的表达式是否打印 “简化表达式 + dtype”，例如：`x*2+1 @ f64`。

- **`header_locals_limit: u32`**
  控制 REPL 顶部 header 中展示多少个最近局部变量名称。

#### `[optimization]`

控制优化流水线（const_fold + e-graph 重写 + 类型恢复）的保守程度。

- **`mode: string`**
  - `"conservative"`（默认）：不做加法/乘法结合律重写，常量折叠仅当整节点两侧均为常量时执行，尽量保持与 IEEE 754 一致的舍入。
  - `"aggressive"`：启用重结合规则（如 `(x+1)+2` → `x+(1+2)`），并在类型恢复后再跑一遍 const_fold，从而把 `1+2` 折成 `3` 等；可能改变浮点运算顺序与舍入，不适合要求逐字节可复现的场景。

- **`const_chain_fold: bool`**（可选）
  是否在加减/乘除链中折叠相邻常量（例如 `(x+1)+2` → `x+3`）。
  - 不配置时：`conservative` 视为 `false`，`aggressive` 视为 `true`。
  - 配置后：覆盖上述默认，例如在 `mode = "conservative"` 下显式写 `const_chain_fold = true` 可单独开启常量链折叠。

`gonidium run` 与 `gonidium repl` 会读取工作目录下的 `gonidium.toml` 中的 `[optimization]`，并传入优化管线。

#### `[diagnostics]`

- key：固定为严重级别名：
  - `allow` / `info` / `warning` / `error`
- value：由 `DiagCode::short_code()` 组成的字符串数组，例如 `"P001"`, `"L007"`。

Gonidium 在启动时会将该表映射到 `DiagConfig`，逻辑等价于：

```rust
let mut cfg = DiagConfig::default();
for code in allow_list   { cfg = cfg.set(code, Severity::Allow); }
for code in info_list    { cfg = cfg.set(code, Severity::Info); }
for code in warning_list { cfg = cfg.set(code, Severity::Warning); }
for code in error_list   { cfg = cfg.set(code, Severity::Error); }
```

#### `[backend.*]`（预留）

预留给代码生成后端的风格配置，例如：

- 生成函数名称（`function_name`）
- 顶部 module 文档（`module_doc`）

这些设置不会改变表达式语义，只影响输出代码的样式。当前内置的 `PythonBackend`
使用固定的函数名，未来可以在这里挂接更细粒度的配置。

### 全局配置：`config.toml`（预留）

未来计划支持用户级别的全局配置文件，遵循 XDG 路径约定，例如：

- macOS / Linux：`~/.config/gonidium/config.toml`
- Windows：`%APPDATA%/gonidium/config.toml`

全局配置的结构可以与 `gonidium.toml` 相同，用作「默认值」或「个人偏好」，合并优先级建议为：

1. CLI 参数 / 环境变量
2. 项目内 `gonidium.toml`
3. 全局 `config.toml`
4. 内置默认值

### 与现有组件的关系

- **`DiagConfig`**：
  `[diagnostics]` 区块直接映射到 `DiagConfig`，统一控制 parse / lower / opt 阶段的诊断严重级别。

- **REPL (`ReplConfig`)**：
  `[repl]` 区块将用于初始化 `ReplConfig`，控制：
  - 是否默认做优化。
  - 输出格式（是否打印简化表达式）。
  - header 展示策略。

- **后端 (`Backend` trait + PythonBackend)**：
  `[backend.*]` 将为基于 `Backend` trait 的代码生成后端提供轻量级的 codegen 行为调节点，不影响核心推导逻辑。

### 当前生效范围（v1）

当前 CLI 会在工作目录查找 `gonidium.toml` 并加载配置：

- `gonidium run ...`：读取 `[diagnostics]` 以构建 `DiagConfig`
- `gonidium repl`：读取 `[diagnostics]` 与 `[repl]`

如果文件不存在或解析失败，将回退到内置默认配置。
