chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/config/templates.py

@@ -0,0 +1,340 @@
+"""Block-by-block Jinja2 template overrides (DESIGN 8.6 V2, docs/IMPLEMENTATION_PLAN.md M1-22).
+
+A `TemplateSet` renders named templates (e.g. `rtl_module.sv.j2`) built from an ordered
+stack of layers, most specific first. DESIGN.md's lookup order for a template is::
+
+    block -> project -> organisation -> pack
+
+("block" here is the project's own per-IP-block layer, DESIGN 8.6's `blocks:` section;
+"pack" is the lowest, always-present fallback.) Each layer may contribute, for a given
+template name:
+
+* a **whole-file** template: a file named exactly like the template, in that layer's
+  ``directory``, whose top level has real content (not just `{% block %}` tags). The most
+  specific layer that has a whole file for a name is the base of the render.
+* a **block-only fragment** that overrides individual `{% block %}` regions without
+  touching the rest of the file. Two conventions produce a fragment, and both may be used
+  together:
+
+  1. **Same file name, in a more specific layer's directory**, containing *only*
+     `{% block ... %}...{% endblock %}` definitions (no other top-level output). Detected
+     automatically by parsing the file: if every top-level node is a block definition or
+     whitespace, it is a fragment, not a whole-file replacement.
+  2. **`templates.override` mapping** (`ResolvedProfile.for_block(...).profile.templates
+     .override`, or any other `Mapping[str, str]` a caller assembles the same way): a
+     block name (not necessarily the template's file name) to a file path containing that
+     one block's `{% block <name> %}...{% endblock %}` definition. This is what DESIGN.md's
+     example ``templates: override: { rtl_header: templates/header.j2 }`` means: the key is
+     the *block name* `rtl_header`, not a template file name, so it applies to any template
+     in the chain that defines a block called `rtl_header`.
+
+Both conventions are implemented with real Jinja2 inheritance: each more specific layer's
+contribution is compiled as a virtual template `layer:<n>/<name>` that `{% extends %}` the
+next less specific layer's virtual template. A block a more specific layer does not touch
+is therefore untouched in the rendered output -- it simply falls through Jinja's own block
+resolution. This is also why overriding one block never changes any other block's source
+or rendering: each block's *content* lives in exactly one layer's fragment/whole file.
+
+Gap vs. `core/config/models.py`: `BlockOverride` (the project's own `blocks:` per-IP-block
+section) has no `templates` field, so a project cannot currently express a block-scoped
+template override through the resolved `Profile` alone -- only a project-wide
+`templates.override`. `TemplateSet` accepts a "block" layer as plain data (an optional
+directory and/or override mapping) so a caller can still supply one (e.g. read from
+`.chipgraph/blocks/<block>/templates/`, by convention, until `models.py` grows a field);
+this module does not itself decide where a per-block layer's directory or overrides come
+from.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from jinja2 import BaseLoader, Environment, StrictUndefined, nodes
+from jinja2.exceptions import TemplateNotFound as Jinja2TemplateNotFound
+from jinja2.exceptions import UndefinedError
+from jinja2.sandbox import SandboxedEnvironment
+
+__all__ = [
+    "BlockSource",
+    "TemplateLayer",
+    "TemplateNotFoundError",
+    "TemplateRenderError",
+    "TemplateSet",
+    "TemplateSetError",
+]
+
+_VIRTUAL_PREFIX = "layer:"
+
+
+class TemplateSetError(Exception):
+    """Base error for `TemplateSet` problems."""
+
+
+class TemplateNotFoundError(TemplateSetError):
+    """No layer contributes anything (whole file or fragment) for a template name."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"template {name!r} not found in any layer")
+        self.name = name
+
+
+class TemplateRenderError(TemplateSetError):
+    """Rendering failed; names the template and the layer chain that produced it."""
+
+    def __init__(self, name: str, layers: Sequence[str], cause: Exception) -> None:
+        chain = " -> ".join(layers) if layers else "(no layer)"
+        super().__init__(
+            f"error rendering template {name!r} (layer chain, least to most specific: "
+            f"{chain}): {cause}"
+        )
+        self.name = name
+        self.layers = tuple(layers)
+        self.__cause__ = cause
+
+
+@dataclass(frozen=True)
+class TemplateLayer:
+    """One layer in the lookup stack: a directory of whole/fragment files, and/or an
+    explicit block-name-to-path override mapping (DESIGN 8.6 V2's `templates.override`).
+
+    `name` is a short label used in `explain()` output and error messages, e.g. "block",
+    "project", "org", "pack".
+    """
+
+    name: str
+    directory: Path | None = None
+    override: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class BlockSource:
+    """Which layer (and file, if any) a rendered block's content came from."""
+
+    block: str
+    layer: str
+    path: Path | None
+
+
+@dataclass(frozen=True)
+class _Contribution:
+    """One layer's compiled contribution to a template's inheritance chain."""
+
+    layer_name: str
+    source: str
+    is_root: bool  # True: a whole-file base/replacement (does not extend the chain so far)
+    block_paths: dict[str, Path | None]
+
+
+def _read(path: str | Path) -> str:
+    p = Path(path)
+    try:
+        return p.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise TemplateSetError(f"cannot read template file {p}: {exc}") from exc
+
+
+def _is_pure_fragment(source: str, parser_env: Environment, origin: str) -> bool:
+    """True if `source`'s top level has only `{% block %}` tags and/or whitespace text."""
+    try:
+        parsed = parser_env.parse(source)
+    except Exception as exc:
+        raise TemplateSetError(f"cannot parse template fragment {origin}: {exc}") from exc
+    for top in parsed.body:
+        if isinstance(top, nodes.Block):
+            continue
+        if isinstance(top, nodes.Output) and all(
+            isinstance(child, nodes.TemplateData) and child.data.strip() == ""
+            for child in top.nodes
+        ):
+            continue
+        return False
+    return True
+
+
+def _block_names(source: str, parser_env: Environment, origin: str) -> list[str]:
+    try:
+        parsed = parser_env.parse(source)
+    except Exception as exc:
+        raise TemplateSetError(f"cannot parse template fragment {origin}: {exc}") from exc
+    return [b.name for b in parsed.find_all(nodes.Block)]
+
+
+class _LayeredLoader(BaseLoader):
+    """Serves the virtual `layer:<n>/<name>` sources a `TemplateSet` compiles."""
+
+    def __init__(self) -> None:
+        self._sources: dict[str, str] = {}
+
+    def add(self, virtual_name: str, source: str) -> None:
+        self._sources[virtual_name] = source
+
+    def get_source(
+        self, environment: Environment, template: str
+    ) -> tuple[str, str | None, Callable[[], bool] | None]:
+        try:
+            source = self._sources[template]
+        except KeyError as exc:
+            raise Jinja2TemplateNotFound(template) from exc
+        return source, None, lambda: True
+
+
+class TemplateSet:
+    """Renders templates built from ordered layers (most specific first)."""
+
+    def __init__(self, layers: Sequence[TemplateLayer]) -> None:
+        self._layers: tuple[TemplateLayer, ...] = tuple(layers)
+        self._loader = _LayeredLoader()
+        self._env = SandboxedEnvironment(
+            loader=self._loader,
+            undefined=StrictUndefined,
+            autoescape=False,
+            keep_trailing_newline=True,
+        )
+        # A plain (non-sandboxed) environment used only to parse candidate sources when
+        # deciding whether they are whole files or block-only fragments, and to list the
+        # block names they define. No template of ours is *rendered* through it.
+        self._parser_env = Environment()
+        self._chains: dict[str, tuple[list[str], dict[str, BlockSource]]] = {}
+
+    # -- chain construction --------------------------------------------------------
+
+    def _gather_layer_candidates(
+        self, layer: TemplateLayer, name: str
+    ) -> tuple[str | None, Path | None, dict[str, str]]:
+        """Return (whole_or_fragment_source_for_name, its_path, {block_name: path}) for
+        one layer's directory file plus any `override` entries keyed by `name` itself."""
+        whole_source: str | None = None
+        whole_path: Path | None = None
+
+        if name in layer.override:
+            whole_path = Path(layer.override[name])
+            whole_source = _read(whole_path)
+        elif layer.directory is not None:
+            candidate = layer.directory / name
+            if candidate.is_file():
+                whole_path = candidate
+                whole_source = _read(candidate)
+
+        block_overrides = {
+            block_name: path for block_name, path in layer.override.items() if block_name != name
+        }
+        return whole_source, whole_path, block_overrides
+
+    def _build_contribution(self, layer: TemplateLayer, name: str) -> _Contribution | None:
+        whole_source, whole_path, block_override_paths = self._gather_layer_candidates(layer, name)
+
+        pieces: list[str] = []
+        block_paths: dict[str, Path | None] = {}
+        is_root = False
+
+        if whole_source is not None:
+            origin = str(whole_path)
+            if _is_pure_fragment(whole_source, self._parser_env, origin):
+                pieces.append(whole_source)
+                for block_name in _block_names(whole_source, self._parser_env, origin):
+                    block_paths[block_name] = whole_path
+            else:
+                # A whole (non-fragment) file: it is the base, replacing anything less
+                # specific accumulated so far.
+                pieces = [whole_source]
+                for block_name in _block_names(whole_source, self._parser_env, origin):
+                    block_paths[block_name] = whole_path
+                is_root = True
+
+        for block_name, path_str in block_override_paths.items():
+            path = Path(path_str)
+            source = _read(path)
+            origin = str(path)
+            if not _is_pure_fragment(source, self._parser_env, origin):
+                raise TemplateSetError(
+                    f"templates.override[{block_name!r}] = {origin!r} must contain only "
+                    "{% block %} definitions, not whole-template content"
+                )
+            pieces.append(source)
+            for found in _block_names(source, self._parser_env, origin):
+                block_paths[found] = path
+
+        if not pieces:
+            return None
+
+        return _Contribution(
+            layer_name=layer.name,
+            source="\n".join(pieces),
+            is_root=is_root,
+            block_paths=block_paths,
+        )
+
+    def _build_chain(self, name: str) -> tuple[list[str], dict[str, BlockSource]]:
+        cached = self._chains.get(name)
+        if cached is not None:
+            return cached
+
+        # Layers are stored most-specific-first; process least-specific-first so each
+        # more specific contribution can `{% extends %}` the previous virtual template.
+        layers_asc = list(reversed(self._layers))
+
+        parent_virtual: str | None = None
+        chain_layer_names: list[str] = []
+        block_sources: dict[str, BlockSource] = {}
+        index = 0
+
+        for layer in layers_asc:
+            contribution = self._build_contribution(layer, name)
+            if contribution is None:
+                continue
+
+            if contribution.is_root:
+                # Resets the chain: this whole file replaces anything accumulated so far.
+                source = contribution.source
+                parent_virtual = None
+                chain_layer_names = []
+            else:
+                if parent_virtual is None:
+                    raise TemplateSetError(
+                        f"layer {layer.name!r} overrides block(s) "
+                        f"{sorted(contribution.block_paths)} of template {name!r}, but no "
+                        "less specific layer provides a whole (base) file for it"
+                    )
+                source = f'{{% extends "{parent_virtual}" %}}\n{contribution.source}'
+
+            virtual_name = f"{_VIRTUAL_PREFIX}{index}/{name}"
+            self._loader.add(virtual_name, source)
+            index += 1
+            parent_virtual = virtual_name
+            chain_layer_names.append(layer.name)
+
+            for block_name, path in contribution.block_paths.items():
+                block_sources[block_name] = BlockSource(
+                    block=block_name, layer=layer.name, path=path
+                )
+
+        if parent_virtual is None:
+            raise TemplateNotFoundError(name)
+
+        # Publish the final, most specific virtual template under the public name too.
+        self._loader.add(name, f'{{% extends "{parent_virtual}" %}}\n')
+
+        result = (chain_layer_names, block_sources)
+        self._chains[name] = result
+        return result
+
+    # -- public API ------------------------------------------------------------------
+
+    def render(self, name: str, context: Mapping[str, object] | None = None) -> str:
+        """Render template `name` against `context`. Deterministic, no implicit state."""
+        chain_layers, _ = self._build_chain(name)
+        template = self._env.get_template(name)
+        try:
+            return template.render(dict(context) if context is not None else {})
+        except UndefinedError as exc:
+            raise TemplateRenderError(name, chain_layers, exc) from exc
+
+    def explain(self, name: str) -> list[tuple[str, str, Path | None]]:
+        """Which layer (and file, if any) each block of `name` was resolved from.
+
+        Returns a list of `(block_name, layer_name, path)`, sorted by block name.
+        """
+        _, block_sources = self._build_chain(name)
+        return sorted((b.block, b.layer, b.path) for b in block_sources.values())

