chipgraph 0.1.0__py3-none-any.whl

chipgraph/checks/generated.py

@@ -0,0 +1,151 @@
+"""`GeneratedCheck`: generated files are not edited by hand.
+
+Also exports `stamp`/`verify`, the two functions generators use to mark a file as
+generated and later confirm it has not been hand-edited. See DESIGN.md 7.3.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import time
+
+from chipgraph.checks._common import (
+    ArgError,
+    compute_idempotency_key,
+    error_result,
+    glob_to_regex,
+    iter_repo_files,
+    optional_bool,
+    require_list_of_str,
+    sha256_file,
+)
+from chipgraph.core.contracts import CheckResult, CheckSpec, Issue
+from chipgraph.core.contracts.types import CheckStatus
+from chipgraph.core.plugin_api.types import ToolContext
+
+_MARKER_SEARCH_LINES = 20
+_COMMENT_CLOSERS = {"<!--": " -->"}
+
+# A marker line: an optional comment prefix, then `chipgraph:generated sha256=<64 hex>`,
+# then an optional closer (for `<!--`-style comments).
+_MARKER_RE = re.compile(
+    r"^\s*(?://|#|--|;|<!--)?\s*chipgraph:generated sha256=([0-9a-f]{64})\s*(?:-->)?\s*$"
+)
+
+
+def stamp(text: str, comment_prefix: str = "//") -> str:
+    """Insert or replace the generation marker as the first line of `text`.
+
+    The marker's hash covers `text` with any existing marker's first line removed, so
+    calling `stamp` again on already-stamped, unedited text is a no-op (byte for byte).
+    """
+    lines = text.splitlines(keepends=True)
+    has_marker = bool(lines) and _MARKER_RE.match(_strip_eol(lines[0])) is not None
+    base_text = "".join(lines[1:]) if has_marker else text
+
+    digest = hashlib.sha256(base_text.encode("utf-8")).hexdigest()
+    closer = _COMMENT_CLOSERS.get(comment_prefix, "")
+    eol = _eol_of(lines[0]) if lines else "\n"
+    marker_line = f"{comment_prefix} chipgraph:generated sha256={digest}{closer}{eol}"
+    return marker_line + base_text
+
+
+def verify(text: str) -> bool | None:
+    """Check `text`'s generation marker against its content.
+
+    Returns `True` if the marker matches, `False` if it does not (hand-edited), or
+    `None` if no marker is found in the first 20 lines.
+    """
+    lines = text.splitlines(keepends=True)
+    limit = min(len(lines), _MARKER_SEARCH_LINES)
+    for i in range(limit):
+        m = _MARKER_RE.match(_strip_eol(lines[i]))
+        if m is None:
+            continue
+        stored = m.group(1)
+        remainder = "".join(lines[:i] + lines[i + 1 :])
+        actual = hashlib.sha256(remainder.encode("utf-8")).hexdigest()
+        return actual == stored
+    return None
+
+
+def _strip_eol(line: str) -> str:
+    return line.rstrip("\n").rstrip("\r")
+
+
+def _eol_of(line: str) -> str:
+    if line.endswith("\r\n"):
+        return "\r\n"
+    if line.endswith("\n"):
+        return "\n"
+    return "\n"
+
+
+class GeneratedCheck:
+    """Checks that generated files still match the marker hash they were stamped with."""
+
+    id = "generated"
+    name = "Generated"
+
+    async def run(self, spec: CheckSpec, ctx: ToolContext) -> CheckResult:
+        start = time.monotonic()
+        args = spec.args
+
+        try:
+            globs = require_list_of_str(args, "files")
+            require_marker = optional_bool(args, "require_marker", False)
+            regexes = [glob_to_regex(g) for g in globs]
+        except ArgError as exc:
+            return error_result(spec, str(exc), start)
+
+        all_files = iter_repo_files(ctx.repo_root)
+        matched = [f for f in all_files if any(r.fullmatch(f) for r in regexes)]
+
+        issues: list[Issue] = []
+        read_files: dict[str, str] = {}
+        for f in matched:
+            full_path = ctx.repo_root / f
+            read_files[f] = sha256_file(full_path)
+            try:
+                text = full_path.read_text()
+            except (OSError, UnicodeDecodeError) as exc:
+                issues.append(
+                    Issue(
+                        file=f,
+                        rule="generated",
+                        severity="error",
+                        msg=f"could not read `{f}`: {exc}",
+                    )
+                )
+                continue
+
+            result = verify(text)
+            if result is False:
+                issues.append(
+                    Issue(
+                        file=f,
+                        rule="generated",
+                        severity="error",
+                        msg=f"`{f}` was edited by hand after it was generated",
+                    )
+                )
+            elif result is None:
+                issues.append(
+                    Issue(
+                        file=f,
+                        rule="generated",
+                        severity="error" if require_marker else "warning",
+                        msg=f"`{f}` has no generation marker",
+                    )
+                )
+
+        key = compute_idempotency_key(spec.id, args, tuple(read_files.items()))
+        status: CheckStatus = "fail" if any(i.severity == "error" for i in issues) else "pass"
+        return CheckResult(
+            check_id=spec.id,
+            status=status,
+            issues=tuple(issues),
+            duration_s=time.monotonic() - start,
+            idempotency_key=key,
+        )

chipgraph/checks/hardcode.py

@@ -0,0 +1,233 @@
+"""`HardcodeCheck`: numbers the contract already names must not be typed by hand in RTL.
+
+A layer-1 (structure) cross check (DESIGN.md 7.3). It reads the Design Model
+`chipgraph ingest` wrote for the shared numbers a design must not duplicate, scans the
+integer literals of the RTL files in scope (via the pyslang token stream, so numbers
+inside comments and strings are never seen; sized literals like `32'h8000_4000` are
+decoded), and reports each literal that equals a shared number.
+
+Shared numbers come from the model:
+
+* every memory region's base, size and end address (`base + size`) whose value is at
+  least arg `min_value` (default `0x100`); and
+* every interrupt line number, but only counted when the literal is used as an index on
+  the arg `irq_vector` net (small line numbers are otherwise indistinguishable from
+  ordinary constants, so they are not flagged elsewhere).
+
+A `hardcode.literal` issue is *not* raised when the literal's line carries the arg
+`allow_comment` marker (default `contract:`, matching QSoC's `// contract: <key>` tag) or
+when the file is one of the generated packages listed in arg `generated`.
+
+A missing model is a whole-check `error` (run `chipgraph ingest` first).
+
+Example profile usage (`.chipgraph.yml`):
+
+```yaml
+adapters:
+  hardcode:
+    use: hardcode
+    scope: ["design/**/rtl/**/*.sv"]
+    min_value: 0x100
+    generated: ["design/common/rtl/qnsc_pkg.sv"]
+```
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from pathlib import Path
+
+from chipgraph.checks._common import (
+    ArgError,
+    compute_idempotency_key,
+    error_result,
+    glob_to_regex,
+    iter_repo_files,
+    optional_list_of_str,
+    optional_str,
+    require_list_of_str,
+    sha256_file,
+)
+from chipgraph.checks._model import ModelUnavailable, load_model
+from chipgraph.checks._xref_syntax import parse_rtl
+from chipgraph.core.contracts import CheckResult, CheckSpec, Issue
+from chipgraph.core.contracts.types import CheckStatus
+from chipgraph.core.model.model import DesignModel
+from chipgraph.core.plugin_api.types import ToolContext
+
+_DEFAULT_MIN_VALUE = 0x100
+_DEFAULT_ALLOW_COMMENT = "contract:"
+
+
+class HardcodeCheck:
+    """Checks that no RTL literal duplicates a memory-map or interrupt number."""
+
+    id = "hardcode"
+    name = "Hardcode"
+    per_block = False  # chip-wide: `chipgraph check` runs it once, not per block
+
+    async def run(self, spec: CheckSpec, ctx: ToolContext) -> CheckResult:
+        start = time.monotonic()
+        args = spec.args
+
+        try:
+            scope = require_list_of_str(args, "scope")
+            if not scope:
+                raise ArgError("args['scope'] must list at least one glob")
+            min_value = _int_arg(args, "min_value", _DEFAULT_MIN_VALUE)
+            allow_comment = optional_str(args, "allow_comment", _DEFAULT_ALLOW_COMMENT)
+            generated = set(optional_list_of_str(args, "generated"))
+            ignore = optional_list_of_str(args, "ignore")
+            irq_vector = optional_str(args, "irq_vector", "")
+        except ArgError 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")
+
+        shared = _shared_numbers(loaded.model, min_value)
+        irq_lines = _interrupt_lines(loaded.model)
+
+        scope_regexes = [glob_to_regex(p) for p in scope]
+        ignore_regexes = [glob_to_regex(p) for p in ignore]
+        in_scope = [
+            f
+            for f in iter_repo_files(ctx.repo_root)
+            if any(r.fullmatch(f) for r in scope_regexes)
+            and not any(r.fullmatch(f) for r in ignore_regexes)
+        ]
+
+        issues: list[Issue] = []
+        for rel in in_scope:
+            if rel in generated:
+                continue
+            issues.extend(
+                _file_issues(ctx.repo_root / rel, rel, shared, irq_lines, allow_comment, irq_vector)
+            )
+        issues.sort(key=lambda i: (i.file or "", i.line or 0, i.rule, i.msg))
+
+        file_hashes = [(f, sha256_file(ctx.repo_root / f)) for f in in_scope]
+        file_hashes.append(("<model>", loaded.build_inputs_hash or "none"))
+        key = compute_idempotency_key(spec.id, args, file_hashes)
+        status: CheckStatus = "fail" if any(i.severity == "error" for i in issues) else "pass"
+        return CheckResult(
+            check_id=spec.id,
+            status=status,
+            issues=tuple(issues),
+            duration_s=time.monotonic() - start,
+            idempotency_key=key,
+        )
+
+
+def _int_arg(args: object, key: str, default: int) -> int:
+    from collections.abc import Mapping
+
+    if not isinstance(args, Mapping) or key not in args:
+        return default
+    val = args[key]
+    if isinstance(val, bool) or not isinstance(val, int):
+        raise ArgError(f"args[{key!r}] must be an integer")
+    return val
+
+
+def _shared_numbers(model: DesignModel, min_value: int) -> dict[int, list[str]]:
+    """Map each shared memory-map number (>= `min_value`) to the model keys naming it."""
+    out: dict[int, list[str]] = {}
+
+    def add(value: object, label: str) -> None:
+        if isinstance(value, bool) or not isinstance(value, int):
+            return
+        if value < min_value:
+            return
+        out.setdefault(value, [])
+        if label not in out[value]:
+            out[value].append(label)
+
+    for region in model.by_kind("memory_region"):
+        base = getattr(region, "base", None)
+        size = getattr(region, "size", None)
+        add(base, f"{region.key}.base")
+        add(size, f"{region.key}.size")
+        if isinstance(base, int) and isinstance(size, int):
+            add(base + size, f"{region.key}.end")
+    return out
+
+
+def _interrupt_lines(model: DesignModel) -> dict[int, list[str]]:
+    """Map each interrupt line number to the interrupt keys that use it."""
+    out: dict[int, list[str]] = {}
+    for irq in model.by_kind("interrupt"):
+        line = getattr(irq, "line", None)
+        if isinstance(line, int) and not isinstance(line, bool):
+            out.setdefault(line, [])
+            if irq.key not in out[line]:
+                out[line].append(irq.key)
+    return out
+
+
+def _file_issues(
+    path: Path,
+    rel: str,
+    shared: dict[int, list[str]],
+    irq_lines: dict[int, list[str]],
+    allow_comment: str,
+    irq_vector: str,
+) -> list[Issue]:
+    parsed = parse_rtl(path)
+    issues: list[Issue] = [
+        Issue(
+            file=rel, line=pf.line, rule="parse", severity="error", msg=f"parse error: {pf.message}"
+        )
+        for pf in parsed.parse_errors
+    ]
+    text_lines = path.read_text(errors="ignore").splitlines()
+    index_re = re.compile(rf"{re.escape(irq_vector)}\s*\[\s*(\d+)\s*\]") if irq_vector else None
+
+    for lit in parsed.literals:
+        if _has_marker(parsed.line_comments.get(lit.line, ""), allow_comment):
+            continue
+        keys = shared.get(lit.value)
+        if keys:
+            issues.append(
+                Issue(
+                    file=rel,
+                    line=lit.line,
+                    rule="hardcode.literal",
+                    severity="error",
+                    msg=(
+                        f"literal {lit.raw!r} (= {lit.value}) duplicates the contract number "
+                        f"{', '.join(sorted(keys))}; take it from the contract, "
+                        f"or tag the line `// {allow_comment} <key>`"
+                    ),
+                )
+            )
+            continue
+        # An interrupt line number only counts as a shared number when used as an index
+        # on the interrupt vector net.
+        if index_re is not None and lit.value in irq_lines:
+            line_text = text_lines[lit.line - 1] if 0 < lit.line <= len(text_lines) else ""
+            if any(int(m.group(1)) == lit.value for m in index_re.finditer(line_text)):
+                keys = irq_lines[lit.value]
+                issues.append(
+                    Issue(
+                        file=rel,
+                        line=lit.line,
+                        rule="hardcode.literal",
+                        severity="error",
+                        msg=(
+                            f"literal {lit.raw!r} indexes {irq_vector!r} at bit {lit.value}, the "
+                            f"contract line of {', '.join(sorted(keys))}; take it from the contract"
+                        ),
+                    )
+                )
+    return issues
+
+
+def _has_marker(comment: str, allow_comment: str) -> bool:
+    return allow_comment in comment
+
+
+__all__ = ["HardcodeCheck"]

chipgraph/checks/layout.py

@@ -0,0 +1,155 @@
+"""`LayoutCheck`: every file in scope lives where the project's layout templates say.
+
+See DESIGN.md 7.3 for the `layout` check and its `.chipgraph.yml` example.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from chipgraph.checks._common import (
+    ArgError,
+    CompiledTemplate,
+    compile_template,
+    compute_idempotency_key,
+    error_result,
+    glob_to_regex,
+    iter_repo_files,
+    require_dict,
+    require_list_of_str,
+    sha256_file,
+    str_or_list_of_str,
+)
+from chipgraph.core.contracts import CheckResult, CheckSpec, Issue
+from chipgraph.core.contracts.types import CheckStatus
+from chipgraph.core.plugin_api.types import ToolContext
+
+
+class LayoutCheck:
+    """Checks that every in-scope file matches at least one declared layout template."""
+
+    id = "layout"
+    name = "Layout"
+
+    async def run(self, spec: CheckSpec, ctx: ToolContext) -> CheckResult:
+        start = time.monotonic()
+        args = spec.args
+
+        try:
+            templates_by_kind = _flatten_templates(require_dict(args, "templates"))
+            scope = require_list_of_str(args, "scope")
+            ignore = args.get("ignore", [])
+            if not isinstance(ignore, list) or not all(isinstance(v, str) for v in ignore):
+                raise ArgError("args['ignore'] must be a list of strings")
+            values = _parse_values(args.get("values", {}))
+            _check_no_duplicate_templates(templates_by_kind)
+            compiled = [(kind, tmpl, compile_template(tmpl)) for kind, tmpl in templates_by_kind]
+        except ArgError as exc:
+            return error_result(spec, str(exc), start)
+
+        scope_regexes = [glob_to_regex(p) for p in scope]
+        ignore_regexes = [glob_to_regex(p) for p in ignore]
+
+        all_files = iter_repo_files(ctx.repo_root)
+        in_scope = [
+            f
+            for f in all_files
+            if any(r.fullmatch(f) for r in scope_regexes)
+            and not any(r.fullmatch(f) for r in ignore_regexes)
+        ]
+
+        issues: list[Issue] = []
+        for path in in_scope:
+            issues.extend(_check_file(path, compiled, values))
+
+        file_hashes = tuple((f, sha256_file(ctx.repo_root / f)) for f in in_scope)
+        key = compute_idempotency_key(spec.id, args, file_hashes)
+        status: CheckStatus = "fail" if any(i.severity == "error" for i in issues) else "pass"
+        return CheckResult(
+            check_id=spec.id,
+            status=status,
+            issues=tuple(issues),
+            duration_s=time.monotonic() - start,
+            idempotency_key=key,
+        )
+
+
+def _flatten_templates(templates: dict[str, Any]) -> list[tuple[str, str]]:
+    out: list[tuple[str, str]] = []
+    for kind, val in templates.items():
+        for tmpl in str_or_list_of_str(val, f"args['templates'][{kind!r}]"):
+            out.append((kind, tmpl))
+    if not out:
+        raise ArgError("args['templates'] must declare at least one template")
+    return out
+
+
+def _check_no_duplicate_templates(templates_by_kind: list[tuple[str, str]]) -> None:
+    seen: dict[str, str] = {}
+    for kind, tmpl in templates_by_kind:
+        if tmpl in seen:
+            raise ArgError(f"templates {seen[tmpl]!r} and {kind!r} are identical: {tmpl!r}")
+        seen[tmpl] = kind
+
+
+def _parse_values(raw: Any) -> dict[str, list[str]]:
+    if not isinstance(raw, dict):
+        raise ArgError("args['values'] must be a mapping")
+    out: dict[str, list[str]] = {}
+    for name, allowed in raw.items():
+        out[name] = str_or_list_of_str(allowed, f"args['values'][{name!r}]")
+    return out
+
+
+def _check_file(
+    path: str,
+    compiled: list[tuple[str, str, CompiledTemplate]],
+    values: dict[str, list[str]],
+) -> list[Issue]:
+    matches: list[tuple[str, dict[str, str]]] = []
+    for kind, _tmpl, compiled_tmpl in compiled:
+        groups = compiled_tmpl.match(path)
+        if groups is not None:
+            matches.append((kind, groups))
+
+    if not matches:
+        return [
+            Issue(
+                file=path,
+                rule="layout",
+                severity="error",
+                msg=f"`{path}` is not in any layout template",
+            )
+        ]
+
+    # A file may syntactically match more than one template (e.g. an overly broad and a
+    # more specific one). It passes if at least one match has only allowed placeholder
+    # values; otherwise we report the value violations of the first match.
+    first_violations: list[Issue] | None = None
+    for _kind, groups in matches:
+        violations = _value_violations(path, groups, values)
+        if not violations:
+            return []
+        if first_violations is None:
+            first_violations = violations
+    assert first_violations is not None
+    return first_violations
+
+
+def _value_violations(
+    path: str, groups: dict[str, str], values: dict[str, list[str]]
+) -> list[Issue]:
+    issues: list[Issue] = []
+    for name, val in groups.items():
+        allowed = values.get(name)
+        if allowed is not None and val not in allowed:
+            issues.append(
+                Issue(
+                    file=path,
+                    rule="layout",
+                    severity="error",
+                    msg=f"{name} `{val}` is not one of: {', '.join(allowed)}",
+                )
+            )
+    return issues