hdl-kgraph 0.1.0__tar.gz

hdl_kgraph-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e .[dev]
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        # One macOS/Windows run to catch grammar-wheel platform gaps cheaply.
+        include:
+          - { os: macos-latest, python-version: "3.12" }
+          - { os: windows-latest, python-version: "3.12" }
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e .[dev]
+      - run: pytest --cov=hdl_kgraph

hdl_kgraph-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hdl-kgraph
+    permissions:
+      id-token: write # required for PyPI trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4

hdl_kgraph-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# hdl-kgraph artifacts
+.hdl-kgraph/
+*.db
+*.sqlite3

hdl_kgraph-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to hdl-kgraph
+
+Thanks for your interest! The project is pre-alpha — see
+[ROADMAP.md](ROADMAP.md) for what's planned and where help is most valuable.
+
+## Dev setup
+
+```bash
+git clone https://github.com/chuanseng-ng/hdl-kgraph
+cd hdl-kgraph
+pip install -e .[dev]
+```
+
+Before pushing:
+
+```bash
+ruff check . && ruff format --check . && mypy && pytest
+```
+
+CI runs the same checks on Python 3.10–3.13.
+
+## The most valuable contribution: fixtures
+
+HDL parsing lives and dies by real-world edge cases. If hdl-kgraph
+mis-extracts (or chokes on) your code, please open an issue with the
+**smallest self-contained HDL file that reproduces it** — strip proprietary
+content, keep the construct. Accepted reproductions land in `tests/fixtures/`
+and become permanent regression tests.
+
+## Code conventions
+
+- The graph schema (`src/hdl_kgraph/schema.py`) is the project's contract.
+  Extending it (new node/edge kinds) is fine; changing existing meanings needs
+  discussion in an issue first.
+- Parsers are pass-1 only: per-file extraction, no cross-file resolution.
+  Cross-file logic belongs in the pass-2 linker (`graph/builder.py`).
+- Every cross-file edge gets a confidence score per the convention in
+  `schema.py`.

hdl_kgraph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ng Chuan Seng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hdl_kgraph-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: hdl-kgraph
+Version: 0.1.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: 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.1).** SystemVerilog/Verilog structural extraction, the
+> pass-2 linker, SQLite persistence, and the `build`/`status`/`query`/`tree`
+> CLI are in. The preprocessor and filelists land in M2, VHDL 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 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).
+
+Coming next:
+
+```bash
+hdl-kgraph build -f sim/tb.f      # drive the build from a filelist (M2)
+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)

hdl_kgraph-0.1.0/README.md

@@ -0,0 +1,99 @@
+# 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.1).** SystemVerilog/Verilog structural extraction, the
+> pass-2 linker, SQLite persistence, and the `build`/`status`/`query`/`tree`
+> CLI are in. The preprocessor and filelists land in M2, VHDL 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 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).
+
+Coming next:
+
+```bash
+hdl-kgraph build -f sim/tb.f      # drive the build from a filelist (M2)
+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)