chipgraph 0.1.0__py3-none-any.whl

chipgraph/packs/digital_rtl/layout.py

@@ -0,0 +1,144 @@
+"""Where a block's RTL and testbench files go: from the profile's `layout` (M2-11a).
+
+A project says where each kind of file lives with `layout:` templates (and per block,
+`blocks.<b>.layout`). The built-in rules write new files there:
+
+- `digital-rtl/rtl_module` writes `{layout.rtl}/{module}.sv`;
+- `dv/tb_module` writes `{layout.tb}/test_{block}.py`;
+- a plan's write sets must stay inside the block's `rtl` and `tb` layout paths.
+
+`layout_dir(resolved, block, kind)` is the directory part of the block's first `kind`
+template: `{block}`/`{BLOCK}` filled in, cut before the file name and before the first
+segment with a glob or another placeholder. QSoC's `design/{block}/rtl/*.sv` gives
+`design/pwm/rtl` for `pwm`; tinysoc's `rtl/*.sv` gives `rtl`; `dv/{block}/**` gives
+`dv/timer`. With a list of templates the first one is where new files go.
+
+`layout_vars(resolved, block)` is what the graph fills `{layout.rtl}` and `{layout.tb}`
+with (template values, not params: they never change an instance id). A project with no
+`rtl` or `tb` layout key keeps the built-in defaults, `rtl` and `dv/{block}`.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+
+from chipgraph.core.config.loader import ResolvedProfile
+from chipgraph.core.config.models import Profile
+
+LayoutValue = str | tuple[str, ...]
+
+RTL_VAR = "layout.rtl"
+"""The template value of the block's RTL directory."""
+TB_VAR = "layout.tb"
+"""The template value of the block's testbench directory."""
+
+DEFAULT_DIRS: Mapping[str, str] = {"rtl": "rtl", "tb": "dv/{block}"}
+"""The directories the built-in rules use when the profile has no layout key for a kind."""
+
+_KINDS: Mapping[str, str] = {RTL_VAR: "rtl", TB_VAR: "tb"}
+_DYNAMIC = re.compile(r"[*?\[\]{}]")
+
+
+class LayoutError(ValueError):
+    """The profile's layout does not say where a kind of file goes."""
+
+
+def _profile(resolved: ResolvedProfile | Profile, block: str) -> Profile:
+    if isinstance(resolved, ResolvedProfile):
+        return resolved.for_block(block)
+    override = resolved.blocks.get(block)
+    if override is not None and override.layout:
+        return resolved.model_copy(update={"layout": {**resolved.layout, **override.layout}})
+    return resolved
+
+
+def _fill(template: str, block: str) -> str:
+    return template.replace("{block}", block).replace("{BLOCK}", block.upper())
+
+
+def templates(resolved: ResolvedProfile | Profile, block: str, kind: str) -> tuple[str, ...]:
+    """The block's `kind` layout templates, `{block}`/`{BLOCK}` filled in (maybe none)."""
+    value: LayoutValue | None = _profile(resolved, block).layout.get(kind)
+    if value is None:
+        return ()
+    raw = (value,) if isinstance(value, str) else tuple(value)
+    return tuple(_fill(t, block) for t in raw)
+
+
+def template_dir(template: str) -> str:
+    """The directory part of a filled layout template ('' when it has none)."""
+    parts = template.split("/")
+    out: list[str] = []
+    for part in parts[:-1]:  # the last segment is the file (or `**`)
+        if not part or part == "." or _DYNAMIC.search(part):
+            break
+        out.append(part)
+    return "/".join(out)
+
+
+def layout_dir(resolved: ResolvedProfile | Profile, block: str, kind: str) -> str:
+    """The directory new `kind` files of `block` go to (see the module docstring).
+
+    Raises `LayoutError` when the block's layout has no `kind` key, or its first
+    template has no directory part.
+    """
+    found = templates(resolved, block, kind)
+    if not found:
+        raise LayoutError(
+            f"block {block!r} has no layout.{kind}: say where its {kind} files go in "
+            f'.chipgraph.yml, e.g. `layout: {{ {kind}: "<dir>/*" }}`'
+        )
+    directory = template_dir(found[0])
+    if not directory or directory == ".." or directory.startswith("../"):
+        raise LayoutError(
+            f"block {block!r}: layout.{kind} {found[0]!r} has no directory part before its "
+            "first glob or placeholder; start it with the directory, e.g. 'rtl/*.sv'"
+        )
+    return directory
+
+
+def dir_or_default(resolved: ResolvedProfile | Profile, block: str, kind: str) -> str:
+    """`layout_dir`, or the built-in default (`DEFAULT_DIRS`) when the key is missing."""
+    if not templates(resolved, block, kind):
+        return _fill(DEFAULT_DIRS[kind], block)
+    return layout_dir(resolved, block, kind)
+
+
+def layout_vars(resolved: ResolvedProfile | Profile, block: str) -> dict[str, str]:
+    """`{layout.rtl}` and `{layout.tb}` for `block` (raises `LayoutError` on a bad template)."""
+    return {var: dir_or_default(resolved, block, kind) for var, kind in _KINDS.items()}
+
+
+def write_globs(resolved: ResolvedProfile | Profile, block: str) -> tuple[str, ...]:
+    """The paths a plan of `block` may write: its `rtl` and `tb` layout templates.
+
+    A kind with no layout key allows everything under its default directory.
+    """
+    out: list[str] = []
+    for kind in ("rtl", "tb"):
+        found = templates(resolved, block, kind)
+        out.extend(found or (f"{_fill(DEFAULT_DIRS[kind], block)}/**",))
+    return tuple(dict.fromkeys(out))
+
+
+def fill_vars(template: str, values: Mapping[str, str]) -> str:
+    """`template` with each `{name}` of `values` replaced; other placeholders stay."""
+    for name, value in values.items():
+        template = template.replace("{" + name + "}", value)
+    return template
+
+
+__all__ = [
+    "DEFAULT_DIRS",
+    "RTL_VAR",
+    "TB_VAR",
+    "LayoutError",
+    "dir_or_default",
+    "fill_vars",
+    "layout_dir",
+    "layout_vars",
+    "template_dir",
+    "templates",
+    "write_globs",
+]

