企业官网建设流程全解析

导读

本指南以 jevgrep 仓库的 test/parser/README.md 为核心，完整剖析该项目对源码解析器（Parser）行为的一整套测试体系：覆盖 Python 与 TypeScript 两种语言的源码坐标提取、Unicode 多字节字符的字节边界处理、装饰器与注释归属、无效语法与超限输入的回退策略、结构化类归属，以及可取消的长任务并发隔离。读者将掌握bun run test:parser的测试入口、底层捆绑 Python 运行时（Pyodide）与 TypeScript 编译器的协同方式，并理解为什么这些测试直接决定了 jevgrep 作为"按语义检索代码"的 CLI 工具（Find code by asking what it does）能够稳定、无损地把大文件切分为可送入上下文的源码单元。

一、测试范围与目标：parser 行为测试在测什么

文档开篇即给出该测试目录的职责边界：

These tests cover source coordinates, Unicode byte boundaries, decorators, comments, invalid-syntax fallback, structural class ownership and cancellation.

即 test/parser 下的测试统一验证以下六类行为：

除此之外，文档还明确了三条贯穿全部测试的不变量（invariant）：

1. 单元必须锚定在不可变的源码快照上（Keep selected units tied to their immutable source snapshot）：测试通过{ path, source, contentHash }这样的快照对象驱动解析，保证每次解析都是纯函数式的。
2. 切分大单元必须保留原始字节（Splitting large units must preserve source bytes）：无论按多大上限切分，所有单元拼接后必须逐字节还原整个文件。
3. 重名声明不得挂错类上下文（duplicate declaration names must not attach the wrong class context）：同名类各自的方法必须归属到各自的结构头。

最后给出运行入口：

Runbun run test:parserfor isolated Docker checks and packaged CLI coverage.

二、运行方式：一条命令背后的两段式 CI 门禁

在根目录 package.json 中，test:parser被定义为两段命令的组合：

bun run test:parser # 展开为： bash scripts/test-docker.sh node --experimental-strip-types --test test/parser/*.test.ts \ && bash scripts/test-installed.sh --test-name-pattern "runtime has|local commands|parses Python"

• 第一段：通过 scripts/test-docker.sh 在隔离 Docker 环境内，用 Node 的--experimental-strip-types与--test模式直接运行test/parser/*.test.ts，即本目录的两个测试文件 cpython.test.ts 与 source.test.ts；
• 第二段：通过 scripts/test-installed.sh 以--test-name-pattern过滤运行"runtime has / local commands / parses Python"等命名测试，验证打包后的 CLI 在真实安装场景下解析 Python 的能力。

正如仓库文档 integration-verification.md 所记录的，test:parser是合并后的命名门禁：Node 侧一致性测试 + 打包 CLI 覆盖率测试。

三、测试基础设施：捆绑的 CPython 与 TypeScript 编译器

3.1 无需系统 Python：Pyodide 捆绑运行时

文档特别强调这些测试直接使用捆绑的 Python 运行时与 TypeScript 解析器，不要求系统安装 Python，也不依赖任何历史 spike 的匹配（"They exercise the bundled Python runtime and TypeScript parser directly, without requiring a system Python installation or matching a historical spike"）。

捆绑运行时的载体是 packages/core/src/python-worker.mjs：它通过fork启动一个 Node worker 子进程，在其中loadPyodide({ indexURL: ... })加载 Pyodide（浏览器内 Python/WASM 运行时，仓库锁定版本见 pyodide-0.25.1.LICENSE），并预先编译四个受信任的辅助程序：

["inspect", "preview", "neighborhood", "calls"].map(...) // 从 assets/python/*.py 读取源码并 compile

worker 采用单解释器串行化模型（见 packages/core/src/python.ts）：所有请求按 id 排队进入同一个 Pyodide 解释器，任何时刻只处理一个请求，彻底避免 CPython 解析状态被并发污染。

3.2 四种辅助程序的分工

这四种程序全部由 packages/core/src/source.ts 的runPython<T>(helper, input, signal)统一调度，构成 jevgrep 从"文件切分"到"查询预览"的完整解析链路。

3.3 TypeScript 侧：直接调用编译器 API

对于.ts/.tsx/.js/.jsx/.mjs/.cjs文件，source.ts 不依赖第三方解析服务，而是直接调用 TypeScript 编译器：

const kind = path.endsWith(".tsx") ? ts.ScriptKind.TSX : ... : ts.ScriptKind.TS; const file = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, kind);

并通过parseDiagnostics判断是否存在语法错误（syntaxFallback）。

四、源码坐标与结构化单元（inspect 流程）

4.1 Python 侧：AST 遍历 +.context片段

assets/python/inspect.py 以ast.parse解析源码后，用递归的visit(nodes, prefix, owner_headers)提取声明：

• 声明的起始行取装饰器与函数体的最小值：start = min([node.lineno, *[d.lineno for d in node.decorator_list]])，保证@property之类装饰器不会被切掉；
• 类只要包含子声明，就在子声明之间插入名为<类名>.context的区间片段（如Café.context），并逐层累积ownerHeaders；
• 普通函数/方法输出为name+ 起止行号。

对应测试 source.test.ts 中一个非常典型的样例：

@decorator class Café: """docs""" value = 1 @property def first(self): def nested(): return "é" return nested() class Inner: def method(self): pass tail = 2

解析结果被断言为：

Café.context 2-5 Café.first 6-10 Café.context 11-11 Café.Inner.context 12-12 Café.Inner.method 13-14 Café.context 15-15

即：类头与每个子声明之间都生成context单元，嵌套类递归归属，且多字节字符é不影响行号坐标。

4.2 TypeScript 侧：AST 节点递归 + 装饰器成员

source.ts 对 TS AST 采用add(node, prefix, ownerHeaders)递归：遇到含成员的ClassDeclaration时，把"类头到第一个成员"之间的区间登记为<类名>.context，成员则带上前缀递归。测试 source.test.ts 验证了@trace get value()这样的装饰器成员被完整保留，同时行注释// getter与文件头/** header */被单独记录在comments中。

