Skip to content

Eriemon/verilog-generator

readable-verilog-generator

Verified

Use when creating, writing, reviewing, annotating, repairing, refactoring, or validating readable Verilog RTL, including synthesizable Verilog-2001 .v files, existing-RTL analysis, semantic comment annotation, testbench scaffold planning, ASIC-quality review, local or remote Vivado/xsim validation, evidence-backed repair, and workflow trace diagnosis.

FileKindSize
SKILL.mdskill md21.3 KB
agents/openai.yamlconfig363 B
assets/examples/existing_rtl/fsm_without_default.vother761 B
assets/examples/existing_rtl/fsm_without_default_spec.mdmarkdown311 B
assets/examples/existing_rtl/leaf_counter.vother314 B
assets/examples/existing_rtl/missing_output_register.vother423 B
assets/examples/existing_rtl/missing_output_register_spec.mdmarkdown331 B
assets/examples/existing_rtl/ready_valid_slice.vother967 B
assets/examples/existing_rtl/ready_valid_slice_spec.mdmarkdown420 B
assets/examples/existing_rtl/reset_gap_counter.vother319 B
assets/examples/existing_rtl/reset_gap_counter_spec.mdmarkdown212 B
assets/examples/existing_rtl/tb_ready_valid_slice.vother846 B
assets/examples/existing_rtl/top_counter.vother271 B
assets/examples/existing_rtl/traffic_light.vother2.5 KB
assets/examples/existing_rtl/traffic_light_spec.mdmarkdown585 B
assets/examples/readme/axis_packet_meter.vother10.2 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/generated/rtl/comb_hierarchy_budget.vother1.9 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/generated/tb/tb_comb_hierarchy_budget.vother2.5 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_child_loop.vother447 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_over_budget.vother527 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_q_cut.vother467 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_within_budget.vother450 B
assets/examples/remote_fixtures/comb_hierarchy_budget/spec.jsonconfig1.7 KB
assets/examples/remote_fixtures/comb_operation_budget/comb_operation_budget_bad.vother187 B
assets/examples/remote_fixtures/comb_operation_budget/generated/rtl/comb_operation_budget.vother6.1 KB
assets/examples/remote_fixtures/comb_operation_budget/generated/tb/tb_comb_operation_budget.vother5.7 KB
assets/examples/remote_fixtures/comb_operation_budget/spec.jsonconfig2.9 KB
assets/examples/remote_fixtures/comb_parity_mux/generated/rtl/comb_parity_mux.vother2.1 KB
assets/examples/remote_fixtures/comb_parity_mux/generated/tb/tb_comb_parity_mux.vother2.8 KB
assets/examples/remote_fixtures/comb_parity_mux/spec.jsonconfig1.9 KB
assets/examples/remote_fixtures/pipeline_delay/generated/rtl/pipeline_delay.vother4.5 KB
assets/examples/remote_fixtures/pipeline_delay/generated/tb/tb_pipeline_delay.vother2.6 KB
assets/examples/remote_fixtures/pipeline_delay/spec.jsonconfig2.2 KB
assets/examples/remote_fixtures/ready_valid_slice/generated/rtl/ready_valid_slice.vother5.2 KB
assets/examples/remote_fixtures/ready_valid_slice/generated/tb/tb_ready_valid_slice.vother2.9 KB
assets/examples/remote_fixtures/ready_valid_slice/spec.jsonconfig2.6 KB
assets/examples/rtl_erie_verilog_spec.jsonconfig2.1 KB
assets/examples/use_case_templates/jesd_adc.jsonconfig2.4 KB
assets/examples/use_case_templates/jesd_dac.jsonconfig2.5 KB
assets/examples/use_case_templates/mxfe_mixed.jsonconfig2.7 KB
assets/examples/use_case_templates/spi_adc.jsonconfig2.8 KB
assets/examples/use_case_templates/spi_dac.jsonconfig2.7 KB
assets/examples/verilog_pattern_templates/axi4_lite_csr.jsonconfig2.1 KB
assets/examples/verilog_pattern_templates/axi_interconnect_dma.jsonconfig2.3 KB
assets/examples/verilog_pattern_templates/axis_ready_valid.jsonconfig2.3 KB
assets/examples/verilog_pattern_templates/conv_load_store.jsonconfig1.8 KB
assets/external_interface_catalog.jsonconfig2.9 KB
assets/ideal_bad_style_metrics.jsonconfig17.5 KB
assets/installer/manifest.projection.jsonconfig2.8 KB
assets/installer/platforms.jsonconfig1.3 KB
assets/interface_templates/ahb_lite_config.vincother2.3 KB
assets/interface_templates/apb_config.vincother861 B
assets/interface_templates/axi4_full_master.vincother1.8 KB
assets/interface_templates/axi4_full_slave.vincother1.8 KB
assets/interface_templates/axi4_lite_config.vincother1.6 KB
assets/interface_templates/axi_stream_duplex.vincother1.1 KB
assets/interface_templates/catalog.jsonconfig2.6 KB
assets/project_ip_interface_manifest.template.jsonconfig9.4 KB
assets/readme-workflow.pngbinary1.4 MB
assets/readme/design-profile-cn.pngbinary1.4 MB
assets/readme/design-profile.pngbinary1.4 MB
assets/readme/evidence-guard-cn.pngbinary1.4 MB
assets/readme/evidence-guard.pngbinary1.4 MB
assets/readme/hero-overview-cn.pngbinary1.5 MB
assets/readme/hero-overview.pngbinary1.5 MB
assets/readme/project-facts-cn.pngbinary1.2 MB
assets/readme/project-facts.pngbinary1.3 MB
assets/readme/rule-rendering-cn.pngbinary1.4 MB
assets/readme/rule-rendering.pngbinary1.2 MB
assets/style_templates/header_prompt_none_mode.txtmarkdown2.1 KB
assets/style_templates/header_prompt_table_mode.txtmarkdown2.5 KB
assets/style_templates/rtl_bus_grouping.tplother1.0 KB
assets/style_templates/rtl_fsm.tplother832 B
assets/style_templates/rtl_header_bilingual.tplother1.6 KB
assets/style_templates/rtl_instantiation.tplother496 B
assets/style_templates/rtl_region_order.tplother987 B
assets/use_case_templates/catalog.jsonconfig2.8 KB
assets/use_case_templates/jesd_adc/README.mdmarkdown699 B
assets/use_case_templates/jesd_adc/constraints/system_constr.xdcother454 B
assets/use_case_templates/jesd_adc/manifest.jsonconfig1.7 KB
assets/use_case_templates/jesd_adc/tcl/common_bd.tclother4.0 KB
assets/use_case_templates/jesd_adc/tcl/system_bd.tclother920 B
assets/use_case_templates/jesd_adc/tcl/system_project.tclother1.0 KB
assets/use_case_templates/jesd_adc/verilog/system_top.vother2.9 KB
assets/use_case_templates/jesd_dac/README.mdmarkdown745 B
assets/use_case_templates/jesd_dac/constraints/system_constr.xdcother299 B
assets/use_case_templates/jesd_dac/manifest.jsonconfig1.7 KB
assets/use_case_templates/jesd_dac/tcl/common_bd.tclother4.8 KB
assets/use_case_templates/jesd_dac/tcl/system_bd.tclother923 B
assets/use_case_templates/jesd_dac/tcl/system_project.tclother1.1 KB
assets/use_case_templates/jesd_dac/verilog/system_top.vother2.9 KB
assets/use_case_templates/mxfe_mixed/README.mdmarkdown739 B
assets/use_case_templates/mxfe_mixed/constraints/system_constr.xdcother380 B
assets/use_case_templates/mxfe_mixed/manifest.jsonconfig1.8 KB
assets/use_case_templates/mxfe_mixed/tcl/common_bd.tclother5.4 KB
assets/use_case_templates/mxfe_mixed/tcl/system_bd.tclother1.2 KB
assets/use_case_templates/mxfe_mixed/tcl/system_project.tclother1.2 KB
assets/use_case_templates/mxfe_mixed/verilog/system_top.vother3.4 KB
assets/use_case_templates/spi_adc/README.mdmarkdown925 B
assets/use_case_templates/spi_adc/constraints/system_constr.xdcother635 B
assets/use_case_templates/spi_adc/manifest.jsonconfig1.7 KB
assets/use_case_templates/spi_adc/tcl/common_bd.tclother6.3 KB
assets/use_case_templates/spi_adc/tcl/system_bd.tclother1.6 KB
assets/use_case_templates/spi_adc/tcl/system_project.tclother982 B
assets/use_case_templates/spi_adc/verilog/system_top.vother4.2 KB
assets/use_case_templates/spi_dac/README.mdmarkdown757 B
assets/use_case_templates/spi_dac/constraints/system_constr.xdcother546 B
assets/use_case_templates/spi_dac/manifest.jsonconfig1.6 KB
assets/use_case_templates/spi_dac/tcl/common_bd.tclother5.7 KB
assets/use_case_templates/spi_dac/tcl/system_bd.tclother1.0 KB
assets/use_case_templates/spi_dac/tcl/system_project.tclother981 B
assets/use_case_templates/spi_dac/verilog/system_top.vother3.5 KB
assets/verilog_formatter_config/defaults.jsonconfig6.2 KB
assets/verilog_formatter_config/profiles/conservative.jsonconfig283 B
assets/verilog_formatter_config/profiles/example_compat.jsonconfig484 B
assets/verilog_formatter_config/profiles/formatter-lint.jsonconfig121 B
assets/verilog_formatter_config/profiles/formatter-normalize.jsonconfig182 B
assets/verilog_formatter_config/profiles/formatter-preserve.jsonconfig385 B
assets/verilog_formatter_config/profiles/formatting.jsonconfig270 B
assets/verilog_formatter_config/profiles/lint.jsonconfig269 B
assets/verilog_formatter_config/profiles/migration.jsonconfig239 B
assets/verilog_formatter_config/profiles/stress_cases_compat.jsonconfig484 B
assets/verilog_formatter_config/profiles/vitis-wrapper.jsonconfig486 B
assets/verilog_formatter_config/schema.jsonconfig13.7 KB
assets/verilog_formatter_config/templates/task-batch.jsonconfig212 B
assets/verilog_formatter_config/templates/task-inplace.jsonconfig221 B
assets/verilog_formatter_config/templates/task-single-file.jsonconfig220 B
assets/verilog_pattern_templates/axi4_lite_csr_shell.vincother562 B
assets/verilog_pattern_templates/axi_interconnect_port_groups.vincother592 B
assets/verilog_pattern_templates/axis_ready_valid_slice.vincother494 B
assets/verilog_pattern_templates/catalog.jsonconfig2.2 KB
assets/verilog_pattern_templates/conv_load_store_pipeline.vincother457 B
assets/verilog_pattern_templates/counter_state_bridge.vincother443 B
assets/verilog_pattern_templates/equivalence_wrapper_probe.vincother306 B
assets/verilog_pattern_templates/fsm_state_transition.vincother1.0 KB
assets/verilog_pattern_templates/phase_output_registering.vincother404 B
assets/verilog_pattern_templates/wrapper_top_stitching.vincother608 B
assets/verilog_quality_gates.jsonconfig38.2 KB
assets/verilog_style_rules.jsonconfig11.8 KB
assets/xilinx_primitive_semantics.jsonconfig21.4 KB
references/checklists/capability-distillation-checklist.mdmarkdown3.0 KB
references/checklists/lint-checklist.mdmarkdown3.6 KB
references/checklists/verilog-readability-gate.mdmarkdown3.5 KB
references/corpus/verilog-style-observations.mdmarkdown4.6 KB
references/integration/configuration.mdmarkdown19.9 KB
references/integration/host-integration.mdmarkdown10.6 KB
references/rules/asic-verilog-quality.mdmarkdown3.9 KB
references/rules/erie-style.mdmarkdown6.3 KB
references/rules/testbench-patterns.mdmarkdown3.2 KB
references/rules/verilog-code-comment-naming-standard.mdmarkdown55.6 KB
references/rules/verilog-comment-placement.mdmarkdown8.4 KB
references/rules/verilog-pattern-templates.mdmarkdown1.1 KB
references/rules/verilog-quality-gates.mdmarkdown21.4 KB
references/rules/xilinx-primitive-exemptions.mdmarkdown10.6 KB
references/skill/installation.mdmarkdown6.1 KB
references/skill/script-guide.mdmarkdown7.5 KB
references/skill/skill-standards.mdmarkdown2.1 KB
references/workflows/verilog_dispatcher.mdmarkdown6.4 KB
references/workflows/workflow-contracts.mdmarkdown15.1 KB
scripts/__init__.pyscript53 B
scripts/python/__init__.pyscript55 B
scripts/python/corpus/analyze_verilog_style_corpus.pyscript25.3 KB
scripts/python/existing_rtl/existing_rtl.pyscript81.1 KB
scripts/python/existing_rtl/existing_rtl_improvement.pyscript109.9 KB
scripts/python/existing_rtl/intervention.pyscript8.3 KB
scripts/python/existing_rtl/optimizer.pyscript25.8 KB
scripts/python/existing_rtl/reflection.pyscript86.7 KB
scripts/python/existing_rtl/semantic_contract.pyscript45.6 KB
scripts/python/existing_rtl/verifier.pyscript15.3 KB
scripts/python/existing_rtl/verify_repair.pyscript4.6 KB
scripts/python/existing_rtl/verify_repair_core.pyscript45.7 KB
scripts/python/existing_rtl/verify_repair_patch_apply.pyscript23.5 KB
scripts/python/existing_rtl/verify_repair_patch_categories.pyscript35.5 KB
scripts/python/existing_rtl/verify_repair_patch_plan.pyscript25.1 KB
scripts/python/existing_rtl/verify_repair_patching.pyscript2.4 KB
scripts/python/existing_rtl/verify_repair_support.pyscript25.6 KB
scripts/python/existing_rtl/verify_repair_testbench.pyscript45.9 KB
scripts/python/existing_rtl/verify_reporting.pyscript16.1 KB
scripts/python/facade/__init__.pyscript45 B
scripts/python/facade/existing_rtl_api.pyscript14.0 KB
scripts/python/facade/quality_api.pyscript19.9 KB
scripts/python/facade/representative_cases.pyscript38.3 KB
scripts/python/facade/verilog_api.pyscript6.5 KB
scripts/python/facade/workflow_api.pyscript63.2 KB
scripts/python/generation/tb_generator.pyscript54.9 KB
scripts/python/header_contract.pyscript21.1 KB
scripts/python/installation/__init__.pyscript52 B
scripts/python/installation/bundle.pyscript16.3 KB
scripts/python/installation/catalog.pyscript16.6 KB
scripts/python/installation/cli.pyscript26.4 KB
scripts/python/installation/projection.pyscript14.2 KB
scripts/python/installation/receipt.pyscript13.4 KB
scripts/python/installation/transaction.pyscript29.0 KB
scripts/python/quality/clock_name_roles.pyscript1.0 KB
scripts/python/quality/comment_placement.pyscript49.5 KB
scripts/python/quality/declaration_region_policy.pyscript8.0 KB
scripts/python/quality/deliverable_gate.pyscript51.9 KB
scripts/python/quality/external_interface_stubs.pyscript41.5 KB
scripts/python/quality/formatter_ast.pyscript85.0 KB
scripts/python/quality/formatter_ast_instances.pyscript5.4 KB

