rtl-aid 0.1.0__py3-none-any.whl

rtl_aid/__init__.py

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

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()

rtl_aid/core.py

@@ -0,0 +1,364 @@
+import re
+import os
+import tempfile
+import json
+import sys
+
+class VerilogWikiParser(object):
+    def __init__(self, paths, verbose=0, ci=False, json_graph=False, print_errors=False, exclude=None, dry_run=False):
+        self.paths = paths
+        self.modules = {}
+        self.called_by = {}
+        self.modified_files = []
+        self.verbose = verbose
+        self.ci = ci
+        self.json_graph = json_graph
+        self.print_errors = print_errors
+        self.exclude = exclude or []
+        self.issues = []
+        self.dry_run = dry_run
+
+    # -------------------------
+    # CLEAN COMMENTS
+    # -------------------------
+    def clean(self, text):
+        text = re.sub(r"//[^\n]*", "\n", text)
+        text = re.sub(r"/\*.*?\*/", "", text, flags=re.S)
+        return text
+
+    # -------------------------
+    # PARSING
+    # -------------------------
+    def extract_module_and_ports(self, text):
+        pattern = r"module\s+(\w+)\s*(#\s*\((.*?)\))?\s*\((.*?)\)\s*;"
+        m = re.search(pattern, text, flags=re.S)
+        if not m:
+            return None
+
+        mod_name = m.group(1)
+        param_block = m.group(3) or ""
+        port_block = m.group(4)
+
+        inputs, outputs, inouts = [], [], []
+        parameters = []
+
+        for p in re.split(r",\s*\n|,\s*", param_block):
+            p = p.strip()
+            if p.startswith("parameter"):
+                param_str = re.sub(r"\bparameter\b", "", p).strip()
+                param_str = re.sub(r"^(integer|logic|reg|wire|bit|byte|shortint|int|longint|signed|unsigned)\s+", "", param_str)
+                parameters.append(param_str.strip())
+
+        ports = re.split(r",\s*\n|,\s*", port_block)
+
+        current_direction = None
+        for p in ports:
+            p = p.strip()
+            if not p:
+                continue
+
+            p = re.sub(r"`\w+\s+", "", p)
+            tokens = p.split()
+            if not tokens:
+                continue
+
+            name = tokens[-1]
+
+            if "input" in tokens:
+                current_direction = "input"
+            elif "output" in tokens:
+                current_direction = "output"
+            elif "inout" in tokens:
+                current_direction = "inout"
+
+            if current_direction == "input":
+                inputs.append(name)
+            elif current_direction == "output":
+                outputs.append(name)
+            elif current_direction == "inout":
+                inouts.append(name)
+
+        return {
+            "name": mod_name,
+            "inputs": inputs,
+            "outputs": outputs,
+            "inouts": inouts,
+            "parameters": parameters
+        }
+
+    def remove_module_header(self, text):
+        return re.sub(r"\bmodule\b[^;]*;", "", text)
+
+    def extract_calls(self, text, known_modules, current_module):
+        calls = set()
+        text = self.remove_module_header(text)
+
+        pattern = r"\b(\w+)\s*(?:#\s*\(.*?\))?\s+\w+\s*\("
+        for m in re.finditer(pattern, text, flags=re.S):
+            mod_name = m.group(1)
+            if mod_name in known_modules:
+                calls.add(mod_name)
+
+        return sorted(list(calls))
+
+    _TB_SUFFIXES = ("_tb.v", "_tb.sv", "_bench.v", "_bench.sv", "_testbench.v", "_testbench.sv")
+    _RTL_EXTENSIONS = (".v", ".sv")
+
+    def _is_rtl_file(self, filename):
+        return (
+            any(filename.endswith(ext) for ext in self._RTL_EXTENSIONS)
+            and not any(filename.endswith(s) for s in self._TB_SUFFIXES)
+        )
+
+    # -------------------------
+    # SCAN
+    # -------------------------
+    def scan(self):
+        file_texts = {}
+        all_files = []
+
+        def is_excluded(path):
+            for ex in self.exclude:
+                if ex in path:
+                    return True
+            return False
+
+        for p in self.paths:
+            if os.path.isfile(p):
+                if not is_excluded(p):
+                    all_files.append(p)
+            else:
+                for root, dirs, files in os.walk(p):
+                    dirs[:] = [d for d in dirs if not is_excluded(os.path.join(root, d))]
+                    if is_excluded(root):
+                        continue
+                    for f in files:
+                        if self._is_rtl_file(f):
+                            full_path = os.path.join(root, f)
+                            if not is_excluded(full_path):
+                                all_files.append(full_path)
+
+        for path in all_files:
+            with open(path, "r") as fh:
+                text = self.clean(fh.read())
+
+            file_texts[path] = text
+
+            mod = self.extract_module_and_ports(text)
+            if not mod:
+                continue
+
+            self.modules[mod["name"]] = {
+                "file": path,
+                "calls": [],
+                "inputs": mod["inputs"],
+                "outputs": mod["outputs"],
+                "inouts": mod["inouts"],
+                "parameters": mod["parameters"]
+            }
+
+        known_modules = set(self.modules.keys())
+
+        for path, text in file_texts.items():
+            mod = self.extract_module_and_ports(text)
+            if not mod:
+                continue
+
+            mod_name = mod["name"]
+            self.modules[mod_name]["calls"] = self.extract_calls(
+                text, known_modules, mod_name
+            )
+
+        self.build_called_by()
+
+    def build_called_by(self):
+        for mod in self.modules:
+            self.called_by[mod] = []
+
+        for caller, data in self.modules.items():
+            for callee in data["calls"]:
+                if callee in self.called_by:
+                    self.called_by[callee].append(caller)
+
+    # -------------------------
+    # EXISTING MD PARSE
+    # -------------------------
+    def parse_existing_sections(self, path):
+        if not os.path.exists(path):
+            return {}
+
+        with open(path) as f:
+            content = f.read()
+
+        sections = {}
+        for sec in ["Description", "Parameters", "Inputs", "Outputs", "Inouts", "Calls", "Called By"]:
+            m = re.search(rf"## {sec}\n(.*?)(\n##|\Z)", content, re.S)
+            if m:
+                sections[sec] = m.group(1).strip()
+
+        return sections
+
+    # -------------------------
+    # DIFF
+    # -------------------------
+    def diff_lists(self, old, new):
+        old_set = set(old)
+        new_set = set(new)
+        return len(new_set - old_set), len(old_set - new_set)
+
+    # -------------------------
+    # MARKDOWN
+    # -------------------------
+    def generate_markdown(self, out_dir):
+        if not self.dry_run:
+            os.makedirs(out_dir, exist_ok=True)
+        
+        managed_sections = ["Parameters", "Inputs", "Outputs", "Inouts", "Calls", "Called By"]
+
+        for mod, data in self.modules.items():
+            fname = os.path.join(out_dir, f"{mod}.md")
+
+            old_content = ""
+            if os.path.exists(fname):
+                with open(fname) as f:
+                    old_content = f.read()
+
+            old_sections = self.parse_existing_sections(fname)
+            desc = old_sections.get("Description", "TODO: Add description")
+
+            if desc.startswith("TODO"):
+                self.issues.append(f"{mod}: missing description")
+
+            def format_list(lst):
+                return "\n".join([f"- {x}" for x in lst]) if lst else "- None"
+
+            new_sections = {
+                "Parameters": format_list(data["parameters"]),
+                "Inputs": format_list(data["inputs"]),
+                "Outputs": format_list(data["outputs"]),
+                "Inouts": format_list(data["inouts"]),
+                "Calls": format_list([f"[{c}]({c}.md)" for c in data["calls"]]),
+                "Called By": format_list([f"[{c}]({c}.md)" for c in self.called_by.get(mod, [])]),
+            }
+
+            # DIFF LOGIC
+            diffs = {}
+            for key in ["Parameters", "Inputs", "Outputs", "Inouts", "Calls"]:
+                old_list = re.findall(r"- (.+)", old_sections.get(key, ""))
+                new_list = re.findall(r"- (.+)", new_sections[key])
+                add, rem = self.diff_lists(old_list, new_list)
+                diffs[key] = (add, rem)
+
+            content = ""
+            if not old_content:
+                content = f"# {mod}\n\n## Description\n{desc}\n\n"
+                for k, v in new_sections.items():
+                    content += f"## {k}\n{v}\n\n"
+            else:
+                content = old_content
+                for sec in managed_sections:
+                    new_sec_text = f"## {sec}\n{new_sections[sec]}\n"
+                    pattern = rf"## {sec}\n.*?(?=\n##|\Z)"
+                    if re.search(pattern, content, flags=re.S):
+                        content = re.sub(pattern, new_sec_text, content, flags=re.S)
+                    else:
+                        content += f"\n{new_sec_text}\n"
+
+            content = content.strip() + "\n"
+
+            if content != old_content:
+                if not self.dry_run:
+                    with open(fname, "w") as f:
+                        f.write(content)
+
+                diff_str = f"{mod}: " + ", ".join([f"{k} +{a}/-{r}" for k, (a, r) in diffs.items()])
+                self.modified_files.append((fname, diff_str))
+
+    # -------------------------
+    # LOGGING
+    # -------------------------
+    def write_log(self):
+        if self.modified_files:
+            if self.dry_run:
+                print("\n[DRY RUN] Would write:")
+                for fname, _ in self.modified_files:
+                    print(f"  {fname}")
+                if self.verbose >= 2:
+                    print("\nDetailed section diffs:")
+                    for _, diff_str in self.modified_files:
+                        print(f"  {diff_str}")
+            else:
+                tmp = tempfile.NamedTemporaryFile(delete=False, mode="w", suffix=".log")
+                tmp.write("Modified files:\n")
+                for fname, _ in self.modified_files:
+                    tmp.write(fname + "\n")
+                tmp.write("\nDetailed section diffs:\n")
+                for _, diff_str in self.modified_files:
+                    tmp.write(diff_str + "\n")
+                tmp.close()
+
+                if self.verbose >= 1:
+                    print("\nModified files:")
+                    for fname, _ in self.modified_files:
+                        print(fname)
+
+                if self.verbose >= 2:
+                    print("\nDetailed section diffs:")
+                    for _, diff_str in self.modified_files:
+                        print(diff_str)
+
+                print(f"\nLog file: {tmp.name}")
+
+        if not self.ci:
+            missing_docs = [mod for mod in self.modules if any(f"{mod}: missing description" in i for i in self.issues)]
+            if missing_docs:
+                print("\nMissing Docs Summary Report:")
+                for m in missing_docs:
+                    print(f"  - {m}")
+
+    # -------------------------
+    # JSON GRAPH
+    # -------------------------
+    def write_json(self, out_dir):
+        if not self.json_graph:
+            return
+
+        graph = {}
+        for m, d in self.modules.items():
+            graph[m] = {
+                "calls": d["calls"],
+                "called_by": self.called_by.get(m, [])
+            }
+
+        path = os.path.join(out_dir, "graph.json")
+        with open(path, "w") as f:
+            json.dump(graph, f, indent=2)
+
+    # -------------------------
+    # CI VALIDATION
+    # -------------------------
+    def run_ci_checks(self):
+        if not self.ci:
+            return
+
+        for mod, data in self.modules.items():
+            if not data["inputs"] and not data["outputs"]:
+                self.issues.append(f"{mod}: no IO")
+
+            if mod in data["calls"]:
+                self.issues.append(f"{mod}: self-instantiation")
+
+        if self.issues:
+            if not self.dry_run:
+                tmp = tempfile.NamedTemporaryFile(delete=False, mode="w", suffix="_errors.log")
+                tmp.write("CI FAIL:\n")
+                for i in self.issues:
+                    tmp.write(i + "\n")
+                tmp.close()
+                print(f"\nError log file: {tmp.name}")
+
+            if self.print_errors or self.dry_run:
+                print("\nCI FAIL:")
+                for i in self.issues:
+                    print(i)
+            sys.exit(1)