4.3 重名类的归属隔离

测试 source.test.ts 专门构造了两个同名class Same（Python 与 TS 各一份），断言Same.first与Same.second的ownerHeaders分别指向各自类所在行（1-1 与 4-4），从测试层面坐实了文档中"duplicate declaration names must not attach the wrong class context"的不变量。实现上，Python 侧通过 inspect.py 递归携带owner_headers元组，TypeScript 侧通过add()递归参数ownerHeaders逐层累积。

五、Unicode 字节边界与无损切分

这是 parser 测试最具工程深度的部分。文档明确要求"切分大单元必须保留源字节"，而源码快照的行号基于UTF-8 字节偏移（见 source.ts 的sourceText，用Buffer.byteLength计算行偏移表）。

5.1 切分算法 textUnits

当某个声明或文本范围超过maxUnitBytes（默认 24000 字节）时，source.ts 的textUnits负责把它切成多个有界单元，关键细节有三点：

1. UTF-8 边界回退：while (finish > start && (raw[finish]! & 0xc0) === 0x80) finish--;避免把多字节字符拦腰截断；
2. 整行对齐：优先回退到最近的\n（lastIndexOf(10)），尽量保持单元以完整行结束；
3. 部分标记：被切分的单元全部打上partial: true。

测试 source.test.ts 用"é漢🙂".repeat(10) + "\r\nend"配合maxUnitBytes: 16验证：每个切片的字节数 ≤ 16，且用new TextDecoder("utf-8", { fatal: true })逐片解码后拼接，能与原串逐字节一致——fatal模式保证中间任何非法 UTF-8 序列都会让测试失败。

5.2 CR-only 与 CRLF 源码

• cpython.test.ts 用 25KB 字符串的 CR-only 声明验证"oversized CR-only declarations retain every source byte in bounded units"：CPython 冻结辅助程序报告 LF 坐标，而调用方按 LF 切片（见 source.ts 的注释），两者协调后仍能无损还原；
• source.test.ts 则用maxParseBytes: 12强制触发fallback: "size"，验证超限回退时 CRLF 行尾依然逐字节保留。

5.3 超大 Unicode 行的字节跨度

source.test.ts 还验证了sourceByteStart/sourceByteEnd字节跨度与TextDecoder严格解码的双重一致性，从坐标、字节、文本三个层面保证了切分的无损性。