scripts/python/quality/comment_placement.py

View on GitHub
"""校验生成 Verilog 中注释位置和注释语义是否满足 skill 约束。"""

# 延迟注解求值,避免运行期导入 Path 与 Any 时触发额外类型解析。
from __future__ import annotations

# 正则用于识别 Verilog 构造和低质量注释模板。
import re

# dataclass 用于携带单文件扫描共享上下文,避免 helper 参数过长。
from dataclasses import dataclass

# Path 负责递归扫描生成的 Verilog 文件。
from pathlib import Path

# Any 只用于 JSON 风格报告字典的值类型表达。
from typing import Any

# 低信息注释模板用于阻断占位式或套话式 Verilog 注释。
GENERIC_COMMENT_PATTERNS = (  # Verilog 注释负例正则集合
    re.compile(r"泛泛"),  # 中文泛化注释标记
    re.compile(r"逐行中文注释"),  # 批量注释占位话术
    re.compile(r"占位"),  # 未替换占位文本
    re.compile(r"\bplaceholder\b", re.IGNORECASE),  # 英文占位文本
    re.compile(r"这里处理逻辑"),  # 无构造语义的模板注释
    re.compile(r"模块结束\s*$"),  # 未命名关闭对象的 endmodule 注释
    re.compile(r"//"),  # 注释正文中残留注释符号
)

