Metadata-Version: 2.4
Name: hdl-kgraph
Version: 0.2.0
Summary: Knowledge graph extractor for SystemVerilog, Verilog, and VHDL
Project-URL: Homepage, https://github.com/chuanseng-ng/hdl-kgraph
Project-URL: Issues, https://github.com/chuanseng-ng/hdl-kgraph/issues
Project-URL: Roadmap, https://github.com/chuanseng-ng/hdl-kgraph/blob/main/ROADMAP.md
Author: Ng Chuan Seng
License-Expression: MIT
License-File: LICENSE
Keywords: eda,hdl,knowledge-graph,systemverilog,tree-sitter,verilog,vhdl
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: networkx>=3.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: tree-sitter-systemverilog>=0.3.1
Requires-Dist: tree-sitter>=0.23
Provides-Extra: all
Requires-Dist: fastmcp>=2; extra == 'all'
Requires-Dist: watchdog>=4; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: fastmcp>=2; extra == 'mcp'
Provides-Extra: watch
Requires-Dist: watchdog>=4; extra == 'watch'
Description-Content-Type: text/markdown

# hdl-kgraph

[![CI](https://github.com/chuanseng-ng/hdl-kgraph/actions/workflows/ci.yml/badge.svg)](https://github.com/chuanseng-ng/hdl-kgraph/actions/workflows/ci.yml)

**A knowledge graph for your HDL design.** hdl-kgraph parses SystemVerilog,
Verilog, and VHDL sources and builds a queryable graph of modules, entities,
instances, ports, parameters, signals, classes, packages, and the
relationships between them — design hierarchy, port connectivity, package
imports, class inheritance, clock domains, and more.

> **Status: alpha (v0.2).** SystemVerilog/Verilog structural extraction, the
> pass-2 linker, SQLite persistence, the `build`/`status`/`query`/`tree`
> CLI, and real-world inputs — the SV preprocessor, `.f` filelists, include
> dirs, and `hdl-kgraph.toml` config — are in. VHDL lands in M3. See
> [ROADMAP.md](ROADMAP.md).

## Why

HDL codebases are graphs — hierarchy, connectivity, clock domains — but the
tools that understand them are locked inside simulators and synthesis flows.
hdl-kgraph extracts that structure into a local-first SQLite database you can
query from the CLI, scripts, or (later) AI assistants via MCP. The
architecture follows
[code-review-graph](https://github.com/tirth8205/code-review-graph), adapted
for hardware.

## Quickstart

```bash
pip install hdl-kgraph

hdl-kgraph build ./rtl            # parse sources -> ./rtl/.hdl-kgraph/graph.db
hdl-kgraph build -f sim/tb.f      # drive the build from a vendor-style filelist
hdl-kgraph build -D SYNTHESIS -D WIDTH=8 -I include   # defines + incdirs
hdl-kgraph status                 # files, parse errors, node/edge counts
hdl-kgraph tree soc_top           # print the design hierarchy from a top module
hdl-kgraph query instances-of fifo
hdl-kgraph query unresolved       # what couldn't be resolved (vendor IP, macros)
```

`build` accepts `--exclude GLOB` (repeatable) and `--max-file-size KB` to keep
generated netlists and vendored IP out of the graph. Files with syntax errors
still yield partial results; `status` reports the parse-error count.
Unresolved instance targets render as `[?]` in `tree` and ambiguous matches as
`[~0.6]` — see the confidence convention in [ROADMAP.md](ROADMAP.md).

Filelists support `+incdir+`/`+define+`, nested `-f`, `-y`/`-v` library
dirs, and `$VAR` expansion. When no defines are given at all, conditionals
on undefined names emit *both* branches: the side a define-less compile
would select at full confidence, the alternative at 0.6. Repeatable inputs
can also live in an `hdl-kgraph.toml` at the build root (CLI flags win):

```toml
[build]
filelists = ["sim/tb.f"]
defines   = ["SYNTHESIS", "WIDTH=8"]
incdirs   = ["include"]
exclude   = ["vendor/*"]
```

Coming next:

```bash
hdl-kgraph impact rtl/uart_tx.sv  # what does my change affect? (M4)
hdl-kgraph visualize              # interactive HTML graph (M5)
hdl-kgraph serve --mcp            # MCP server for AI assistants (M6)
```

## What gets extracted

- **Design units:** modules, interfaces/modports, packages, programs,
  checkers, UDPs; VHDL entities, architectures, packages, configurations
- **Structure:** instances with port connections and parameter overrides,
  generate blocks, `include`/`define` relationships, filelists
- **Verification:** SV classes (UVM hierarchies via inheritance chains),
  constraints, covergroups, assertions/properties/sequences, clocking blocks
- **Dataflow (M5):** signal drivers/readers, clock and reset trees,
  CDC-suspect crossings

Every cross-file edge carries a confidence score (resolved → heuristic), so
the graph is honest about what was proven syntactically vs inferred by name
matching. The full schema is documented in [ROADMAP.md](ROADMAP.md).

## Roadmap at a glance

| Milestone | Theme |
|---|---|
| M1 (v0.1) | SystemVerilog/Verilog structural graph + CLI |
| M2 (v0.2) | Preprocessor, `.f` filelists, includes |
| M3 (v0.3) | VHDL + mixed-language linking |
| M4 (v0.4) | Incremental updates, watch mode, impact analysis |
| M5 (v0.5) | Clock/reset/CDC analyses, lint checks, visualization |
| M6 (v0.6) | MCP server for AI assistants |
| M7 (v0.7) | Semantic enrichment (pyslang, GHDL) |
| M8 (v1.0) | C/C++/Python boundary (DPI-C, cocotb), stable API |
| M9 (v1.x) | Chisel/FIRRTL, Amaranth, SpinalHDL |
| M10 (v1.x) | Tcl/SDC/UPF constraints, Perl scripting, SLN portable stimulus |

Details and acceptance criteria: [ROADMAP.md](ROADMAP.md).

## Development

```bash
git clone https://github.com/chuanseng-ng/hdl-kgraph
cd hdl-kgraph
pip install -e .[dev]
ruff check . && ruff format --check . && mypy && pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md). The single most useful contribution
right now: the smallest HDL file that breaks extraction.

## License

[MIT](LICENSE)
