chipgraph 0.1.0__py3-none-any.whl

chipgraph/orgs/qnsc/naming-v1.yml

@@ -0,0 +1,113 @@
+# =============================================================================
+# QNSC naming rule, as data for chipgraph's `naming` check.
+#
+# Translated from QNSC_RTL_Design_Naming_Rule V1.1 as enforced by QSoC
+# `flow/lint/naming_rules.yml` at commit 7a917d1 (repository
+# quynhonsemiconductor/vlsi_deep_training, Apache-2.0). The rule ids and messages
+# keep the source document's section numbering ("2.1 module", "1.5 vocabulary", ...)
+# so a reviewer can compare this file with section 4.3 of the rule document.
+#
+# Unlike the source text checker, chipgraph classifies each identifier by its
+# SystemVerilog syntax node kind (pyslang), so the pattern for a `port` is only ever
+# applied to a real port declaration, never to a same-named signal or a reference.
+# =============================================================================
+
+schema_version: 1
+document: QNSC_RTL_Design_Naming_Rule
+version: "1.1"
+ignore_comment: "naming-check: ignore"
+
+# -----------------------------------------------------------------------------
+# Allowed-name pattern per object kind (section 2 -- module, instance, RTL).
+# The whole identifier must match the pattern.
+# -----------------------------------------------------------------------------
+identifiers:
+  module:
+    rule: "2.1 module"
+    # A QNSC functional module, a wrapper around an IP, or a generic QNSC module.
+    pattern: '^(?:m_qnsc_wrap_[a-z0-9_]+|m_qnsc_[a-z0-9_]+|qnsc_[a-z0-9_]+)$'
+    message: "must be m_qnsc_<function>, m_qnsc_wrap_<block> or qnsc_<function>"
+
+  port:
+    rule: "1.2 port prefix"
+    pattern: '^(?:i_|o_|io_)[a-z0-9_]+$'
+    message: "must start with i_, o_ or io_"
+
+  parameter:
+    rule: "2.4 parameter"
+    pattern: '^(?:P_|C_|S_)[A-Z0-9_]+$'
+    message: >-
+      must be P_<FUNCTION> (parameter), C_<FUNCTION> (constant) or S_<STATE>
+      (FSM state), uppercase
+
+  localparam:
+    rule: "2.4 parameter"
+    pattern: '^(?:P_|C_|S_)[A-Z0-9_]+$'
+    message: >-
+      must be P_<FUNCTION> (parameter), C_<FUNCTION> (constant) or S_<STATE>
+      (FSM state), uppercase
+
+  enum_value:
+    rule: "2.4 parameter"
+    pattern: '^S_[A-Z0-9_]+$'
+    message: "an FSM state must be S_<STATE>, uppercase"
+
+  instance:
+    rule: "2.2 instance"
+    pattern: '^u_[a-z0-9_]+$'
+    message: "must be u_<function>[_<index>]"
+
+  signal:
+    rule: "2.3 signal"
+    pattern: '^(?:r_|w_|mem_)[a-z0-9_]+$'
+    message: >-
+      must be r_<function> if registered, w_<function> if combinational, or
+      mem_<function> if a memory array
+
+  memory:
+    rule: "2.3 signal"
+    pattern: '^mem_[a-z0-9_]+$'
+    message: "a memory array must be mem_<function>"
+
+  genvar:
+    rule: "2.3 signal"
+    pattern: '^[a-z][a-z0-9_]*$'
+    message: "must be lowercase with _ only"
+
+# -----------------------------------------------------------------------------
+# Lexical rules (section 1), applied to every identifier declared in a file.
+# -----------------------------------------------------------------------------
+lexical:
+  - rule: "1.1 case"
+    forbid_pattern: '[a-z][A-Z]|[A-Z]{2,}[a-z]'
+    allow_if_matches: '^(?:P_|C_|S_)[A-Z0-9_]+$'   # uppercase constants are fine
+    message: >-
+      uses mixed case; identifiers are lowercase with _ (uppercase only for P_/C_/S_)
+
+  - rule: "1.3 active low"
+    forbid_pattern: '\b(?:rstn|resetn|reset_b|rst_bar)\b'
+    message: "active low is _n after the meaning, as in i_rst_n_sys"
+
+  - rule: "1.4 index"
+    forbid_pattern: '[a-z]\d+(?:_|$)'
+    allow_if_matches: '^(?:P_|C_|S_)[A-Z0-9_]+$'
+    message: "a numeric index takes an underscore, as in timer_0"
+
+# -----------------------------------------------------------------------------
+# Mandatory vocabulary (section 1.5): left is forbidden, right is the project term.
+# -----------------------------------------------------------------------------
+vocabulary:
+  rule: "1.5 vocabulary"
+  message: "the project term is"
+  replace:
+    irq: int
+    interrupt: int
+    clock: clk
+    reset: rst
+    config: cfg
+    debug: dbg
+    power: pwr
+    memory: mem
+    peripheral: peri
+    multiplexer: mux
+    analog: ana