# 单文件扫描上下文集中携带发现项、统计和语言策略。
@dataclass
class CommentPlacementContext:
    """保存 comment placement 单文件扫描期间共享的报告容器。"""

    # list_issues 是跨文件共享的 COMMENT_PLACEMENT 发现项列表。
    list_issues: list[dict[str, Any]]  # 注释位置违规发现项

    # dict_metrics 是跨文件共享的扫描统计字典。
    dict_metrics: dict[str, Any]  # 注释位置扫描统计

    # str_rel_path 写入发现项 path 字段。
    str_rel_path: str  # 当前 Verilog 文件相对扫描根路径

    # str_comment_language 控制中文注释门槛。
    str_comment_language: str  # 本轮期望注释语言

# 单行扫描上下文集中保存分类和注释正文。
@dataclass
class VerilogLineContext:
    """保存当前 Verilog 行的解析信息和构造分类。"""

    # list_infos 允许 helper 查询相邻行和原始行号。
    list_infos: list[dict[str, Any]]  # 当前文件完整逐行记录

    # int_index 是当前行在 list_infos 中的位置。
    int_index: int  # 当前扫描行索引

    # dict_info 是当前行的代码/注释记录。
    dict_info: dict[str, Any]  # 当前 Verilog 行记录

    # str_construct 是当前行的原始构造分类。
    str_construct: str  # 当前行 Verilog 构造类型

    # str_counted_construct 是写入指标统计的折叠分类。
    str_counted_construct: str  # 指标统计使用的构造类型

    # code_text 是去掉注释后的当前行 Verilog 代码。
    code_text: str  # 当前行 Verilog 代码文本

    # comment_text 是当前行提取出的注释正文。
    comment_text: str  # 当前行 Verilog 注释正文

# 对外入口扫描 Verilog 文件并累计注释位置问题。
def validate_comment_placement(root: Path, comment_language: str) -> tuple[list[dict[str, Any]], dict[str, Any]]:
    """
    检查目录下 Verilog 文件的同/邻行注释约束。

    :param root: 需要递归扫描的生成 RTL 根目录。
    :param comment_language: 期望注释语言;`zh` 要求注释正文包含中文。
    :return: 发现项列表和扫描统计指标。
    """

    # list_issues 保存 COMMENT_PLACEMENT 错误,供静态 lint 汇总。
    list_issues: list[dict[str, Any]] = []  # lint 调用方接收的 COMMENT_PLACEMENT 错误列表

    # dict_metrics 记录扫描规模和按构造分类的违规数量。
    dict_metrics: dict[str, Any] = {  # 注释位置扫描统计容器
        "scanned_files": 0,  # 已扫描 Verilog 文件数量
        "code_lines": 0,  # 含 Verilog 代码的行数
        "same_line_comment_lines": 0,  # 满足同/邻行注释要求的行数
        "violations": 0,  # 注释位置违规总数
        "by_construct": {},  # 构造类型到 checked/violations 的映射
    }

    # 单文件入口需要把父目录作为相对路径根,避免 glob 扫描到零个文件。
    path_target = root.resolve()  # 当前注释门禁的规范路径

    # 按入口类型选择单文件或目录扫描路径。
    if path_target.is_file():

        # 非 Verilog 单文件保持空扫描语义,Verilog 文件只进入一次队列。
        list_sources = [path_target] if path_target.suffix.lower() == ".v" else []  # 单文件扫描列表

        # 单文件报告使用父目录作为稳定的相对路径根。
        path_scan_root = path_target.parent  # 单文件报告使用的相对路径根

    # 目录入口沿用递归扫描和稳定排序行为。
    else:

        # 递归获取目录下全部 Verilog 文件。
        list_sources = sorted(path_target.glob("**/*.v"))  # 目录下全部 Verilog 文件

        # 目录本身作为报告中的相对路径根。
        path_scan_root = path_target  # 目录报告使用的相对路径根

    # 按路径排序保证报告顺序稳定;单文件列表本身已满足该条件。
    for path_verilog in list_sources:

        # 单文件扫描会更新 list_issues 和 dict_metrics。
        _scan_verilog_file(
            path_verilog,
            path_scan_root,
            comment_language,
            list_issues,
            dict_metrics,
        )

    # 返回发现项和统计信息给静态 lint 调用方。
    return list_issues, dict_metrics

