moonbit-rtl

moonbit-rtl is a small, inspectable Verilog-2001 RTL front end written in MoonBit. It is aimed at teaching examples, FPGA repositories, and lightweight pre-review checks where a full HDL toolchain would be too heavy.

The project currently provides four layers:

1. a source model with spans and line/column mapping;
2. a handwritten lexer and error-recovering parser for a practical Verilog-2001 subset;
3. a semantic index containing module symbols, signal drivers, widths, and hierarchy edges;
4. a deterministic diagnostic and CLI layer for local use and CI.

Quick start

Install MoonBit 0.10.3 or a newer compatible release, then run:

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
moon run src/cli -- check examples/broken.v --format=json

The native CLI exits with status 0 when no error diagnostic is produced and status 1 when a source or semantic error is found. Warnings remain visible without failing a normal check.

Commands

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

Text diagnostics use the familiar file:line:column form. JSON output is a stable array intended for CI adapters. SARIF output is suitable for code scanning integrations. Graph output is Graphviz DOT and can be rendered with any Graphviz-compatible tool.

Implemented subset and rules

The parser covers modules, ANSI and non-ANSI-style port declarations, scalar and ranged signals, continuous assignments, procedural assignments, always blocks with edge sensitivity, if, case, begin/end, instances, positional connections, and named port connections. Unsupported constructs are preserved as recoverable syntax errors so later modules can still be indexed.

Code	Meaning	Default severity
RTL101	duplicate module declaration	warning
RTL102	unresolved module instance	error
RTL201	internal signal is never driven	warning
RTL202	signal has multiple independent drivers	error
RTL203	output port is never assigned	warning
RTL204	known assignment widths do not match	warning

The implementation does not invoke an external Verilog parser. That keeps the source and diagnostics easy to audit and leaves a clear path for SystemVerilog extensions, an LSP adapter, automatic fixes, and a JSON IR in later releases.

Repository layout

src/source       source files, spans, and locations
src/lexer        tokens and handwritten lexer
src/syntax       public AST and visitor
src/parser       recovering Verilog-2001 subset parser
src/semantic     symbol index, drivers, widths, hierarchy
src/diagnostic   text, JSON, and DOT renderers
src/lint         rule configuration and diagnostics
src/cli          native command-line entry point
examples         small valid and intentionally broken RTL designs
docs             design notes and hackathon submission notes

Development

Formatting and checks are kept explicit in CI:

moon fmt
moon check --deny-warn --target all
moon test --target all
moon info
git diff --exit-code

The repository is tested with the MoonBit 0.10.3 toolchain requested by the hackathon guidance. The local compatibility check also accepts current CLI releases where moon fmt --deny-warn and moon info --deny-warn have not yet been exposed; CI invokes those flags when the installed tool supports them and falls back to the equivalent clean-diff verification otherwise.

Project status and roadmap

This is a focused first release, not a complete SystemVerilog implementation. The next natural milestones are richer literal widths, port direction/type checks across instances, a library API for editor integrations, more precise control-flow analysis, SystemVerilog declarations, and a machine-readable IR.

License and source provenance

The project is released under the Apache License 2.0. It is an original MoonBit implementation created for the MoonBit ecosystem; it does not copy a third-party RTL parser or vendor HDL source code. The implementation uses MoonBit’s standard library and the official moonbitlang/x filesystem/system helpers only. See docs/source-notes.md for the full provenance record and CONTRIBUTING.md for contribution expectations.