chipgraph/orgs/qnsc/profile.yml

@@ -0,0 +1,5 @@
+# QNSC organization profile (D36): the shared rules a project inherits with
+# `extends: [org:qnsc]`. Kept minimal on purpose -- it points the `naming` check at the
+# organization's data-defined naming rule; a project overrides or adds the rest.
+naming:
+  rules: org:qnsc/naming-v1.yml

chipgraph/packs/__init__.py

@@ -0,0 +1,8 @@
+"""Built-in packs shipped with chipgraph (DECISIONS D36).
+
+Each pack is one subdirectory with a `pack.yml` manifest and, when it has code, an
+`__init__.py`. Directory names are snake_case (`spec_core/`) so the code is importable;
+the pack name in `pack.yml` keeps its dashes (`spec-core`). Pack code registers through
+the `chipgraph.adapters.<kind>` entry points, like any adapter. `chipgraph.core` must not
+import this package (enforced by import-linter).
+"""

chipgraph/packs/assist/__init__.py

@@ -0,0 +1,16 @@
+"""The ``assist`` pack: whole-project assistance commands (DECISIONS D36).
+
+This pack ships ``/audit`` (task M1-20): it runs every deterministic check the project's
+profile configures over the whole project, records their findings in the finding store as
+usual, then builds a report that groups the findings by DESIGN.md 4.8 layer and severity
+(:mod:`chipgraph.packs.assist.audit`). The report is what ``chipgraph audit`` prints and
+the ``audit`` MCP tool returns; ``chipgraph try`` (task M1-21) reuses :func:`run_audit`.
+
+The pack carries no code adapters of its own -- it orchestrates the checks other packs
+register -- so, like every built-in pack, its directory is discovered by
+:func:`chipgraph.app.build.builtin_packs_dir`.
+"""
+
+from chipgraph.packs.assist.audit import AuditReport, run_audit
+
+__all__ = ["AuditReport", "run_audit"]

chipgraph/packs/assist/ask/__init__.py