六、装饰器、注释与"文档字符串"的语义区分

6.1 装饰器计入声明坐标

Python 侧 inspect.py 的start = min([node.lineno, *[d.lineno for d in node.decorator_list]])与 neighborhood/preview 中的start(node)函数保持一致，确保装饰器行是声明单元的起点。测试 cpython.test.ts 用跨行装饰器@(\n decorator\n)验证坐标落在 2-5 行（不含装饰器本身），语义上装饰器归属声明但不单独成单元。

6.2 注释的独立坐标

• Python：上下文窗口采用保守的整行注释策略——source.ts 对.py/.pyi用正则/^\s*#/收集行注释；source.test.ts 验证尾部注释# tail与A.x声明的结束行分离；
• TypeScript：通过ts.getLeadingCommentRanges / getTrailingCommentRanges收集注释范围并去重排序（source.ts）；source.test.ts 验证 TS 单元保留内嵌注释原文（// end、/*important*/）；
• 无效语法回退时：即便语法失败，comments仍负责界定上下文窗口边界（source.ts）。

6.3 f-string 表达式不是 docstring

source.test.ts 验证f"compute {value}"被识别为query-named implementation而非文档字符串；而 source.test.ts 验证带括号的("""docs...""")会被跳过，真正实现行return "IMPORTANT"才进入预览 span。这一区分的实现位于 assets/python/preview.py：只有"首个 body 节点是纯字符串字面量且 body 长度 > 1"时，才把下一节点视为实现起点。

6.4 Python 2 式语法的甄别

测试还系统性地把"长得像 Python 2"的写法分成两类（source.test.ts）：

• 回退类：print "old"、exec "x=1"、except Exception, e、<>、123L、0755、`expression`、元组解包形参def target((first, second))、type Alias = int、def targetT、嵌套双引号 f-string 等，统一fallback: "syntax"且mode: "text"；
• 仍可解析类：print("old")、print >> stream、except ... as e、raise ... from cause、0o755 + 0xFF + 0b11、u"text" + r"raw" + rb"bytes"、元组解包在 for 循环与列表推导中、注释里出现的旧语法字符串等，仍保持mode: "python"。

这是对参考 Python 3.11 语言边界的精确校准：只有真正"无法编译为 3.11 AST"的源码才走文本回退。

七、无效语法与超限输入的回退策略

source.ts 定义了统一的fallback(reason)，产生mode: "text"+ 整文件按textUnits切分的结果，回退原因有三类：

测试 source.test.ts 用三组样例（bad.py语法错误、bad.ts语法错误、readme.md不支持类型）统一断言：回退后mode === "text"、首单元从第 1 行开始、末单元覆盖到最后一行——即回退绝不丢行。

值得强调的是文档中的一句关键约束："A malformed source file may use text fallback; a broken bundled runtime must surface a setup failure"——坏源码可以走文本回退，但捆绑运行时自身损坏（如 Pyodide 加载失败）必须作为安装/设置失败显式暴露，绝不允许静默降级。对应到代码 source.ts：runPython抛出的运行时错误会被原样传递，而只有 Python 侧返回的sourceError（如SyntaxError）才被转换为fallback("syntax")。

八、取消机制：AbortController 与并发隔离

取消是 parser 测试的另一核心主题。文档将其列为测试覆盖范围之一，cpython.test.ts 用四个测试层层验证：

8.1 取消后运行时必须可恢复

测试 cpython.test.ts 验证：中止一个正在运行的inspect请求后（first.abort()），紧接着的def recovered(): pass请求能正常解析并返回坐标；随后再对一个 50 万行的大请求 20ms 超时中止，之后的def broken(): del 1正确返回null（语法失败），def healthy(): pass依然正常——取消只丢弃被取消解释器的状态，不毒化整个运行时。

8.2 取消一个请求不伤及并发无关请求

测试 cpython.test.ts 用两个并发请求验证：取消一个 10 万行的大解析，独立的def retained(): pass请求照常完成。实现位于 packages/core/src/python.ts 的stop(owner, error, cancellation)：当取消导致 worker 被杀时，对"未取消的其他 pending 请求"会用新的runPython重新入队执行（注释明确"Helpers have no side effects; unrelated requests can survive a cancelled interpreter"）。

