# 诊断与限制

Stack 诊断是结构化结果，不是控制台文本。它包含稳定代码、`error` 或 `warning` 严重级别、从 1 开始且 end-exclusive 的源码范围、简洁消息和有序 `expected` 列表；适用时还包含修复帮助与相关源码范围。

## 处理与严重级别

工具依次处理编码与 token、语法、标识符与默认值、语义限制、主题与图标、布局、渲染。前四阶段的错误会阻止渲染。主题、图标、密度和布局提示警告可与回退 SVG 同时出现。

编辑源码后，Playground 会清除旧诊断。选择结果可聚焦主范围，相关信息可指向较早的声明。

## 复杂度限制

| 项目                    |           Draft Stack 1.0 限制 |
| ----------------------- | -----------------------------: |
| 每份文档的图            |                              1 |
| 节点                    |                        1 至 40 |
| 分组                    |                        0 至 12 |
| 图下分组嵌套            |                           3 层 |
| 连线                    | 0 至 80 与节点数两倍中的较小值 |
| 发出警告前的节点 degree |       12 条 incident edge 声明 |

超过硬限制会产生 `STK4003`。超过建议 degree 的节点仍有效，但产生 `STK4002`。请把大型系统拆成多张聚焦的图。

## 可移植诊断代码

| Code      | Severity | 含义                                   |
| --------- | -------- | -------------------------------------- |
| `STK1001` | Error    | 输入不是有效 UTF-8                     |
| `STK1002` | Error    | 存在 byte order mark                   |
| `STK1003` | Error    | 字符串转义或解码值无效                 |
| `STK2001` | Error    | 声明的语言版本不受支持                 |
| `STK2002` | Error    | 出现意外 token、声明、属性、值或操作符 |
| `STK2003` | Error    | 当前结构完成前输入结束                 |
| `STK3001` | Error    | 标识符无效                             |
| `STK3002` | Error    | 标识符被重复声明                       |
| `STK3003` | Error    | 连线引用未知节点                       |
| `STK3004` | Error    | 分组被用作连线端点                     |
| `STK3005` | Error    | 连线连接节点自身                       |
| `STK3006` | Error    | 声明了精确重复连线                     |
| `STK3007` | Error    | 一个 block 中属性重复                  |
| `STK3008` | Error    | 标题、标签或详情违反文本约束           |
| `STK3009` | Error    | 分组没有后代节点                       |
| `STK3010` | Error    | 分组嵌套超过语言限制                   |
| `STK3011` | Error    | 布局引用在作用域内无效                 |
| `STK3012` | Error    | 布局块或单例布局语句重复               |
| `STK3013` | Error    | 图标标识符格式错误                     |
| `STK3014` | Error    | 图包含多条主题语句                     |
| `STK4001` | Warning  | 顺序提示无法满足                       |
| `STK4002` | Warning  | 节点超过建议 incident-edge degree      |
| `STK4003` | Error    | 图超过语言复杂度限制                   |
| `STK5001` | Warning  | 有效主题中没有图标，使用 kind 回退     |
| `STK6001` | Warning  | 请求的非核心主题不可用，使用 `default` |

代码族中，`STK1000` 表示编码/词法，`STK2000` 表示语法，`STK3000` 表示名称/语义，`STK4000` 表示布局/复杂度，`STK5000` 表示图标，`STK6000` 表示主题。`STK9000` 用于实现失败，而不是源码错误。实现只能使用自己的非 `STK` 前缀添加诊断。

## 恢复规则

解析器可以恢复并一次报告多个独立错误，但不能把部分图渲染成有效结果。未知声明、属性、枚举值和操作符绝不会被忽略，以避免成功外观掩盖语义丢失。