# tree-sitter/tree-sitter-verilog architecture

> Architecture diagram of the GitHub repository tree-sitter/tree-sitter-verilog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tree-sitter/tree-sitter-verilog
- Repository: https://github.com/tree-sitter/tree-sitter-verilog

## Overview

##### Project type and purpose
- This is a language-grammar plugin project (“tree-sitter-verilog”) for the Tree-sitter parsing library. It provides a SystemVerilog grammar and parser implementation in C, plus multi-language bindings (Node, Python, Go, Rust, Swift).

##### File structure
- Top-level:
- Core grammar & parser:
– src/grammar.json, src/node-types.json (node-type definitions)
– src/parser.c (C parser entry point)
– grammar.js (JavaScript helper)
- Bindings (bridge between the core C library and each target language):
– bindings/c (headers, pkgconfig)
– bindings/node (binding.cc, binding_test.js, index.js/.d.ts, binding.gyp)
– bindings/python (CPython extension, tests, packaging)
– bindings/go (cgo wrapper, tests)
– bindings/rust (build.rs, lib.rs, Cargo.toml)
– bindings/swift (Xcode project, headers, tests, Package.swift)
- Build & packaging files:
– CMakeLists.txt, Makefile for C build
– Cargo.toml/lock for Rust
– package.json + lock + binding.gyp + eslint.config.mjs for Node
– setup.py, pyproject.toml for Python
– Package.swift + Package.resolved for Swift
– go.mod/sum for Go
- CI / deployment:
– .github/workflows (lint, ci, publish)
- Tests & examples:
– test/corpus (Verilog test files)
– examples/module.v

##### README for architectural clues
- Confirms the project’s sole responsibility is providing the SystemVerilog grammar for Tree-sitter.
- Shows install/test instructions per platform/package manager.

a. Main components
1. Core Parser Component
- Grammar specification (grammar.json, node-types.json)
- Generated parser C code (parser.c + tree_sitter headers)
2. Build & Packaging Layer
- C build toolchain (CMake/Make)
- Language-specific build scripts (Cargo, setup.py, binding.gyp, Package.swift, go build)
3. Language Bindings
- Node.js (N-API / NAN)
- Python (CPython C extension)
- Go (cgo)
- Rust (FFI + build.rs)
- Swift (Clang module + Swift package)
4. Consumers / Clients
- JavaScript programs (npm)
- Python scripts (pip)
- Go applications
- Rust crates
- Swift apps
5. CI & Publishing
- GitHub Actions workflows
- Artifacts (npmjs.org, crates.io, PyPI, homebrew? not explicit)

b. Relationships & interactions
- Developer runs “tree-sitter generate” or builds the C core → outputs a shared library (libtree-sitter-verilog.so/.dylib/.dll).
- Each language binding references the shared library (or static lib) via FFI.
- Package manager tools invoke build scripts to compile the C core plus wrapper.
- Client code imports the binding package, calls the parse API to generate syntax trees.

c. Architectural patterns & design principles
- Plugin/Grammar pattern: core grammar + runtime parser library.
- Polyglot FFI layer: one codebase with multiple language adapters.
- Single-source grammar, generated artifacts reused across bindings.
- CI-driven release pipelines for each package registry.