8.3 空闲 worker 不得挂住 Node 进程

测试 cpython.test.ts 在子进程中运行runPython('inspect', ...)并等待退出码：由于 python.ts 在 pending 清空后调用owner.worker.unref()与channel?.unref?.()，且 python-worker.mjs 监听disconnect主动process.exit(0)，空闲解释器不会让 Node 进程残留为孤儿进程。

8.4 AbortError 语义

runPython通过signal?.throwIfAborted()前置检查 +signal.addEventListener("abort", abort)响应中止，取消时以DOMException("Python parsing cancelled", "AbortError")reject 调用方（python.ts），测试统一用assert.rejects(pending, { name: "AbortError" })断言。

九、健壮性边界：菱形继承、空套件与超限声明

9.1 菱形继承 MRO 不指数爆炸

测试 cpython.test.ts（超时 120 秒）构造了 24 层Left/Right/Join菱形继承链，验证calls辅助程序解析Leaf.target → self.helper()时能正确定位到最底层Root.helper（返回caller: Leaf.target, name: Root.helper），且不因重复解析同一 MRO 路径而指数级遍历。实现上 assets/python/calls.py 用带缓存的linearizations字典保存每个类的线性化结果，并对已见过的(owner, name, ancestor, target)组合去重（seen集合）。

9.2 空套件不崩溃

source.test.ts 用 700 行空行的def f():验证：pythonPreview返回parseUnavailable: true、matchedDeclarations: 0，inspect则安全降级为文本模式，而不是在node.body[0]上抛异常。

9.3 超大声明切片 + 保留 CR

cpython.test.ts 验证 25KB 的 CR-only 声明被切成多个 ≤24000 字节的单元后，sourceForUnit拼接结果与原始源码完全相等。

十、从解析器到检索链路：这些测试支撑了什么

Parser 测试并不是孤立的质量门禁，它直接支撑 jevgrep 的端到端检索链路（详见 packages/core/src/retrieve.ts 与 packages/core/src/preview.ts 的调用关系）：

1. inspect产出的SourceUnit（name/range/ownerHeaders/sourceByteStart/End）是所有"单元级检索"与上下文切片的原料；
2. neighborhood为正向选中的方法补充"类头 + 紧邻方法"（见测试 source.test.ts：只加类头与前后各一个小邻居，绝不把整个类拖进来）；
3. preview在预算内生成query-named declaration header / implementation / enclosing class context / distributed context等多基底的标注窗口（assets/python/preview.py），其"缺失词汇不构成不相关证据"的scope字段声明保证了检索的召回安全；
4. calls提供同文件继承方法调用线索（caller → callee 坐标），是 jevgrep 跨声明关联的重要依据。

因此，test/parser/cpython.test.ts 与 test/parser/source.test.ts 中每一条断言，都对应着检索链路里一个可被 Agent 依赖的坐标或字节级承诺：坐标不错、字节不丢、取消可恢复、回退不丢行。

十一、如何复现与继续深入

• 运行全部 parser 测试：bun run test:parser（Docker 隔离 + 打包 CLI 两段门禁）；
• 单独跑 Node 侧一致性测试：bash scripts/test-docker.sh node --experimental-strip-types --test test/parser/*.test.ts；
• 阅读实现：
  • 解析入口与切分算法：packages/core/src/source.ts
  • Python 运行时调度：packages/core/src/python.ts、packages/core/src/python-worker.mjs
  • 四个辅助程序：packages/core/assets/python/inspect.py、preview.py、neighborhood.py、calls.py
  • 仓库级验证记录：integration-verification.md

需要说明的适用前提：所有坐标基于 UTF-8 字节偏移的 LF 行模型，Python 侧以参考 CPython 3.11 AST 为准（超出即回退），TypeScript 侧依赖编译器 API 的parseDiagnostics；测试运行需要 Node 的--experimental-strip-types支持与 bun 脚本环境。理解这些边界后，你就能在 jevgrep 之上扩展自己的解析行为测试，或在集成检索链路时正确依赖inspect/preview/neighborhood/calls返回的坐标契约。