# 单文件扫描封装宏续行状态和逐行分类逻辑。
def _scan_verilog_file(
    path_verilog: Path,
    root: Path,
    comment_language: str,
    list_issues: list[dict[str, Any]],
    dict_metrics: dict[str, Any],
) -> None:
    """
    扫描单个 Verilog 文件并把违规写入共享报告。

    :param path_verilog: 当前正在检查的 `.v` 文件。
    :param root: 扫描根目录,用于生成相对路径。
    :param comment_language: 期望注释语言。
    :param list_issues: 跨文件累计的发现项列表。
    :param dict_metrics: 跨文件累计的统计字典。
    :return: 无业务返回值,直接更新 `list_issues` 和 `dict_metrics`。
    """

    # rel_path 写入 lint 发现项,保持历史 path:line 格式。
    rel_path = path_verilog.relative_to(root).as_posix()  # 当前文件相对扫描根的 POSIX 路径

    # context 聚合单文件扫描中反复传递的共享报告状态。
    context = CommentPlacementContext(list_issues, dict_metrics, rel_path, comment_language)  # 单文件扫描上下文

    # testbench 文件允许 task/function helper,其余 RTL 禁止。
    bool_is_testbench = _is_testbench(path_verilog)  # 当前文件是否按测试平台处理

    # line_infos 把 Verilog 代码和注释切分成统一记录。
    list_line_infos = _verilog_line_infos(  # 当前 Verilog 文件的逐行解析记录
        path_verilog.read_text(encoding="utf-8", errors="ignore").splitlines()  # 忽略非法编码后的源码行
    )  # 当前文件的逐行代码/注释信息

    # 记录本文件已进入扫描。
    dict_metrics["scanned_files"] += 1  # 扫描文件累计数量

    # 宏续行状态用于禁止续行尾部行内注释。
    bool_in_multiline_macro = False  # 是否位于反斜杠延续的 define 宏体中

    # 逐行检查 Verilog 构造和注释位置。
    for int_index, dict_info in enumerate(list_line_infos):

        # 空代码行只作为邻接注释上下文,不参与构造计数。
        if not dict_info["has_code"]:

            # 跳过纯注释或空白行。
            continue

        # verilog_line_context_current 聚合当前行后续 helper 需要的全部解析信息。
        verilog_line_context_current = _build_line_context(  # 当前行扫描上下文
            list_line_infos,  # 相邻行检查需要的整文件记录
            int_index,  # 当前行在整文件记录中的索引
            dict_info,  # 当前行代码和注释记录
            bool_is_testbench,  # 当前文件是否使用 testbench 规则
        )

        # 当前行进入代码行统计。
        dict_metrics["code_lines"] += 1  # Verilog 代码行累计数量

        # checked 记录该构造被检查过一次。
        _bump(dict_metrics, verilog_line_context_current.str_counted_construct, "checked")

        # 宏续行需要在普通构造规则前优先处理。
        tuple_macro_state = _handle_multiline_macro_line(  # 宏规则的新状态与处理标记
            verilog_line_context_current,  # 泛化和构造专属检查所需行上下文
            bool_in_multiline_macro,  # 进入当前行前的宏续行状态
            context,  # 写入发现项和统计的扫描上下文
        )

        # 保存宏规则返回的新续行状态。
        bool_in_multiline_macro = tuple_macro_state[0]  # 处理当前行后的宏续行状态

        # 当前行若已由宏规则处理,则跳过普通构造检查。
        bool_macro_line_handled = tuple_macro_state[1]  # 当前行是否属于多行宏规则范围

        # 宏续行处理函数返回 True 且本行属于宏体时,普通规则不再重复检查。
        if bool_macro_line_handled:

            # 续行宏规则已经完成本行诊断。
            continue

        # 不要求同/邻行注释的构造只检查已有注释的质量。
        if not _construct_requires_same_line_comment(
            verilog_line_context_current.str_construct,
            verilog_line_context_current.code_text,
        ):

            # 非强制注释构造仍可统计有效同/邻行注释。
            _handle_optional_comment_line(
                context,
                verilog_line_context_current.str_counted_construct,
                dict_info,
                verilog_line_context_current.str_construct,
                verilog_line_context_current.comment_text,
            )

            # 进入下一条 Verilog 代码行。
            continue

        # 强制注释构造需要先确认注释是否存在并满足语言要求。
        if _required_comment_is_available(
            verilog_line_context_current.list_infos,
            verilog_line_context_current.int_index,
            verilog_line_context_current.str_construct,
            verilog_line_context_current.comment_text,
            comment_language,
        ):

            # 当前构造已有合格注释证据。
            dict_metrics["same_line_comment_lines"] += 1  # 满足强制注释要求的行数

        # 同/邻行注释缺失时登记强制注释违规
        else:

            # 缺失注释时登记当前构造违规。
            _add_issue(
                context.list_issues,
                context.dict_metrics,
                verilog_line_context_current.str_counted_construct,
                "Verilog code line must use a same-line or adjacent explanatory comment in the requested language.",
                context.str_rel_path,
                int(dict_info["line_no"]),
            )

            # 缺注释后无需继续检查注释质量。
            continue

        # 注释存在后再检查泛化、end 命名、generate label 和 task/function 边界。
        _validate_construct_comment_quality(
            verilog_line_context_current,  # 构造质量检查需要的行上下文
            bool_is_testbench,  # 当前文件是否测试平台
            context,  # 发现项写入使用的扫描上下文
        )

# 单行上下文构造集中处理代码、注释和构造分类。
def _build_line_context(
    list_line_infos: list[dict[str, Any]],
    int_index: int,
    dict_info: dict[str, Any],
    bool_is_testbench: bool,
) -> VerilogLineContext:
    """
    根据当前行记录构造 VerilogLineContext。

    :param list_line_infos: 当前文件完整逐行记录。
    :param int_index: 当前行在逐行记录中的索引。
    :param dict_info: 当前行代码/注释记录。
    :param bool_is_testbench: 当前文件是否按 testbench 规则处理。
    :return: 带代码、注释和构造分类的行上下文。
    """

    # code_text 是去掉 Verilog 注释后的源码片段。
    code_text = str(dict_info["code"]).strip()  # 用于构造分类的代码片段

    # comment_text 是当前行 Verilog 注释正文。
    comment_text = str(dict_info["comment"]).strip()  # 用于语言和泛化检查的注释片段

    # str_construct 决定该行是否必须带同/邻行注释。
    str_construct = _classify_construct(code_text, bool_is_testbench)  # 注释策略分派构造类型

    # str_counted_construct 折叠 end 构造,保证指标分类稳定。
    str_counted_construct = _metric_construct(str_construct)  # 指标统计使用的构造分类

    # 返回当前行后续 helper 共享的解析上下文。
    return VerilogLineContext(
        # 当前文件和当前行定位。
        list_line_infos,
        int_index,
        dict_info,

        # 构造分类同时服务规则分派和统计桶。
        str_construct,
        str_counted_construct,

        # 代码片段和注释片段服务后续质量检查。
        code_text,
        comment_text,
    )

# 宏续行规则优先于普通同/邻行注释规则。
def _handle_multiline_macro_line(
    line_context: VerilogLineContext,
    in_multiline_macro: bool,
    context: CommentPlacementContext,
) -> tuple[bool, bool]:
    """
    处理反斜杠延续的多行 `define` 注释约束。

    :param line_context: 当前 Verilog 行的解析信息。
    :param in_multiline_macro: 进入本行前是否处于宏续行体。
    :param context: 单文件扫描共享上下文。
    :return: 处理当前行后的宏续行状态,以及当前行是否已由宏规则处理。
    """

    # 已在宏体中时,禁止续行尾部携带注释。
    if in_multiline_macro:

        # 宏体续行存在注释会影响宏文本拼接。
        if line_context.comment_text:

            # 续行注释违规写入 lint 发现项。
            _add_issue(
                context.list_issues,
                context.dict_metrics,
                line_context.str_counted_construct,
                (
                    "Multiline macro continuation must not carry an inline comment; "
                    "bind one pure comment before the macro."
                ),
                context.str_rel_path,
                int(line_context.dict_info["line_no"]),
            )

        # 反斜杠消失代表宏续行结束。
        if not line_context.code_text.endswith("\\"):

            # 当前行关闭多行宏状态。
            return False, True

        # 仍在宏体中,下一行继续走宏续行规则。
        return True, True

    # 新的多行 define 需要纯前导注释说明宏用途。
    if line_context.code_text.startswith("`define") and line_context.code_text.endswith("\\"):

        # `define 起始行自身不能携带行内注释。
        if line_context.comment_text:

            # 起始行注释违规会破坏宏延续可读性。
            _add_issue(
                context.list_issues,
                context.dict_metrics,
                line_context.str_counted_construct,
                "Multiline macro `define line must use a pure leading comment, not an inline continuation comment.",
                context.str_rel_path,
                int(line_context.dict_info["line_no"]),
            )

        # 多行宏必须由前一行纯注释描述宏语义。
        if not _valid_leading_comment(
            line_context.list_infos,
            line_context.int_index,
            context.str_comment_language,
            keyword="宏",
        ):

            # 缺少前导说明时登记宏级违规。
            _add_issue(
                context.list_issues,
                context.dict_metrics,
                line_context.str_counted_construct,
                "Multiline macro must have a pure explanatory comment immediately before the `define line.",
                context.str_rel_path,
                int(line_context.dict_info["line_no"]),
            )

        # 后续行进入宏续行规则。
        return True, True

    # 普通行不改变宏续行状态。
    return False, False

