chipgraph 0.1.0__py3-none-any.whl

chipgraph/packs/digital_rtl/plan/resolver.py

@@ -0,0 +1,400 @@
+"""`foreach: plan.modules`: one rule instance per module of an approved plan (DESIGN.md 5.3).
+
+The gate `plan:<block>` hangs on the `gen` rule `digital-rtl/plan_expand`, whose only
+file input is the plan: approving it pins the plan file's hash, and editing the plan
+afterwards puts the gate back to waiting (the existing gate behaviour, `gate.py`).
+
+`plan_modules` is what the project's resolver calls for `plan.modules`. For each block
+it reads the plan only when that gate is approved at the plan's current hash, and only
+when the plan still passes `plan_check` (limits included: defence in depth). Anything
+else (no plan, not approved, edited since, invalid, over a limit) expands to nothing.
+The graph is rebuilt on every build and `next_task`, so a plan that changes simply
+yields no instances until it is approved again. Each module's entry carries:
+
+- params `block` and `module`;
+- the module's write set (`writes`): the instance's outputs must stay inside it;
+- its `depends_on` as ordering edges to the same rule's instances of those modules;
+- the approved plan artifact (`plan_expand`'s output) as an input, so every expanded
+  instance runs after the gate and the expansion;
+- the profile's `style.exemplars` and naming rules file as inputs (M2-11a), so editing
+  one makes the module stale and it is written again. An exemplar an approved plan
+  writes, or one a role of a `plan.modules` agent rule must not read, is left out;
+- the block's layout directories as template values (`{layout.rtl}`, `{layout.tb}`,
+  `chipgraph.packs.digital_rtl.layout`).
+
+Two more selectors over the same approved plans (M2-11a), whose entries take every
+module's write set and the block's testbench (the outputs of the `tb-author` rules over
+`blocks`) as inputs, so their instances run after all of them:
+
+- `plan.block`: one entry per block with an approved, valid plan (`digital-rtl/open_pr`,
+  `digital-rtl/pr_gate`); none for the others;
+- `plan.blocks`: one entry per block of the profile; a block without an approved plan
+  gets a plain entry, with no extra input (`digital-rtl/review`, which also reviews a
+  change no plan made).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from chipgraph.app.context import AppContext
+from chipgraph.app.errors import AppError
+from chipgraph.checks.plan_check import (
+    DEFAULT_PLAN_PATH,
+    PLAN_MODULES,
+    PlanEnvError,
+    PlanReport,
+    check_plan_file,
+    dependency_depth,
+    topo_order,
+)
+from chipgraph.core.config.loader import ResolvedProfile
+from chipgraph.core.config.models import PlanCfg
+from chipgraph.core.contracts import RuleInstance, RuleSpec
+from chipgraph.core.engine.gate import GateStatus, gate_id_for
+from chipgraph.core.engine.graph import ForeachEntry, GraphError, build_graph, kind_for
+from chipgraph.core.runtime.roles import denied_kind, find_role
+from chipgraph.packs.digital_rtl.layout import LayoutError, fill_vars, layout_vars
+from chipgraph.packs.digital_rtl.plan.model import Plan
+
+PLAN_RULE = "digital-rtl/plan"
+"""The agent rule that writes a block's plan."""
+EXPAND_RULE = "digital-rtl/plan_expand"
+"""The `gen` rule behind the gate `plan:<block>`; it writes the approved plan artifact."""
+PLAN_BLOCK = "plan.block"
+"""The selector over the blocks with an approved, valid plan."""
+PLAN_BLOCKS = "plan.blocks"
+"""The selector over every block, with the plan's files as inputs when it is approved."""
+TB_ROLE = "tb-author"
+"""The role of the rules whose outputs are a block's testbench."""
+
+
+class _Blocks:
+    def __init__(self, blocks: Iterable[str]) -> None:
+        self._blocks = sorted(blocks)
+
+    def expand(self, expr: str) -> list[dict[str, str]]:
+        if expr != "blocks":
+            raise GraphError(f"rule {EXPAND_RULE!r} must be 'foreach: blocks', not {expr!r}")
+        return [{"block": b} for b in self._blocks]
+
+
+@dataclass(frozen=True)
+class PlanGate:
+    """A block's plan gate: its id, the instance it is evaluated on, and the paths."""
+
+    block: str
+    gate_id: str
+    instance: RuleInstance
+    plan_path: str
+    approved_path: str
+
+
+def plan_gates(
+    rules: Iterable[RuleSpec], blocks: Iterable[str], *, repo: str = "."
+) -> dict[str, PlanGate]:
+    """Every block's `PlanGate`, from the loaded `digital-rtl/plan_expand` rule.
+
+    Raises `AppError` when the rule is not loaded (the `digital-rtl` pack is off) or has
+    no gate.
+    """
+    rule = next((r for r in rules if r.id == EXPAND_RULE), None)
+    if rule is None:
+        raise AppError(
+            f"foreach 'plan.modules' needs rule {EXPAND_RULE!r}: add the 'digital-rtl' pack "
+            "to the profile's packs"
+        )
+    if rule.gate is None:
+        raise AppError(f"rule {EXPAND_RULE!r} must have a gate (plan:{{block}})")
+    try:
+        graph = build_graph([rule], _Blocks(blocks), repo=repo)
+    except GraphError as exc:
+        raise AppError(str(exc)) from exc
+    gates: dict[str, PlanGate] = {}
+    for instance in graph.instances.values():
+        block = instance.params["block"]
+        plan_path = next(
+            (ref.path for ref in instance.inputs if ref.path is not None),
+            DEFAULT_PLAN_PATH.format(block=block),
+        )
+        approved = instance.outputs[0].path or ""
+        gates[block] = PlanGate(
+            block=block,
+            gate_id=gate_id_for(rule.gate, instance.params),
+            instance=instance,
+            plan_path=plan_path,
+            approved_path=approved,
+        )
+    return gates
+
+
+def gate_status(ctx: AppContext, gate: PlanGate) -> GateStatus:
+    """The status of a block's plan gate, at the plan's current hash."""
+    return ctx.gates.status(gate.gate_id, gate.instance)
+
+
+def within_limits(report: PlanReport, limits: PlanCfg) -> bool:
+    """The plan is inside the profile's limits (checked again, apart from `plan_check`)."""
+    plan = report.plan
+    if plan is None:
+        return False
+    return (
+        len(plan.modules) <= limits.max_modules
+        and dependency_depth(plan) <= limits.max_depth
+        and sum(m.budget.tries for m in plan.modules) <= limits.max_total_tries
+    )
+
+
+@dataclass(frozen=True)
+class ApprovedPlan:
+    """A block's plan, approved at its current hash and still valid."""
+
+    gate: PlanGate
+    plan: Plan
+    vars: Mapping[str, str] = field(default_factory=dict)
+
+    @property
+    def block(self) -> str:
+        return self.gate.block
+
+    def module_writes(self) -> tuple[str, ...]:
+        """Every file of the plan's write sets, in build order."""
+        return tuple(
+            path
+            for name in topo_order(self.plan)
+            if (module := self.plan.module(name)) is not None
+            for path in module.write_paths
+        )
+
+
+def _vars(resolved: ResolvedProfile, block: str) -> dict[str, str]:
+    try:
+        return layout_vars(resolved, block)
+    except LayoutError as exc:
+        raise AppError(str(exc)) from exc
+
+
+def approved_plan(
+    ctx: AppContext, rules: Sequence[RuleSpec], gate: PlanGate
+) -> ApprovedPlan | None:
+    """The block's plan when it is approved at its current hash and valid, else None."""
+    if gate_status(ctx, gate) != "approved":
+        return None
+    resolved = ctx.require_profile()
+    try:
+        report = check_plan_file(
+            ctx.root,
+            gate.block,
+            plan_path=gate.plan_path,
+            resolved=resolved,
+            rules=rules,
+            check_existing=False,  # checked before approval; now the files are the plan's
+        )
+    except PlanEnvError:
+        return None
+    if not report.ok or report.plan is None or not within_limits(report, resolved.profile.plan):
+        return None
+    return ApprovedPlan(gate=gate, plan=report.plan, vars=_vars(resolved, gate.block))
+
+
+def approved_plans(ctx: AppContext, rules: Sequence[RuleSpec]) -> dict[str, ApprovedPlan]:
+    """Every block's `ApprovedPlan`, for the blocks that have one."""
+    resolved = ctx.require_profile()
+    gates = plan_gates(rules, resolved.profile.blocks, repo=ctx.store.repo)
+    found: dict[str, ApprovedPlan] = {}
+    for block in sorted(gates):
+        approved = approved_plan(ctx, rules, gates[block])
+        if approved is not None:
+            found[block] = approved
+    return found
+
+
+def _naming_file(root: Path, resolved: ResolvedProfile, block: str) -> str | None:
+    """The naming rules file the profile names, repo-relative, when it is in the repo."""
+    from chipgraph.checks.naming import _resolve_rules_path, _RulesError
+    from chipgraph.packs.digital_rtl.rtl.context import _naming_ref
+
+    ref = _naming_ref(resolved, block)
+    if ref is None:
+        return None
+    try:
+        path = _resolve_rules_path(ref, root)
+    except _RulesError:
+        return None
+    try:
+        rel = path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return None
+    return rel if path.is_file() else None
+
+
+def style_inputs(
+    ctx: AppContext,
+    rules: Sequence[RuleSpec],
+    block: str,
+    *,
+    planned: Iterable[str] = (),
+) -> tuple[str, ...]:
+    """The style files a planned module is written after: exemplars and naming rules.
+
+    Only files that exist; never one in `planned` (a file an approved plan writes:
+    it would be an input of the module that writes it), and never one a role of an
+    agent rule over `plan.modules` must not read.
+    """
+    resolved = ctx.require_profile()
+    roles = [
+        role
+        for rule in rules
+        if rule.foreach == PLAN_MODULES and rule.kind == "agent" and rule.role is not None
+        if (role := find_role(rule.role)) is not None
+    ]
+    skip = set(planned)
+    candidates = [*resolved.for_block(block).style.exemplars]
+    naming = _naming_file(ctx.root, resolved, block)
+    if naming is not None:
+        candidates.append(naming)
+    out: list[str] = []
+    for rel in dict.fromkeys(candidates):
+        if rel in skip or not (ctx.root / rel).is_file():
+            continue
+        if any(denied_kind(role, kind_for(rel), rel) is not None for role in roles):
+            continue
+        out.append(rel)
+    return tuple(out)
+
+
+def module_entries(
+    ctx: AppContext,
+    rules: Sequence[RuleSpec],
+    approved: ApprovedPlan,
+    *,
+    planned: Iterable[str] = (),
+) -> list[ForeachEntry]:
+    """The `plan.modules` entries of one block's approved plan."""
+    plan = approved.plan
+    style = style_inputs(ctx, rules, approved.block, planned=planned)
+    entries: list[ForeachEntry] = []
+    for name in topo_order(plan):
+        module = plan.module(name)
+        assert module is not None
+        entries.append(
+            ForeachEntry(
+                params={"block": approved.block, "module": module.name},
+                inputs=(approved.gate.approved_path, *style),
+                after=tuple(
+                    {"block": approved.block, "module": dep}
+                    for dep in dict.fromkeys(module.depends_on)
+                ),
+                writes=frozenset(module.write_paths),
+                vars=dict(approved.vars),
+            )
+        )
+    return entries
+
+
+def block_entries(ctx: AppContext, rules: Sequence[RuleSpec], gate: PlanGate) -> list[ForeachEntry]:
+    """The `plan.modules` entries of one block: none unless its plan is approved and valid."""
+    approved = approved_plan(ctx, rules, gate)
+    if approved is None:
+        return []
+    return module_entries(ctx, rules, approved, planned=approved.module_writes())
+
+
+def testbench_files(
+    rules: Sequence[RuleSpec], block: str, values: Mapping[str, str]
+) -> tuple[str, ...]:
+    """The block's testbench: the outputs of the `tb-author` rules over `blocks`."""
+    out: list[str] = []
+    for rule in sorted(rules, key=lambda r: r.id):
+        if rule.kind == "agent" and rule.role == TB_ROLE and rule.foreach == "blocks":
+            out.extend(fill_vars(t, {**values, "block": block}) for t in rule.outputs)
+    return tuple(dict.fromkeys(out))
+
+
+def block_files(
+    rules: Sequence[RuleSpec], approved: ApprovedPlan
+) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """The block's RTL (every module's write set) and testbench files."""
+    return approved.module_writes(), testbench_files(rules, approved.block, approved.vars)
+
+
+def plan_block_entry(rules: Sequence[RuleSpec], approved: ApprovedPlan) -> ForeachEntry:
+    """The `plan.block` / `plan.blocks` entry of a block with an approved plan."""
+    rtl, tb = block_files(rules, approved)
+    return ForeachEntry(
+        params={"block": approved.block},
+        inputs=tuple(dict.fromkeys((approved.gate.approved_path, *rtl, *tb))),
+        vars=dict(approved.vars),
+    )
+
+
+@dataclass
+class PlanExpansion:
+    """The approved plans of a project, read once per graph, and the entries they give."""
+
+    ctx: AppContext
+    rules: Sequence[RuleSpec]
+    _approved: dict[str, ApprovedPlan] | None = None
+
+    @property
+    def approved(self) -> dict[str, ApprovedPlan]:
+        if self._approved is None:
+            self._approved = approved_plans(self.ctx, self.rules)
+        return self._approved
+
+    def modules(self) -> list[ForeachEntry]:
+        """`plan.modules`: every module of every approved plan."""
+        planned = {p for a in self.approved.values() for p in a.module_writes()}
+        entries: list[ForeachEntry] = []
+        for block in sorted(self.approved):
+            entries.extend(
+                module_entries(self.ctx, self.rules, self.approved[block], planned=planned)
+            )
+        return entries
+
+    def blocks_with_plan(self) -> list[ForeachEntry]:
+        """`plan.block`: one entry per block with an approved plan."""
+        return [plan_block_entry(self.rules, self.approved[b]) for b in sorted(self.approved)]
+
+    def every_block(self) -> list[ForeachEntry]:
+        """`plan.blocks`: every block; an approved plan's files as inputs when it has one."""
+        resolved = self.ctx.require_profile()
+        entries: list[ForeachEntry] = []
+        for block in sorted(resolved.profile.blocks):
+            approved = self.approved.get(block)
+            if approved is not None:
+                entries.append(plan_block_entry(self.rules, approved))
+            else:
+                entries.append(ForeachEntry(params={"block": block}, vars=_vars(resolved, block)))
+        return entries
+
+
+def plan_modules(ctx: AppContext, rules: Sequence[RuleSpec]) -> list[ForeachEntry]:
+    """`foreach: plan.modules`: every module of every block's approved, valid plan."""
+    return PlanExpansion(ctx, rules).modules()
+
+
+__all__ = [
+    "EXPAND_RULE",
+    "PLAN_BLOCK",
+    "PLAN_BLOCKS",
+    "PLAN_RULE",
+    "TB_ROLE",
+    "ApprovedPlan",
+    "PlanExpansion",
+    "PlanGate",
+    "approved_plan",
+    "approved_plans",
+    "block_entries",
+    "block_files",
+    "gate_status",
+    "module_entries",
+    "plan_block_entry",
+    "plan_gates",
+    "plan_modules",
+    "style_inputs",
+    "testbench_files",
+    "within_limits",
+]