@@ -0,0 +1,58 @@
+"""`/ask` (task M1-13): questions about the project, answered only with checked citations.
+
+- `ask_context(ctx, question, limit)` (`retrieve`): the sources an answer may use, from
+  typed Design Model lookups (`ModelQuery`) and a safe FTS5 search over entities and the
+  indexed documents (`fts`). Nothing from an `nda` file.
+- `ask_check(ctx, answer)` (`check`): every citation of an `AskAnswer` must name an indexed
+  `path:line` or a `model:<key>`; an answer that is not `unknown` needs at least one.
+- `run_ask` / `answer_question` (`answer`): the API-runtime answerer behind `chipgraph
+  ask`, with the same contract and checker. In Claude Code, `/chipgraph:ask` runs the
+  `chipgraph:asker` subagent over the `ask_context` and `ask_check` MCP tools instead.
+- `index_documents` (`documents`): the document set `chipgraph ingest` indexes after it
+  writes the model store (which drops earlier documents).
+"""
+
+from chipgraph.packs.assist.ask.answer import (
+    AskResult,
+    answer_question,
+    make_provider,
+    parse_answer,
+    run_ask,
+)
+from chipgraph.packs.assist.ask.check import ask_check, check_answer, check_citation
+from chipgraph.packs.assist.ask.contract import (
+    UNKNOWN_ANSWER,
+    AskAnswer,
+    AskCheck,
+    AskContext,
+    AskSource,
+    CitationCheck,
+    DocLine,
+)
+from chipgraph.packs.assist.ask.documents import DocumentIndexReport, index_documents
+from chipgraph.packs.assist.ask.fts import fts_query, question_terms
+from chipgraph.packs.assist.ask.retrieve import ask_context, retrieve
+
+__all__ = [
+    "UNKNOWN_ANSWER",
+    "AskAnswer",
+    "AskCheck",
+    "AskContext",
+    "AskResult",
+    "AskSource",
+    "CitationCheck",
+    "DocLine",
+    "DocumentIndexReport",
+    "answer_question",
+    "ask_check",
+    "ask_context",
+    "check_answer",
+    "check_citation",
+    "fts_query",
+    "index_documents",
+    "make_provider",
+    "parse_answer",
+    "question_terms",
+    "retrieve",
+    "run_ask",
+]

chipgraph/packs/assist/ask/_db.py

