chipgraph 0.1.0__py3-none-any.whl

chipgraph/packs/spec_core/gen/agents_md/agents_md.md.j2

@@ -0,0 +1,178 @@
+{#- The chipgraph-managed block of AGENTS.md (pack spec-core, task M1-15).
+
+Rendered by chipgraph.packs.spec_core.gen.agents_md.render_agents_md, which normalizes the
+output: trailing spaces are dropped and runs of blank lines collapse to one. So a tag on a
+line of its own may leave a blank line (fine between paragraphs), while inside a list or a
+table every tag starts the line of the item it guards, so no blank line appears there.
+A project overrides one section with `templates.override: { agents_md_<name>: <file> }`.
+-#}
+## Project rules for coding agents (chipgraph)
+{% block agents_md_intro %}
+
+These rules come from this repository's chipgraph profile and the organization rules it
+extends. Follow them whenever you add or change a file.
+{% endblock %}
+{% block agents_md_project %}
+### Project and blocks
+
+- Project: {{ code(project.name) }}
+{% if project.extends %}- Extends: {% for e in project.extends %}{{ code(e) }}{% if not loop.last %}, {% endif %}{% endfor %}
+{% endif %}{% if project.packs %}- Packs: {% for p in project.packs %}{{ code(p) }}{% if not loop.last %}, {% endif %}{% endfor %}
+{% endif %}{% if project.chip_spec %}- Chip spec: {{ code(project.chip_spec.path) }} (format {{ code(project.chip_spec.format) }})
+{% endif %}{% if project.ip_dir %}- Per-IP specs: {{ code(project.ip_dir) }}
+{% endif %}- Target: {{ project.target_kind }}{% if project.pdk %}, PDK {{ code(project.pdk) }}{% endif %}
+{% if blocks %}
+
+Each block is an IP. Its instances are the names the chip's memory map uses for it; a
+block with no instances listed matches the instance of the same name.
+
+| Block | Instances |
+|---|---|
+{% for b in blocks %}| {{ code(b.name, cell=True) }} | {% if b.instances %}{% for i in b.instances %}{{ code(i, cell=True) }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}-{% endif %} |
+{% endfor %}
+{% endif %}
+{% endblock %}
+{% block agents_md_layout %}
+{% if layout or block_layout %}
+### Where files go
+
+Create each kind of file only at the path its template gives; do not invent new
+directories.{% if placeholders %} In a template, {% for p in placeholders %}{{ code(p) }} is the block name{% if p == "{BLOCK}" %} in upper case{% endif %}{% if not loop.last %} and {% endif %}{% endfor %}.{% endif %}
+{% if layout %}
+
+| Kind | Path template |
+|---|---|
+{% for row in layout %}| {{ text(row.kind) }} | {% if row.templates %}{% for t in row.templates %}{{ code(t, cell=True) }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %} |
+{% endfor %}
+{% endif %}
+{% if block_layout %}
+
+Per-block overrides:
+
+| Block | Kind | Path template |
+|---|---|---|
+{% for row in block_layout %}| {{ code(row.block, cell=True) }} | {{ text(row.kind) }} | {% if row.templates %}{% for t in row.templates %}{{ code(t, cell=True) }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %} |
+{% endfor %}
+{% endif %}
+{% endif %}
+{% endblock %}
+{% block agents_md_naming %}
+{% if naming or naming_checker %}
+### Naming
+{% for rules in naming %}
+
+From {{ code(rules.ref) }} ({{ text(rules.document) }} v{{ text(rules.version) }}). The whole
+name must match the pattern for its kind:
+
+| Kind | Pattern | Rule | Message |
+|---|---|---|---|
+{% for row in rules.identifiers %}| {{ text(row.kind) }} | {{ code(row.pattern, cell=True) }} | {{ text(row.rule) }} | {{ text(row.message) }} |
+{% endfor %}
+{% if rules.lexical %}
+
+Every declared name also follows:
+
+{% for lex in rules.lexical %}- {{ text(lex.rule) }}: {{ text(lex.message) }}
+{% endfor %}
+{% endif %}
+{% if rules.vocabulary %}
+
+Words ({{ text(rules.vocabulary.rule) }}): use the project term on the right, never the
+word on the left: {% for pair in rules.vocabulary.pairs %}{{ code(pair[0]) }} -> {{ code(pair[1]) }}{% if not loop.last %}, {% endif %}{% endfor %}.
+{% endif %}
+
+A declaration line that ends with the comment {{ code(rules.ignore_comment) }} is exempt;
+use it only with a reason the reviewer accepts.
+{% endfor %}
+{% if naming_checker %}
+
+Naming is checked by the {{ code(naming_checker.use) }} checker{% if naming_checker.command %}: {{ code(naming_checker.command) }}{% endif %}.
+{% endif %}
+{% endif %}
+{% endblock %}
+{% block agents_md_checks %}
+### Before you open a PR
+
+Run these from the repository root and fix what they report:
+
+```sh
+chipgraph ingest    # build the Design Model; the cross checks read it
+chipgraph check     # run every configured check; exits 1 if one fails
+chipgraph audit     # every finding, grouped by layer
+```
+
+Scope a run with `chipgraph check --block <block>` or `chipgraph check --only <check>`.
+`chipgraph ingest --strict` and `chipgraph audit --strict` also exit 1, on an error-level
+ingest issue or a blocking finding.
+{% if checks %}
+
+Configured checks (a severity caps what the check reports; a command's `{block}` is the
+block name):
+
+| Check | Adapter | Severity | Command |
+|---|---|---|---|
+{% for c in checks %}| {{ code(c.id, cell=True) }} | {{ text(c.use) }} | {{ text(c.severity) if c.severity else "-" }} | {{ code(c.command, cell=True) if c.command else "-" }} |
+{% endfor %}
+{% endif %}
+{% if block_checks %}
+
+Per-block check overrides:
+
+| Block | Check | Adapter | Severity | Command |
+|---|---|---|---|---|
+{% for c in block_checks %}| {{ code(c.block, cell=True) }} | {{ code(c.id, cell=True) }} | {{ text(c.use) }} | {{ text(c.severity) if c.severity else "-" }} | {{ code(c.command, cell=True) if c.command else "-" }} |
+{% endfor %}
+{% endif %}
+{% endblock %}
+{% block agents_md_requirements %}
+### Requirement IDs
+
+- A requirement ID in a spec must match {{ code(requirements.id_pattern) }}{% if requirements.uses_block %}, with `{block}`/`{BLOCK}` replaced by the block name in lower/upper case{% if requirements.example %} (for {{ code(requirements.example.block) }}: {{ code(requirements.example.pattern) }}){% endif %}{% endif %}.
+{% if requirements.trace_check %}- Name the ID in the test that covers it: the {{ code(requirements.trace_check) }} check traces each requirement to a test.
+{% endif %}{% if requirements.infer %}- A spec without IDs is read in a temporary mode: each numbered item of its "{{ text(requirements.infer_heading) }}" section counts as one requirement, keyed by block and content hash. A declared ID always wins; add IDs rather than rely on this.
+{% endif %}
+{% if block_requirements %}
+
+Per-block overrides:
+
+| Block | ID pattern | Inferred from "{{ text(requirements.infer_heading) }}" |
+|---|---|---|
+{% for r in block_requirements %}| {{ code(r.block, cell=True) }} | {{ code(r.id_pattern, cell=True) }} | {{ "yes" if r.infer else "no" }} |
+{% endfor %}
+{% endif %}
+{% endblock %}
+{% block agents_md_paths %}
+{% if paths %}
+### Path exceptions
+
+These paths follow different rules. Do not write under a path whose write is `deny`,
+and do not add a new exception without a reason the reviewer accepts.
+
+| Path | Block | Checks | Write | Reason |
+|---|---|---|---|---|
+{% for p in paths %}| {{ code(p.glob, cell=True) }} | {{ code(p.block, cell=True) if p.block else "-" }} | {{ text(", ".join(p.checks)) if p.checks else "-" }} | {{ p.write }} | {{ text(p.reason) if p.reason else "-" }} |
+{% endfor %}
+{% endif %}
+{% endblock %}
+{% block agents_md_data %}
+{% if nda %}
+### Data labels
+
+Files matching these paths are labeled `nda`. Never send their content to a cloud model
+(do not paste it into a prompt, an issue or a web tool){% if nda.model == "local" %}; only a local model may read them (`nda_model: local`){% else %}; no model may read them (`nda_model: block`){% endif %}.
+
+{% for p in nda.paths %}- {{ code(p) }}
+{% endfor %}
+{% endif %}
+{% endblock %}
+{% block agents_md_generated %}
+{% if generated %}
+### Generated files
+
+chipgraph or the project's flow generates these files. Do not edit them by hand: change
+their source and regenerate them.
+
+{% for g in generated %}- {{ code(g) }}
+{% endfor %}
+{% endif %}
+{% endblock %}

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

@@ -0,0 +1,110 @@
+"""The ``diagram`` generator (pack ``spec-core``): figures rendered from the Design Model.
+
+Public API:
+
+- :func:`render` — pure: a :class:`~chipgraph.core.model.DesignModel` in, a
+  ``{file name: bytes}`` mapping out. The same model always gives byte-identical bytes.
+- :class:`DiagramGenerator` — the ``chipgraph.adapters.generator`` plugin: rebuilds a model
+  from ``facts`` (entity/relation JSON dumps), writes the files under ``out_dir`` and
+  returns their paths, sorted.
+
+Four figures, each written as an SVG and an uncompressed drawio ``mxfile``:
+
+======================  =========================================
+Kind                     Files
+======================  =========================================
+``blocks``               ``block_diagram.svg`` / ``.drawio``
+``memory_map``           ``memory_map.svg`` / ``.drawio``
+``interrupts``           ``interrupt_map.svg`` / ``.drawio``
+``clocks``               ``clock_reset_tree.svg`` / ``.drawio``
+======================  =========================================
+
+Determinism: everything is sorted by model key (or address, for the memory map), element
+ids come from escaped model keys, coordinates are integers, XML is escaped, line endings
+are ``\\n`` and the drawio ``mxfile`` carries no timestamp/etag/agent attribute. Figures
+are computed from the model, never drawn by an AI (DESIGN.md 4.6).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+
+from chipgraph.core.model import DEFAULT_ENTITY_KINDS, DesignModel, EntityBase, Relation
+from chipgraph.packs.spec_core.gen.diagram._diagrams import (
+    block_diagram,
+    clock_reset_tree,
+    interrupt_map,
+    memory_map,
+)
+from chipgraph.packs.spec_core.gen.diagram._scene import Scene, scene_to_drawio, scene_to_svg
+
+DEFAULT_KINDS: tuple[str, ...] = ("blocks", "memory_map", "interrupts", "clocks")
+"""The diagram kinds :func:`render` produces by default, in output order."""
+
+_BUILDERS = {
+    "blocks": ("block_diagram", block_diagram),
+    "memory_map": ("memory_map", memory_map),
+    "interrupts": ("interrupt_map", interrupt_map),
+    "clocks": ("clock_reset_tree", clock_reset_tree),
+}
+
+
+def render(model: DesignModel, kinds: Iterable[str] = DEFAULT_KINDS) -> dict[str, bytes]:
+    """Render `model` into a ``{file name: bytes}`` mapping (SVG and drawio per kind).
+
+    Raises ``ValueError`` for an unknown kind. The result is deterministic: the same model
+    (regardless of entity insertion order) yields byte-identical output.
+    """
+    files: dict[str, bytes] = {}
+    for kind in kinds:
+        try:
+            stem, builder = _BUILDERS[kind]
+        except KeyError:
+            raise ValueError(
+                f"unknown diagram kind {kind!r}; known kinds: {sorted(_BUILDERS)}"
+            ) from None
+        scene: Scene = builder(model)
+        files[f"{stem}.svg"] = scene_to_svg(scene)
+        files[f"{stem}.drawio"] = scene_to_drawio(scene)
+    return files
+
+
+def facts_to_model(facts: Iterable[Mapping[str, object]]) -> DesignModel:
+    """Rebuild a `DesignModel` from `facts` (entity and relation JSON dumps, intermixed).
+
+    A fact with ``src`` and ``dst`` keys is a relation; every other mapping is an entity,
+    parsed through the default entity-kind registry (so pack kinds round-trip as ext).
+    """
+    entities: list[EntityBase] = []
+    relations: list[Relation] = []
+    for fact in facts:
+        if "src" in fact and "dst" in fact:
+            relations.append(Relation.model_validate(dict(fact)))
+        else:
+            entities.append(DEFAULT_ENTITY_KINDS.parse(dict(fact)))
+    return DesignModel.build(entities, relations)
+
+
+class DiagramGenerator:
+    """`Generator` plugin ``diagram``: render the Design Model figures to `out_dir`."""
+
+    name = "diagram"
+
+    def generate(self, out_dir: Path, facts: Iterable[Mapping[str, object]]) -> tuple[Path, ...]:
+        """Rebuild the model from `facts`, write every figure under `out_dir`, return paths.
+
+        Paths are returned sorted, and files are written with ``\\n`` line endings.
+        """
+        model = facts_to_model(facts)
+        files = render(model)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        written: list[Path] = []
+        for name in sorted(files):
+            path = out_dir / name
+            path.write_bytes(files[name])
+            written.append(path)
+        return tuple(sorted(written))
+
+
+__all__ = ["DEFAULT_KINDS", "DiagramGenerator", "facts_to_model", "render"]

chipgraph/packs/spec_core/gen/diagram/__main__.py

@@ -0,0 +1,44 @@
+"""``python -m chipgraph.packs.spec_core.gen.diagram --root <repo> --out <dir>``.
+
+Reads the Design Model from the project's model store (``default_model_db_path(root)``)
+and writes the four figures into ``--out``. Prints a clear message and exits 1 when the
+model store does not exist yet (run ``chipgraph ingest`` first).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from chipgraph.core.model import default_model_db_path
+from chipgraph.core.model.store import ModelStore
+from chipgraph.packs.spec_core.gen.diagram import render
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Render the model's figures; return a process exit code."""
+    parser = argparse.ArgumentParser(prog="python -m chipgraph.packs.spec_core.gen.diagram")
+    parser.add_argument("--root", type=Path, default=Path("."), help="project repo root")
+    parser.add_argument("--out", type=Path, required=True, help="output directory for figures")
+    args = parser.parse_args(argv)
+
+    db_path = default_model_db_path(args.root)
+    if not db_path.is_file():
+        print(
+            f"no Design Model at {db_path}; run 'chipgraph ingest' to build it first",
+            file=sys.stderr,
+        )
+        return 1
+
+    model = ModelStore(db_path).read()
+    files = render(model)
+    args.out.mkdir(parents=True, exist_ok=True)
+    for name in sorted(files):
+        (args.out / name).write_bytes(files[name])
+        print(f"wrote {args.out / name}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())