chipgraph/core/contracts/__init__.py

@@ -0,0 +1,75 @@
+"""Core contracts: the pydantic models every other part of chipgraph builds against.
+
+`chipgraph.core.contracts` knows nothing about chips or tools: no project, bus, PDK or
+tool names appear here.
+"""
+
+from chipgraph.core.contracts.agent import AgentResult, Decision
+from chipgraph.core.contracts.artifact import Artifact, ArtifactRef, ProducedBy
+from chipgraph.core.contracts.check import CheckResult, CheckSpec, Issue
+from chipgraph.core.contracts.event import Event, EventType, RunManifest
+from chipgraph.core.contracts.finding import Evidence, Finding, FindingSeverity, FindingStatus
+from chipgraph.core.contracts.gate import Approval, GateSpec
+from chipgraph.core.contracts.rule import Budget, InputSpec, RuleInstance, RuleSpec, RunSpec
+from chipgraph.core.contracts.types import (
+    ArtifactKind,
+    CheckStatus,
+    DataLabel,
+    FailureLabel,
+    ModelTier,
+    RuleId,
+    RuleKind,
+    Severity,
+    Sha256,
+)
+
+__all__ = [
+    "AgentResult",
+    "Approval",
+    "Artifact",
+    "ArtifactKind",
+    "ArtifactRef",
+    "Budget",
+    "CheckResult",
+    "CheckSpec",
+    "CheckStatus",
+    "DataLabel",
+    "Decision",
+    "Event",
+    "EventType",
+    "Evidence",
+    "FailureLabel",
+    "Finding",
+    "FindingSeverity",
+    "FindingStatus",
+    "GateSpec",
+    "InputSpec",
+    "Issue",
+    "ModelTier",
+    "ProducedBy",
+    "RuleId",
+    "RuleInstance",
+    "RuleKind",
+    "RuleSpec",
+    "RunManifest",
+    "RunSpec",
+    "Severity",
+    "Sha256",
+]
+
+TOP_LEVEL_MODELS = (
+    ArtifactRef,
+    Artifact,
+    RuleSpec,
+    RuleInstance,
+    CheckSpec,
+    CheckResult,
+    GateSpec,
+    Approval,
+    Event,
+    RunManifest,
+    AgentResult,
+    Decision,
+    Finding,
+)
+"""Top-level models: each gets its own file in `schemas/` (see export.py)."""