d. Key technologies & frameworks
- Tree-sitter (parser generator)
- C / ANSI C for core parsing
- N-API/NAN for Node.js extension
- CPython C API for Python
- cgo for Go
- Rust’s FFI + Cargo
- Swift Package Manager + Clang module maps
- GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Parser Component
    subgraph "Core Parser Component"
        direction TB
        GJSON["grammar.json"]:::core
        NTJSON["node-types.json"]:::core
        PARSEC["parser.c"]:::core
        ALLOC["alloc.h"]:::core
        ARRAY["array.h"]:::core
        PARSEH["parser.h"]:::core
        GJS["grammar.js"]:::core
        CBUILD["C Core Build\n(CMake/Make)"]:::build
        SLIB["Shared Library\n(libtree-sitter-verilog)"]:::core
    end

    %% Build & Packaging Layer
    subgraph "Build & Packaging Layer"
        direction TB
        CML["CMakeLists.txt"]:::build
        MK["Makefile"]:::build
        BGYP["binding.gyp"]:::build
        PKGJSON["package.json"]:::build
        PKGLOCK["package-lock.json"]:::build
        ESL["eslint.config.mjs"]:::build
        CTOML["Cargo.toml"]:::build
        CLOCK["Cargo.lock"]:::build
        SPY["setup.py"]:::build
        PYO["pyproject.toml"]:::build
        PSP["Package.swift"]:::build
        PRES["Package.resolved"]:::build
        GMOD["go.mod"]:::build
        GSUM["go.sum"]:::build
    end

    %% C Headers / pkg-config
    subgraph "C Headers / pkg-config"
        direction TB
        CH["tree-sitter-verilog.h"]:::build
        PCIN["tree-sitter-verilog.pc.in"]:::build
    end

    %% Language Bindings
    subgraph "Language Bindings"
        direction TB
        subgraph "Node.js Binding" 
            direction TB
            NBCC["binding.cc"]:::binding
            NBIDX["index.js"]:::binding
            NBTYP["index.d.ts"]:::binding
            NBTEST["binding_test.js"]:::binding
        end
        subgraph "Python Binding"
            direction TB
            PYBIND["binding.c"]:::binding
            PYINIT["__init__.py"]:::binding
            PYINI["__init__.pyi"]:::binding
            PYTYP["py.typed"]:::binding
            PYTEST["test_binding.py"]:::binding
        end
        subgraph "Go Binding"
            direction TB
            GOBIND["binding.go"]:::binding
            GOTEST["binding_test.go"]:::binding
        end
        subgraph "Rust Binding"
            direction TB
            RSB["build.rs"]:::binding
            RSLIB["lib.rs"]:::binding
            RSCARGO["Cargo.toml"]:::binding
        end
        subgraph "Swift Binding"
            direction TB
            SVH["verilog.h"]:::binding
            SVTEST["TreeSitterVerilogTests.swift"]:::binding
            SVPKG["Package.swift"]:::binding
            SVRES["Package.resolved"]:::binding
        end
    end

    %% Clients
    subgraph "Clients / Consumers"
        direction TB
        JSCLIENT["JavaScript Programs"]:::client
        PYCLIENT["Python Scripts"]:::client
        GOCLIENT["Go Applications"]:::client
        RSCLIENT["Rust Crates"]:::client
        SWCLIENT["Swift Apps"]:::client
    end

    %% CI & Deployment
    subgraph "CI & Deployment"
        direction TB
        CI1["ci.yml"]:::ci
        CI2["lint.yml"]:::ci
        CI3["publish.yml"]:::ci
        DBA["dependabot.yml"]:::ci
    end

    %% Tests & Examples
    subgraph "Tests & Examples"
        direction TB
        CORPUS["test/corpus/*"]:::test
        EXMOD["module.v"]:::test
        BINJS["test-uvm.js"]:::test
        BINSH["get-uvm.sh"]:::test
    end

    %% Connections
    GJSON --> CBUILD
    NTJSON --> CBUILD
    PARSEC --> CBUILD
    ALLOC --> CBUILD
    ARRAY --> CBUILD
    PARSEH --> CBUILD
    GJS --> CBUILD

    CBUILD --> SLIB

    SLIB --> NBCC
    SLIB --> PYBIND
    SLIB --> GOBIND
    SLIB --> RSLIB
    SLIB --> SVH

    NBCC -->|"build via binding.gyp"| BGYP
    NBIDX --> BGYP
    NBTEST --> BGYP
    NBTYP --> BGYP
    BGYP --> JSCLIENT

    PYBIND --> SPY
    PYBIND --> PYO
    PYTEST --> SPY
    SPY --> PYCLIENT

    GOBIND --> GMOD
    GOBIND --> GSUM
    GOBIND --> GOCLIENT

    RSB --> RSCARGO
    RSLIB --> RSCARGO
    RSCARGO --> RSCLIENT

    SVPKG --> SVRES
    SVH --> SVPKG
    SVTEST --> SVPKG
    SVPKG --> SWCLIENT

    CI1 --> CBUILD
    CI2 --> BGYP
    CI2 --> CTOML
    CI2 --> SPY
    CI2 --> GMOD
    CI2 --> RSCARGO
    CI2 --> SVPKG
    CI3 --> JSCLIENT
    CI3 --> PYCLIENT
    CI3 --> GOCLIENT
    CI3 --> RSCLIENT
    CI3 --> SWCLIENT

    CORPUS --> CBUILD
    EXMOD --> CBUILD
    BINJS --> BGYP
    BINSH --> BGYP

    %% Click Events
    click GJSON "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/src/grammar.json"
    click NTJSON "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/src/node-types.json"
    click PARSEC "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/src/parser.c"
    click ALLOC "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/src/tree_sitter/alloc.h"
    click ARRAY "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/src/tree_sitter/array.h"
    click PARSEH "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/src/tree_sitter/parser.h"
    click GJS "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/grammar.js"
    click CML "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/CMakeLists.txt"
    click MK "https://github.com/tree-sitter/tree-sitter-verilog/tree/master/Makefile"
    click BGYP "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/binding.gyp"
    click PKGJSON "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/package.json"
    click PKGLOCK "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/package-lock.json"
    click ESL "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/eslint.config.mjs"
    click CTOML "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/Cargo.toml"
    click CLOCK "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/Cargo.lock"
    click SPY "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/setup.py"
    click PYO "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/pyproject.toml"
    click PSP "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/Package.swift"
    click PRES "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/Package.resolved"
    click GMOD "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/go.mod"
    click GSUM "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/go.sum"
    click CH "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/c/tree-sitter-verilog.h"
    click PCIN "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/c/tree-sitter-verilog.pc.in"
    click NBCC "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/node/binding.cc"
    click NBIDX "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/node/index.js"
    click NBTYP "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/node/index.d.ts"
    click NBTEST "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/node/binding_test.js"
    click PYBIND "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/python/tree_sitter_verilog/binding.c"
    click PYINIT "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/python/tree_sitter_verilog/__init__.py"
    click PYINI "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/python/tree_sitter_verilog/__init__.pyi"
    click PYTYP "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/python/tree_sitter_verilog/py.typed"
    click PYTEST "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/python/tests/test_binding.py"
    click GOBIND "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/go/binding.go"
    click GOTEST "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/go/binding_test.go"
    click RSB "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/rust/build.rs"
    click RSLIB "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/rust/lib.rs"
    click RSCARGO "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/Cargo.toml"
    click SVH "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/swift/TreeSitterVerilog/verilog.h"
    click SVTEST "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bindings/swift/TreeSitterVerilogTests/TreeSitterVerilogTests.swift"
    click SVPKG "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/Package.swift"
    click SVRES "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/Package.resolved"
    click CI1 "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/.github/workflows/ci.yml"
    click CI2 "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/.github/workflows/lint.yml"
    click CI3 "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/.github/workflows/publish.yml"
    click DBA "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/.github/dependabot.yml"
    click CORPUS "https://github.com/tree-sitter/tree-sitter-verilog/tree/master/test/corpus/*"
    click EXMOD "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/examples/module.v"
    click BINJS "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bin/test-uvm.js"
    click BINSH "https://github.com/tree-sitter/tree-sitter-verilog/blob/master/bin/get-uvm.sh"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px
    classDef build fill:#FFF9C4,stroke:#F57F17,stroke-width:1px
    classDef binding fill:#C8E6C9,stroke:#1B5E20,stroke-width:1px
    classDef client fill:#F8BBD0,stroke:#880E4F,stroke-width:1px
    classDef ci fill:#FFE0B2,stroke:#E65100,stroke-width:1px
    classDef test fill:#CFD8DC,stroke:#455A64,stroke-width:1px
```
