chipgraph 0.1.0__py3-none-any.whl

chipgraph/checks/_naming_rules.py

@@ -0,0 +1,127 @@
+"""The `naming` check's rules, as a versioned pydantic data model.
+
+A naming rule file (e.g. `src/chipgraph/orgs/qnsc/naming-v1.yml`) declares, as data:
+
+- per **object kind** (`module`, `port`, `parameter`, `localparam`, `enum_value`,
+  `instance`, `signal`, `memory`, `genvar`, ...) an allowed `pattern`, a `rule` id and a
+  `message`;
+- **lexical** rules that apply to every identifier declared in a file (a forbidden
+  regex with an optional allow-if escape hatch);
+- a **vocabulary** map of forbidden word -> project term;
+- the `ignore_comment` that exempts a declaration line.
+
+The check (`chipgraph.checks.naming`) reads this model; it does not hard-code any
+pattern. Rule ids and messages follow the source document's numbering ("2.1 module",
+"1.5 vocabulary", ...) so a reviewer can compare the file with the document line by line.
+
+The JSON Schema of this model is committed at `schemas/formats/naming-rules.schema.json`
+(regenerate with `python -m chipgraph.checks.naming`).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# The object kinds a rule file may constrain. These are the classifications the check
+# derives from the pyslang syntax tree, not free-form strings.
+ObjectKind = Literal[
+    "module",
+    "port",
+    "parameter",
+    "localparam",
+    "enum_value",
+    "instance",
+    "signal",
+    "memory",
+    "genvar",
+]
+
+
+def _valid_regex(pattern: str) -> str:
+    try:
+        re.compile(pattern)
+    except re.error as exc:  # pragma: no cover - exercised via model validation
+        raise ValueError(f"invalid regex {pattern!r}: {exc}") from exc
+    return pattern
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class KindRule(_Model):
+    """The allowed-name rule for one object kind: a pattern the whole name must match."""
+
+    rule: str = Field(description="The rule id, e.g. '2.1 module'.")
+    pattern: str = Field(description="A regex the identifier must fully match to pass.")
+    message: str = Field(description="Human-readable message shown when the name is rejected.")
+
+    @field_validator("pattern")
+    @classmethod
+    def _check_pattern(cls, value: str) -> str:
+        return _valid_regex(value)
+
+
+class LexicalRule(_Model):
+    """A lexical rule: a forbidden pattern with an optional allow-if escape hatch."""
+
+    rule: str = Field(description="The rule id, e.g. '1.1 case'.")
+    forbid_pattern: str = Field(description="A regex that, if found in a name, is a violation.")
+    allow_if_matches: str | None = Field(
+        default=None,
+        description="If set, a name fully matching this regex is exempt from this rule.",
+    )
+    message: str = Field(description="Human-readable message shown when the rule fires.")
+
+    @field_validator("forbid_pattern", "allow_if_matches")
+    @classmethod
+    def _check_pattern(cls, value: str | None) -> str | None:
+        return _valid_regex(value) if value is not None else None
+
+
+class VocabularyRule(_Model):
+    """The mandatory-vocabulary rule: each forbidden word maps to the project term."""
+
+    rule: str = Field(description="The rule id, e.g. '1.5 vocabulary'.")
+    replace: dict[str, str] = Field(description="Map of forbidden word -> preferred project term.")
+    message: str = Field(description="Human-readable message prefix shown when a word is used.")
+
+
+class NamingRules(_Model):
+    """A naming rule file: per-kind patterns, lexical rules, vocabulary and metadata."""
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    document: str = Field(description="Name of the source naming-rule document.")
+    version: str = Field(description="Version of the source document these rules enforce.")
+    ignore_comment: str = Field(
+        default="naming-check: ignore",
+        description="A trailing line comment matching this exempts the declaration line.",
+    )
+    identifiers: dict[ObjectKind, KindRule] = Field(
+        description="Allowed-name rule per object kind (module, port, signal, ...)."
+    )
+    lexical: tuple[LexicalRule, ...] = Field(
+        default=(), description="Lexical rules applied to every identifier declared in a file."
+    )
+    vocabulary: VocabularyRule | None = Field(
+        default=None, description="The mandatory-vocabulary rule, if any."
+    )
+
+
+def schema_json() -> str:
+    """The JSON Schema of a naming rule file, as committed under `schemas/formats/`."""
+    return json.dumps(NamingRules.model_json_schema(), indent=2, sort_keys=True) + "\n"
+
+
+__all__ = [
+    "KindRule",
+    "LexicalRule",
+    "NamingRules",
+    "ObjectKind",
+    "VocabularyRule",
+    "schema_json",
+]

chipgraph/checks/_xref_syntax.py

@@ -0,0 +1,260 @@
+"""Syntax-tree helpers shared by the `connect` and `hardcode` cross checks.
+
+Both checks look at RTL *structure*, not the elaborated model: `connect` needs the
+hierarchy instances of the top module and their named port connections; `hardcode` needs
+every integer literal a file types, with its decoded value and line, and the comment on
+that line (so a `// contract:` tag can exempt it). Neither elaborates: a single file with
+missing packages still parses (matching `naming`'s single-file, syntax-only parse).
+
+Everything here is pure and deterministic and never raises on malformed input: a parse
+error is returned as a `ParseFailure` (via `chipgraph.checks._naming_pyslang.parse_errors`),
+never thrown.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pyslang.syntax import SyntaxKind, SyntaxNode, SyntaxTree
+
+from chipgraph.checks._naming_pyslang import ParseFailure, parse_errors, parse_file
+
+
+@dataclass(frozen=True, slots=True)
+class PortConn:
+    """One named port connection `.port(expr)` of an instance."""
+
+    port: str
+    expr: str
+    line: int
+
+
+@dataclass(frozen=True, slots=True)
+class Instance:
+    """One hierarchy instance in a module: `module_name inst_name (.p(e), ...)`."""
+
+    module: str
+    name: str
+    line: int
+    connections: tuple[PortConn, ...] = ()
+
+    def connection(self, port: str) -> PortConn | None:
+        """The named connection to `port`, or None if it is not connected by name."""
+        for conn in self.connections:
+            if conn.port == port:
+                return conn
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class IntLiteral:
+    """One integer literal token in RTL: its decoded value, line and raw text."""
+
+    value: int
+    line: int
+    raw: str
+
+
+@dataclass(slots=True)
+class ParsedRtl:
+    """The syntax facts one RTL file yields, plus any parse errors."""
+
+    instances: list[Instance] = field(default_factory=list)
+    literals: list[IntLiteral] = field(default_factory=list)
+    parse_errors: tuple[ParseFailure, ...] = ()
+    line_comments: dict[int, str] = field(default_factory=dict)
+
+
+def parse_rtl(path: Path) -> ParsedRtl:
+    """Parse the RTL at `path`, returning its instances, literals and parse errors."""
+    tree = parse_file(path)
+    text = path.read_text(errors="ignore")
+    return ParsedRtl(
+        instances=_instances(tree),
+        literals=_literals(tree),
+        parse_errors=tuple(parse_errors(tree)),
+        line_comments=_line_comments(text),
+    )
+
+
+def parse_rtl_text(text: str, name: str = "source") -> ParsedRtl:
+    """Parse RTL `text` (for tests), returning its instances, literals and parse errors."""
+    tree = SyntaxTree.fromText(text, name)
+    return ParsedRtl(
+        instances=_instances(tree),
+        literals=_literals(tree),
+        parse_errors=tuple(parse_errors(tree)),
+        line_comments=_line_comments(text),
+    )
+
+
+# --------------------------------------------------------------------------------------
+# instances and their named port connections
+# --------------------------------------------------------------------------------------
+
+
+def _instances(tree: Any) -> list[Instance]:
+    sm = tree.sourceManager
+
+    def line_of(token: Any) -> int:
+        return int(sm.getLineNumber(token.location))
+
+    out: list[Instance] = []
+    for hi in _find(tree.root, SyntaxKind.HierarchyInstantiation):
+        module = _text(getattr(hi, "type", None))
+        if not module:
+            continue
+        for inst in _find(hi, SyntaxKind.HierarchicalInstance):
+            decl = getattr(inst, "decl", None)
+            name = _text(getattr(decl, "name", None)) if decl is not None else ""
+            conns: list[PortConn] = []
+            for npc in _find(inst, SyntaxKind.NamedPortConnection):
+                port = _text(getattr(npc, "name", None))
+                if not port:
+                    continue
+                expr = _text(getattr(npc, "expr", None))
+                conns.append(PortConn(port=port, expr=expr, line=line_of(npc.getFirstToken())))
+            out.append(
+                Instance(
+                    module=module,
+                    name=name,
+                    line=line_of(inst.getFirstToken()),
+                    connections=tuple(conns),
+                )
+            )
+    return out
+
+
+# --------------------------------------------------------------------------------------
+# integer literals (tokens, so comments and strings are never scanned)
+# --------------------------------------------------------------------------------------
+
+_RADIX = {"b": 2, "o": 8, "d": 10, "h": 16}
+
+
+def _literals(tree: Any) -> list[IntLiteral]:
+    """Every integer literal in `tree`, decoded, in source order.
+
+    Works on the token stream, so numbers inside comments or strings are never seen. A
+    sized literal (`32'h8000_4000`) is three tokens -- the size `IntegerLiteral`, the
+    `IntegerBase` (`'h`) and the digits `IntegerLiteral` -- so the size token is skipped
+    and the digits are decoded with the base's radix. A bare `IntegerLiteral` with no
+    base before or after it is a plain decimal.
+    """
+    sm = tree.sourceManager
+    tokens = _tokens(tree.root)
+    out: list[IntLiteral] = []
+    for i, tok in enumerate(tokens):
+        kind = str(getattr(tok, "kind", ""))
+        if not kind.endswith("IntegerLiteral"):
+            continue
+        prev = str(getattr(tokens[i - 1], "kind", "")) if i > 0 else ""
+        nxt = str(getattr(tokens[i + 1], "kind", "")) if i + 1 < len(tokens) else ""
+        raw = str(getattr(tok, "rawText", "") or "")
+        line = int(sm.getLineNumber(tok.location))
+        if prev.endswith("IntegerBase"):
+            base = str(getattr(tokens[i - 1], "rawText", "") or "").lstrip("'").lower()
+            value = _decode(raw, _RADIX.get(base[:1], 10))
+        elif nxt.endswith("IntegerBase"):
+            # A size prefix (`32` in `32'h...`), not a value of its own.
+            continue
+        else:
+            value = _decode(raw, 10)
+        if value is not None:
+            out.append(IntLiteral(value=value, line=line, raw=raw))
+    return out
+
+
+def _decode(digits: str, radix: int) -> int | None:
+    """Decode `digits` (with `_` separators) in `radix`; None if it is not a plain number.
+
+    A literal with `x`/`z`/`?` bits (`8'bxxxx_xxxx`) has no single value, so it is
+    dropped rather than guessed at.
+    """
+    cleaned = digits.replace("_", "")
+    if not cleaned:
+        return None
+    try:
+        return int(cleaned, radix)
+    except ValueError:
+        return None
+
+
+# --------------------------------------------------------------------------------------
+# shared token/node walking
+# --------------------------------------------------------------------------------------
+
+
+def _find(node: Any, kind: SyntaxKind) -> list[Any]:
+    out: list[Any] = []
+
+    def walk(n: Any) -> None:
+        if n is None:
+            return
+        if getattr(n, "kind", None) == kind:
+            out.append(n)
+        if isinstance(n, SyntaxNode):
+            for i in range(len(n)):
+                try:
+                    child = n[i]
+                except Exception:  # pragma: no cover - defensive against odd child slots
+                    child = None
+                walk(child)
+
+    walk(node)
+    return out
+
+
+def _tokens(node: Any) -> list[Any]:
+    out: list[Any] = []
+
+    def walk(n: Any) -> None:
+        if n is None:
+            return
+        if isinstance(n, SyntaxNode):
+            for i in range(len(n)):
+                try:
+                    child = n[i]
+                except Exception:  # pragma: no cover - defensive against odd child slots
+                    child = None
+                walk(child)
+        else:
+            out.append(n)
+
+    walk(node)
+    return out
+
+
+def _text(node: Any) -> str:
+    """The trimmed source text of `node` (or a token), or '' when it is None/missing."""
+    if node is None:
+        return ""
+    if getattr(node, "isMissing", False):
+        return ""
+    return str(node).strip()
+
+
+def _line_comments(text: str) -> dict[int, str]:
+    """Map each 1-based line number to its `//` comment text (without the `//`), if any.
+
+    A best-effort text scan used only to read a `// contract:`-style exemption marker;
+    the literals themselves come from the token stream, never from this.
+    """
+    out: dict[int, str] = {}
+    for i, line in enumerate(text.splitlines(), start=1):
+        idx = line.find("//")
+        if idx >= 0:
+            out[i] = line[idx + 2 :]
+    return out
+
+
+__all__ = [
+    "Instance",
+    "IntLiteral",
+    "ParsedRtl",
+    "PortConn",
+    "parse_rtl",
+    "parse_rtl_text",
+]

chipgraph/checks/cdc_struct.py

@@ -0,0 +1,235 @@
+"""`CdcStructCheck`: structural clock-domain-crossing check on the Design Model (layer 1).
+
+A layer-1 (structure) check (DESIGN.md 4.8): a signal that crosses from one clock domain
+to another must pass through a synchroniser cell declared in the profile (e.g.
+`qnsc_sync`). A crossing that goes straight into a flop of another domain -- directly or
+through plain combinational logic -- is an error.
+
+The Design Model does not hold nets or connections (`adapters/tool/pyslang.py`), so this
+check elaborates the block's RTL itself (`_cdc_elaborate`) and analyses clock domains and
+their crossings structurally (`_cdc_analyze`). It is a per-block check: it runs on the RTL
+of the block being checked. Issues cite the destination flop's file and line.
+
+Rules:
+
+* `cdc.unsynchronised` (error): a register samples another domain with no synchroniser.
+* `cdc.unknown_domain` (info): a register samples an input whose clock domain is unknown.
+* `cdc.not_analysed` (info): a path leaves what this structural check resolves.
+
+Args:
+
+* `sync_cells` (list of str, required): module names that are synchronisers.
+* `scope` (list of glob str, optional): RTL files to analyse; `{block}` is substituted
+  from `ctx.params`. Defaults to the files of the RTL modules the model attributes to the
+  block, plus the files of every module they instantiate (so a synchroniser or child IP
+  the block wires up is elaborated and recognised, not treated as an unknown blackbox).
+* `clock_patterns` (list of str, optional): regexes that recognise a clock port by name
+  (default `^i_clk`, `^clk`).
+* `ignore` (list of glob str, optional): files to drop (default: any `vendor` path).
+
+Example profile usage (`.chipgraph.yml`):
+
+```yaml
+adapters:
+  cdc_struct:
+    use: cdc_struct
+    sync_cells: [qnsc_sync]
+```
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from pathlib import Path
+
+from chipgraph.checks._cdc_analyze import Crossing, Kind, analyse
+from chipgraph.checks._cdc_elaborate import elaborate
+from chipgraph.checks._common import (
+    ArgError,
+    compute_idempotency_key,
+    error_result,
+    glob_to_regex,
+    iter_repo_files,
+    optional_list_of_str,
+    require_list_of_str,
+    sha256_file,
+)
+from chipgraph.checks._model import ModelUnavailable, block_param, load_model
+from chipgraph.core.contracts import CheckResult, CheckSpec, Issue
+from chipgraph.core.contracts.types import CheckStatus, Severity
+from chipgraph.core.model.entities import ModuleEntity
+from chipgraph.core.model.model import DesignModel
+from chipgraph.core.plugin_api.types import ToolContext
+
+_DEFAULT_CLOCK_PATTERNS = (r"^i_clk", r"^clk")
+_DEFAULT_IGNORE = ("**/vendor/**", "vendor/**")
+
+_RULE_BY_KIND: dict[Kind, tuple[str, Severity]] = {
+    Kind.UNSYNCHRONISED: ("cdc.unsynchronised", "error"),
+    Kind.UNKNOWN_DOMAIN: ("cdc.unknown_domain", "info"),
+    Kind.NOT_ANALYSED: ("cdc.not_analysed", "info"),
+}
+
+
+class CdcStructCheck:
+    """Checks that every clock-domain crossing goes through a declared synchroniser."""
+
+    id = "cdc_struct"
+    name = "CDC (structural)"
+    per_block = True  # a block's RTL is analysed at a time
+
+    async def run(self, spec: CheckSpec, ctx: ToolContext) -> CheckResult:
+        start = time.monotonic()
+        args = spec.args
+        block = block_param(ctx)
+        try:
+            sync_cells = frozenset(require_list_of_str(args, "sync_cells"))
+            scope = [_substitute(g, block) for g in optional_list_of_str(args, "scope")]
+            ignore = optional_list_of_str(args, "ignore") or list(_DEFAULT_IGNORE)
+            clock_patterns = optional_list_of_str(args, "clock_patterns") or list(
+                _DEFAULT_CLOCK_PATTERNS
+            )
+            clock_matchers = [re.compile(p) for p in clock_patterns]
+        except (ArgError, re.error) as exc:
+            return error_result(spec, str(exc), start)
+
+        try:
+            loaded = load_model(ctx.repo_root)
+        except ModelUnavailable as exc:
+            return error_result(spec, str(exc), start, rule="model")
+
+        block_modules = _block_modules(loaded.model, block)
+
+        scope_files = _scope_files(ctx.repo_root, scope, ignore, loaded.model, block_modules)
+        if not scope_files:
+            # Nothing to analyse (a block with no RTL yet): a clean pass, not an error.
+            return _result(spec, [], scope_files, ctx.repo_root, loaded.build_inputs_hash, start)
+
+        tops = {m.name for m in block_modules} or None
+        elaboration = elaborate(
+            (ctx.repo_root / f for f in scope_files),
+            sync_cells=sync_cells,
+            clock_matchers=clock_matchers,
+            repo_root=ctx.repo_root,
+            tops=tops,
+        )
+
+        issues: list[Issue] = [
+            Issue(
+                file=diag.file,
+                line=diag.line,
+                rule="parse",
+                severity="error",
+                msg=f"elaboration error: {diag.message}",
+            )
+            for diag in elaboration.diagnostics
+        ]
+        for module in sorted(elaboration.modules):
+            for crossing in analyse(elaboration.modules[module]):
+                issues.append(_issue(crossing))
+
+        return _result(spec, issues, scope_files, ctx.repo_root, loaded.build_inputs_hash, start)
+
+
+def _issue(crossing: Crossing) -> Issue:
+    rule, severity = _RULE_BY_KIND[crossing.kind]
+    return Issue(
+        file=crossing.loc.file,
+        line=crossing.loc.line,
+        rule=rule,
+        severity=severity,
+        msg=crossing.detail,
+    )
+
+
+def _block_modules(model: DesignModel, block: str | None) -> list[ModuleEntity]:
+    """The RTL modules the model attributes to `block` (all modules when no block)."""
+    block_key = f"block:{block}" if block else None
+    out: list[ModuleEntity] = []
+    for entity in model.by_kind("module"):
+        assert isinstance(entity, ModuleEntity)
+        if block_key is None or entity.block == block_key:
+            out.append(entity)
+    return out
+
+
+def _scope_files(
+    repo_root: Path,
+    scope: list[str],
+    ignore: list[str],
+    model: DesignModel,
+    block_modules: list[ModuleEntity],
+) -> list[str]:
+    """The repo-relative RTL files to analyse, deterministically ordered.
+
+    An explicit `scope` (globs, `{block}` already substituted) wins. Otherwise the files
+    of the block's modules, *plus* the files of every module they instantiate (following
+    `instantiates` transitively): so a synchroniser or child IP the block wires up is
+    elaborated too and can be recognised, instead of being an unknown blackbox. `ignore`
+    globs (vendor by default) are dropped either way, so a vendored cell is not analysed
+    as a top of its own.
+    """
+    ignore_regexes = [glob_to_regex(p) for p in ignore]
+
+    def kept(rel: str) -> bool:
+        return not any(r.fullmatch(rel) for r in ignore_regexes)
+
+    if scope:
+        regexes = [glob_to_regex(g) for g in scope]
+        return sorted(
+            f
+            for f in iter_repo_files(repo_root)
+            if any(r.fullmatch(f) for r in regexes) and kept(f)
+        )
+
+    files = {m.file for m in _with_instantiated(model, block_modules) if m.file}
+    return sorted(f for f in files if kept(f))
+
+
+def _with_instantiated(model: DesignModel, block_modules: list[ModuleEntity]) -> list[ModuleEntity]:
+    """`block_modules` plus every module reachable through `instantiates`, deduped."""
+    by_key = {m.key: m for m in model.by_kind("module") if isinstance(m, ModuleEntity)}
+    seen: dict[str, ModuleEntity] = {m.key: m for m in block_modules}
+    frontier = list(seen)
+    while frontier:
+        src = frontier.pop()
+        for rel in model.get_relations(src=src, kind="instantiates"):
+            child = by_key.get(rel.dst)
+            if child is not None and child.key not in seen:
+                seen[child.key] = child
+                frontier.append(child.key)
+    return list(seen.values())
+
+
+def _substitute(glob: str, block: str | None) -> str:
+    if "{block}" not in glob:
+        return glob
+    if block is None:
+        raise ArgError(f"scope glob {glob!r} uses {{block}} but no block is set in ctx.params")
+    return glob.replace("{block}", block)
+
+
+def _result(
+    spec: CheckSpec,
+    issues: list[Issue],
+    scope_files: list[str],
+    repo_root: Path,
+    build_inputs_hash: str | None,
+    start: float,
+) -> CheckResult:
+    ordered = sorted(issues, key=lambda i: (i.file or "", i.line or 0, i.rule, i.msg))
+    file_hashes = [(f, sha256_file(repo_root / f)) for f in scope_files]
+    file_hashes.append(("<model>", build_inputs_hash or "none"))
+    key = compute_idempotency_key(spec.id, spec.args, file_hashes)
+    status: CheckStatus = "fail" if any(i.severity == "error" for i in ordered) else "pass"
+    return CheckResult(
+        check_id=spec.id,
+        status=status,
+        issues=tuple(ordered),
+        duration_s=time.monotonic() - start,
+        idempotency_key=key,
+    )
+
+
+__all__ = ["CdcStructCheck"]