bb-parse-ast

name	bb-parse-ast
description	解析 SystemVerilog RTL 为 AST JSON，供 CDC 检查 / signal path tracing / module dep 分析。统一 3 个后端 (pyverilog / verible / slang)，auto 模式自动降级。触发场景：(1) bba-guru-synthesis CDC 前；(2) bb-trace-signal-path / bb-find-module-deps 之前；(3) 显式 /bb-parse-ast。
user-invocable	true
arguments	[{"name":"file_list","type":"path","required":true,"description":"file_list.f"},{"name":"design_name","type":"string","required":true},{"name":"backend","type":"enum<auto,pyverilog,verible,slang>","required":false,"default":"auto","description":"auto = pyverilog → verible → slang 自动降级"},{"name":"output_format","type":"enum<json,pickle>","required":false,"default":"json"},{"name":"stamp","type":"string","required":false,"description":"默认 <auto YYYYMMDD-HHMMSS>"}]

bb-parse-ast

解析 RTL 为 AST JSON。统一 3 个后端，对下游透明。

职责

• 调用者：bba-guru-synthesis、bb-check-cdc、bb-trace-signal-path、bb-find-module-deps
• 输出 schema 对所有 backend 一致（下游无需感知差异）
• 禁止使用：Task / Agent / Skill

Backend 选择

backend	触发条件	实现
auto	默认	按 pyverilog → verible → slang 顺序尝试
pyverilog	显式指定	纯 Python，覆盖 SystemVerilog 2012 子集
verible	显式指定或 pyverilog 失败	verible-verilog-syntax，覆盖 SV 2017
slang	显式指定或前两者都失败	slang，覆盖 SV 2017 + UVM

Input Args

arg	type	required	默认	说明
file_list	path	true	—	file_list.f
design_name	string	true	—	—
backend	enum	false	auto	auto|pyverilog|verible|slang
output_format	enum	false	json	json|pickle
stamp	string	false	<auto>	—

Output Contract

field	值
artifact_path	designs/<name>/ast/ast_<stamp>.json
script_path	designs/<name>/ast/parse_ast_<stamp>.{py|sh}
backend_used	pyverilog|verible|slang
valid	bool
error	string (e.g. UNSUPPORTED_SV_SYNTAX)

4-Phase 执行

Phase 1 — Render

• backend=pyverilog → scripts/render_parser_py.py
• backend=verible → scripts/render_fallback_sh.py（参数 --backend verible）
• backend=slang → scripts/render_fallback_sh.py（参数 --backend slang）
• backend=auto → 内部 try/except 链，先 pyverilog 再 verible 再 slang

Phase 2 — Run

timeout 600 uv run python <script_path> 或 bash <script_path>（verible/slang 是 shell）。

Phase 3 — Parse

• scripts/parse_ast_output.py（pyverilog 输出归一化）
• scripts/parse_fallback_output.py + scripts/normalize_{verible,slang}.py（verible/slang 输出归一化）

归一化输出 schema 对所有 backend 一致，下游可直接消费。

Phase 4 — Return

返回 JSON。error=UNSUPPORTED_SV_SYNTAX 仅在 backend=pyverilog 且 auto 模式禁用时返回。

资源索引

• scripts/render_parser_py.py — pyverilog 渲染
• scripts/parse_ast_output.py — pyverilog 输出归一化
• scripts/run_parser.py — pyverilog 驱动
• scripts/render_fallback_sh.py — verible/slang 渲染（shell wrapper）
• scripts/parse_fallback_output.py — verible/slang 输出归一化主入口
• scripts/normalize_verible.py / scripts/normalize_slang.py — 后端特定归一化
• references/fallback/*.md — verible / slang 后端文档
• Gotcha/ — pyverilog 已知陷阱