# 非强制注释构造只在注释存在时检查质量。
def _handle_optional_comment_line(
    context: CommentPlacementContext,
    str_counted_construct: str,
    info: dict[str, Any],
    str_construct: str,
    comment: str,
) -> None:
    """
    处理 module/end/case 等非强制同/邻行注释构造。

    :param context: 单文件扫描共享上下文。
    :param str_counted_construct: 指标统计使用的构造分类。
    :param info: 当前行代码/注释记录。
    :param str_construct: 当前行 Verilog 构造分类。
    :param comment: 当前行注释正文。
    :return: 无业务返回值,直接更新报告容器。
    """

    # 没有合格注释时,非强制构造不登记违规。
    if not comment or not _comment_satisfies_language(comment, context.str_comment_language):

        # 可选注释缺失不影响当前构造。
        return

    # 当前行已有可统计的同/邻行注释。
    context.dict_metrics["same_line_comment_lines"] += 1  # 可选构造上的有效注释行数

    # end 类构造存在注释时必须说明关闭对象。
    if str_construct in {"module_end", "task_end", "function_end", "generate_end"} and not _valid_end_comment(comment):

        # end 注释格式不合格时登记违规。
        _add_issue(
            context.list_issues,
            context.dict_metrics,
            str_counted_construct,
            "End construct comment must name the construct being closed and start with an end/结束 phrase.",
            context.str_rel_path,
            int(info["line_no"]),
        )

# 强制注释构造允许 always 使用邻接纯注释。
def _required_comment_is_available(
    infos: list[dict[str, Any]],
    index: int,
    str_construct: str,
    comment: str,
    comment_language: str,
) -> bool:
    """
    判断强制注释构造是否已经具备合格说明。

    :param infos: 当前文件的逐行代码/注释记录。
    :param index: 当前行在 `infos` 中的位置。
    :param str_construct: 当前行 Verilog 构造分类。
    :param comment: 当前行注释正文。
    :param comment_language: 期望注释语言。
    :return: True 表示同/邻行注释满足语言要求。
    """

    # 同行注释满足语言要求时直接通过。
    if _comment_satisfies_language(comment, comment_language):

        # 同行注释是首选证据。
        return True

    # always 与 generate 都允许使用 formatter 保留的相邻纯注释说明块目的。
    if str_construct in {"always", "generate"} and _valid_adjacent_comment(infos, index, comment_language):

        # 邻接纯注释可替代块关键字行内注释。
        return True

    # 其他强制注释构造必须在同一行给出说明。
    return False

# 同/邻行注释存在后继续检查构造专属质量。
def _validate_construct_comment_quality(
    line_context: VerilogLineContext,
    is_testbench: bool,
    context: CommentPlacementContext,
) -> None:
    """
    检查泛化注释、结束注释、generate 标签和 task/function 约束。

    :param line_context: 当前 Verilog 行的解析信息。
    :param is_testbench: 当前文件是否为测试平台。
    :param context: 单文件扫描共享上下文。
    :return: 无业务返回值,直接更新报告容器。
    """

    # counted_construct 统一折叠 end/task/function 构造到指标分类。
    str_counted_construct = line_context.str_counted_construct  # 当前违规写入的统计分类

    # 泛化注释无法证明生成器理解了当前 Verilog 构造。
    if _comment_is_generic(line_context.comment_text):

        # 泛化注释登记为当前构造违规。
        _add_issue(
            context.list_issues,
            context.dict_metrics,
            str_counted_construct,
            (
                "Generic Verilog comment is not allowed; describe the construct, "
                "signal, condition, or verification purpose."
            ),
            context.str_rel_path,
            int(line_context.dict_info["line_no"]),
        )

    # end 类构造的注释必须说明关闭对象。
    if (
        line_context.str_construct in {"module_end", "task_end", "function_end", "generate_end"}
        and not _valid_end_comment(line_context.comment_text)
    ):

        # end 注释缺少结束短语时登记违规。
        _add_issue(
            context.list_issues,
            context.dict_metrics,
            str_counted_construct,
            "End construct comment must name the construct being closed and start with an end/结束 phrase.",
            context.str_rel_path,
            int(line_context.dict_info["line_no"]),
        )

    # module 声明注释必须说明模块或测试平台用途。
    if line_context.str_construct == "module" and not _module_comment_valid(line_context.comment_text):

        # module 注释缺少模块语义时登记违规。
        _add_issue(
            context.list_issues,
            context.dict_metrics,
            str_counted_construct,
            "Module declaration comment must identify the module or testbench purpose.",
            context.str_rel_path,
            int(line_context.dict_info["line_no"]),
        )

    # 命名 generate 分支必须使用 gen_ 前缀。
    bool_generate_label_missing_prefix = (  # generate 具名分支是否缺少前缀
        line_context.str_construct == "generate"  # 当前行已经被分类为 generate
        and "begin:" in line_context.code_text  # 只有具名 begin 分支需要标签规则
        and "gen_" not in line_context.code_text  # 标签中未出现 gen_ 前缀
    )  # generate 具名分支缺少 gen_ 前缀

    # 命名 generate 分支缺少 gen_ 前缀时登记违规。
    if bool_generate_label_missing_prefix:

        # generate 标签缺少 gen_ 前缀时登记违规。
        _add_issue(
            context.list_issues,
            context.dict_metrics,
            str_counted_construct,
            "Generate branch labels must begin with `gen_` and the same line must explain the branch.",
            context.str_rel_path,
            int(line_context.dict_info["line_no"]),
        )

    # task/function 只能出现在测试平台并带前导说明。
    if line_context.str_construct in {"task", "function"}:

        # task/function 的文件边界和前导注释由专用 helper 检查。
        _validate_task_or_function_comment(
            line_context.list_infos,
            line_context.int_index,
            is_testbench,
            context,
            str_counted_construct,
            line_context.str_construct,
        )

# 测试平台 task/function 需要纯前导注释,RTL 中则禁止。
def _validate_task_or_function_comment(
    infos: list[dict[str, Any]],
    index: int,
    is_testbench: bool,
    context: CommentPlacementContext,
    str_counted_construct: str,
    str_construct: str,
) -> None:
    """
    检查 task/function 是否只在 testbench 中以说明注释出现。

    :param infos: 当前文件的逐行代码/注释记录。
    :param index: 当前行在 `infos` 中的位置。
    :param is_testbench: 当前文件是否为测试平台。
    :param context: 单文件扫描共享上下文。
    :param str_counted_construct: 指标统计使用的构造分类。
    :param str_construct: 当前行 Verilog 构造分类。
    :return: 无业务返回值,直接更新报告容器。
    """

    # 非 testbench RTL 禁止 task/function helper。
    if not is_testbench:

        # RTL 中出现 task/function 时直接登记违规。
        _add_issue(
            context.list_issues,
            context.dict_metrics,
            str_counted_construct,
            "RTL task/function blocks are not allowed; only testbenches may use documented helpers.",
            context.str_rel_path,
            int(infos[index]["line_no"]),
        )

        # RTL 禁止路径不再检查前导注释。
        return

    # task/function 在 testbench 中必须有对应中文前导说明。
    str_keyword = "任务" if str_construct == "task" else "函数"  # 前导注释必须包含的中文关键词

    # 测试平台 helper 缺少前导说明时登记违规。
    if not _valid_leading_comment(infos, index, context.str_comment_language, keyword=str_keyword):

        # 前导注释缺失会降低 testbench helper 可读性。
        _add_issue(
            context.list_issues,
            context.dict_metrics,
            str_counted_construct,
            "Testbench task/function declarations must have a pure leading purpose comment.",
            context.str_rel_path,
            int(infos[index]["line_no"]),
        )

