Metadata-Version: 2.4
Name: hdl-kgraph
Version: 0.6.2
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.4,>=0.3.1
Requires-Dist: tree-sitter-vhdl<2,>=1.5
Requires-Dist: tree-sitter<0.26,>=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.5).** SystemVerilog/Verilog structural extraction, the
> pass-2 linker, SQLite persistence, the `build`/`status`/`query`/`tree`
> CLI, real-world inputs — the SV preprocessor, `.f` filelists, include
> dirs, and `hdl-kgraph.toml` config — VHDL with mixed-language linking
> (entities, architectures, packages, configurations, `--lib` library
> mapping), incremental rebuilds (`update`, `watch`, `detect-changes`,
> `impact`), and the M5 analyses — dataflow, clock domains / reset tree /
> CDC suspects, lint checks, graph metrics, UVM topology, and an
> interactive `visualize` — are in. 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).

To judge whether the graph is trustworthy on real RTL, `build`/`update`/`watch`
take `-v/--verbose`: pipeline stages as they run, per-file parse-error counts,
the full preprocessor warnings (unresolved `` `include``s with the search path,
malformed `` `define``s, ...). The same diagnostics are persisted with the
build, so `hdl-kgraph status --errors` lists them per file after the fact —
including files that were skipped, with reasons.

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/*"]

[vhdl.libraries]
work = "src/vhdl"        # or: hdl-kgraph build --lib work=./src/vhdl
```

**Mixed Verilog/VHDL designs link into one hierarchy.** VHDL names are
case-insensitive (normalized to lowercase, original casing kept in attrs);
`tree` and `query` cross the language boundary in both directions, and a
VHDL configuration overriding a component's default binding is honored.
Cross-language matches are by name at confidence ≤0.8 — never 1.0 — because
vendor tools may bind differently (case folding, library prefixes,
extended/escaped identifiers, generic-dependent wrappers); the score is the
honest contract.

**Incremental updates** keep the graph fresh as you edit. `update` re-parses
only changed/added/removed files plus their dependents — files that
`` `include `` an edited header or expand a macro it defines — and re-links
everything else from stored parse results (one file edited in a 2000-file
design updates in under a second; see [docs/benchmarks.md](docs/benchmarks.md)).
A change to the effective build inputs (defines, incdirs, filelists, library
map) falls back to a full rebuild automatically, as does a database written
by an older schema version — the database is a derived cache, so rebuild *is*
the migration.

```bash
hdl-kgraph update                  # re-parse only what changed, re-link, save
hdl-kgraph detect-changes          # M/A/D lines vs the last build; exit 1 if dirty
hdl-kgraph detect-changes --git    # ...or vs git HEAD (any ref works)
hdl-kgraph impact rtl/uart_tx.sv   # what does my change affect?
hdl-kgraph impact fifo --files     # affected files instead of design units
hdl-kgraph watch ./rtl             # debounced update on every save burst
```

`impact` walks reverse `INSTANTIATES`/`IMPORTS`/`INCLUDES`/`EXTENDS` (plus
VHDL `USES_PACKAGE`/`IMPLEMENTS`/`BINDS` and macro-use) edges transitively:
the instantiating parents, importers, includers, and subclasses a change can
break. `watch` needs the `watchdog` extra: `pip install 'hdl-kgraph[watch]'`.

**Analyses (M5)** turn structure into insight. Dataflow (`DRIVES`/`READS`)
is extracted from always/process blocks, continuous assigns, and instance
port directions; clocks and resets carry evidence scores (sensitivity-list
proof = 1.0, name-pattern heuristics = 0.4):

```bash
hdl-kgraph query clock-domains     # clock nets, alias-merged across hierarchy
hdl-kgraph query cdc               # signals driven in domain A, read in domain B
hdl-kgraph query reset-tree        # async vs (heuristic) sync resets
hdl-kgraph query drivers ready     # what drives signal 'ready' (--readers flips it)
hdl-kgraph query uvm               # UVM components by role + TEST_COVERS links
hdl-kgraph lint                    # unconnected ports, undriven/unread signals,
                                   #   dead modules, redundant parameter overrides
hdl-kgraph metrics --communities   # fan-in/out, hubs/bridges, Louvain subsystems
hdl-kgraph visualize -o graph.html # self-contained interactive HTML (d3 vendored,
                                   #   opens air-gapped): hierarchy + force views,
                                   #   filter by node/edge kind and clock domain
```

CDC findings are *suspects*, not violations — synchronizers are not
recognized (SDC `set_clock_groups` suppression lands with M10). `lint`
always exits 0; it is a report, not a gate. All new commands take `--json`.

**AI assistants (M6)** can query the design directly over MCP — find
modules, walk the hierarchy, trace signal drivers, and run impact analysis
without leaving the conversation:

```bash
pip install 'hdl-kgraph[mcp]'
hdl-kgraph setup                  # detect installed assistants (Claude Code/
                                  #   Desktop, Cursor, Codex, Windsurf, Gemini
                                  #   CLI, VS Code) and write their MCP config
hdl-kgraph serve --mcp            # or run the server by hand (stdio;
                                  #   --http HOST:PORT for streamable HTTP)
```

The server is read-only and picks up database rebuilds automatically.
Nine tools, paginated for LLM context windows: see [docs/mcp.md](docs/mcp.md)
for the tool reference and manual config snippets for other MCP clients.

## 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:** signal drivers/readers (process-, assign-, and
  instance-level), 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)