chipgraph/core/contracts/_paths.py

@@ -0,0 +1,26 @@
+"""Shared path validation for artifact and rule-output paths.
+
+Not part of the public API of this package (no leading re-export in ``__init__``).
+"""
+
+from __future__ import annotations
+
+
+def validate_relative_path(path: str, *, field_name: str = "path") -> str:
+    """Validate a POSIX path relative to a repo root; return it unchanged if valid.
+
+    The path must not be empty, must not start with ``/`` (absolute), must not
+    contain backslashes, and no segment may be ``.`` or ``..``. Placeholders such
+    as ``{block}`` are allowed inside segments (used by rule output templates).
+    """
+    if path == "":
+        raise ValueError(f"{field_name} must not be empty")
+    if path.startswith("/"):
+        raise ValueError(f"{field_name} must be relative, got absolute path {path!r}")
+    if "\\" in path:
+        raise ValueError(f"{field_name} must be a POSIX path, got {path!r}")
+    segments = path.split("/")
+    for segment in segments:
+        if segment in ("", ".", ".."):
+            raise ValueError(f"{field_name} must not contain '.', '..' or empty segments: {path!r}")
+    return path

chipgraph/core/contracts/agent.py

@@ -0,0 +1,49 @@
+"""Agent results and decisions: the output of AI agent rules and their sub-decisions."""
+
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class AgentResult(BaseModel):
+    """The outcome of running an agent rule."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    status: Literal["done", "failed", "needs_human", "budget_exhausted"] = Field(
+        description="The final status of the agent run."
+    )
+    files_written: tuple[str, ...] = Field(
+        default=(), description="Paths of files the agent wrote."
+    )
+    assumptions: tuple[str, ...] = Field(
+        default=(), description="Assumptions the agent made while working."
+    )
+    open_questions: tuple[str, ...] = Field(
+        default=(), description="Questions the agent could not resolve on its own."
+    )
+    tokens: int | None = Field(default=None, ge=0, description="Tokens consumed by the agent run.")
+    cost: float | None = Field(default=None, ge=0, description="Cost of the agent run, in USD.")
+
+    @model_validator(mode="after")
+    def _check_needs_human_has_question(self) -> Self:
+        if self.status == "needs_human" and len(self.open_questions) < 1:
+            raise ValueError("status='needs_human' requires at least one open question")
+        return self
+
+
+class Decision(BaseModel):
+    """A single resolved decision, made by a rule, a small model, or a large model."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    question_id: str = Field(description="The id of the question this decision answers.")
+    value: str | int | float | bool = Field(description="The decided value.")
+    confidence: float = Field(ge=0, le=1, description="Confidence in this decision, from 0 to 1.")
+    backend: Literal["rule", "small", "large"] = Field(
+        description="What made this decision: a rule, a small model, or a large model."
+    )

