📝 docs(vscode): 代码阅读规格补上 Rust
This commit is contained in:
cruldra committed
1 parent
69608f9c70
commit
340c81084a
1 file changed
+41
-4
@@ -15,6 +15,7 @@
|
||||
| 流程 | 源码 →（tree-sitter）语法树 → 通用代码块树 → 译文 |
|
||||
| 第一版翻译 | 只做中文模板直译；AI 解读以后作为另一个翻译插件加 |
|
||||
| 第一版语言 | TypeScript / TSX（含 JavaScript / JSX）、Python、Shell 脚本（bash / sh / zsh）、Dockerfile |
|
||||
| Rust | `.rs`（VS Code 的 rust）：读成导入、结构体、枚举、实现、函数、特质；serde、thiserror、axum、sqlx、tauri 各一张库卡片。tokio 不单独做。见「Rust」 |
|
||||
| 扩展方式 | 写代码注册：语言插件、翻译插件都实现约定接口，通过本插件 `activate()` 导出的 API 注册；内置实现也走同一个 API |
|
||||
| 多种翻译怎么选 | 预览顶部筛选栏最右边的下拉框，整个文件一起换，按语言记住选择；只有一种时不显示 |
|
||||
| 块筛选 | 预览顶部钉住一条筛选栏，按块的属性（种类、访问级别、异步……）筛；属性由语言插件按和语言无关的 id 报（通用的由宿主从 facts 推），名字由翻译插件起，webview 不认识任何语言；筛选整个工作区共用、记住 |
|
||||
@@ -146,9 +147,10 @@
|
||||
| command 命令 | `square-terminal` | pipeline 管道 | `square-terminal` | | |
|
||||
| directive 解析指令 | `terminal` | stage 阶段 | `layers` | run 执行 | `square-terminal` |
|
||||
| copy 复制 | `copy` | setting 设置 | `sliders-horizontal` | label 标签 | `tag` |
|
||||
| health 健康检查 | `activity` | start 启动 | `play` | | |
|
||||
| health 健康检查 | `activity` | start 启动 | `play` | trait 特质 | `network` |
|
||||
| impl 实现 | `square-function` | | | | |
|
||||
|
||||
库规则的种类用规则给的图标（`KindBadge.icon`），跟在语言的种类图标后面：SQLAlchemy 数据表 `database`、数据类 `package`、Pydantic 数据模型 `braces`（和类型块同一个图标，颜色不同）、Celery 应用 `server-cog`、定时任务 `calendar-clock`、FastAPI 接口 `globe`、FastAPI 路由器 `network`、React 组件 `atom`、副作用 `zap`、事件处理 `mouse-pointer-click`。数据类写了 `frozen=True` 再加一把锁（`lock`，悬停「不可修改」）。
|
||||
库规则的种类用规则给的图标（`KindBadge.icon`），跟在语言的种类图标后面：SQLAlchemy 数据表 `database`、数据类 `package`、Pydantic 数据模型 `braces`（和类型块同一个图标，颜色不同）、Celery 应用 `server-cog`、定时任务 `calendar-clock`、FastAPI 接口 `globe`、FastAPI 路由器 `network`、React 组件 `atom`、副作用 `zap`、事件处理 `mouse-pointer-click`、serde 可序列化 `braces`、thiserror 错误 `triangle-alert`、axum 接口 `globe`、sqlx 查询 `database`、tauri 桌面命令 `square-function`。数据类写了 `frozen=True` 再加一把锁（`lock`，悬停「不可修改」）。实现块再由规则 `rust.impl` 换成卡片，左边因此有两个「实现」图标。
|
||||
|
||||
这组图标由插件自己定义，是一个封闭的集合：契约里的 `KIND_ICON_NAMES`（上表 26 个——命令、管道、执行共用一个，解释器、解析指令共用一个，选项、设置共用一个，字段、标签共用一个——加库规则用的 9 个（React 组件的原子、副作用的闪电、事件处理的点击手势也在里面），lucide 的 kebab-case 名字），类型 `KindIconName` 是它们的联合，概念的 `icon` 只能写其中一个，写别的是类型错误。内置种类 → 图标名在 `contract.ts` 的 `KIND_ICONS`（宿主写进概念列表）。webview 给每个名字配一个逐个 import 的 lucide 图标组件（`kindIcons.tsx` 的 `KIND_ICON_COMPONENTS`，打包只带这些，预览脚本约 157 kB）；webview 的 `KindIconName` 照契约手抄，`kindIconNames.test.ts` 核对两边一样。规则要新图标就把名字加进这组、在 webview 配上图标，没有按任意名字找图标的路。
|
||||
- 右上角的图标按钮（原型组件 `Reader / BlockTools`，普通块、属性表块、库规则的卡片共用）：只有图标、不带字，名字写在悬停提示和 `aria-label` 里；整排是 `role="group"`（`aria-label="块操作"`）。先是「问 AI」（sparkles 图标，点开 / 收起块下面的问答区，展开时带按下的底色、`aria-expanded`；文件不在工作区文件夹里时没有，见「问 AI」），再是「编辑 / 预览」切换：预览时铅笔「编辑」，编辑时眼睛「预览」、带按下的底色（`--vscode-toolbar-activeBackground`）。按钮宽 24px、高 20px（和种类图标同高），图标 14px、`descriptionForeground` 色；悬停 `--vscode-toolbar-hoverBackground`，键盘聚焦描 1px `--vscode-focusBorder`；Tab 能走到，回车 / 空格切换。
|
||||
@@ -572,6 +574,7 @@
|
||||
```ts
|
||||
export type BlockKind =
|
||||
| 'import' | 'function' | 'class' | 'enum' | 'exception' | 'type' | 'field' | 'const' | 'variable'
|
||||
| 'trait' | 'impl' // Rust：特质、实现（属性表）
|
||||
| 'if' | 'else' | 'loop' | 'try' | 'catch' | 'finally' | 'return' | 'statement' | 'comment'
|
||||
| 'interpreter' | 'options' | 'case' | 'command' | 'pipeline' // shell：解释器、选项（属性表），分情况、命令、管道（一行译文）
|
||||
| 'directive' | 'stage' | 'run' | 'copy' | 'setting' | 'label' | 'health' | 'start' // Dockerfile：解析指令、阶段、健康检查、启动（属性表），执行、复制、设置、标签（一行译文）
|
||||
@@ -1119,7 +1122,7 @@ export interface CommandRule {
|
||||
|
||||
### 启用、认领、优先
|
||||
|
||||
- 启用：宿主收集这份源码里各层导入块的 `ImportFacts.sources`（去掉引号），有一个等于规则的某个库、或以「库.」「库/」开头（子模块），规则才对这份源码启用。规则不用自己读导入语句。`libraries` 是空数组的规则不看导入，`languageIds` 里这几种语言的源码都启用（React：新的 JSX 写法不用导入 react。Pydantic：子类文件常常只导入父模型、不再导入 pydantic，见「内置：Pydantic 数据模型」）。
|
||||
- 启用：宿主收集这份源码里各层导入块的 `ImportFacts.sources`（去掉引号），有一个等于规则的某个库、或以「库.」「库/」「库::」开头（子模块；Rust 的路径用 `::`，`use axum::routing::get` 的来源是 `axum::routing`），规则才对这份源码启用。规则不用自己读导入语句。`libraries` 是空数组的规则不看导入，`languageIds` 里这几种语言的源码都启用（React：新的 JSX 写法不用导入 react。Pydantic：子类文件常常只导入父模型、不再导入 pydantic，见「内置：Pydantic 数据模型」）。
|
||||
- 认领：宿主从顶层往下每块问一遍启用的规则，按注册顺序，第一个认领的算（先注册的优先）；被认领的块留下的子块照样问。
|
||||
- 出错：规则抛错、或替身不合约定（种类 id 没带规则 id 前缀、并进来的不是这块的子块、属性表里的引用标的不是自己 / 规则没给 `resolve` / 引用的段没带下标、放进卡片里的块不是留下的子块 / 放了几处 / 没有那一行或子行、要略去的块还有子块）时，宿主记一条警告日志（输出面板「Superpowers」），当它没认、接着问下一个规则；都没认这块照常显示。预览不会因为规则出错而失败。
|
||||
- 并进来的子块：不再单独成块，由规则挑（`absorbs`），宿主不替规则多并。没并进来的子块（方法、规则不讲的注释）不管写在哪（字段中间也算），都照源码顺序是替身的子块，预览里照常看得见。替身的编辑范围同别的块，是原块整条语句（从头部开始，到原块连同各子块的最后一行，类就是整个类），盖住留下的子块的行：替身编辑时预览不画这些子块，同一行不会同时在两处能改（见「预览（代码块树）」）。内置规则并成员时连同紧挨在它前面的注释块一起并（讲的是这个成员），讲方法的注释、最后面的注释照常留下。
|
||||
@@ -1611,6 +1614,16 @@ export interface CommandRule {
|
||||
|
||||
和原型不一样的地方：原型里「做什么」「意思」、派生值的读法（「title；没有就按路径查 PAGE_TITLES」）是照设计手写的中文，实现里是注释原文、照翻译插件翻的译文和词表；条件照翻译插件读（`===` 是「全等」，原型写「是」）；渲染大纲带下一层的行有折叠箭头；副作用子卡片收起时不换成一行摘要，「做什么」那一行的箭头收起它下面的语句。
|
||||
|
||||
### 内置：Rust 的库
|
||||
|
||||
文件导入了对应 crate 才启用（来源等于 crate 名，或以 `crate::` 开头）。tokio 不单独做卡片，异步已经写在函数上。样例 `fixtures/rustLibs.rs`。
|
||||
|
||||
- serde（`rules/serde.ts`，`libraries: ['serde']`）：`derive` 了 `Serialize` 或 `Deserialize` 的结构体。种类 `serde.struct`，标签「可序列化」，图标 `braces`，颜色同结构体（暗 #4ec9b0 / 亮 #267f99）。名称后面再标一个「可序列化」。`rename_all = "camelCase"` 收成选项「字段名改驼峰」。字段表多一列「序列化」：`rename` 写「改名 xxx」，`skip` / `skip_serializing` 写「不输出」，没标是「—」。
|
||||
- thiserror（`rules/thiserror.ts`，`libraries: ['thiserror']`）：`derive` 了 `Error` 的枚举。种类 `thiserror.error`，标签「错误」，图标 `triangle-alert`，颜色同异常（暗 #f14c4c / 亮 #cd3131）。变体表「变体 | 何时 | 展示」：何时是变体上面的文档注释，展示是 `#[error("…")]` 的文案。变体上的 `#[from]` 或 `#[source]` 在展示后面标「透传来源」。
|
||||
- axum（`rules/axum.ts`，`libraries: ['axum']`）：处理函数上的 `#[get("/path")]`、`#[axum::post(…)]` 等（get / post / put / delete / patch / head / options / trace），或顶层语句里 `Router` 的 `.route(路径, get(函数))`。函数已经标了路由属性时，这句 `route` 不再单独成卡。种类 `axum.route`，标签「接口」，图标 `globe`，颜色同 FastAPI 接口（暗 #61afef / 亮 #1a6fb5）。属性表：名称、说明、异步（是）、请求（一项「方法」、一项「路径」、路径里的 `{名字}` 对上参数写成「路径参数」，`Path(id): Path<Uuid>` 写 `id: Uuid`）、返回。
|
||||
- sqlx（`rules/sqlx.ts`，`libraries: ['sqlx']`）：`query!` / `query_as!` / `query_scalar!`。种类 `sqlx.query`，标签「查询」，图标 `database`，颜色暗 #ce9178 / 亮 #a31515。紧挨在前面的注释收成「说明」，不再单独成块。SQL 原文等宽，参数 `$1` 对上传入的表达式，`query_as!` / `query_scalar!` 的第一个实参是返回类型，`query!` 的返回类型是「—」。
|
||||
- tauri（`rules/tauri.ts`，`libraries: ['tauri']`）：`#[tauri::command]` 的函数。种类 `tauri.command`，标签「桌面命令」，图标 `square-function`，颜色暗 #e5c07b / 亮 #9a6a00。名称后面再标「桌面命令」。参数表「名称 | 类型 | 来源」：`State<…>` 是「窗口状态」，其余是「调用方传入」。
|
||||
|
||||
## 命令规则
|
||||
|
||||
shell 脚本大半是一条条命令，一条命令读成什么取决于命令本身（`rm -rf` 是「删除（连同里面的东西、不提示）」，`tar -xzf` 是「解压 tar.gz」）。这些既不是语法（语言插件不管），也不是某种语言的措辞（翻译插件不该认识几十个命令）。命令规则是第五种插件：按命令名注册，把一条命令连同它的选项读成一句译文，像库规则按库认写法一样。
|
||||
@@ -1724,6 +1737,20 @@ shell 脚本大半是一条条命令，一条命令读成什么取决于命令
|
||||
- `run_instruction` → run（整条指令，shell 写法的带 `embedded`）；`copy_instruction`、`add_instruction` → copy；`label_instruction` → label；`env_instruction`、`arg_instruction` → variable（facts 的 scope 分构建参数、环境变量）；WORKDIR / USER / EXPOSE / VOLUME / STOPSIGNAL / SHELL / MAINTAINER → setting；`healthcheck_instruction` → health；`cmd_instruction`、`entrypoint_instruction` → start；`onbuild_instruction` → setting，包着的指令照这些规则是它的子块；别的（语法错误）→ statement。
|
||||
- 连着写的同种指令（紧挨着下一行）并成一块：ENV、ARG 并成一个变量块（declarators 是各条的全部），LABEL 和从同一个地方复制的 COPY 并成一块（`TextBlock.group`，头部盖住全部）；ADD、带 heredoc 的 COPY 不并。
|
||||
|
||||
### Rust
|
||||
|
||||
语法包是 `@vscode/tree-sitter-wasm` 里的 `tree-sitter-rust.wasm`（和 python 的 wasm 同一层：包入口就在 `wasm/`）。`languageIds: ['rust']`。样例 `fixtures/rustLang.rs`、`fixtures/rustLibs.rs`。原型是 `docs/prototype/code-reader/openpencil/exports/` 的 `rust-lang.png`、`rust-lib.png`、`rust-notes.png`。中文直译 `translators/rustZh.ts`：结构体不叫「类」，可见性不叫「访问级别」，`pub` 是「公开」。
|
||||
|
||||
可见性：`pub` 公开，没写是本模块，`pub(super)` 父模块，`pub(crate)` 和 `pub(in …)` 本 crate。公开写在 `facts.access`，其余写在块的 `access` 属性上（筛选值 `module` / `super` / `crate`）。说明是紧挨在前面的文档注释（`///`、`/**`）的第一句，句号留着。
|
||||
|
||||
- `use` → import。来源是路径去掉最后一节（`std::sync::Arc` 的来源是 `std::sync`）。导入项表「名字 | 别名」，没起别名是「—」，`*` 是「*」。
|
||||
- `struct` → class（中文直译把这个种类叫「结构体」）。字段不单独成块，表「字段 | 类型 | 可见性」。元组结构体没有这张表。
|
||||
- `enum` → enum。变体表「变体 | 携带的数据」：没带数据是「—」，`Failed(String)` 写类型，`Running { pid: u32 }` 写字段原文。
|
||||
- `fn` → function。有才显示：说明、异步（只有 `async fn` 写「是」）、可见性、输入参数表「名称 | 类型」、返回（没写是 `()`）。函数体里直接写的 `match` 收成「分情况」表「分支 | 做什么」，N 支：优先用这一支里的注释，否则是 `return` 那句或这一支的第一句，不展开成子块。
|
||||
- `trait` → trait（图标 `network`，颜色同声明关键字的蓝）。方法表「名称 | 参数 | 返回」，只列签名，不展开函数体。
|
||||
- `impl` → impl（图标 `square-function`，颜色同函数）。标题是「某类型 的方法」（`impl Trait for Type` 取 Type）。方法是子块。不看导入的规则 `rules/rustImpl.ts`（`libraries: []`，种类 `rust.impl`）把每张方法卡放进方法表那一行，点方法名展开，和 React 事件处理同一条路。方法卡的参数表叫「参数」。
|
||||
- 其余（`let`、`const`、宏调用）→ statement。`//` 注释单独成块。
|
||||
|
||||
### 属性表信息（facts）从哪来
|
||||
|
||||
- TypeScript 函数：`function_declaration` / `generator_function_declaration` / `function_signature`、类里的 `method_definition` / 方法签名、值是带语句块主体函数的变量和类字段、`export default` 的函数值。名称取声明名 / 变量名 / 字段名；说明取紧贴在前面的 JSDoc 注释节点（见上面代码块树规则）；参数来自 `formal_parameters`（`required_parameter` / `optional_parameter` 的 pattern、type、value，JavaScript 的 `assignment_pattern`），不带括号的单参数箭头函数取 `parameter`；返回类型取 `return_type` 里的类型；异步看有没有 `async`；类成员的装饰器是类主体里排在它前面的 `decorator` 兄弟节点。
|
||||
@@ -1738,6 +1765,7 @@ shell 脚本大半是一条条命令，一条命令读成什么取决于命令
|
||||
- Shell：解释器取 `#!` 后面的整句，第一个词是 `env` 的是按 PATH 找、程序名是它后面那个词，否则是写死的路径、程序名是路径最后一节。选项：每个开关一项，单字母换成 bash 的长名字（e → errexit、u → nounset、x → xtrace……），`-o 名字` 照写，`-` 开、`+` 关。变量：`variable_assignment` 的 name / value，声明里没给值的只有 name。函数：name 是函数名，doc 是紧贴在上面的注释；`positional` 是主体里（不进嵌套的函数）用到的 `$N` / `${N}` / `${N:-…}`，照位置排，`local x="$N"`、`x=$N` 给它起名字；`prints` 是没重定向到别处的 `echo` / `printf`（进 if、循环、分情况，不进 `$(…)`、管道、嵌套的函数）；`captured` 看同一文件里有没有 `$(函数名 …)`；`returns` 是主体里的 `return` 命令。
|
||||
- Dockerfile：解析指令是每行注释 `# 名字=值` 的名字（小写）和值；阶段取 `image_spec` 的 name / tag / digest 字段、`as` 字段（image_alias），stage 看镜像名是不是前面某个阶段的名字（不分大小写），选项是 `param`、`mount_param` 节点的原文 `--名字=值`（值在语法树里没有单独的节点，按原文拆，记下值从哪开始）；变量是 `env_pair` 的 name / value、`arg_instruction` 的 name / default；健康检查的 none 看有没有 NONE，检查命令是里面的 `cmd_instruction`；数组写法取 `json_string_array`，shell 写法取 `shell_command` 里各个 `shell_fragment`（`line_continuation` 不算），只有一个 `<<EOT` 的取它下面 `heredoc_block` 从第一行到最后一行。
|
||||
- Python 变量：`assignment` 的 left / type / right，说明是紧跟在后面的属性 docstring 的字符串节点（见上面代码块树规则）；right 是 `dictionary` 时 entries 是它的具名子节点（注释除外）：`pair` 的 key / value（value 又是 `dictionary` 时连它的 entries）、`dictionary_splat` 里的表达式。
|
||||
- Rust：函数的 name / parameters / return_type，`async` 只在写了时填；`self` 的类型节点是整个接收者（`&mut self`）。结构体、枚举、特质、实现的名称、说明、可见性见「Rust」。字段和变体携带的数据由中文直译读语法树，不另做 facts。
|
||||
|
||||
## 中文模板直译
|
||||
|
||||
@@ -1890,7 +1918,7 @@ type BlockView = BlockViewBase & ({ translation: PreviewText, table?: PreviewTab
|
||||
|
||||
带自己颜色的段（`Segment.color`，库规则按库的配色给，例如 FastAPI 的 HTTP 方法、成功的状态码）：暗色、亮色两个写在元素的 style 上（`--color-dark` / `--color-light`），`.cr-colored` 按主题挑一个，盖过词性的颜色；词性照旧报（`role`）。
|
||||
|
||||
种类（种类图标的颜色 + 块底 7% + 边框 35%；亮色主题同色系；图标见「预览（代码块树）」）：import 导入 #c586c0；function 函数 #dcdcaa；class 类、type 类型 #4ec9b0；enum 枚举 #b180d7（亮色 #652d90）；exception 异常 #f14c4c（亮色 #cd3131，和尝试、捕获、最终同一色系，更红一些）；field 字段、const 常量、variable 变量 #9cdcfe；if 条件、else 否则 #ce9178；loop 循环 #8f9cff；try 尝试、catch 捕获、finally 最终 #f48771；return 返回 #89d185；statement 语句 #9d9d9d；comment 注释 #6a9955（虚线框）；Shell 的 interpreter 解释器同语句 #9d9d9d，options 选项 #e5c07b（亮色 #9a6a00），case 分情况同条件 #ce9178，command 命令、pipeline 管道 #d7ba7d（亮色 #7c5f12）；Dockerfile 的 directive 解析指令同语句，stage 阶段 #56b6c2（亮色 #127f8c），run 执行同命令，copy 复制同导入，setting 设置同选项，label 标签同变量，health 健康检查同尝试 / 捕获，start 启动同返回（原型 DOCKER_KINDS 的颜色）；库规则的种类用规则给的颜色（`badge.color` 的 dark / light，webview 写在块的 style 上按主题挑），内置 SQLAlchemy 数据表 #e8a860 / #a3590d，Celery 应用 #98c379 / #4d7f17，定时任务 #56b6c2 / #127f8c，数据类 #ef7fb0 / #b3306c，FastAPI 接口 #61afef / #1a6fb5，FastAPI 路由器 #7aa2f7 / #34548a。编辑状态：底色 `--vscode-editor-background`，边框 `--vscode-focusBorder`。
|
||||
种类（种类图标的颜色 + 块底 7% + 边框 35%；亮色主题同色系；图标见「预览（代码块树）」）：import 导入 #c586c0；function 函数、impl 实现 #dcdcaa；class 类、type 类型 #4ec9b0；trait 特质同声明关键字的蓝；enum 枚举 #b180d7（亮色 #652d90）；exception 异常 #f14c4c（亮色 #cd3131，和尝试、捕获、最终同一色系，更红一些）；field 字段、const 常量、variable 变量 #9cdcfe；if 条件、else 否则 #ce9178；loop 循环 #8f9cff；try 尝试、catch 捕获、finally 最终 #f48771；return 返回 #89d185；statement 语句 #9d9d9d；comment 注释 #6a9955（虚线框）；Shell 的 interpreter 解释器同语句 #9d9d9d，options 选项 #e5c07b（亮色 #9a6a00），case 分情况同条件 #ce9178，command 命令、pipeline 管道 #d7ba7d（亮色 #7c5f12）；Dockerfile 的 directive 解析指令同语句，stage 阶段 #56b6c2（亮色 #127f8c），run 执行同命令，copy 复制同导入，setting 设置同选项，label 标签同变量，health 健康检查同尝试 / 捕获，start 启动同返回（原型 DOCKER_KINDS 的颜色）；库规则的种类用规则给的颜色（`badge.color` 的 dark / light，webview 写在块的 style 上按主题挑），内置 SQLAlchemy 数据表 #e8a860 / #a3590d，Celery 应用 #98c379 / #4d7f17，定时任务 #56b6c2 / #127f8c，数据类 #ef7fb0 / #b3306c，FastAPI 接口 #61afef / #1a6fb5，FastAPI 路由器 #7aa2f7 / #34548a。编辑状态：底色 `--vscode-editor-background`，边框 `--vscode-focusBorder`。
|
||||
|
||||
## 代码位置
|
||||
|
||||
@@ -1929,6 +1957,14 @@ vscode/src/codeReader/
|
||||
languages/shared.ts 语言插件共用的建树工具；异常类（withExceptions：按整份文件认异常类，类块换成异常块，并类属性、取构造参数）
|
||||
languages/typescript.ts （call：调用的结构，new 是新建；TYPESCRIPT_EXCEPTIONS：认异常类的父类名、类字段、constructor）
|
||||
languages/python.ts （iteration：推导式的结构；call：调用的结构；PYTHON_EXCEPTIONS：自带的异常类、类属性、__init__）
|
||||
languages/rust.ts Rust：代码块树、可见性、文档注释第一句、字段 / 变体 / match
|
||||
rustRows.ts Rust 属性表的行（中文直译和库规则共用）
|
||||
rules/rustImpl.ts impl 的方法放进方法表那一行
|
||||
rules/serde.ts serde：可序列化的结构体
|
||||
rules/thiserror.ts thiserror：错误枚举
|
||||
rules/axum.ts axum：接口
|
||||
rules/sqlx.ts sqlx：查询
|
||||
rules/tauri.ts tauri：桌面命令
|
||||
languages/displayNames.ts 中文名的共用部分：第一小句、行尾记号、按优先级汇总
|
||||
languages/pythonNames.ts Python 的中文名写法（Annotated、@Comment、行尾记号、docstring）
|
||||
languages/bash.ts bash / sh / zsh（shellscript）：代码块树、facts（解释器、选项、按位置的参数、输出、返回）、command（命令的结构、重定向）、symbols（同一文件里的函数、变量）
|
||||
@@ -2016,6 +2052,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vit
|
||||
- 语言插件（`languages/bash.test.ts`，真实解析）：`fixtures/fetchRuntime.sh` 的代码块树（种类、行号、层级，同原型 `SHELL_BLOCKS`，原型略去的行也在）；elif / else 展平、while / for 的主体是子块、条件串和命令串；解释器（env、写死的路径）、选项（连写拆开、`-o`、`+`、`set --` 不是）、变量（local 一句几个、没值的、readonly 和顶层全大写写死的是常量）、函数（按位置的参数和名字、打印的几句、被 `$(…)` 拿去用、写了的 return）；命令的词（写死的文字、有展开的没有）和重定向；同一文件里的名字（函数、赋值、local、for、read、展开，第几个参数不算）；行尾 `# @Comment`。
|
||||
- 中文直译（`translators/bashZh.test.ts`，走 `readBlockViews`）：`fetchRuntime.sh` 整份逐行同 `FETCH_READING`（即上面「Shell 脚本」的样例）；展开（长度、去头去尾、截取、没设时、替换、特殊变量）、条件、重定向、命令规则（不认识的选项照抄、没有规则的照抄）、`&&` / `||`、遍历、`$(dirname "$0")`、常量；字符串色 / 变量色 / 常量色；规则出错照抄命令并报告。
|
||||
- 宿主：命令规则按语言、注册顺序给（`registry.test.ts`），shellscript 的 document 消息带命令规则读的译文、shell 的种类名、同一文件里的名字（`editor/documentMessage.test.ts`），跳到之前最近的定义、定义处算写入（`localSymbols.test.ts`）。
|
||||
- Rust（`languages/rust.test.ts`、`rules/rustLibs.test.ts`，真实解析）：`fixtures/rustLang.rs` 的导入、结构体、枚举、实现（方法放进方法表那一行）、函数（异步、分情况）、特质逐行同预览；给结构体加一个字段，字段表那一行标成新增。`fixtures/rustLibs.rs` 的 serde（改名、不输出、字段名改驼峰）、thiserror（展示、透传来源）、axum（方法、路径、路径参数）、sqlx、tauri 逐行同预览；没导入 serde 时 derive 仍是结构体；改 axum 的路径，路径那一格标成改过。`axum::routing` 这种来源算导入了 axum。
|
||||
- Dockerfile：
|
||||
- 语言插件（`languages/dockerfile.test.ts`，真实解析）：两份 luffy 的 Dockerfile 的代码块树（同原型，后端的三行注释是阶段说明）；并块（紧挨着才并，空行、注释、别的指令隔开，COPY 要从同一个地方，ADD、heredoc 的 COPY 不并，第一个 FROM 之前的是顶层）；ONBUILD 和各种设置；facts（解析指令、阶段的名称 / 序号 / 说明 / 标签 / 摘要 / 平台 / 接着前面的阶段、构建参数和环境变量并块、健康检查两种写法和 NONE、启动）；嵌着的 shell 的几段（续行去掉、heredoc 正文）；数组写法的命令（VOLUME、SHELL 的数组不算）；同一文件里的名字（阶段名在 --from、--mount 的 from、FROM 里，变量）；中文名；着色。
|
||||
- 中文直译（`translators/dockerfileZh.test.ts`，走 `readBlockViews`，RUN 交给 bash 的插件）：两份 luffy 的 Dockerfile 整份逐行同 `NEXT_READING`、`BACKEND_READING`；阶段的各种写法、变量的展开和注解、RUN 的选项 / 数组写法 / heredoc / 一条循环 / 带重定向的一串、没有 shell 插件时照抄、复制和 ADD、设置、健康检查、启动；阶段名和表里变量名的源码下标、RUN 的源码按 shell 着色。
|
||||
|
||||
Reference in new issue
Block a user