@@ -0,0 +1,57 @@
+"""Read-only lookups in the documents table of the model store (`ModelStore.add_document`).
+
+`ModelStore` offers full-text `search` only; `/ask` also needs exact line lookups (the
+context around a hit, and checking that a cited `file:line` is indexed). These read the
+same `documents(path, line, text)` table, read-only, and treat a missing database or
+table as "no documents".
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+
+class DocumentLines:
+    """Line lookups over the indexed documents of the store at `db_path`."""
+
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = db_path
+        self._counts: dict[str, int] | None = None
+
+    def line_counts(self) -> dict[str, int]:
+        """Indexed path -> its number of lines (the highest line number)."""
+        if self._counts is None:
+            rows = self._query("SELECT path, MAX(line) FROM documents GROUP BY path", ())
+            self._counts = {str(path): int(count) for path, count in rows}
+        return self._counts
+
+    def is_indexed(self, path: str) -> bool:
+        return path in self.line_counts()
+
+    def lines(self, path: str, start: int, end: int) -> list[tuple[int, str]]:
+        """The `(line, text)` rows of `path` from `start` to `end`, inclusive, in order."""
+        rows = self._query(
+            "SELECT line, text FROM documents WHERE path = ? AND line BETWEEN ? AND ? "
+            "ORDER BY line",
+            (path, start, end),
+        )
+        return [(int(line), str(text)) for line, text in rows]
+
+    def _query(self, sql: str, params: tuple[object, ...]) -> list[tuple[Any, ...]]:
+        if not self.db_path.is_file():
+            return []
+        try:
+            conn = sqlite3.connect(f"{self.db_path.resolve().as_uri()}?mode=ro", uri=True)
+        except sqlite3.Error:
+            return []
+        try:
+            return list(conn.execute(sql, params))
+        except sqlite3.Error:
+            return []
+        finally:
+            conn.close()
+
+
+__all__ = ["DocumentLines"]

chipgraph/packs/assist/ask/_project.py

@@ -0,0 +1,230 @@
+"""The project as `/ask` sees it: the stored Design Model, its indexed documents, labels.
+
+`AskProject.load` opens the project's model store (it never ingests: a missing store is
+an error telling the user to run `chipgraph ingest`). Entities read from an `nda` file are
+hidden from `/ask` like `nda` documents are: never shown, never citable.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from chipgraph.app.context import AppContext
+from chipgraph.app.errors import AppError
+from chipgraph.core.model import (
+    DesignModel,
+    ModelQuery,
+    ModelStore,
+    QueryError,
+    default_model_db_path,
+)
+from chipgraph.core.model.entities import EntityBase
+from chipgraph.core.state.artifacts import LabelRules
+from chipgraph.packs.assist.ask._db import DocumentLines
+
+_HEX_FIELDS = frozenset({"offset", "base", "address"})
+_SKIP_FIELDS = frozenset({"schema_version", "key", "kind", "name", "source"})
+_MAX_LIST = 24
+
+
+@dataclass
+class AskProject:
+    """The stored model, a query API on it, the indexed documents and the data labels."""
+
+    root: Path
+    store: ModelStore
+    model: DesignModel
+    query: ModelQuery
+    docs: DocumentLines
+    labels: LabelRules
+
+    @classmethod
+    def load(cls, ctx: AppContext) -> AskProject:
+        """Open the project's model store; `AppError` if there is none yet."""
+        db_path = default_model_db_path(ctx.root)
+        if not db_path.is_file():
+            raise AppError("no Design Model yet: run `chipgraph ingest`")
+        store = ModelStore(db_path)
+        model = store.read()
+        return cls(
+            root=ctx.root,
+            store=store,
+            model=model,
+            query=ModelQuery(model, store),
+            docs=DocumentLines(db_path),
+            labels=ctx.store.labels,
+        )
+
+    # --- visibility -------------------------------------------------------------------
+
+    def visible(self, entity: EntityBase) -> bool:
+        """False for an entity read from an `nda` file: `/ask` never shows or cites it."""
+        file = entity.source.file
+        return not (file and self.labels.label_for(file) == "nda")
+
+    def get(self, key: str) -> EntityBase | None:
+        """The visible entity `key`, or None."""
+        entity = self.model.get(key)
+        return entity if entity is not None and self.visible(entity) else None
+
+    # --- entity facts -----------------------------------------------------------------
+
+    def block_of(self, entity: EntityBase) -> str | None:
+        """The block key an entity belongs to, from its typed fields, attrs or owner."""
+        block = getattr(entity, "block", None)
+        if isinstance(block, str) and block:
+            return block
+        attr = entity.attrs.get("block")
+        if isinstance(attr, str) and attr:
+            return attr
+        if entity.kind == "block":
+            return entity.key
+        for owner_field in ("module", "register"):
+            owner_key = getattr(entity, owner_field, None)
+            if isinstance(owner_key, str) and owner_key:
+                owner = self.model.get(owner_key)
+                if owner is not None:
+                    return self.block_of(owner)
+        # Keys like `open_item:<block>.<id>` or `register:<block>.<name>`.
+        _, _, rest = entity.key.partition(":")
+        head, dot, _ = rest.partition(".")
+        if dot and f"block:{head}" in self.model.entities:
+            return f"block:{head}"
+        return None
+
+    def blocks_of(self, entity: EntityBase) -> set[str]:
+        """Every block an entity belongs to: `block_of`, plus an `attrs.blocks` name list."""
+        blocks = {b for b in (self.block_of(entity),) if b}
+        names = entity.attrs.get("blocks")
+        if isinstance(names, list):
+            blocks |= {f"block:{n}" for n in names if isinstance(n, str) and n}
+        return blocks
+
+    def module_of(self, entity: EntityBase) -> str | None:
+        module = getattr(entity, "module", None)
+        if isinstance(module, str) and module:
+            return module
+        return entity.key if entity.kind == "module" else None
+
+    def defined_at(self, entity: EntityBase) -> str | None:
+        """`path:line` where the entity was read from, when that file is indexed."""
+        file, line = entity.source.file, entity.source.line
+        if file and line and self.docs.is_indexed(file):
+            return f"{file}:{line}"
+        return None
+
+    def summary(self, entity: EntityBase) -> str:
+        """A one-line, factual summary of an entity, from its typed fields and relations."""
+        parts = [f"{entity.kind} {entity.name}"]
+        facts = _fields(entity)
+        extra = self._relations_summary(entity)
+        body = "; ".join(f"{k}={_fmt(k, v)}" for k, v in facts.items())
+        if extra:
+            body = f"{body}; {extra}" if body else extra
+        return f"{parts[0]}: {body}" if body else parts[0]
+
+    def _relations_summary(self, entity: EntityBase) -> str:
+        try:
+            if entity.kind == "block":
+                return self._block_summary(entity)
+            if entity.kind == "module":
+                return self._module_summary(entity)
+            if entity.kind == "requirement":
+                trace = self.query.trace(entity.key)
+                bits = []
+                verifies = self._visible_keys(trace.verifies)
+                implements = self._visible_keys(trace.implements)
+                if verifies:
+                    bits.append(f"verified_by={_names(verifies)}")
+                if implements:
+                    bits.append(f"implemented_by={_names(implements)}")
+                return "; ".join(bits)
+        except QueryError:
+            return ""
+        children = self._visible_keys(
+            [r.dst for r in self.model.relations if r.src == entity.key and r.kind == "contains"]
+        )
+        if children:
+            return f"contains={_names(children)}"
+        return ""
+
+    def _block_summary(self, block: EntityBase) -> str:
+        info = self.query.block(block.name)
+        members: dict[str, list[str]] = {}
+        for entity in self.model.entities.values():
+            if entity.kind in ("block", "port", "field") or not self.visible(entity):
+                continue
+            if self.block_of(entity) == block.key:
+                members.setdefault(entity.kind, []).append(entity.key)
+        for kind, keys in (("module", info.modules), ("clock", info.clocks)):
+            for key in self._visible_keys(keys):
+                if key not in members.setdefault(kind, []):
+                    members[kind].append(key)
+        bits = [f"{kind}s={_names(sorted(keys))}" for kind, keys in sorted(members.items())]
+        resets = self._visible_keys(info.resets)
+        if resets:
+            bits.append(f"resets={_names(resets)}")
+        return "; ".join(bits)
+
+    def _module_summary(self, module: EntityBase) -> str:
+        info = self.query.module(module.name)
+        ports = self._visible_keys(info.ports)
+        parameters = self._visible_keys(info.parameters)
+        instances = [i for i in info.instances if self.get(i["module_key"]) is not None]
+        parents = [i for i in info.instantiated_by if self.get(i["module_key"]) is not None]
+        bits = [f"ports={_names(ports)}"] if ports else []
+        if parameters:
+            bits.append(f"parameters={_names(parameters)}")
+        if instances:
+            bits.append(
+                "instances="
+                + ", ".join(f"{i['instance_name']} ({i['module_key']})" for i in instances)
+            )
+        if parents:
+            bits.append(
+                "instantiated_by="
+                + ", ".join(f"{i['module_key']} as {i['instance_name']}" for i in parents)
+            )
+        return "; ".join(bits)
+
+    def _visible_keys(self, keys: list[str]) -> list[str]:
+        """`keys` without the entities `/ask` may not show (unknown ones are kept)."""
+        return [k for k in keys if (e := self.model.get(k)) is None or self.visible(e)]
+
+
+def _fields(entity: EntityBase) -> dict[str, object]:
+    data = entity.model_dump(mode="json")
+    out: dict[str, object] = {}
+    for key, value in data.items():
+        if key in _SKIP_FIELDS or value in (None, "", [], {}):
+            continue
+        if key == "attrs":
+            for attr_key, attr_value in value.items():
+                if attr_value not in (None, "", [], {}):
+                    out[attr_key] = attr_value
+            continue
+        out[key] = value
+    return out
+
+
+def _fmt(key: str, value: object) -> str:
+    if isinstance(value, int) and not isinstance(value, bool):
+        if key in _HEX_FIELDS:
+            return f"{value:#x}"
+        if value >= 0x100:
+            return f"{value} ({value:#x})"
+        return str(value)
+    if isinstance(value, str):
+        return value
+    return json.dumps(value)
+
+
+def _names(keys: list[str]) -> str:
+    shown = keys[:_MAX_LIST]
+    more = f" (+{len(keys) - len(shown)} more)" if len(keys) > len(shown) else ""
+    return "[" + ", ".join(shown) + "]" + more
+
+
+__all__ = ["AskProject"]