chipgraph/core/contracts/artifact.py

@@ -0,0 +1,68 @@
+"""Artifacts: the nodes of the build graph."""
+
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from chipgraph.core.contracts._paths import validate_relative_path
+from chipgraph.core.contracts.types import ArtifactKind, DataLabel, RuleId, Sha256
+
+
+class ArtifactRef(BaseModel):
+    """A reference to an artifact, identifying it without describing its content."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    repo: str = Field(
+        default=".", description="The workspace member (repo) id this artifact belongs to."
+    )
+    kind: ArtifactKind = Field(description="The kind of artifact this is, e.g. rtl, spec, report.")
+    path: str | None = Field(
+        default=None,
+        description="POSIX path to the artifact, relative to the repo root, when it is file-based.",
+    )
+    model_key: str | None = Field(
+        default=None,
+        description="Key into the Design Model when this artifact is model-based, not a file.",
+    )
+    label: DataLabel = Field(
+        default="internal", description="Data sensitivity label: public, internal, or nda."
+    )
+
+    @model_validator(mode="after")
+    def _check_exactly_one_locator(self) -> Self:
+        if (self.path is None) == (self.model_key is None):
+            raise ValueError("ArtifactRef needs exactly one of 'path' or 'model_key' to be set")
+        if self.path is not None:
+            validate_relative_path(self.path, field_name="path")
+        return self
+
+
+class ProducedBy(BaseModel):
+    """Records which rule instance and run produced an artifact."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    rule_id: RuleId = Field(description="The id of the rule that produced this artifact.")
+    run_id: str = Field(description="The id of the run in which this artifact was produced.")
+
+
+class Artifact(BaseModel):
+    """A concrete artifact: a reference plus its content hash and provenance."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    ref: ArtifactRef = Field(description="The reference identifying this artifact.")
+    content_hash: Sha256 = Field(description="SHA-256 hash of the artifact's content.")
+    produced_by: ProducedBy | None = Field(
+        default=None,
+        description="Which rule and run produced this; None if human-written or pre-existing.",
+    )
+    inputs_hash: Sha256 | None = Field(
+        default=None,
+        description="Hash of the inputs this was produced from; None when not produced by a rule.",
+    )

chipgraph/core/contracts/check.py

@@ -0,0 +1,76 @@
+"""Checks: deterministic verification of artifacts, and their specs and results."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from chipgraph.core.contracts.types import CheckStatus, Severity
+
+_LOG_TAIL_MAX_CHARS = 4000
+_TRUNCATION_MARKER = "…"
+
+
+class CheckSpec(BaseModel):
+    """The specification of a check: which adapter runs it and with what arguments."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    id: str = Field(description="The id of this check.")
+    capability: str = Field(description="The capability this check exercises, e.g. lint, sim.")
+    adapter: str = Field(description="The adapter id that implements this check.")
+    args: dict[str, Any] = Field(default={}, description="Arguments passed to the adapter.")
+
+
+class Issue(BaseModel):
+    """A single issue found by a check, such as a lint violation."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    file: str | None = Field(default=None, description="The file this issue was found in, if any.")
+    line: int | None = Field(default=None, ge=1, description="The 1-based line number, if any.")
+    rule: str = Field(default="", description="The specific rule within the check that fired.")
+    severity: Severity = Field(default="error", description="How serious this issue is.")
+    msg: str = Field(description="A human-readable message describing the issue.")
+
+
+class CheckResult(BaseModel):
+    """The outcome of running a check."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    check_id: str = Field(description="The id of the check that was run.")
+    status: CheckStatus = Field(description="The overall outcome of the check.")
+    issues: tuple[Issue, ...] = Field(
+        default=(), description="Issues found while running the check."
+    )
+    log_tail: str = Field(
+        default="", description="The tail of the check's log output, truncated to 4000 characters."
+    )
+    duration_s: float = Field(ge=0, description="How long the check took to run, in seconds.")
+    idempotency_key: str = Field(
+        description="A key identifying repeat runs of the same check invocation."
+    )
+
+    @property
+    def ok(self) -> bool:
+        """Whether this result counts as acceptable: pass or skipped."""
+        return self.status in ("pass", "skipped")
+
+    @model_validator(mode="after")
+    def _truncate_log_tail(self) -> Self:
+        if len(self.log_tail) > _LOG_TAIL_MAX_CHARS:
+            keep = _LOG_TAIL_MAX_CHARS - len(_TRUNCATION_MARKER)
+            object.__setattr__(self, "log_tail", _TRUNCATION_MARKER + self.log_tail[-keep:])
+        return self
+
+    @model_validator(mode="after")
+    def _check_pass_has_no_errors(self) -> Self:
+        if self.status == "pass" and any(issue.severity == "error" for issue in self.issues):
+            raise ValueError(
+                "CheckResult with status='pass' must not have any issue of severity 'error'"
+            )
+        return self