# 统一登记 COMMENT_PLACEMENT 发现项并同步统计。
def _add_issue(
    list_issues: list[dict[str, Any]],
    dict_metrics: dict[str, Any],
    str_construct: str,
    message: str,
    rel: str,
    line_no: int,
) -> None:
    """
    把单条注释位置违规写入发现项列表。

    :param list_issues: 共享发现项列表。
    :param dict_metrics: 共享统计字典。
    :param str_construct: 指标统计使用的构造分类。
    :param message: 面向调用者的英文违规说明。
    :param rel: 当前文件相对扫描根的路径。
    :param line_no: 当前 Verilog 文件中的 1 基行号。
    :return: 无业务返回值,直接更新 `list_issues` 和 `dict_metrics`。
    """

    # dict_issue 保持 static_lint 已消费的字段形状。
    dict_issue = {  # COMMENT_PLACEMENT 单条错误发现项
        "severity": "error",  # 注释位置问题均按 error 输出
        "message": message,  # 英文诊断说明
        "path": f"{rel}:{line_no}",  # 相对路径和 Verilog 行号
        "stage": "static",  # 发现项来自静态 lint 阶段
        "source": "current_module_issue",  # 与其他当前模块 lint 来源保持一致
        "detail": f"COMMENT_PLACEMENT construct={str_construct} line={line_no}",  # 机器可读细节
    }

    # 追加发现项到共享列表。
    list_issues.append(dict_issue)

    # 顶层违规数同步递增。
    dict_metrics["violations"] += 1  # 全部构造违规总量

    # 构造级违规数同步递增。
    _bump(dict_metrics, str_construct, "violations")

# 构造级 checked/violations 计数器递增。
def _bump(dict_metrics: dict[str, Any], str_construct: str, key: str) -> None:
    """
    更新单个 Verilog 构造分类的统计桶。

    :param dict_metrics: 共享统计字典。
    :param str_construct: 指标统计使用的构造分类。
    :param key: 需要递增的桶内字段,通常是 `checked` 或 `violations`。
    :return: 无业务返回值,直接更新 `dict_metrics`。
    """

    # by_construct 是构造名到计数桶的映射。
    dict_by_construct = dict_metrics.setdefault("by_construct", {})  # 构造维度统计映射

    # 新构造首次出现时建立 checked/violations 双计数。
    dict_bucket = dict_by_construct.setdefault(str_construct, {"checked": 0, "violations": 0})  # 当前构造计数桶

    # 指定计数字段递增一次。
    dict_bucket[key] = int(dict_bucket.get(key, 0)) + 1  # 当前构造指定计数值

# Verilog 单行代码分类,控制后续注释策略。
def _classify_construct(code: str, is_tb: bool) -> str:
    """
    根据一行 Verilog 代码推断构造类型。

    :param code: 已移除注释的 Verilog 代码文本。
    :param is_tb: 当前文件是否为测试平台;保留参数以兼容旧签名。
    :return: 构造分类名称。
    """

    # is_tb 当前不参与分类,保留以避免调用方签名漂移。
    del is_tb

    # stripped 是分类正则使用的规范化代码文本。
    stripped = code.strip()  # 去除首尾空白后的 Verilog 代码

    # end_result 优先识别各类结束构造。
    str_end_result = _classify_end_construct(stripped)  # 结束关键字对应的关闭构造分类

    # 命中结束构造时直接返回。
    if str_end_result:

        # 返回结束构造分类。
        return str_end_result

    # declaration_result 覆盖 module、宏、端口、参数和信号声明。
    str_declaration_result = _classify_declaration_construct(stripped)  # 声明类 Verilog 构造分类

    # 命中声明构造时直接返回。
    if str_declaration_result:

        # 返回声明构造分类。
        return str_declaration_result

    # 过程块分类覆盖 task/function/generate/always/case 的首次命中。
    str_behavior_result = _classify_behavior_construct(stripped)  # 过程块或测试平台 helper 分类

    # 命中行为构造时直接返回。
    if str_behavior_result:

        # 返回行为构造分类。
        return str_behavior_result

    # branch_or_instance_result 覆盖条件分支和模块实例化。
    str_branch_or_instance_result = _classify_branch_or_instance(stripped)  # 分支或实例化分类

    # 命中分支或实例化时直接返回。
    if str_branch_or_instance_result:

        # 返回分支或实例化分类。
        return str_branch_or_instance_result

    # 未命中特定模式时按普通语句处理。
    return "statement"

# end 类 Verilog 构造优先识别,避免被普通语句吞掉。
def _classify_end_construct(stripped: str) -> str | None:
    """
    识别 endmodule、endtask、endfunction 和 endgenerate。

    :param stripped: 去除首尾空白后的 Verilog 代码。
    :return: 对应结束构造分类;无法识别时返回 None。
    """

    # endmodule 独立归入 module_end,便于注释关闭语义检查。
    if stripped.startswith("endmodule"):

        # 返回模块结束构造。
        return "module_end"

    # endtask 归入测试平台任务结束。
    if stripped.startswith("endtask"):

        # 返回任务关闭构造。
        return "task_end"

    # endfunction 归入测试平台函数结束。
    if stripped.startswith("endfunction"):

        # 返回函数关闭构造。
        return "function_end"

    # endgenerate 参与 generate 注释统计。
    if stripped.startswith("endgenerate"):

        # 返回生成块关闭构造。
        return "generate_end"

    # 当前行不是结束构造。
    return None

# 声明类 Verilog 构造需要检查同一行用途注释。
def _classify_declaration_construct(stripped: str) -> str | None:
    """
    识别 module、宏、预处理指令、参数、端口、信号和 assign。

    :param stripped: 去除首尾空白后的 Verilog 代码。
    :return: 声明类构造分类;无法识别时返回 None。
    """

    # module 声明行需要验证模块用途注释。
    if re.match(r"^module\b", stripped):

        # 返回模块声明构造。
        return "module"

    # `define 宏行需要专门处理多行延续。
    if stripped.startswith("`define"):

        # 返回宏定义构造。
        return "macro"

    # 其他反引号行按预处理指令处理。
    if stripped.startswith("`"):

        # 返回预处理指令构造。
        return "directive"

    # 参数声明必须携带同一行语义注释。
    if re.match(r"^(parameter|localparam)\b", stripped):

        # 返回参数声明构造。
        return "parameter"

    # 端口声明需要解释信号方向和用途。
    if re.match(r"^(input|output|inout)\b", stripped):

        # 返回端口声明构造。
        return "port"

    # 常见信号声明需要解释寄存器、连线或循环变量用途。
    if re.match(r"^(reg|wire|tri1|integer|genvar)\b", stripped):

        # 返回信号声明构造。
        return "signal"

    # assign 连续赋值需要说明组合逻辑含义。
    if re.match(r"^assign\b", stripped):

        # 返回连续赋值构造。
        return "assign"

    # 当前行不是声明类构造。
    return None

# 行为块和过程块分类覆盖 task/function/generate/always/case。
def _classify_behavior_construct(stripped: str) -> str | None:
    """
    识别 task、function、generate、always/initial 和 case。

    :param stripped: 去除首尾空白后的 Verilog 代码。
    :return: 行为类构造分类;无法识别时返回 None。
    """

    # task 声明只允许出现在测试平台。
    if re.match(r"^(task)\b", stripped):

        # 返回任务 helper 构造。
        return "task"

    # function 声明在 RTL 中禁用,测试平台路径另行检查。
    if re.match(r"^(function)\b", stripped):

        # 返回函数 helper 构造。
        return "function"

    # generate 或具名 gen_ begin 分支按 generate 处理。
    if stripped.startswith("generate") or ("begin:" in stripped and "gen_" in stripped):

        # 返回生成块构造。
        return "generate"

    # always/initial 过程块允许相邻纯注释。
    if re.match(r"^(always|initial)\b", stripped):

        # 返回过程块构造。
        return "always"

    # case/endcase 分支语义通常由内部 item 注释承载。
    if re.match(r"^(case|endcase)\b", stripped):

        # 返回选择分支构造。
        return "case"

    # 当前行不是行为块构造。
    return None

