chipgraph 0.1.0__py3-none-any.whl

chipgraph/learn/models.py

@@ -0,0 +1,145 @@
+"""Result models for `chipgraph learn` (DESIGN.md 8.6 V1).
+
+`learn` reads an existing repository and infers the conventions a `.chipgraph.yml`
+declares: where files live (`layout`), how identifiers are named (`naming`), the common
+file header, the filelist style, and the document template. It reports each inference as
+evidence with a coverage statistic ("97% of ports match `^(i|o|io)_`") rather than as a
+silent guess, so a human reviews the draft before it is used.
+
+These models are the machine-readable form of that report. They live outside
+`chipgraph.core` on purpose: `learn` reasons about chips, tools and file layouts, which
+`core` must not.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Kind = Literal[
+    "module",
+    "port",
+    "parameter",
+    "localparam",
+    "enum_value",
+    "instance",
+    "signal",
+    "memory",
+    "genvar",
+]
+"""The identifier kinds `learn` infers a naming pattern for (from `_naming_pyslang`)."""
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class Coverage(_Model):
+    """How many observed items an inferred pattern matches: `matched` of `total`."""
+
+    matched: int = Field(ge=0, description="Number of observed items the pattern matches.")
+    total: int = Field(ge=0, description="Total number of observed items of this kind.")
+
+    @property
+    def ratio(self) -> float:
+        """`matched / total`, or `1.0` when there is nothing to cover."""
+        return 1.0 if self.total == 0 else self.matched / self.total
+
+    @property
+    def percent(self) -> int:
+        """Coverage as a whole-number percentage, e.g. `97`."""
+        return round(self.ratio * 100)
+
+
+class LayoutRule(_Model):
+    """An inferred `layout` entry: an artifact kind and its path template, with coverage."""
+
+    kind: str = Field(description="The artifact kind, e.g. 'rtl', 'filelist', 'spec', 'tb'.")
+    template: str = Field(description="The inferred path template, e.g. 'rtl/{block}.sv'.")
+    coverage: Coverage = Field(description="Files of this kind the template matches.")
+    examples: tuple[str, ...] = Field(
+        default=(), description="A few example paths the template was inferred from."
+    )
+
+
+class NamingRule(_Model):
+    """An inferred naming pattern for one identifier kind, with coverage and evidence."""
+
+    kind: Kind = Field(description="The identifier kind this rule constrains.")
+    pattern: str = Field(description="A regex the identifier must fully match to pass.")
+    coverage: Coverage = Field(description="Declared identifiers of this kind the pattern matches.")
+    emitted: bool = Field(
+        description="Whether coverage met the threshold, so this is a rule (not an observation)."
+    )
+    description: str = Field(
+        description="Human-readable summary, e.g. '97% of ports match `^(i|o|io)_`'."
+    )
+    examples: tuple[str, ...] = Field(
+        default=(), description="A few example identifiers the pattern was inferred from."
+    )
+
+
+class Observation(_Model):
+    """A learned fact reported for the reviewer, not emitted as a check (e.g. the header)."""
+
+    topic: str = Field(description="What was observed, e.g. 'header', 'filelist', 'doc'.")
+    summary: str = Field(description="A human-readable one-line summary of the observation.")
+    coverage: Coverage | None = Field(
+        default=None, description="Coverage, when the observation is a ratio."
+    )
+    detail: dict[str, Any] = Field(
+        default_factory=dict, description="Structured detail, e.g. the header text or headings."
+    )
+
+
+class LearnResult(_Model):
+    """The full result of `learn`: a draft profile plus the evidence behind it (DESIGN 8.6)."""
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    root: str = Field(description="The repository root that was learned, as given.")
+    project: str = Field(description="The inferred project name (the root directory name).")
+    threshold: float = Field(
+        description="Minimum coverage for a naming pattern to be emitted as a rule."
+    )
+    blocks: tuple[str, ...] = Field(
+        default=(), description="Block names inferred from the repeated directory level."
+    )
+    layout: tuple[LayoutRule, ...] = Field(
+        default=(), description="Inferred layout templates, one per artifact kind."
+    )
+    naming: tuple[NamingRule, ...] = Field(
+        default=(), description="Inferred naming patterns, per identifier kind."
+    )
+    observations: tuple[Observation, ...] = Field(
+        default=(), description="Learned facts reported for review (header, filelist, doc)."
+    )
+    vendor_paths: tuple[str, ...] = Field(
+        default=(), description="Vendor/third-party path globs to exempt from checks."
+    )
+    filelist_style: Literal["filelist", "root", "none"] = Field(
+        default="none",
+        description=(
+            "How filelist paths resolve: 'filelist' (relative to the filelist's own dir, "
+            "which the `filelist` check enforces), 'root' (relative to the repo root, which "
+            "it cannot yet), or 'none' (no filelists found)."
+        ),
+    )
+    naming_rules_document: str = Field(
+        default="learned", description="The `document` field written into the naming-rules file."
+    )
+
+    @property
+    def emitted_naming(self) -> tuple[NamingRule, ...]:
+        """The naming rules whose coverage met the threshold."""
+        return tuple(r for r in self.naming if r.emitted)
+
+
+__all__ = [
+    "Coverage",
+    "Kind",
+    "LayoutRule",
+    "LearnResult",
+    "NamingRule",
+    "Observation",
+]

chipgraph/learn/try_run.py

@@ -0,0 +1,228 @@
+"""`chipgraph try`: run chipgraph read-only against a repo, writing nothing into it.
+
+`try` lets a user evaluate chipgraph on a repository before committing a `.chipgraph.yml`
+(DESIGN.md 8.4). It infers a draft profile (or reads one), then runs only *read* commands:
+`ingest` into a temporary state directory, `check`, and `audit` when that pack's API is
+importable. It guarantees three things the tests pin:
+
+- the repository is left byte-identical (its `.chipgraph/` is never created): every write
+  goes to a private working copy under a temp directory, so the repo is only ever read;
+- local plugins are disabled (`CHIPGRAPH_LOCAL_PLUGINS=0`): an untrusted repo must not run
+  its own code during a `try`;
+- it runs the `assist` pack's audit over the temporary state (no second ingest).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from chipgraph.app.checks import ProfileCheckRunner
+from chipgraph.app.context import AppContext
+from chipgraph.core.contracts import ArtifactRef, CheckResult, RuleInstance
+from chipgraph.learn.draft import (
+    build_naming_rules,
+    build_profile_dict,
+    dump_naming_rules_yaml,
+    dump_yaml,
+)
+from chipgraph.learn.infer import DEFAULT_THRESHOLD, learn
+from chipgraph.learn.models import LearnResult
+
+_LOCAL_PLUGINS_ENV = "CHIPGRAPH_LOCAL_PLUGINS"
+_NAMING_RULES_NAME = "chipgraph.draft.naming.yml"
+_SKIP_COPY = frozenset({".git", ".chipgraph"})
+
+
+@dataclass(slots=True)
+class TryReport:
+    """What `try` did: the draft it used, the ingest stats, check results, audit status."""
+
+    result: LearnResult
+    ingest_ok: bool
+    ingest_summary: str
+    checks: list[tuple[str, str | None, CheckResult]] = field(default_factory=list)
+    audit_available: bool = False
+    audit_summary: str = ""
+
+    @property
+    def check_files_with_issues(self) -> int:
+        """Number of distinct files any check reported an issue for."""
+        files: set[str] = set()
+        for _cid, _blk, result in self.checks:
+            for issue in result.issues:
+                if issue.file:
+                    files.add(issue.file)
+        return len(files)
+
+
+def try_run(
+    repo_root: Path,
+    *,
+    profile_path: Path | None = None,
+    threshold: float = DEFAULT_THRESHOLD,
+) -> TryReport:
+    """Learn (or read a draft), then run ingest/check/audit read-only against `repo_root`.
+
+    `profile_path`, when given, is a draft profile written by `learn --out`; otherwise the
+    repo is learned fresh. Nothing is ever written into `repo_root`: a private working copy
+    is made under a temp dir, and all state and the model DB land there.
+    """
+    repo_root = repo_root.resolve()
+    result = learn(repo_root, threshold=threshold)
+
+    with _local_plugins_disabled(), tempfile.TemporaryDirectory(prefix="chipgraph-try-") as tmp:
+        work = Path(tmp) / "repo"
+        _mirror_repo(repo_root, work)
+        _place_profile(work, result, profile_path)
+        ctx = AppContext.load(work)
+        report = _run_readonly(ctx, result)
+    return report
+
+
+# --------------------------------------------------------------------------------------
+# read-only run against the working copy
+# --------------------------------------------------------------------------------------
+
+
+def _run_readonly(ctx: AppContext, result: LearnResult) -> TryReport:
+    ingest_ok, ingest_summary = _try_ingest(ctx)
+    checks = _run_checks(ctx)
+    audit_available, audit_summary = _try_audit(ctx)
+    return TryReport(
+        result=result,
+        ingest_ok=ingest_ok,
+        ingest_summary=ingest_summary,
+        checks=checks,
+        audit_available=audit_available,
+        audit_summary=audit_summary,
+    )
+
+
+def _try_ingest(ctx: AppContext) -> tuple[bool, str]:
+    from chipgraph.app.ingest import run_ingest
+
+    try:
+        report = run_ingest(ctx)
+    except Exception as exc:  # a draft may not ingest cleanly; try must not crash
+        return False, f"ingest failed: {exc}"
+    stats = report.result.stats
+    return (
+        not report.has_error,
+        f"inputs={stats.inputs} entities={stats.entities} relations={stats.relations}",
+    )
+
+
+def _run_checks(ctx: AppContext) -> list[tuple[str, str | None, CheckResult]]:
+    resolved = ctx.require_profile()
+    runner = ProfileCheckRunner(ctx)
+    check_ids = sorted(resolved.profile.adapters)
+    raw_blocks = sorted(resolved.profile.blocks)
+    out: list[tuple[str, str | None, CheckResult]] = []
+
+    async def _run() -> None:
+        for cid in check_ids:
+            blocks: list[str | None] = (
+                list(raw_blocks) if runner.runs_per_block(cid) and raw_blocks else [None]
+            )
+            for block in blocks:
+                instance = _instance(cid, block)
+                result = await runner.run(cid, instance)
+                out.append((cid, block, result))
+
+    asyncio.run(_run())
+    return out
+
+
+def _instance(check_id: str, block: str | None) -> RuleInstance:
+    params = {"block": block} if block is not None else {}
+    rule_id = "chipgraph/try"
+    return RuleInstance(
+        rule_id=rule_id,
+        params=params,
+        outputs=(ArtifactRef(kind="report", path=f".chipgraph/tmp/try-{check_id}.json"),),
+        instance_id=RuleInstance.make_id(rule_id, params),
+    )
+
+
+def _try_audit(ctx: AppContext) -> tuple[bool, str]:
+    """Run the `assist` pack's audit over what `try` already ingested; its one-line summary.
+
+    Ingest has already run into the temporary state, so the audit does not repeat it. An
+    audit that fails is reported, not raised: `try` is a first look at a repo.
+    """
+    from chipgraph.packs.assist import run_audit
+
+    try:
+        report = run_audit(ctx, ingest=False)
+    except Exception as exc:
+        return True, f"audit ran with errors: {exc}"
+    return True, f"audit: {report.summary_line()}"
+
+
+# --------------------------------------------------------------------------------------
+# working copy and profile placement
+# --------------------------------------------------------------------------------------
+
+
+def _mirror_repo(src: Path, dest: Path) -> None:
+    """Copy `src` into `dest`, skipping `.git` and any existing `.chipgraph/` state.
+
+    `try` reads the repo and writes only into this copy, so the real repo is untouched.
+    """
+    shutil.copytree(
+        src,
+        dest,
+        symlinks=True,
+        ignore=shutil.ignore_patterns(*_SKIP_COPY),
+        ignore_dangling_symlinks=True,
+    )
+
+
+def _place_profile(work: Path, result: LearnResult, profile_path: Path | None) -> None:
+    """Write the profile (draft or given) and its naming rules into the working copy."""
+    if profile_path is not None:
+        data = yaml.safe_load(profile_path.read_text(encoding="utf-8")) or {}
+        rules_src = profile_path.parent / _NAMING_RULES_NAME
+        if rules_src.is_file():
+            (work / _NAMING_RULES_NAME).write_text(
+                rules_src.read_text(encoding="utf-8"), encoding="utf-8"
+            )
+    else:
+        data = _draft_for_work(work, result)
+    (work / ".chipgraph.yml").write_text(dump_yaml(data), encoding="utf-8")
+
+
+def _draft_for_work(work: Path, result: LearnResult) -> dict[str, Any]:
+    rules = build_naming_rules(result)
+    naming_ref: str | None = None
+    if rules is not None:
+        (work / _NAMING_RULES_NAME).write_text(dump_naming_rules_yaml(rules), encoding="utf-8")
+        naming_ref = _NAMING_RULES_NAME
+    return build_profile_dict(result, naming_rules_ref=naming_ref)
+
+
+@contextmanager
+def _local_plugins_disabled() -> Iterator[None]:
+    """Force `CHIPGRAPH_LOCAL_PLUGINS=0` for the duration, restoring the prior value."""
+    prior = os.environ.get(_LOCAL_PLUGINS_ENV)
+    os.environ[_LOCAL_PLUGINS_ENV] = "0"
+    try:
+        yield
+    finally:
+        if prior is None:
+            os.environ.pop(_LOCAL_PLUGINS_ENV, None)
+        else:
+            os.environ[_LOCAL_PLUGINS_ENV] = prior
+
+
+__all__ = ["TryReport", "try_run"]

