rtl-aid 0.1.0__tar.gz

rtl_aid-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vishwaksen Reddy Dhareddy
+
+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.

rtl_aid-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: rtl-aid
+Version: 0.1.0
+Summary: CI-native documentation layer for RTL projects
+Author: vishwaksen-1
+License: MIT
+Project-URL: Homepage, https://github.com/vishwaksen-1/rtl-aid
+Project-URL: Issues, https://github.com/vishwaksen-1/rtl-aid/issues
+Keywords: verilog,systemverilog,rtl,fpga,asic,eda,documentation,linting,ci,hardware,verilator,dependency-graph,code-analysis,agentic
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# rtl-aid
+
+CI-native documentation layer for RTL projects.
+
+Parses Verilog/SystemVerilog source files, extracts module structure, and generates Markdown documentation that stays in sync with your RTL — automatically.
+
+---
+
+## Tools
+
+| Command | Purpose |
+|---------|---------|
+| `rtldoc` | Generate and maintain module documentation |
+| `rtllint` | Run verilator lint and tag warnings inline in source |
+
+---
+
+## Installation
+
+```bash
+pip install rtl-aid
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/vishwaksen-1/rtl-aid
+cd rtl-aid
+pip install -e .
+```
+
+**Requirements**
+
+- Python 3.7+
+- `rtllint` requires [verilator](https://verilator.org) — a system binary, not installable via pip:
+
+```bash
+# Debian / Ubuntu
+sudo apt install verilator
+
+# macOS
+brew install verilator
+```
+
+`rtldoc` has no external dependencies. If verilator is missing, `rtllint` will exit with a clear error and install instructions.
+
+---
+
+## rtldoc
+
+### Quick start
+
+```bash
+# Document all modules in a directory
+rtldoc -d rtl/
+
+# Document specific files
+rtldoc -f rtl/core/alu.v rtl/core/decoder.v
+
+# Custom output directory
+rtldoc -d rtl/ -o docs/modules/
+```
+
+### What gets generated
+
+For each module, a Markdown file is created or updated:
+
+```markdown
+# alu
+
+## Description
+TODO: Add description
+
+## Parameters
+- DATA_WIDTH = 8
+- OP_WIDTH = 4
+
+## Inputs
+- clk
+- rst
+- op
+- operand_a
+- operand_b
+
+## Outputs
+- result
+- overflow
+
+## Calls
+- [mux4](mux4.md)
+
+## Called By
+- [cpu_core](cpu_core.md)
+```
+
+The `Description` section is **never overwritten** — you write it once, rtldoc preserves it on every run. All other sections are auto-managed.
+
+### CLI reference
+
+```
+rtldoc (-d DIR [DIR...] | -f FILE [FILE...]) [options]
+
+Input:
+  -d, --dir DIR [DIR...]    Recursively scan directories for .v / .sv files
+  -f, --file FILE [FILE...]  Parse specific files (no directory traversal)
+
+Output:
+  -o, --out OUT_DIR          Output directory (default: temp/docs/modules)
+  --json-graph               Write dependency graph to graph.json
+
+Filtering:
+  --exclude PATTERN [...]    Exclude paths containing any of these strings
+
+Run modes:
+  --dry-run                  Show what would be written without touching files
+  --ci                       Fail (exit 1) on missing descriptions, no-IO modules,
+                             or self-instantiations
+  --print-errors             Print CI issues to stdout (in addition to the error log)
+
+Verbosity:
+  -v                         Print modified file paths
+  -vv                        Print modified files + section-level diffs (+adds/-removals)
+```
+
+### CI integration
+
+```yaml
+# .github/workflows/docs.yml
+- name: Check RTL docs
+  run: rtldoc -d rtl/ -o docs/modules/ --ci --print-errors
+```
+
+Exit codes: `0` = clean, `1` = CI check failed.
+
+Testbench files (`_tb.v`, `_tb.sv`, `_bench.v`, `_testbench.v`, and `.sv` variants) are automatically excluded from scanning.
+
+### Dry run
+
+Preview what would change before committing:
+
+```bash
+rtldoc -d rtl/ --dry-run
+```
+
+```
+[DRY RUN] Would write:
+  docs/modules/alu.md
+  docs/modules/decoder.md
+
+5 module(s) processed — 2 doc(s) would be written, 3 unchanged
+```
+
+### Dependency graph
+
+```bash
+rtldoc -d rtl/ --json-graph -o docs/modules/
+```
+
+Writes `docs/modules/graph.json`:
+
+```json
+{
+  "cpu_core": {
+    "calls": ["alu", "decoder", "register_file"],
+    "called_by": []
+  },
+  "alu": {
+    "calls": ["mux4"],
+    "called_by": ["cpu_core"]
+  }
+}
+```
+
+---
+
+## rtllint
+
+Runs `verilator --lint-only -Wall` on a file and tags each warned line with an inline comment. Useful for tracking lint debt without blocking a build.
+
+### Usage
+
+```bash
+rtllint rtl/core/alu.v
+
+# With include directories
+rtllint -I rtl/includes -I rtl/common rtl/core/alu.v
+
+# Multiple files
+rtllint rtl/core/*.v
+
+# Preview without modifying files
+rtllint --dry-run rtl/core/alu.v
+```
+
+### What gets written
+
+Given a verilator warning on line 75:
+
+```
+%Warning-WIDTHEXPAND: rtl/alu.v:75:12: Operator ADD generates 9 bits ...
+```
+
+rtllint modifies `alu.v` in place:
+
+```verilog
+// lint-test: verilator --lint-only -Wall rtl/alu.v
+// tb-test: tba
+...
+assign result = a + b;  /* Check: Operator ADD generates 9 bits ... */
+```
+
+Re-running rtllint replaces existing `/* Check: */` tags — it does not stack duplicates.
+
+### CLI reference
+
+```
+rtllint FILE [FILE...] [options]
+
+  -I, --include DIR    Add include directory (repeatable)
+  --dry-run            Show issues without modifying files
+  -v                   Print full verilator output
+```
+
+Exit codes: `0` = no issues found, `1` = one or more warnings/errors.
+
+---
+
+## Design principles
+
+- **No heavy dependencies** — stdlib only, no parser frameworks
+- **CI-first** — every flag is designed for scripted use
+- **Safe for teams** — manual descriptions are never overwritten
+- **Diff-aware** — files are only touched when content actually changes
+
+---
+
+## Supported syntax
+
+| Feature | Status |
+|---------|--------|
+| Verilog-2001 (`.v`) | Supported |
+| SystemVerilog (`.sv`) | Supported (port/param parsing) |
+| ANSI port declarations | Supported |
+| Comma-inherited port direction (`output reg a, b`) | Supported |
+| Parameterised modules (`#(parameter ...)`) | Supported |
+| Module instantiations with `#()` param override | Supported |
+| Testbench auto-exclusion | Supported |
+| Pre-2001 Verilog style | Not supported |
+| Multi-module files | Not supported (first module only) |

rtl_aid-0.1.0/README.md

@@ -0,0 +1,249 @@
+# rtl-aid
+
+CI-native documentation layer for RTL projects.
+
+Parses Verilog/SystemVerilog source files, extracts module structure, and generates Markdown documentation that stays in sync with your RTL — automatically.
+
+---
+
+## Tools
+
+| Command | Purpose |
+|---------|---------|
+| `rtldoc` | Generate and maintain module documentation |
+| `rtllint` | Run verilator lint and tag warnings inline in source |
+
+---
+
+## Installation
+
+```bash
+pip install rtl-aid
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/vishwaksen-1/rtl-aid
+cd rtl-aid
+pip install -e .
+```
+
+**Requirements**
+
+- Python 3.7+
+- `rtllint` requires [verilator](https://verilator.org) — a system binary, not installable via pip:
+
+```bash
+# Debian / Ubuntu
+sudo apt install verilator
+
+# macOS
+brew install verilator
+```
+
+`rtldoc` has no external dependencies. If verilator is missing, `rtllint` will exit with a clear error and install instructions.
+
+---
+
+## rtldoc
+
+### Quick start
+
+```bash
+# Document all modules in a directory
+rtldoc -d rtl/
+
+# Document specific files
+rtldoc -f rtl/core/alu.v rtl/core/decoder.v
+
+# Custom output directory
+rtldoc -d rtl/ -o docs/modules/
+```
+
+### What gets generated
+
+For each module, a Markdown file is created or updated:
+
+```markdown
+# alu
+
+## Description
+TODO: Add description
+
+## Parameters
+- DATA_WIDTH = 8
+- OP_WIDTH = 4
+
+## Inputs
+- clk
+- rst
+- op
+- operand_a
+- operand_b
+
+## Outputs
+- result
+- overflow
+
+## Calls
+- [mux4](mux4.md)
+
+## Called By
+- [cpu_core](cpu_core.md)
+```
+
+The `Description` section is **never overwritten** — you write it once, rtldoc preserves it on every run. All other sections are auto-managed.
+
+### CLI reference
+
+```
+rtldoc (-d DIR [DIR...] | -f FILE [FILE...]) [options]
+
+Input:
+  -d, --dir DIR [DIR...]    Recursively scan directories for .v / .sv files
+  -f, --file FILE [FILE...]  Parse specific files (no directory traversal)
+
+Output:
+  -o, --out OUT_DIR          Output directory (default: temp/docs/modules)
+  --json-graph               Write dependency graph to graph.json
+
+Filtering:
+  --exclude PATTERN [...]    Exclude paths containing any of these strings
+
+Run modes:
+  --dry-run                  Show what would be written without touching files
+  --ci                       Fail (exit 1) on missing descriptions, no-IO modules,
+                             or self-instantiations
+  --print-errors             Print CI issues to stdout (in addition to the error log)
+
+Verbosity:
+  -v                         Print modified file paths
+  -vv                        Print modified files + section-level diffs (+adds/-removals)
+```
+
+### CI integration
+
+```yaml
+# .github/workflows/docs.yml
+- name: Check RTL docs
+  run: rtldoc -d rtl/ -o docs/modules/ --ci --print-errors
+```
+
+Exit codes: `0` = clean, `1` = CI check failed.
+
+Testbench files (`_tb.v`, `_tb.sv`, `_bench.v`, `_testbench.v`, and `.sv` variants) are automatically excluded from scanning.
+
+### Dry run
+
+Preview what would change before committing:
+
+```bash
+rtldoc -d rtl/ --dry-run
+```
+
+```
+[DRY RUN] Would write:
+  docs/modules/alu.md
+  docs/modules/decoder.md
+
+5 module(s) processed — 2 doc(s) would be written, 3 unchanged
+```
+
+### Dependency graph
+
+```bash
+rtldoc -d rtl/ --json-graph -o docs/modules/
+```
+
+Writes `docs/modules/graph.json`:
+
+```json
+{
+  "cpu_core": {
+    "calls": ["alu", "decoder", "register_file"],
+    "called_by": []
+  },
+  "alu": {
+    "calls": ["mux4"],
+    "called_by": ["cpu_core"]
+  }
+}
+```
+
+---
+
+## rtllint
+
+Runs `verilator --lint-only -Wall` on a file and tags each warned line with an inline comment. Useful for tracking lint debt without blocking a build.
+
+### Usage
+
+```bash
+rtllint rtl/core/alu.v
+
+# With include directories
+rtllint -I rtl/includes -I rtl/common rtl/core/alu.v
+
+# Multiple files
+rtllint rtl/core/*.v
+
+# Preview without modifying files
+rtllint --dry-run rtl/core/alu.v
+```
+
+### What gets written
+
+Given a verilator warning on line 75:
+
+```
+%Warning-WIDTHEXPAND: rtl/alu.v:75:12: Operator ADD generates 9 bits ...
+```
+
+rtllint modifies `alu.v` in place:
+
+```verilog
+// lint-test: verilator --lint-only -Wall rtl/alu.v
+// tb-test: tba
+...
+assign result = a + b;  /* Check: Operator ADD generates 9 bits ... */
+```
+
+Re-running rtllint replaces existing `/* Check: */` tags — it does not stack duplicates.
+
+### CLI reference
+
+```
+rtllint FILE [FILE...] [options]
+
+  -I, --include DIR    Add include directory (repeatable)
+  --dry-run            Show issues without modifying files
+  -v                   Print full verilator output
+```
+
+Exit codes: `0` = no issues found, `1` = one or more warnings/errors.
+
+---
+
+## Design principles
+
+- **No heavy dependencies** — stdlib only, no parser frameworks
+- **CI-first** — every flag is designed for scripted use
+- **Safe for teams** — manual descriptions are never overwritten
+- **Diff-aware** — files are only touched when content actually changes
+
+---
+
+## Supported syntax
+
+| Feature | Status |
+|---------|--------|
+| Verilog-2001 (`.v`) | Supported |
+| SystemVerilog (`.sv`) | Supported (port/param parsing) |
+| ANSI port declarations | Supported |
+| Comma-inherited port direction (`output reg a, b`) | Supported |
+| Parameterised modules (`#(parameter ...)`) | Supported |
+| Module instantiations with `#()` param override | Supported |
+| Testbench auto-exclusion | Supported |
+| Pre-2001 Verilog style | Not supported |
+| Multi-module files | Not supported (first module only) |

rtl_aid-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rtl-aid"
+version = "0.1.0"
+description = "CI-native documentation layer for RTL projects"
+readme = "README.md"
+requires-python = ">=3.7"
+license = { text = "MIT" }
+authors = [
+    { name = "vishwaksen-1" }
+]
+keywords = [
+    "verilog", "systemverilog", "rtl", "fpga", "asic", "eda",
+    "documentation", "linting", "ci", "hardware", "verilator",
+    "dependency-graph", "code-analysis", "agentic"
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/vishwaksen-1/rtl-aid"
+Issues = "https://github.com/vishwaksen-1/rtl-aid/issues"
+
+[project.scripts]
+rtldoc = "rtl_aid.cli:main"
+rtllint = "rtl_aid.lint:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

rtl_aid-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rtl_aid-0.1.0/src/rtl_aid/__init__.py

@@ -0,0 +1,4 @@
+from .core import VerilogWikiParser
+
+__version__ = "0.1.0"
+__all__ = ["VerilogWikiParser"]

rtl_aid-0.1.0/src/rtl_aid/cli.py

@@ -0,0 +1,94 @@
+import argparse
+from .core import VerilogWikiParser
+
+def main():
+    parser = argparse.ArgumentParser()
+
+    group = parser.add_mutually_exclusive_group(required=True)
+    
+    group.add_argument(
+        "-d", "--dir",
+        nargs="+",
+        metavar="DIR",
+        help="One or more directories to recursively scan for Verilog (.v) files"
+    )
+    
+    group.add_argument(
+        "-f", "--file",
+        nargs="+",
+        metavar="FILE",
+        help="One or more specific Verilog files to parse (no directory traversal)"
+    )
+    
+    parser.add_argument(
+        "-o", "--out",
+        default="temp/docs/modules",
+        metavar="OUT_DIR",
+        help="Output directory for generated markdown docs (default: temp/docs/modules)"
+    )
+    
+    parser.add_argument(
+        "-v",
+        action="count",
+        default=0,
+        help="Verbose mode: -v shows modified files, -vv shows detailed section diffs"
+    )
+    
+    parser.add_argument(
+        "--ci",
+        action="store_true",
+        help="Enable CI mode: fail (exit 1) on issues like missing docs, no IO, or invalid structures"
+    )
+    
+    parser.add_argument(
+        "--print-errors",
+        action="store_true",
+        help="Print errors to stdout in addition to the error log file"
+    )
+    
+    parser.add_argument(
+        "--json-graph",
+        action="store_true",
+        help="Generate dependency graph as JSON (graph.json) in output directory"
+    )
+    
+    parser.add_argument(
+        "--exclude",
+        nargs="+",
+        metavar="EXCLUDE",
+        help="Directories or files to exclude from scanning"
+    )
+
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be written without touching any files"
+    )
+
+    args = parser.parse_args()
+
+    paths = args.dir if args.dir else args.file
+
+    v = VerilogWikiParser(
+        paths,
+        verbose=args.v,
+        ci=args.ci,
+        json_graph=args.json_graph,
+        print_errors=args.print_errors,
+        exclude=args.exclude,
+        dry_run=args.dry_run,
+    )
+    v.scan()
+    v.generate_markdown(args.out)
+    v.write_json(args.out)
+    v.write_log()
+    v.run_ci_checks()
+
+    total = len(v.modules)
+    written = len(v.modified_files)
+    unchanged = total - written
+    action = "would be written" if args.dry_run else "written"
+    print(f"\n{total} module(s) processed — {written} doc(s) {action}, {unchanged} unchanged")
+
+if __name__ == "__main__":
+    main()