# 条件分支和模块实例化是分类链最后一层。
def _classify_branch_or_instance(stripped: str) -> str | None:
    """
    识别条件分支、case item 和模块实例化。

    :param stripped: 去除首尾空白后的 Verilog 代码。
    :return: `branch`、`instance` 或 None。
    """

    # 条件分支和全大写 case item 视为 branch。
    if re.match(r"^(if|else|default)\b", stripped) or re.match(r"^[A-Z][A-Z0-9_]*\s*:", stripped):

        # 返回条件或 case item 分支构造。
        return "branch"

    # 模块实例化需要解释连接对象或功能。
    if _looks_like_instance(stripped):

        # 返回模块实例化构造。
        return "instance"

    # 当前行既不是分支也不是实例化。
    return None

# 指定构造是否强制要求同/邻行注释。
def _construct_requires_same_line_comment(str_construct: str, code: str) -> bool:
    """
    判断 Verilog 构造是否必须携带解释性注释。

    :param str_construct: 当前行 Verilog 构造分类。
    :param code: 当前行 Verilog 代码文本。
    :return: True 表示该构造需要同/邻行注释。
    """

    # stripped 用于识别纯结构符号行。
    stripped = code.strip()  # 去空白后的 Verilog 代码

    # 这些构造必须在生成代码中解释具体作用。
    if str_construct in {"parameter", "port", "signal", "assign", "instance", "task", "function", "generate"}:

        # 声明、赋值、实例和 helper 声明均需要解释。
        return True

    # always/initial 可用同一行或邻接纯注释解释。
    if str_construct == "always":

        # 过程块需要说明触发条件或行为目的。
        return True

    # 模块、指令、分支和普通语句默认不强制同一行说明。
    if str_construct in {"directive", "module", "module_end", "case", "branch", "statement"}:

        # 可选注释构造不强制报缺失。
        return False

    # 纯括号和 begin/end 行不承载独立语义。
    if stripped in {"#(", "(", ")", ");", "begin", "end"}:

        # 结构符号行不要求独立注释。
        return False

    # 其他未知构造保持宽松,避免误伤合法 Verilog。
    return False

# always/initial 行可以使用相邻纯注释说明块目的。
def _valid_adjacent_comment(infos: list[dict[str, Any]], index: int, comment_language: str) -> bool:
    """
    判断当前行上下相邻行是否存在合格纯注释。

    :param infos: 当前文件的逐行代码/注释记录。
    :param index: 当前行在 `infos` 中的位置。
    :param comment_language: 期望注释语言。
    :return: True 表示邻接纯注释满足语言和非泛化要求。
    """

    # 只检查前一行和后一行,保持旧规则的局部邻接边界。
    for int_neighbor in (index - 1, index + 1):

        # 邻接索引必须落在文件范围内。
        if 0 <= int_neighbor < len(infos):

            # 邻接行记录提供 pure_comment 和 comment 字段。
            dict_info = infos[int_neighbor]  # 相邻行代码/注释记录

            # comment_text 是相邻纯注释正文。
            comment_text = str(dict_info.get("comment") or "").strip()  # 相邻行注释正文

            # 纯注释、语言匹配且非泛化时可作为 always 说明。
            if (
                dict_info.get("pure_comment")
                and _comment_satisfies_language(comment_text, comment_language)
                and not _comment_is_generic(comment_text)
            ):

                # 找到有效邻接注释。
                return True

    # 两侧都没有合格纯注释。
    return False

# 指标分类折叠 end 构造。
def _metric_construct(str_construct: str) -> str:
    """
    把具体构造映射到统计报告使用的聚合分类。

    :param str_construct: 当前行 Verilog 构造分类。
    :return: 指标报告中的构造分类。
    """

    # module_end 统计到 module,避免单独产生结束分类。
    if str_construct in {"module_end"}:

        # 返回模块聚合分类。
        return "module"

    # task/function 的开始和结束都归入 testbench_task。
    if str_construct in {"task", "task_end", "function", "function_end"}:

        # 返回测试平台 helper 聚合分类。
        return "testbench_task"

    # generate_end 统计到 generate。
    if str_construct in {"generate_end"}:

        # 返回 generate 聚合分类。
        return "generate"

    # 其他构造保持原分类。
    return str_construct

# 简单实例化识别用于要求实例行解释。
def _looks_like_instance(code: str) -> bool:
    """
    粗略判断 Verilog 代码行是否像模块实例化。

    :param code: 去空白后的 Verilog 代码。
    :return: True 表示该行符合常见实例化形态。
    """

    # 控制语句和 assign/always 等关键字不能误判为实例。
    if re.match(r"^(if|for|case|assign|always|initial|else|begin|end)\b", code):

        # 关键字行不是模块实例化。
        return False

    # 普通实例和参数化实例两类形态都需要识别。
    return bool(
        re.match(r"^[A-Za-z_][A-Za-z0-9_]*\s+[A-Za-z_][A-Za-z0-9_]*\s*\(", code)
        or re.match(r"^[A-Za-z_][A-Za-z0-9_]*\s*#\s*\(", code)
    )

# 前导纯注释用于说明多行宏和 testbench helper。
def _valid_leading_comment(infos: list[dict[str, Any]], index: int, comment_language: str, *, keyword: str) -> bool:
    """
    检查当前行上一行是否为合格前导纯注释。

    :param infos: 当前文件的逐行代码/注释记录。
    :param index: 当前行在 `infos` 中的位置。
    :param comment_language: 期望注释语言。
    :param keyword: 中文场景下要求出现的关键词。
    :return: True 表示上一行纯注释可解释当前构造。
    """

    # previous 指向当前行的上一行。
    int_previous = index - 1  # 前导注释候选行索引

    # 文件第一行没有前导注释。
    if int_previous < 0:

        # 不存在前导行。
        return False

    # info 保存前导行代码/注释记录。
    dict_info = infos[int_previous]  # 前导行记录

    # comment_text 是前导行注释正文。
    comment_text = str(dict_info["comment"]).strip()  # 前导注释正文

    # 前导行必须是纯注释且满足语言要求。
    if not dict_info["pure_comment"] or not _comment_satisfies_language(comment_text, comment_language):

        # 非纯注释不能解释下方构造。
        return False

    # 泛化前导注释不能作为合格说明。
    if _comment_is_generic(comment_text):

        # 占位或模板注释无效。
        return False

    # 中文模式要求注释显式提到目标构造关键词。
    return keyword in comment_text or comment_language != "zh"

# module 声明注释必须说明模块或 testbench 角色。
def _module_comment_valid(comment: str) -> bool:
    """
    判断 module 声明注释是否包含模块角色词。

    :param comment: module 声明行的注释正文。
    :return: True 表示注释点明模块或测试平台用途。
    """

    # module/testbench 关键词覆盖中英文注释。
    return any(str_token in comment for str_token in ("模块", "测试平台", "module", "testbench"))

# end 类构造注释必须以结束短语开头。
def _valid_end_comment(comment: str) -> bool:
    """
    判断 endmodule/endtask 等注释是否说明关闭语义。

    :param comment: end 构造行的注释正文。
    :return: True 表示注释以结束短语开头。
    """

    # stripped 是去空白后的注释正文。
    stripped = comment.strip()  # end 构造注释正文

    # 中英文结束短语均保持兼容。
    return stripped.startswith("结束") or stripped.lower().startswith(("end ", "end:"))