chipgraph/packs/digital_rtl/plan/show.py

@@ -0,0 +1,176 @@
+"""`chipgraph plan show <block>`: what the approver of gate `plan:<block>` reads.
+
+The summary: the gate's status (and the command that approves it), the check's errors
+and warnings, the modules (summary, requirements, dependencies, write sets, ports,
+budget) in build order, requirement coverage, the limits used, the assumptions and the
+open questions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from chipgraph.app.build import load_rules
+from chipgraph.app.context import AppContext
+from chipgraph.app.errors import AppError
+from chipgraph.checks.plan_check import (
+    PlanEnvError,
+    check_plan_file,
+    dependency_depth,
+    topo_order,
+)
+from chipgraph.packs.digital_rtl.plan.resolver import gate_status, plan_gates
+
+
+def plan_summary(ctx: AppContext, block: str) -> dict[str, Any]:
+    """The summary of `block`'s plan, as plain data (`--json` prints it as is)."""
+    resolved = ctx.require_profile()
+    if block not in resolved.profile.blocks:
+        raise AppError(
+            f"unknown block {block!r}; blocks: {', '.join(sorted(resolved.profile.blocks))}"
+        )
+    rules = load_rules(ctx)
+    gate = plan_gates(rules, resolved.profile.blocks, repo=ctx.store.repo)[block]
+    try:
+        report = check_plan_file(
+            ctx.root, block, plan_path=gate.plan_path, resolved=resolved, rules=rules
+        )
+    except PlanEnvError as exc:
+        raise AppError(str(exc)) from exc
+    status = gate_status(ctx, gate)
+    summary: dict[str, Any] = {
+        "block": block,
+        "path": report.path,
+        "exists": report.exists,
+        "sha256": report.sha256,
+        "gate": {
+            "id": gate.gate_id,
+            "status": status,
+            "instance": gate.instance.instance_id,
+            "approve": (
+                f"chipgraph approve {gate.gate_id} --instance '{gate.instance.instance_id}'"
+            ),
+        },
+        "ok": report.ok,
+        "errors": [_issue(i) for i in report.issues if i.severity == "error"],
+        "warnings": [_issue(i) for i in report.issues if i.severity == "warning"],
+    }
+    plan = report.plan
+    if plan is None:
+        return summary
+    limits = resolved.profile.plan
+    order = topo_order(plan)
+    summary.update(
+        {
+            "top": plan.top,
+            "order": order,
+            "modules": [
+                {
+                    "name": m.name,
+                    "summary": m.summary,
+                    "reqs": list(m.reqs),
+                    "depends_on": list(m.depends_on),
+                    "writes": [w.model_dump(mode="json") for w in m.writes],
+                    "ports": [p.model_dump(mode="json") for p in m.interface.ports],
+                    "budget": m.budget.model_dump(mode="json"),
+                }
+                for name in order
+                if (m := plan.module(name)) is not None
+            ],
+            "coverage": _coverage(report),
+            "limits": {
+                "modules": [len(plan.modules), limits.max_modules],
+                "depth": [dependency_depth(plan), limits.max_depth],
+                "tries": [sum(m.budget.tries for m in plan.modules), limits.max_total_tries],
+            },
+            "assumptions": list(plan.assumptions),
+            "open_questions": list(plan.open_questions),
+        }
+    )
+    return summary
+
+
+def _issue(issue: Any) -> str:
+    where = f"{issue.file}:{issue.line}" if issue.line else str(issue.file)
+    return f"{where} [{issue.rule}] {issue.msg}"
+
+
+def _coverage(report: Any) -> list[dict[str, Any]]:
+    """Each block requirement: the modules covering it, or why it is unassigned, or missing."""
+    plan = report.plan
+    env = report.env
+    if plan is None or env is None:
+        return []
+    rows: list[dict[str, Any]] = []
+    for req in env.requirements:
+        modules = [m.name for m in plan.modules if req.refs & set(m.reqs)]
+        reasons = [u.reason for u in plan.unassigned_reqs if u.req in req.refs]
+        rows.append(
+            {
+                "req": req.ref,
+                "modules": modules,
+                "unassigned": reasons[0] if reasons and not modules else None,
+            }
+        )
+    return rows
+
+
+def render_text(summary: dict[str, Any]) -> str:
+    """The summary as text, for a person."""
+    lines = [f"plan for block {summary['block']}: {summary['path']}"]
+    gate = summary["gate"]
+    lines.append(f"gate {gate['id']}: {gate['status']}")
+    if not summary["exists"]:
+        lines.append("no plan yet: build rule digital-rtl/plan for this block first")
+        return "\n".join(lines) + "\n"
+    lines.append(f"check: {'ok' if summary['ok'] else 'FAILS'}")
+    for error in summary["errors"]:
+        lines.append(f"  error   {error}")
+    for warning in summary["warnings"]:
+        lines.append(f"  warning {warning}")
+    if "modules" not in summary:
+        return "\n".join(lines) + "\n"
+
+    limits = summary["limits"]
+    lines.append(
+        f"top: {summary['top']}   modules {limits['modules'][0]}/{limits['modules'][1]}, "
+        f"depth {limits['depth'][0]}/{limits['depth'][1]}, "
+        f"tries {limits['tries'][0]}/{limits['tries'][1]}"
+    )
+    lines.append("")
+    lines.append("modules (build order):")
+    for m in summary["modules"]:
+        lines.append(f"  {m['name']}: {m['summary']}")
+        lines.append(f"    reqs:       {', '.join(m['reqs']) or '-'}")
+        lines.append(f"    depends on: {', '.join(m['depends_on']) or '-'}")
+        writes = [w["path"] + (" (replaces)" if w["replaces"] else "") for w in m["writes"]]
+        lines.append(f"    writes:     {', '.join(writes)}")
+        ports = [
+            f"{p['name']}:{p['direction']}[{p['width']}]" + (" internal" if p["internal"] else "")
+            for p in m["ports"]
+        ]
+        lines.append(f"    ports:      {', '.join(ports) or '-'}")
+        lines.append(f"    budget:     {m['budget']['tries']} tries, tier {m['budget']['tier']}")
+    lines.append("")
+    lines.append("requirement coverage:")
+    for row in summary["coverage"]:
+        if row["modules"]:
+            lines.append(f"  {row['req']}: {', '.join(row['modules'])}")
+        elif row["unassigned"]:
+            lines.append(f"  {row['req']}: unassigned ({row['unassigned']})")
+        else:
+            lines.append(f"  {row['req']}: NOT COVERED")
+    if not summary["coverage"]:
+        lines.append("  (the block has no requirements in the Design Model)")
+    lines.append("")
+    lines.append("assumptions:")
+    lines.extend(f"  - {a}" for a in summary["assumptions"] or ["none"])
+    lines.append("open questions (read before approving):")
+    lines.extend(f"  - {q}" for q in summary["open_questions"] or ["none"])
+    if gate["status"] != "approved":
+        lines.append("")
+        lines.append(f"approve: {gate['approve']}")
+    return "\n".join(lines) + "\n"
+
+
+__all__ = ["plan_summary", "render_text"]

chipgraph/packs/digital_rtl/pr/__init__.py

@@ -0,0 +1,11 @@
+"""The pull request of a block's planned RTL (M2-11a): its branch, its body, its gate.
+
+- `open`: the `open_pr` tool of rule `digital-rtl/open_pr`: builds the branch
+  `chipgraph/<run id>/<block>` from the block's RTL and testbench files without touching
+  the user's checkout, pushes it, opens the PR and writes `pr/<block>.json`;
+- `gate`: the `pr_gate` tool of rule `digital-rtl/pr_gate`, gated by `pr:<block>`;
+- `body`: the PR body: the plan, requirement coverage, check results and the Critic's
+  verdict, factual and short.
+
+Nothing here merges a pull request, or asks GitHub to.
+"""