rtl_aid/lint.py

@@ -0,0 +1,184 @@
+import re
+import subprocess
+import sys
+import os
+import argparse
+import shutil
+
+
+def _get_verilator_version():
+    try:
+        out = subprocess.check_output(["verilator", "--version"], text=True)
+        return out.strip().splitlines()[0]
+    except Exception:
+        return None
+
+
+def _check_verilator():
+    if not shutil.which("verilator"):
+        print(
+            "Error: verilator is not installed or not in PATH.\n"
+            "\n"
+            "Install it:\n"
+            "  Debian / Ubuntu:  sudo apt install verilator\n"
+            "  macOS:            brew install verilator\n"
+            "  From source:      https://verilator.org/guide/latest/install.html\n"
+            "\n"
+            "Note: verilator is a system tool and cannot be installed via pip.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _run_lint(filepath, include_dirs):
+    cmd = ["verilator", "--lint-only", "-Wall"]
+    for d in include_dirs:
+        cmd.extend(["-I", d])
+    cmd.append(filepath)
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    return result.stdout + result.stderr, cmd
+
+
+def parse_lint_output(output, filepath):
+    """Return {line_num: message} for warnings/errors in filepath only.
+
+    Only the first issue per line is kept — multiple warnings on the same
+    line would produce unreadable inline comments. Verilator continuation
+    lines (context arrows, notes) are skipped; only lines starting with
+    '%Warning' or '%Error' are matched.
+    """
+    issues = {}
+    target_base = os.path.basename(filepath)
+    target_abs = os.path.abspath(filepath)
+
+    # Format: %Warning-TYPE: path:line:col: message
+    #         %Error: path:line:col: message
+    pattern = re.compile(r"^%(Warning[^:]*|Error[^:]*): (.+?):(\d+):\d+: (.+)$")
+    for line in output.splitlines():
+        m = pattern.match(line)
+        if not m:
+            continue
+        warn_file = m.group(2)
+        line_num = int(m.group(3))
+        message = m.group(4).strip()
+
+        if (os.path.basename(warn_file) == target_base
+                or os.path.abspath(warn_file) == target_abs):
+            if line_num not in issues:
+                issues[line_num] = message
+
+    return issues
+
+
+def tag_file(filepath, issues, lint_cmd):
+    """Tag warned lines inline and add lint/tb-test header lines.
+
+    Idempotent: re-running replaces existing /* Check: */ tags and
+    skips header lines that are already present.
+    """
+    with open(filepath, "r") as f:
+        lines = f.readlines()
+
+    # Tag each warned line with a trailing /* Check: ... */ comment.
+    # Verilator line numbers are 1-based; Python list is 0-based.
+    # Guard against line numbers that fall outside the file — this can
+    # happen when a warning originates inside a macro expansion.
+    for line_num, message in sorted(issues.items()):
+        idx = line_num - 1
+        if idx < 0 or idx >= len(lines):
+            continue
+        line = lines[idx].rstrip("\n")
+        line = re.sub(r"\s*/\* Check:.*?\*/", "", line).rstrip()
+        lines[idx] = f"{line}  /* Check: {message} */\n"
+
+    # Insert lint/tb-test headers after the leading comment block (copyright
+    # headers, file-level comments, blank lines at the top).
+    insert_idx = 0
+    for i, line in enumerate(lines):
+        s = line.strip()
+        if s.startswith("//") or s.startswith("/*") or s.startswith("*") or s == "":
+            insert_idx = i + 1
+        else:
+            break
+
+    lint_cmd_str = " ".join(lint_cmd)
+    full_content = "".join(lines)
+    new_headers = []
+    if "// lint-test:" not in full_content:
+        new_headers.append(f"// lint-test: {lint_cmd_str}\n")
+    if "// tb-test:" not in full_content:
+        new_headers.append("// tb-test: tba\n")
+
+    if new_headers:
+        lines = lines[:insert_idx] + new_headers + lines[insert_idx:]
+
+    with open(filepath, "w") as f:
+        f.writelines(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="rtllint",
+        description="Run verilator lint on Verilog files and tag warnings inline"
+    )
+    parser.add_argument(
+        "file",
+        nargs="+",
+        metavar="FILE",
+        help="Verilog/SystemVerilog file(s) to lint"
+    )
+    parser.add_argument(
+        "-I", "--include",
+        dest="include_dirs",
+        action="append",
+        metavar="DIR",
+        default=[],
+        help="Add include directory (passed to verilator as -I, repeatable)"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show issues without modifying any files"
+    )
+    parser.add_argument(
+        "-v",
+        action="store_true",
+        help="Print full verilator output"
+    )
+    args = parser.parse_args()
+
+    _check_verilator()
+
+    if args.v:
+        print(f"Using {_get_verilator_version()}")
+
+    any_issues = False
+    for filepath in args.file:
+        if not os.path.isfile(filepath):
+            print(f"Error: {filepath}: file not found", file=sys.stderr)
+            continue
+
+        output, cmd = _run_lint(filepath, args.include_dirs)
+        issues = parse_lint_output(output, filepath)
+
+        if args.v and output.strip():
+            print(output.strip())
+
+        if not issues:
+            print(f"{filepath}: clean")
+            continue
+
+        any_issues = True
+        if args.dry_run:
+            print(f"\n{filepath}: {len(issues)} issue(s) would be tagged:")
+            for ln, msg in sorted(issues.items()):
+                print(f"  Line {ln}: {msg}")
+        else:
+            tag_file(filepath, issues, cmd)
+            print(f"{filepath}: tagged {len(issues)} issue(s)")
+
+    sys.exit(1 if any_issues else 0)
+
+
+if __name__ == "__main__":
+    main()

rtl_aid-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+rtl_aid/__init__.py,sha256=J3qdjHJISA6Cqd6sKZ2brPidpfxjy2a12O4Z4Wwu0TE,91
+rtl_aid/cli.py,sha256=auXA5TCtGrpgxIf3qWL0ez9FA3BX3htst-YSuE6BY40,2480
+rtl_aid/core.py,sha256=joZ_isBh4jFogCI-GRQ8NmICwqajKScc3QpDX4KajU8,12369
+rtl_aid/lint.py,sha256=zlkb4GVUoDyz_mHqX62b5lMiIZMHAb4ZTnQC9WKAb9I,5707
+rtl_aid-0.1.0.dist-info/licenses/LICENSE,sha256=ZRKXRB0OwPXwHVrgs_FKR0ccE7iVilonlm8hFTEq2II,1082
+rtl_aid-0.1.0.dist-info/METADATA,sha256=DbTgxtm7trwoRNtmsJoVYFt8PkSq4q3IAz4fcYeUkPg,5922
+rtl_aid-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rtl_aid-0.1.0.dist-info/entry_points.txt,sha256=Ix76H3ujuKDefSIxfkE40k19yTwzRu1W2K0Z8aK0Ef0,72
+rtl_aid-0.1.0.dist-info/top_level.txt,sha256=Mm_ImtgV6c0zD1ZqbVx4-P2uwxKTAqpCHiTO0qbQWM8,8
+rtl_aid-0.1.0.dist-info/RECORD,,

rtl_aid-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rtl_aid-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+rtldoc = rtl_aid.cli:main
+rtllint = rtl_aid.lint:main

rtl_aid-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+rtl_aid