chipgraph/packs/digital_rtl/pack.yml

@@ -0,0 +1,25 @@
+schema_version: 1
+name: digital-rtl
+version: 0.1.0
+description: >-
+  Rules and skills for digital RTL (DESIGN.md 8.2). Ships the Critic review of a block's
+  change (the rule `digital-rtl/review`, the skill `review/diff`) and the Planner: the
+  rule `digital-rtl/plan` (skill `plan/modules`, check `plan_check`) and the gate
+  `plan:{block}` on `digital-rtl/plan_expand`, after which rules may say
+  `foreach: plan.modules`; and the RTL of each planned module: the rule
+  `digital-rtl/rtl_module` (role `rtl-author`, which never sees a testbench; skills
+  `lang-sv/rtl` and `org/naming`; checks format, lint, naming, style, hardcode). The
+  target `rtl:<block>` (`targets/`) ties them to the testbench of the `dv` pack, the review and
+  a pull request: `open_pr` pushes the block's branch and opens the PR, `pr_gate` waits on
+  the gate `pr:{block}`; chipgraph never merges. Where a module goes comes from the profile's
+  `layout.rtl`, the testbench's from `layout.tb`. Also the wrappers around vendor IP in the
+  emacs verilog-mode AUTO style: the rule `digital-rtl/wrapper` (role `rtl-author`, skill
+  `rtl/wrapper-auto`) writes a wrapper's source, `digital-rtl/wrapper_gen` (tool `emacs_auto`)
+  expands it (needs Emacs 31 or newer), check `wrap_check`.
+provides:
+  rules:
+    - rules
+    - wrapper/rules
+  skills:
+    - skills
+    - wrapper/skills

chipgraph/packs/digital_rtl/plan/__init__.py

@@ -0,0 +1,34 @@
+"""A block's plan: the file a Planner writes, and what the engine does with it (M2-03).
+
+- `model`: the plan file (`Plan`, `schemas/formats/plan.schema.json`);
+- `chipgraph.checks.plan_check`: `plan_check`, the validation before a person approves;
+- `resolver`: the `foreach: plan.modules` expansion, only from an approved plan;
+- `expand`: the `plan_expand` tool behind the gate `plan:<block>`;
+- `show`: the summary `chipgraph plan show <block>` prints for the approver;
+- `context`: what a `planner` task gets in its context.
+
+Only the model is imported here: the other modules import the check, which imports the
+model, so importing them from this package's `__init__` would make a cycle.
+"""
+
+from chipgraph.packs.digital_rtl.plan.model import (
+    ModuleBudget,
+    Plan,
+    PlanInterface,
+    PlanModule,
+    PlanPort,
+    PlanWrite,
+    UnassignedReq,
+    schema_json,
+)
+
+__all__ = [
+    "ModuleBudget",
+    "Plan",
+    "PlanInterface",
+    "PlanModule",
+    "PlanPort",
+    "PlanWrite",
+    "UnassignedReq",
+    "schema_json",
+]