# 泛化注释识别使用固定负例正则。
def _comment_is_generic(comment: str) -> bool:
    """
    判断 Verilog 注释是否命中低信息模板。

    :param comment: 需要检查的 Verilog 注释正文。
    :return: True 表示注释属于占位或泛化文本。
    """

    # stripped 用于正则匹配前清理首尾空白。
    stripped = comment.strip()  # 待匹配的注释正文

    # 任一负例正则命中即判定为泛化注释。
    return any(pattern.search(stripped) for pattern in GENERIC_COMMENT_PATTERNS)

# 注释语言检查保持 zh 模式下至少包含一个中文字符。
def _comment_satisfies_language(comment: str, comment_language: str) -> bool:
    """
    判断注释正文是否满足请求语言。

    :param comment: 需要检查的 Verilog 注释正文。
    :param comment_language: 期望注释语言。
    :return: True 表示注释满足语言要求。
    """

    # normalized 去除首尾空白,避免空注释误判。
    normalized = comment.strip()  # 语言检查使用的注释正文

    # 空注释不满足任何语言要求。
    if not normalized:

        # 缺少注释正文。
        return False

    # 中文模式要求至少一个中日韩统一表意字符。
    if comment_language == "zh":

        # 任一中文字符即可满足语言门槛。
        return any("\u4e00" <= char <= "\u9fff" for char in normalized)

    # 非中文模式不限制具体字符集。
    return True

# Verilog 行切分入口保留 block comment 状态。
def _verilog_line_infos(lines: list[str]) -> list[dict[str, Any]]:
    """
    把 Verilog 源码行切分为代码、注释和纯注释标记。

    :param lines: 原始 Verilog 文件行。
    :return: 每行的 line_no/code/comment/pure_comment 记录。
    """

    # infos 按原始行号顺序保存切分结果。
    list_infos: list[dict[str, Any]] = []  # Verilog 逐行解析记录

    # block comment 状态会跨行延续。
    bool_in_block_comment = False  # 当前是否位于 /* */ 注释块内部

    # 逐行拆分代码与注释片段。
    for int_line_no, line_text in enumerate(lines, start=1):

        # split helper 返回当前行代码、注释和新的 block 状态。
        tuple_split_result = _split_verilog_code_and_comment(  # 单行 Verilog 切分三元组
            line_text,  # 原始 Verilog 行文本
            bool_in_block_comment,  # 进入当前行前的块注释状态
        )

        # code_text 保留当前行未被注释覆盖的 Verilog 片段。
        code_text = tuple_split_result[0]  # 当前行代码片段

        # comment_text 聚合当前行 // 或 /* */ 注释正文。
        comment_text = tuple_split_result[1]  # 当前行注释片段

        # bool_in_block_comment 更新跨行块注释状态。
        bool_in_block_comment = tuple_split_result[2]  # 离开当前行后的块注释状态

        # has_code 标记当前行是否仍含 Verilog 代码。
        bool_has_code = bool(code_text.strip())  # 当前行是否包含代码

        # has_comment 标记当前行是否含注释正文。
        bool_has_comment = bool(comment_text.strip())  # 当前行是否包含注释

        # 当前行记录保持旧字段名称。
        dict_info = {  # 单行 Verilog 代码/注释记录
            "line_no": int_line_no,  # 原始 Verilog 行号
            "code": code_text,  # 去除注释后的代码片段
            "has_code": bool_has_code,  # 当前行是否有代码
            "comment": comment_text.strip(),  # 行内或块注释的规范化正文
            "pure_comment": bool_has_comment and not bool_has_code,  # 当前行是否为纯注释
        }

        # 追加当前行解析记录。
        list_infos.append(dict_info)

    # 返回完整逐行记录。
    return list_infos

# 单行 Verilog 代码与注释切分,支持 // 和 /* */。
def _split_verilog_code_and_comment(line: str, bool_in_block_comment: bool) -> tuple[str, str, bool]:
    """
    切分一行 Verilog 的代码片段和注释片段。

    :param line: 原始 Verilog 源码行。
    :param bool_in_block_comment: 进入本行前是否处于块注释内部。
    :return: 代码文本、注释文本和离开本行后的块注释状态。
    """

    # code_parts 保留未被注释覆盖的字符。
    list_code_parts: list[str] = []  # 当前行代码字符片段

    # comment_parts 聚合行注释和块注释正文。
    list_comment_parts: list[str] = []  # 当前行注释正文片段

    # index 按字符推进,保留旧 parser 的简单状态机行为。
    int_index = 0  # 当前扫描字符位置

    # 持续扫描直到行尾或遇到 // 行注释。
    while int_index < len(line):

        # 已在块注释内部时只寻找结束符。
        if bool_in_block_comment:

            # end_index 定位当前行中的块注释结束符。
            int_end_index = line.find("*/", int_index)  # 块注释结束符位置

            # 当前行没有结束符时,整段剩余文本都是注释。
            if int_end_index == -1:

                # 收集跨行块注释正文。
                list_comment_parts.append(line[int_index:])

                # 返回仍在块注释中的状态。
                return "".join(list_code_parts), " ".join(list_comment_parts), True

            # 收集结束符之前的块注释正文。
            list_comment_parts.append(line[int_index:int_end_index])

            # 同行块注释结束后恢复代码扫描。
            int_index = int_end_index + 2  # 块注释结束后的扫描位置

            # 当前行已离开块注释。
            bool_in_block_comment = False  # 当前行块注释已经闭合

            # 继续扫描同一行的剩余字符。
            continue

        # 双斜线开启行注释,后续字符全部归入注释。
        if line.startswith("//", int_index):

            # 收集 // 后的注释正文。
            list_comment_parts.append(line[int_index + 2 :])

            # 行注释终止本行扫描。
            break

        # 斜星开启块注释,可能在同一行结束。
        if line.startswith("/*", int_index):

            # end_index 定位同一行内的块注释结束符。
            int_end_index = line.find("*/", int_index + 2)  # 同行块注释结束位置

            # 未找到结束符时进入跨行块注释。
            if int_end_index == -1:

                # 收集块注释起始后的剩余正文。
                list_comment_parts.append(line[int_index + 2 :])

                # 返回进入块注释的状态。
                return "".join(list_code_parts), " ".join(list_comment_parts), True

            # 同行块注释只收集中间正文。
            list_comment_parts.append(line[int_index + 2 : int_end_index])

            # 跳过 */ 后继续扫描后续代码。
            int_index = int_end_index + 2  # 同行块注释后的扫描位置

            # 继续扫描同一行后续字符。
            continue

        # 普通字符属于代码片段。
        list_code_parts.append(line[int_index])

        # 前进到下一个字符。
        int_index += 1  # 下一个字符索引

    # 返回当前行拆分结果和块注释状态。
    return "".join(list_code_parts), " ".join(list_comment_parts), False

# 测试平台文件名用于放宽 task/function 规则。
def _is_testbench(path: Path) -> bool:
    """
    根据文件名判断 Verilog 文件是否为测试平台。

    :param path: 当前 Verilog 文件路径。
    :return: True 表示文件名符合常见 testbench 命名。
    """

    # str_stem 用小写形式匹配 tb 前后缀和 testbench 词。
    str_stem = path.stem.lower()  # 小写文件主名

    # 常见 testbench 命名包括 *_tb、tb_* 和包含 testbench。
    return str_stem.endswith("_tb") or str_stem.startswith("tb_") or "testbench" in str_stem
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall