chipgraph 0.1.0__py3-none-any.whl

chipgraph/packs/spec_core/gen/__init__.py

@@ -0,0 +1,11 @@
+"""Deterministic generators for the ``spec-core`` pack.
+
+Currently the diagram generator,
+:class:`~chipgraph.packs.spec_core.gen.diagram.DiagramGenerator`, which renders block,
+memory-map, interrupt-map and clock/reset-tree figures from the Design Model as SVG and
+drawio. Figures are computed from the model, never drawn by an AI (DESIGN.md 4.6).
+"""
+
+from chipgraph.packs.spec_core.gen.diagram import DiagramGenerator, render
+
+__all__ = ["DiagramGenerator", "render"]

chipgraph/packs/spec_core/gen/agents_md/__init__.py

@@ -0,0 +1,148 @@
+"""The ``agents-md`` generator (pack ``spec-core``): the chipgraph part of an `AGENTS.md`.
+
+Optional and deterministic, no AI (DESIGN.md 4.7, DECISIONS D18/D31). From the resolved
+profile and the organization rules it extends, it writes the project's conventions for
+any coding agent (Codex, Cursor, Claude Code ...): blocks and instances, where files go,
+naming rules, the checks to run before a PR, requirement IDs, path exceptions, data labels
+and generated files.
+
+chipgraph manages only the text between ``<!-- chipgraph:begin -->`` and
+``<!-- chipgraph:end -->``; the rest of the file is the team's and is never changed.
+
+Public API:
+
+- :func:`render_agents_md` — the managed block's content (without the markers).
+  Deterministic: sections sorted, no dates, no absolute paths, ``\\n`` line endings.
+- :func:`update_agents_md` — put a block into an existing file's managed part (or append
+  it, or return it alone when there is no file); malformed markers raise
+  :class:`AgentsMdError`.
+- :func:`agents_md_content` — both in one: the full file content to write.
+
+The block is rendered from the Jinja2 template ``agents_md.md.j2`` through
+:class:`~chipgraph.core.config.templates.TemplateSet` (DESIGN 8.6 V2), so a project can
+replace one section without copying the file: ``templates.override`` in `.chipgraph.yml`
+maps a block name to a file holding that one ``{% block %}``, e.g.
+``templates: { override: { agents_md_checks: templates/agents_checks.j2 } }``. Block
+names: ``agents_md_intro``, ``agents_md_project``, ``agents_md_layout``,
+``agents_md_naming``, ``agents_md_checks``, ``agents_md_requirements``,
+``agents_md_paths``, ``agents_md_data``, ``agents_md_generated``. An override may use the
+same context as the pack template, plus the helpers ``code(s, cell=False)`` (a Markdown
+code span) and ``text(s)`` (one line of text, safe in a table cell). Only overrides named
+``agents_md.md.j2`` or starting with ``agents_md_`` are read here.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from chipgraph.core.config import ResolvedProfile
+from chipgraph.core.config.templates import TemplateLayer, TemplateSet, TemplateSetError
+from chipgraph.packs.spec_core.gen.agents_md._context import build_context
+from chipgraph.packs.spec_core.gen.agents_md._markers import (
+    BEGIN_MARKER,
+    END_MARKER,
+    AgentsMdError,
+    split_managed,
+    update_agents_md,
+)
+
+TEMPLATE_NAME = "agents_md.md.j2"
+"""The pack template's file name (and the key of a whole-file override)."""
+
+BLOCK_PREFIX = "agents_md_"
+"""Every block of the template is named with this prefix."""
+
+NOTE = (
+    "<!-- Generated by chipgraph from the project profile; do not edit this block by hand. "
+    "Regenerate it with `chipgraph agents-md --write`. -->"
+)
+"""The one-line note that opens the managed block."""
+
+_TEMPLATE_DIR = Path(__file__).resolve().parent
+
+_BLANK_RUNS = re.compile(r"\n{3,}")
+
+
+def code(value: object, cell: bool = False) -> str:
+    """`value` as a Markdown code span; with `cell`, `|` is escaped for a table cell."""
+    s = " ".join(str(value).split())
+    if not s:
+        return ""
+    fence = "``" if "`" in s else "`"
+    pad = " " if fence == "``" else ""
+    if cell:
+        s = s.replace("|", "\\|")
+    return f"{fence}{pad}{s}{pad}{fence}"
+
+
+def text(value: object) -> str:
+    """`value` as one line of Markdown text, safe in a table cell.
+
+    Only `<` (else read as an HTML tag, e.g. ``m_qnsc_<function>``) and `|` (a cell
+    separator) are escaped; other Markdown in the value is kept as written.
+    """
+    s = " ".join(str(value).split())
+    for ch in ("<", "|"):
+        s = s.replace(ch, "\\" + ch)
+    return s
+
+
+def _normalize(rendered: str) -> str:
+    lines = [line.rstrip() for line in rendered.replace("\r\n", "\n").split("\n")]
+    out = _BLANK_RUNS.sub("\n\n", "\n".join(lines)).strip("\n")
+    return out + "\n" if out else ""
+
+
+def _template_set(resolved: ResolvedProfile, root: Path) -> TemplateSet:
+    overrides = {
+        name: str(path if (path := Path(value)).is_absolute() else root / path)
+        for name, value in sorted(resolved.profile.templates.override.items())
+        if name == TEMPLATE_NAME or name.startswith(BLOCK_PREFIX)
+    }
+    layers: list[TemplateLayer] = []
+    if overrides:
+        layers.append(TemplateLayer(name="project", override=overrides))
+    layers.append(TemplateLayer(name="pack", directory=_TEMPLATE_DIR))
+    return TemplateSet(layers)
+
+
+def render_agents_md(resolved_profile: ResolvedProfile, root: Path) -> str:
+    """The managed block's content for the project at `root`, without the markers.
+
+    It starts with the one-line generated note, then one section per kind of profile data
+    present. The same profile always gives the same bytes. Raises `AgentsMdError` if the
+    naming rules cannot be read or a template override is broken.
+    """
+    context = build_context(resolved_profile, root)
+    context["code"] = code
+    context["text"] = text
+    try:
+        body = _template_set(resolved_profile, root).render(TEMPLATE_NAME, context)
+    except TemplateSetError as exc:
+        raise AgentsMdError(f"cannot render the AGENTS.md block: {exc}") from exc
+    block = _normalize(body)
+    if BEGIN_MARKER in block or END_MARKER in block:
+        raise AgentsMdError("the rendered AGENTS.md block must not contain the chipgraph markers")
+    return f"{NOTE}\n\n{block}"
+
+
+def agents_md_content(existing: str | None, resolved_profile: ResolvedProfile, root: Path) -> str:
+    """The full file content: `existing` with its managed block (re)generated."""
+    return update_agents_md(existing, render_agents_md(resolved_profile, root))
+
+
+__all__ = [
+    "BEGIN_MARKER",
+    "BLOCK_PREFIX",
+    "END_MARKER",
+    "NOTE",
+    "TEMPLATE_NAME",
+    "AgentsMdError",
+    "agents_md_content",
+    "code",
+    "render_agents_md",
+    "split_managed",
+    "text",
+    "update_agents_md",
+]

chipgraph/packs/spec_core/gen/agents_md/_context.py

@@ -0,0 +1,239 @@
+"""Build the template context for the managed `AGENTS.md` block from a resolved profile.
+
+Everything here is plain data (dicts, lists, strings, booleans), sorted where the profile
+has no meaningful order, so the rendered block is deterministic. No path in the context
+is made absolute: values are shown as the profile spells them.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+
+from chipgraph.checks._naming_rules import NamingRules
+from chipgraph.core.config import ConfigError, ResolvedProfile, resolve_data_ref
+from chipgraph.core.config.models import AdapterCfg, PathRule
+from chipgraph.packs.spec_core.gen.agents_md._markers import AgentsMdError
+
+_WS = re.compile(r"\s+")
+
+
+def _one_line(value: object) -> str:
+    return _WS.sub(" ", str(value)).strip()
+
+
+def _as_list(value: object) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list | tuple):
+        return [str(v) for v in value]
+    return [str(value)]
+
+
+def _command(value: object) -> str | None:
+    if isinstance(value, str):
+        return _one_line(value)
+    if isinstance(value, list | tuple) and value:
+        return " ".join(str(v) for v in value)
+    return None
+
+
+def _check_row(check_id: str, cfg: AdapterCfg) -> dict[str, Any]:
+    extras = cfg.model_dump()
+    severity = extras.get("severity")
+    return {
+        "id": check_id,
+        "use": cfg.use,
+        "severity": str(severity) if severity is not None else None,
+        "command": _command(extras.get("cmd")) if cfg.use == "cmd" else None,
+    }
+
+
+def _path_row(glob: str, rule: PathRule, block: str | None) -> dict[str, Any]:
+    return {
+        "glob": glob,
+        "block": block,
+        "checks": [f"{name} {rule.checks[name]}" for name in sorted(rule.checks)],
+        "write": rule.write,
+        "reason": _one_line(rule.reason) if rule.reason else None,
+    }
+
+
+def _load_naming(ref: str, root: Path) -> dict[str, Any]:
+    try:
+        path = resolve_data_ref(ref, root)
+    except ConfigError as exc:
+        raise AgentsMdError(f"naming rules {ref!r}: {exc}") from exc
+    try:
+        data = yaml.safe_load(path.read_bytes())
+    except (OSError, yaml.YAMLError) as exc:
+        raise AgentsMdError(f"naming rules {ref!r}: cannot read: {exc}") from exc
+    try:
+        rules = NamingRules.model_validate(data)
+    except ValidationError as exc:
+        first = exc.errors()[0]
+        loc = ".".join(str(p) for p in first["loc"])
+        raise AgentsMdError(f"naming rules {ref!r}: invalid: {loc}: {first['msg']}") from exc
+    vocabulary = None
+    if rules.vocabulary is not None:
+        vocabulary = {
+            "rule": rules.vocabulary.rule,
+            "pairs": [[k, rules.vocabulary.replace[k]] for k in sorted(rules.vocabulary.replace)],
+        }
+    return {
+        "ref": ref,
+        "document": rules.document,
+        "version": rules.version,
+        "ignore_comment": rules.ignore_comment,
+        # The rule file's own order (module, port, ...) is kept: it follows the source
+        # document, and it is as deterministic as the file itself.
+        "identifiers": [
+            {
+                "kind": kind,
+                "pattern": rule.pattern,
+                "rule": rule.rule,
+                "message": _one_line(rule.message),
+            }
+            for kind, rule in rules.identifiers.items()
+        ],
+        "lexical": [{"rule": lex.rule, "message": _one_line(lex.message)} for lex in rules.lexical],
+        "vocabulary": vocabulary,
+    }
+
+
+def _naming_refs(resolved: ResolvedProfile) -> list[str]:
+    profile = resolved.profile
+    refs: list[str] = []
+    if profile.naming.rules:
+        refs.append(profile.naming.rules)
+    for check_id in sorted(profile.adapters):
+        cfg = profile.adapters[check_id]
+        rules = cfg.model_dump().get("rules")
+        if cfg.use == "naming" and isinstance(rules, str) and rules not in refs:
+            refs.append(rules)
+    return refs
+
+
+def _generated(resolved: ResolvedProfile) -> list[str]:
+    profile = resolved.profile
+    globs: set[str] = set(_as_list(profile.layout.get("generated")))
+    for cfg in profile.adapters.values():
+        extras = cfg.model_dump()
+        if cfg.use == "generated":
+            globs.update(_as_list(extras.get("files")))
+        globs.update(_as_list(extras.get("generated")))
+    return sorted(globs)
+
+
+def _requirements(resolved: ResolvedProfile) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    profile = resolved.profile
+    req = profile.spec.requirements
+    per_block: list[dict[str, Any]] = []
+    for name in sorted(profile.blocks):
+        if profile.blocks[name].spec.requirements is None:
+            continue
+        eff = resolved.for_block(name).spec.requirements
+        per_block.append(
+            {"block": name, "id_pattern": eff.id_pattern, "infer": eff.infer == "verification"}
+        )
+    uses_block = "{block}" in req.id_pattern or "{BLOCK}" in req.id_pattern
+    overridden = {row["block"] for row in per_block}
+    example = None
+    if uses_block:
+        candidates = [b for b in sorted(profile.blocks) if b not in overridden]
+        if candidates:
+            example = {"block": candidates[0], "pattern": req.id_regex(candidates[0]).pattern}
+    trace = [cid for cid in sorted(profile.adapters) if profile.adapters[cid].use == "trace"]
+    return (
+        {
+            "id_pattern": req.id_pattern,
+            "uses_block": uses_block,
+            "example": example,
+            "infer": req.infer == "verification",
+            "infer_heading": req.infer_heading,
+            "trace_check": trace[0] if trace else None,
+        },
+        per_block,
+    )
+
+
+def build_context(resolved: ResolvedProfile, root: Path) -> dict[str, Any]:
+    """The data the `agents_md.md.j2` template renders, from `resolved` and `root`.
+
+    `root` is only used to resolve the naming rules reference (``org:``, ``preset:``,
+    ``path:`` or relative), exactly as the `naming` check does.
+    """
+    profile = resolved.profile
+
+    layout = [
+        {"kind": kind, "templates": _as_list(profile.layout[kind])}
+        for kind in sorted(profile.layout)
+    ]
+    block_layout = [
+        {"block": name, "kind": kind, "templates": _as_list(override.layout[kind])}
+        for name, override in sorted(profile.blocks.items())
+        for kind in sorted(override.layout)
+    ]
+    all_templates = [t for row in (*layout, *block_layout) for t in row["templates"]]
+
+    block_checks = [
+        {"block": name, **_check_row(check_id, override.adapters[check_id])}
+        for name, override in sorted(profile.blocks.items())
+        for check_id in sorted(override.adapters)
+    ]
+
+    paths = [_path_row(glob, profile.paths[glob], None) for glob in sorted(profile.paths)]
+    paths += [
+        _path_row(glob, override.paths[glob], name)
+        for name, override in sorted(profile.blocks.items())
+        for glob in sorted(override.paths)
+    ]
+
+    checker = profile.naming.checker
+    requirements, block_requirements = _requirements(resolved)
+    chip = profile.spec.chip
+
+    return {
+        "project": {
+            "name": profile.project,
+            "extends": list(profile.extends),
+            "packs": list(profile.packs),
+            "target_kind": profile.target.kind,
+            "pdk": profile.target.pdk,
+            "chip_spec": {"path": chip.path, "format": chip.format} if chip else None,
+            "ip_dir": profile.spec.ip_dir,
+        },
+        "blocks": [
+            {"name": name, "instances": list(profile.blocks[name].instances)}
+            for name in sorted(profile.blocks)
+        ],
+        "layout": layout,
+        "block_layout": block_layout,
+        "placeholders": [p for p in ("{block}", "{BLOCK}") if any(p in t for t in all_templates)],
+        "naming": [_load_naming(ref, root) for ref in _naming_refs(resolved)],
+        "naming_checker": (
+            {"use": checker.use, "command": _command(checker.model_dump().get("cmd"))}
+            if checker is not None
+            else None
+        ),
+        "checks": [_check_row(cid, profile.adapters[cid]) for cid in sorted(profile.adapters)],
+        "block_checks": block_checks,
+        "requirements": requirements,
+        "block_requirements": block_requirements,
+        "paths": paths,
+        "nda": (
+            {"paths": sorted(set(profile.data.nda_paths)), "model": profile.data.nda_model}
+            if profile.data.nda_paths
+            else None
+        ),
+        "generated": _generated(resolved),
+    }
+
+
+__all__ = ["build_context"]

chipgraph/packs/spec_core/gen/agents_md/_markers.py

@@ -0,0 +1,131 @@
+"""The managed block of an `AGENTS.md`: find the markers, replace only what is between.
+
+DESIGN.md 4.7 / DECISIONS D31: chipgraph owns only the text between
+``<!-- chipgraph:begin -->`` and ``<!-- chipgraph:end -->``; everything else in the file
+belongs to the team and is kept byte for byte.
+
+A marker is recognised only as a whole line (surrounding spaces, tabs and a trailing
+``\\r`` allowed), so a team's own prose that mentions the marker inline is not mistaken
+for one. Malformed markers are an error, never a guess.
+"""
+
+from __future__ import annotations
+
+BEGIN_MARKER = "<!-- chipgraph:begin -->"
+END_MARKER = "<!-- chipgraph:end -->"
+
+
+class AgentsMdError(Exception):
+    """The file's markers are malformed, or the managed block could not be rendered."""
+
+
+def _marker_lines(text: str, marker: str) -> list[tuple[int, int, int]]:
+    """Every whole-line occurrence of `marker`: (line number, start offset, end offset).
+
+    The offsets span the marker line without its line ending.
+    """
+    found: list[tuple[int, int, int]] = []
+    offset = 0
+    for number, line in enumerate(text.splitlines(keepends=True), start=1):
+        body = line.rstrip("\r\n")
+        if body.strip(" \t") == marker:
+            found.append((number, offset, offset + len(body)))
+        offset += len(line)
+    return found
+
+
+def split_managed(existing: str) -> tuple[str, str, str] | None:
+    """Split `existing` into (text up to and including the begin marker line's marker,
+    the managed text between the markers, text from the end marker on).
+
+    Returns `None` if the file has no markers at all. Raises `AgentsMdError` for a begin
+    marker without an end, an end without a begin, more than one of either, or an end
+    marker before the begin marker.
+    """
+    begins = _marker_lines(existing, BEGIN_MARKER)
+    ends = _marker_lines(existing, END_MARKER)
+    if not begins and not ends:
+        return None
+    if len(begins) > 1:
+        lines = ", ".join(str(n) for n, _, _ in begins)
+        raise AgentsMdError(
+            f"{BEGIN_MARKER} appears {len(begins)} times (lines {lines}); keep exactly one "
+            "managed block"
+        )
+    if len(ends) > 1:
+        lines = ", ".join(str(n) for n, _, _ in ends)
+        raise AgentsMdError(
+            f"{END_MARKER} appears {len(ends)} times (lines {lines}); keep exactly one "
+            "managed block"
+        )
+    if not ends:
+        raise AgentsMdError(
+            f"{BEGIN_MARKER} on line {begins[0][0]} has no matching {END_MARKER}; add the "
+            "end marker or remove the begin marker"
+        )
+    if not begins:
+        raise AgentsMdError(
+            f"{END_MARKER} on line {ends[0][0]} has no {BEGIN_MARKER} before it; add the "
+            "begin marker or remove the end marker"
+        )
+    begin_line, _, begin_end = begins[0]
+    end_line, end_start, _ = ends[0]
+    if end_line < begin_line:
+        raise AgentsMdError(
+            f"{END_MARKER} (line {end_line}) comes before {BEGIN_MARKER} (line "
+            f"{begin_line}); the begin marker must come first"
+        )
+    # The begin marker's own line ending stays with the managed text's replacement.
+    return existing[:begin_end], existing[begin_end:end_start], existing[end_start:]
+
+
+def _check_block(block: str) -> None:
+    if _marker_lines(block, BEGIN_MARKER) or _marker_lines(block, END_MARKER):
+        raise AgentsMdError("the managed block must not contain the chipgraph markers itself")
+
+
+def wrap_block(block: str) -> str:
+    """`block` between the two markers, newline-terminated."""
+    _check_block(block)
+    body = block if block.endswith("\n") or not block else block + "\n"
+    return f"{BEGIN_MARKER}\n{body}{END_MARKER}\n"
+
+
+def update_agents_md(existing: str | None, block: str) -> str:
+    """The file content after putting `block` in the managed part of `existing`.
+
+    - `existing` is `None` (no file) or empty: the markers with `block` between them.
+    - `existing` has no markers: the team's content unchanged, one blank line, then the
+      marked block appended.
+    - `existing` has one well-formed pair: only the text between the markers is replaced;
+      every byte outside them (and the marker lines themselves) is kept.
+    - Malformed markers raise `AgentsMdError`.
+
+    `block` is the managed content without the markers (as `render_agents_md` returns).
+    Applying the same `block` twice gives the same result as applying it once.
+    """
+    _check_block(block)
+    if existing is None or existing == "":
+        return wrap_block(block)
+    parts = split_managed(existing)
+    if parts is None:
+        if existing.endswith("\n\n"):
+            sep = ""
+        elif existing.endswith("\n"):
+            sep = "\n"
+        else:
+            sep = "\n\n"
+        return existing + sep + wrap_block(block)
+    head, _, tail = parts
+    body = block if block.endswith("\n") or not block else block + "\n"
+    return f"{head}\n{body}{tail}"
+
+
+__all__ = [
+    "BEGIN_MARKER",
+    "END_MARKER",
+    "AgentsMdError",
+    "split_managed",
+    "update_agents_md",
+    "wrap_block",
+]