chipgraph/packs/digital_rtl/plan/__main__.py

@@ -0,0 +1,16 @@
+"""`python -m chipgraph.packs.digital_rtl.plan [PATH]`: write the plan file JSON Schema."""
+
+import sys
+from pathlib import Path
+
+from chipgraph.packs.digital_rtl.plan.model import schema_json
+
+
+def main() -> None:
+    out = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("schemas/formats/plan.schema.json")
+    out.write_text(schema_json(), encoding="utf-8")
+    print(f"wrote {out}")
+
+
+if __name__ == "__main__":
+    main()

chipgraph/packs/digital_rtl/plan/context.py

@@ -0,0 +1,82 @@
+"""What a `planner` task gets in its context, on top of its inputs (DESIGN.md 5.1, 5.3).
+
+So the reply is a valid plan the first time: the block's slice of the Design Model
+(requirements, interface ports, existing modules and their ports), the layout paths a
+module may write, the files that already exist there and those other rules produce,
+the files each module's writes must include, the limits, the naming rule for module
+names, and the plan file's JSON Schema.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from chipgraph.checks._common import compile_template, iter_repo_files
+from chipgraph.checks.plan_check import PlanEnv, PlanEnvError, load_env
+from chipgraph.core.config.loader import ResolvedProfile
+from chipgraph.core.contracts import RuleSpec
+from chipgraph.packs.digital_rtl.plan.model import Plan
+
+
+def _ports(ports: Sequence[Any]) -> list[dict[str, Any]]:
+    return [{"name": p.name, "direction": p.direction, "width": p.width} for p in ports]
+
+
+def _naming(env: PlanEnv) -> dict[str, Any] | None:
+    if env.naming is None:
+        return None
+    module = env.naming.kind_patterns.get("module")
+    return {
+        "rules": env.naming_ref,
+        "module": (
+            {"rule": module[0], "pattern": module[1].pattern, "message": module[2]}
+            if module is not None
+            else None
+        ),
+        "vocabulary": dict(env.naming.vocabulary.replace) if env.naming.vocabulary else {},
+    }
+
+
+def planner_context(
+    root: Path,
+    resolved: ResolvedProfile,
+    rules: Sequence[RuleSpec],
+    block: str,
+    *,
+    plan_path: str,
+) -> dict[str, Any]:
+    """The extra context of block `block`'s planner task (`get_context` key `plan`)."""
+    try:
+        env = load_env(root, block, resolved=resolved, rules=rules)
+    except PlanEnvError as exc:
+        return {"block": block, "plan_path": plan_path, "note": str(exc)}
+    layout = [compile_template(t) for t in env.layout]
+    in_layout = [f for f in iter_repo_files(root) if any(t.match(f) is not None for t in layout)]
+    taken = {**env.agent_outputs, **env.engine_outputs}
+    return {
+        "block": block,
+        "plan_path": plan_path,
+        "requirements": [
+            {"id": r.ref, "declared": r.declared, "text": r.text} for r in env.requirements
+        ],
+        "interface": {"source": env.interface_source, "ports": _ports(env.interface)},
+        "existing_modules": [
+            {"name": m.name, "file": m.file, "ports": _ports(m.ports)} for m in env.existing_modules
+        ],
+        "layout": list(env.layout),
+        "existing_files": [f for f in in_layout if f not in taken],
+        "other_rules_write": sorted(
+            p for p in taken if any(t.match(p) is not None for t in layout)
+        ),
+        "module_outputs": [
+            {"rule": rule_id, "template": template} for rule_id, template in env.module_outputs
+        ],
+        "limits": env.limits.model_dump(mode="json"),
+        "naming": _naming(env),
+        "schema": Plan.model_json_schema(),
+    }
+
+
+__all__ = ["planner_context"]

chipgraph/packs/digital_rtl/plan/expand.py