chipgraph/mcp/__init__.py

@@ -0,0 +1,12 @@
+"""The MCP server (task M0-14): exposes `status`, `build`, `check`, `approve` and
+`config_show` as MCP tools over stdio, for Claude Code or any other MCP client
+(DESIGN.md, section on the MCP server; docs/DECISIONS.md D35).
+
+This package builds on `chipgraph.app` and `chipgraph.core`, never the other way
+around: core must not import `chipgraph.mcp` (see `pyproject.toml`'s import-linter
+contract).
+"""
+
+from chipgraph.mcp.server import build_server, run_stdio
+
+__all__ = ["build_server", "run_stdio"]

chipgraph/mcp/model_tools.py

@@ -0,0 +1,167 @@
+"""MCP tools for the Design Model query API (M1-02).
+
+Each tool opens the project's model db at `default_model_db_path(layout)`. If the db
+does not exist, raises a tool error "no Design Model yet: run `chipgraph ingest`".
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from chipgraph.app.context import AppContext
+from chipgraph.core.model import (
+    ModelQuery,
+    ModelStore,
+    QueryError,
+    default_model_db_path,
+)
+
+
+async def model_block(ctx: AppContext, name: str) -> dict[str, Any]:
+    """Retrieve a block and what it contains."""
+    db_path = default_model_db_path(ctx.layout.root)
+    if not db_path.is_file():
+        raise ValueError("no Design Model yet: run `chipgraph ingest`")
+
+    store = ModelStore(db_path)
+    model = store.read()
+    query = ModelQuery(model, store)
+
+    try:
+        result = query.block(name)
+        return result.model_dump(mode="json")
+    except QueryError as exc:
+        raise ValueError(str(exc)) from exc
+
+
+async def model_module(ctx: AppContext, name: str) -> dict[str, Any]:
+    """Retrieve a module, its ports, parameters, instances, and who instantiates it."""
+    db_path = default_model_db_path(ctx.layout.root)
+    if not db_path.is_file():
+        raise ValueError("no Design Model yet: run `chipgraph ingest`")
+
+    store = ModelStore(db_path)
+    model = store.read()
+    query = ModelQuery(model, store)
+
+    try:
+        result = query.module(name)
+        return result.model_dump(mode="json")
+    except QueryError as exc:
+        raise ValueError(str(exc)) from exc
+
+
+async def model_find(
+    ctx: AppContext,
+    kind: str | None = None,
+    name: str | None = None,
+    limit: int = 100,
+) -> dict[str, Any]:
+    """Find entities by kind, name (glob via fnmatch)."""
+    db_path = default_model_db_path(ctx.layout.root)
+    if not db_path.is_file():
+        raise ValueError("no Design Model yet: run `chipgraph ingest`")
+
+    store = ModelStore(db_path)
+    model = store.read()
+    query = ModelQuery(model, store)
+
+    try:
+        results = query.find(kind=kind, name=name, limit=limit)
+        return {"results": [r.model_dump(mode="json") for r in results]}
+    except QueryError as exc:
+        raise ValueError(str(exc)) from exc
+
+
+async def model_trace(ctx: AppContext, key: str) -> dict[str, Any]:
+    """Trace a requirement or entity: show requirements and links.
+
+    For requirement entities: shows implements, verifies, derives_from, and flags.
+    For other entities: shows requirements that point to them.
+    """
+    db_path = default_model_db_path(ctx.layout.root)
+    if not db_path.is_file():
+        raise ValueError("no Design Model yet: run `chipgraph ingest`")
+
+    store = ModelStore(db_path)
+    model = store.read()
+    query = ModelQuery(model, store)
+
+    try:
+        result = query.trace(key)
+        return result.model_dump(mode="json")
+    except QueryError as exc:
+        raise ValueError(str(exc)) from exc
+
+
+async def model_impact(ctx: AppContext, key: str, max_depth: int = 5) -> dict[str, Any]:
+    """Compute downstream impact from a change at `key`.
+
+    Traverses `contains`, `instantiates`, `connects`, `derives_from`, `implements`,
+    `verifies` relations downstream, up to `max_depth` levels.
+    """
+    db_path = default_model_db_path(ctx.layout.root)
+    if not db_path.is_file():
+        raise ValueError("no Design Model yet: run `chipgraph ingest`")
+
+    store = ModelStore(db_path)
+    model = store.read()
+    query = ModelQuery(model, store)
+
+    try:
+        result = query.impact(key, max_depth=max_depth)
+        return result.model_dump(mode="json")
+    except QueryError as exc:
+        raise ValueError(str(exc)) from exc
+
+
+async def model_neighbors(
+    ctx: AppContext,
+    key: str,
+    kinds: list[str] | None = None,
+    relation: str | None = None,
+    direction: str = "out",
+) -> dict[str, Any]:
+    """Find adjacent entities (one hop) in the specified direction.
+
+    Args:
+        key: The entity key.
+        kinds: If given, filter destinations by these entity kinds.
+        relation: If given, filter relations by this kind.
+        direction: "out" (forward), "in" (backward), or "both" (both).
+    """
+    db_path = default_model_db_path(ctx.layout.root)
+    if not db_path.is_file():
+        raise ValueError("no Design Model yet: run `chipgraph ingest`")
+
+    store = ModelStore(db_path)
+    model = store.read()
+    query = ModelQuery(model, store)
+
+    try:
+        result = query.neighbors(key, kinds=kinds, relation=relation, direction=direction)
+        return result.model_dump(mode="json")
+    except QueryError as exc:
+        raise ValueError(str(exc)) from exc
+
+
+async def model_search(
+    ctx: AppContext,
+    text: str,
+    kinds: list[str] | None = None,
+    limit: int = 20,
+) -> dict[str, Any]:
+    """Full-text search over entities and documents."""
+    db_path = default_model_db_path(ctx.layout.root)
+    if not db_path.is_file():
+        raise ValueError("no Design Model yet: run `chipgraph ingest`")
+
+    store = ModelStore(db_path)
+    model = store.read()
+    query = ModelQuery(model, store)
+
+    try:
+        results = query.search(text, kinds=kinds, limit=limit)
+        return {"results": [r.model_dump(mode="json") for r in results]}
+    except QueryError as exc:
+        raise ValueError(str(exc)) from exc