#moonbit-rtl

moonbit-rtl is a pure-MoonBit Verilog-2001 front end and RTL structure analyzer for teaching, small FPGA projects, and lightweight CI review. It turns source text into a span-aware syntax tree, semantic index, hierarchy graph, lint diagnostics, and machine-readable reports without requiring an external HDL parser.

#What it provides

Error-recovering lexer and parser for a practical Verilog-2001 subset.
Source spans with line/column mapping and stable AST queries.
Module, port, signal, driver, instance, and hierarchy indexing.
Cross-module connection and width contracts, including unknown-state handling.
Control-flow summaries for procedural reads, writes, conditional assignments, and edge-sensitive blocks.
Deterministic text, JSON, SARIF, Graphviz DOT, and semantic JSON IR output.
Library APIs for batch analysis, source metrics, graph analytics, and reports.
A native CLI suitable for local checks and CI smoke tests.

The project intentionally does not claim complete SystemVerilog support, synthesis, simulation, formal verification, or an LSP server.

#Quick start

Install the current stable MoonBit toolchain, then run:

moon update
moon check --target all
moon test --target all
moon run src/cli -- check examples/counter.v
moon run src/cli -- outline examples/hierarchy.v
moon run src/cli -- graph examples/hierarchy.v

On Windows, the repository's WasmGC checks are a portable local smoke path; native test execution may depend on the installed C compiler/runtime.

#CLI

moonbit-rtl check <file> [--format=text|json|sarif]
moonbit-rtl outline <file>
moonbit-rtl graph <file>
moonbit-rtl summary <file>
moonbit-rtl ir <file>
moonbit-rtl tokens <file>

check returns 0 when no error diagnostic is produced, 1 for source or semantic errors, and 2 for invalid usage or unreadable input. JSON is intended for automation, SARIF for code-scanning clients, DOT for Graphviz, and ir for tools that need a stable semantic snapshot.

#Rules

Code	Category	Meaning	Default
RTL101	structure	duplicate module declaration	warning
RTL102	structure	unresolved module instance	error
RTL201	driving	internal signal is never driven	warning
RTL202	driving	signal has multiple independent drivers	error
RTL203	driving	output port is never assigned	warning
RTL204	width	known assignment widths do not match	warning
RTL205	connectivity	instance port direction/width contract mismatch	error
RTL206	connectivity	instance contract cannot be resolved	warning
RTL207	control flow	procedural assignment is conditional	info

Unknown widths and incomplete syntax are kept conservative so that missing information does not become a false positive.

#Library layout

src/source       source files, spans, line indexes, and source bundles
src/lexer        tokens, lexer, token metrics, and delimiter queries
src/syntax       public AST, visitors, queries, and design metrics
src/parser       recovering Verilog parser and recovery analysis
src/semantic     symbol index, contracts, control flow, IR, and graph analytics
src/lint         configurable rules, categories, and diagnostic reports
src/diagnostic   reports, text/JSON/SARIF/DOT/Markdown renderers
src/cli          command-line entry point and reusable batch analysis API
examples         valid and intentionally broken RTL fixtures
benchmarks       deterministic parser/index workload and benchmark instructions
docs              design, rules, IR, benchmark, and acceptance evidence

#Examples and reproducibility

moon run src/cli -- check examples/broken.v --format=json
moon run src/cli -- summary examples/hierarchy.v
moon run src/cli -- ir examples/hierarchy.v
moon run src/cli -- tokens examples/counter.v
moon run benchmarks --target wasm-gc

The benchmark workload is deterministic. It reports input size, iteration count, modules, hierarchy edges, and diagnostics; wall-clock measurements are environment-specific and are recorded separately in docs/benchmarks.md.

#Development

moon fmt
moon check --target all
moon test --target wasm-gc
moon info
.\scripts\count-moonbit-lines.ps1

The GitHub workflow repeats formatting, all-target checks, tests, metadata verification, coverage-oriented smoke tests, and CLI examples on Linux, macOS, and Windows. See CONTRIBUTING.md for code organization and review expectations.

#License and provenance

The project is licensed under Apache-2.0. The analyzer implementation is original MoonBit code. It does not copy or vendor a third-party Verilog parser; the only runtime dependency is the official moonbitlang/x package used for filesystem and system access. See SOURCES.md for dependency and fixture provenance.

#Roadmap

Future compatible extensions may cover selected SystemVerilog declarations, editor adapters, richer data-flow explanations, and automatic fix suggestions. These are future work and are not represented as current functionality.

Site source Report issue Packages Build queue Skills Statistics