@@ -0,0 +1,94 @@
+"""`PlanExpandTool`: the `plan_expand` tool of rule `digital-rtl/plan_expand`.
+
+The rule is gated by `plan:{block}`, so the scheduler runs this only once a person has
+approved the plan at its current hash. It checks the plan once more (all of
+`plan_check`, existing files included) and writes the approved plan artifact
+(`plan/<block>.approved.json` by default): the block, the plan's path and hash, the
+modules in build order with their dependencies and write sets. Every `plan.modules`
+instance takes that artifact as an input, so it runs after this step.
+
+Rule args (both `{block}` templates): `plan` (default `plan/{block}.plan.yml`) and
+`out` (default `plan/{block}.approved.json`).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+from chipgraph.checks._common import compute_idempotency_key
+from chipgraph.checks.plan_check import (
+    DEFAULT_PLAN_PATH,
+    PlanEnvError,
+    check_plan_file,
+    topo_order,
+)
+from chipgraph.core.contracts import CheckResult, CheckSpec, Issue
+from chipgraph.core.plugin_api.types import ToolContext
+
+DEFAULT_APPROVED_PATH = "plan/{block}.approved.json"
+
+
+def _result(spec: CheckSpec, status: str, issues: tuple[Issue, ...], start: float) -> CheckResult:
+    return CheckResult(
+        check_id=spec.id,
+        status=status,  # type: ignore[arg-type]
+        issues=issues,
+        duration_s=time.monotonic() - start,
+        idempotency_key=compute_idempotency_key(spec.id, spec.args, ()),
+    )
+
+
+class PlanExpandTool:
+    """Writes a block's approved plan artifact once its gate is approved."""
+
+    name = "plan_expand"
+    capability = "gen"
+
+    async def run(self, spec: CheckSpec, ctx: ToolContext) -> CheckResult:
+        start = time.monotonic()
+        block = ctx.params.get("block")
+        plan_t = spec.args.get("plan", DEFAULT_PLAN_PATH)
+        out_t = spec.args.get("out", DEFAULT_APPROVED_PATH)
+        if not block or not isinstance(plan_t, str) or not isinstance(out_t, str):
+            msg = "plan_expand needs a block param and string 'plan'/'out' templates"
+            return _result(spec, "error", (Issue(msg=msg),), start)
+        try:
+            report = check_plan_file(ctx.repo_root, block, plan_path=plan_t)
+        except PlanEnvError as exc:
+            return _result(spec, "error", (Issue(rule="plan.env", msg=str(exc)),), start)
+        if not report.exists:
+            issue = Issue(file=report.path, rule="plan.missing", msg=f"no plan at {report.path}")
+            return _result(spec, "fail", (issue,), start)
+        if not report.ok or report.plan is None:
+            errors = tuple(i for i in report.issues if i.severity == "error")
+            return _result(spec, "fail", errors, start)
+
+        plan = report.plan
+        order = topo_order(plan)
+        artifact = {
+            "schema_version": 1,
+            "block": block,
+            "plan": report.path,
+            "plan_sha256": report.sha256,
+            "top": plan.top,
+            "order": order,
+            "modules": [
+                {
+                    "name": name,
+                    "depends_on": list(module.depends_on),
+                    "writes": list(module.write_paths),
+                    "budget": module.budget.model_dump(mode="json"),
+                }
+                for name in order
+                if (module := plan.module(name)) is not None
+            ],
+        }
+        out = ctx.repo_root / out_t.replace("{block}", block)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(json.dumps(artifact, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        warnings = tuple(i for i in report.issues if i.severity != "error")
+        return _result(spec, "pass", warnings, start)
+
+
+__all__ = ["DEFAULT_APPROVED_PATH", "PlanExpandTool"]

chipgraph/packs/digital_rtl/plan/model.py

@@ -0,0 +1,150 @@
+"""The plan file a Planner writes for one block: `plan/<block>.plan.yml` (DESIGN.md 5.1, 5.3).
+
+A plan splits a block into modules. Each module says what it does, which requirements
+it covers, its interface (ports taken from the Design Model, F1), which other modules
+it depends on, the files it writes (its write set, F2) and its budget. The plan also
+lists the assumptions it rests on (F4), the questions a person must answer, and every
+requirement of the block it does not assign, with the reason.
+
+The plan is data a person approves (gate `plan:<block>`) before any node it describes
+can run; `plan_check` (`chipgraph.checks.plan_check`) validates it. The JSON Schema is
+committed at `schemas/formats/plan.schema.json` (regenerate with
+`python -m chipgraph.packs.digital_rtl.plan`).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from chipgraph.core.contracts._paths import validate_relative_path
+from chipgraph.core.contracts.types import ModelTier
+
+_NAME_RE = r"^[A-Za-z_][A-Za-z0-9_]*$"
+_GLOB_OR_PLACEHOLDER = re.compile(r"[*?\[\]{}]")
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class PlanPort(_Model):
+    """One port of a module: from the block's interface in the Design Model, or internal."""
+
+    name: str = Field(pattern=_NAME_RE, description="The port name, as in the Design Model.")
+    direction: Literal["input", "output", "inout"] = Field(description="The port direction.")
+    width: int | str = Field(description="The port width: bits, or the model's expression.")
+    internal: bool = Field(
+        default=False,
+        description=(
+            "A helper port between modules of the block, not on the block's interface. "
+            "Not allowed on the block's top module."
+        ),
+    )
+
+
+class PlanInterface(_Model):
+    """A module's interface."""
+
+    ports: tuple[PlanPort, ...] = Field(default=(), description="The module's ports.")
+
+
+class PlanWrite(_Model):
+    """One file a module writes."""
+
+    path: str = Field(description="Repo-relative POSIX path of the file.")
+    replaces: bool = Field(
+        default=False,
+        description="The file exists and this module replaces it (said explicitly).",
+    )
+
+    @field_validator("path")
+    @classmethod
+    def _check_path(cls, value: str) -> str:
+        validate_relative_path(value, field_name="writes.path")
+        if _GLOB_OR_PLACEHOLDER.search(value):
+            raise ValueError(f"writes.path must be a plain file path, got {value!r}")
+        return value
+
+
+class ModuleBudget(_Model):
+    """How much a module's nodes may spend: tries and the model tier."""
+
+    tries: int = Field(default=3, ge=1, description="Tries the module's agent task may use.")
+    tier: ModelTier = Field(default="medium", description="The model tier to start with.")
+
+
+class PlanModule(_Model):
+    """One module of the plan: one dynamic node per downstream rule."""
+
+    name: str = Field(pattern=_NAME_RE, description="The module name (an RTL identifier).")
+    summary: str = Field(min_length=1, description="What the module does, in a sentence or two.")
+    reqs: tuple[str, ...] = Field(
+        default=(), description="Requirements it covers: REQ ids or inferred requirement keys."
+    )
+    interface: PlanInterface = Field(
+        default_factory=PlanInterface, description="The module's ports."
+    )
+    depends_on: tuple[str, ...] = Field(
+        default=(), description="Modules of this plan that must be built first."
+    )
+    writes: tuple[PlanWrite, ...] = Field(
+        min_length=1, description="Every file the module's nodes write (its write set)."
+    )
+    budget: ModuleBudget = Field(
+        default_factory=ModuleBudget, description="The module's tries and model tier."
+    )
+
+    @property
+    def write_paths(self) -> tuple[str, ...]:
+        """The paths of `writes`, in order."""
+        return tuple(w.path for w in self.writes)
+
+
+class UnassignedReq(_Model):
+    """A requirement of the block that no module covers, and why."""
+
+    req: str = Field(min_length=1, description="The REQ id or inferred requirement key.")
+    reason: str = Field(min_length=1, description="Why no module of this plan covers it.")
+
+
+class Plan(_Model):
+    """A block's plan: its modules, their write sets and order, and what a person must read."""
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this file.")
+    block: str = Field(min_length=1, description="The block this plan is for.")
+    top: str = Field(description="The module that is the block's top (its interface).")
+    modules: tuple[PlanModule, ...] = Field(min_length=1, description="The modules.")
+    assumptions: tuple[str, ...] = Field(
+        default=(), description="Assumptions the plan rests on (F4)."
+    )
+    open_questions: tuple[str, ...] = Field(
+        default=(), description="Questions the approver must read and answer."
+    )
+    unassigned_reqs: tuple[UnassignedReq, ...] = Field(
+        default=(), description="Requirements of the block no module covers, with the reason."
+    )
+
+    def module(self, name: str) -> PlanModule | None:
+        """The module called `name`, if the plan has one."""
+        return next((m for m in self.modules if m.name == name), None)
+
+
+def schema_json() -> str:
+    """The JSON Schema of a plan file, as committed under `schemas/formats/`."""
+    return json.dumps(Plan.model_json_schema(), indent=2, sort_keys=True) + "\n"
+
+
+__all__ = [
+    "ModuleBudget",
+    "Plan",
+    "PlanInterface",
+    "PlanModule",
+    "PlanPort",
+    "PlanWrite",
+    "UnassignedReq",
+    "schema_json",
+]