chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/state/trace.py

@@ -0,0 +1,225 @@
+"""Tracing: OpenTelemetry spans for runs, rule instances, checks and executor calls
+(DESIGN.md 9, "Quan sát"). Attribute names follow the OpenTelemetry GenAI semantic
+conventions where they apply, and `chipgraph.*` otherwise.
+
+Off by default: every caller gets a `NoopTracer` unless it explicitly asks for one, and
+`configure(..., offline=True)` (or `exporter="none"`) always turns tracing off regardless
+of what else is configured (DESIGN.md 9: "offline` turns every export off").
+
+Only `opentelemetry-api` is imported at module level, so importing this module (and
+therefore `chipgraph.core`) never requires the OpenTelemetry SDK or an exporter to be
+installed. `configure()` imports those lazily, only when they are actually needed, and
+raises a clear error if they are missing.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from contextlib import AbstractContextManager, contextmanager, suppress
+from typing import Literal, Protocol, runtime_checkable
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.trace import Span as OtelSpan
+from opentelemetry.trace import TracerProvider as OtelTracerProvider
+
+# --- attribute names ----------------------------------------------------------------
+
+RUN_ID = "chipgraph.run.id"
+TARGET = "chipgraph.target"
+RULE_ID = "chipgraph.rule.id"
+RULE_INSTANCE = "chipgraph.rule.instance"
+RULE_KIND = "chipgraph.rule.kind"
+CHECK_ID = "chipgraph.check.id"
+CHECK_STATUS = "chipgraph.check.status"
+FAILURE_LABEL = "chipgraph.failure.label"
+
+# Agent/LLM calls (used from M2 onward), per the GenAI semantic conventions.
+GEN_AI_OPERATION_NAME = "gen_ai.operation.name"
+GEN_AI_REQUEST_MODEL = "gen_ai.request.model"
+GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens"
+GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+
+# --- span names ------------------------------------------------------------------------
+
+SPAN_RUN = "chipgraph.run"
+SPAN_RULE = "chipgraph.rule"
+SPAN_CHECK = "chipgraph.check"
+SPAN_EXECUTE = "chipgraph.execute"
+SPAN_INVOKE_AGENT = "invoke_agent"
+
+AttrValue = str | int | float | bool
+
+
+@runtime_checkable
+class SpanHandle(Protocol):
+    """A handle to the currently open span."""
+
+    def set(self, key: str, value: AttrValue) -> None:
+        """Set (or overwrite) one attribute on the span."""
+        ...
+
+    def error(self, message: str) -> None:
+        """Mark the span as failed, with `message` as the error description."""
+        ...
+
+
+@runtime_checkable
+class Tracer(Protocol):
+    """Opens spans. `NoopTracer` is the default everywhere; `OtelTracer` is real."""
+
+    def span(self, name: str, **attributes: AttrValue) -> AbstractContextManager[SpanHandle]:
+        """Open a span named `name`, with `attributes` set on it up front."""
+        ...
+
+    def flush(self) -> None:
+        """Export every finished span now. Never raises."""
+        ...
+
+
+class _NoopSpanHandle:
+    """The `SpanHandle` `NoopTracer` hands out: every call is a no-op."""
+
+    __slots__ = ()
+
+    def set(self, key: str, value: AttrValue) -> None:
+        return None
+
+    def error(self, message: str) -> None:
+        return None
+
+
+_NOOP_SPAN_HANDLE = _NoopSpanHandle()
+
+
+class NoopTracer:
+    """A `Tracer` that does nothing, at near-zero cost. The default everywhere."""
+
+    @contextmanager
+    def span(self, name: str, **attributes: AttrValue) -> Iterator[SpanHandle]:
+        yield _NOOP_SPAN_HANDLE
+
+    def flush(self) -> None:
+        return None
+
+
+class _OtelSpanHandle:
+    """The `SpanHandle` `OtelTracer` hands out: wraps a live OpenTelemetry `Span`."""
+
+    __slots__ = ("_span",)
+
+    def __init__(self, span: OtelSpan) -> None:
+        self._span = span
+
+    def set(self, key: str, value: AttrValue) -> None:
+        self._span.set_attribute(key, value)
+
+    def error(self, message: str) -> None:
+        self._span.set_status(otel_trace.Status(otel_trace.StatusCode.ERROR, message))
+
+
+class OtelTracer:
+    """Wraps `opentelemetry.trace.get_tracer`. Real spans, real cost.
+
+    `provider` lets tests inject a `TracerProvider` wired to an in-memory exporter
+    instead of the process-global one.
+    """
+
+    def __init__(
+        self, service_name: str = "chipgraph", *, provider: OtelTracerProvider | None = None
+    ) -> None:
+        self._provider = provider
+        self._tracer = (
+            provider.get_tracer(service_name)
+            if provider is not None
+            else otel_trace.get_tracer(service_name)
+        )
+
+    @contextmanager
+    def span(self, name: str, **attributes: AttrValue) -> Iterator[SpanHandle]:
+        with self._tracer.start_as_current_span(name) as span:
+            for key, value in attributes.items():
+                span.set_attribute(key, value)
+            yield _OtelSpanHandle(span)
+
+    def flush(self) -> None:
+        """Flush the provider's span processors, so `console`/`otlp` output is not
+        left to the interpreter's exit. Tracing must never break a build."""
+        force_flush = getattr(self._provider, "force_flush", None)
+        if force_flush is None:
+            return
+        with suppress(Exception):
+            force_flush()
+
+
+_SDK_HINT = "the OpenTelemetry SDK is not installed; run `pip install chipgraph[otel]`"
+
+
+def configure(
+    exporter: Literal["none", "console", "otlp"],
+    *,
+    offline: bool = False,
+    endpoint: str | None = None,
+) -> Tracer:
+    """Build the `Tracer` a run should use.
+
+    `exporter="none"` or `offline=True` always returns `NoopTracer`, regardless of the
+    other arguments (DESIGN.md 9: `offline` turns every export off). `"console"` prints
+    spans to stdout via the SDK's `ConsoleSpanExporter`. `"otlp"` exports over OTLP/HTTP
+    to `endpoint` (default: the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable).
+    """
+    if offline or exporter == "none":
+        return NoopTracer()
+
+    try:
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider as SdkTracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+    except ImportError as exc:
+        raise RuntimeError(f"tracing exporter {exporter!r} requires {_SDK_HINT}") from exc
+
+    provider = SdkTracerProvider(resource=Resource.create({"service.name": "chipgraph"}))
+
+    if exporter == "console":
+        provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+    elif exporter == "otlp":
+        try:
+            # Only in the `otel` extra, not a hard or dev dependency: not always installed.
+            from opentelemetry.exporter.otlp.proto.http.trace_exporter import (  # type: ignore[import-not-found]
+                OTLPSpanExporter,
+            )
+        except ImportError as exc:
+            raise RuntimeError(f"tracing exporter 'otlp' requires {_SDK_HINT}") from exc
+        target = endpoint or os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+        provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint=target)))
+    else:
+        raise ValueError(f"unknown exporter {exporter!r}")
+
+    return OtelTracer(provider=provider)
+
+
+__all__ = [
+    "CHECK_ID",
+    "CHECK_STATUS",
+    "FAILURE_LABEL",
+    "GEN_AI_OPERATION_NAME",
+    "GEN_AI_REQUEST_MODEL",
+    "GEN_AI_USAGE_INPUT_TOKENS",
+    "GEN_AI_USAGE_OUTPUT_TOKENS",
+    "RULE_ID",
+    "RULE_INSTANCE",
+    "RULE_KIND",
+    "RUN_ID",
+    "SPAN_CHECK",
+    "SPAN_EXECUTE",
+    "SPAN_INVOKE_AGENT",
+    "SPAN_RULE",
+    "SPAN_RUN",
+    "TARGET",
+    "AttrValue",
+    "NoopTracer",
+    "OtelTracer",
+    "SpanHandle",
+    "Tracer",
+    "configure",
+]

chipgraph/learn/__init__.py

@@ -0,0 +1,96 @@
+"""`chipgraph learn` / `chipgraph try`: infer a project's conventions (DESIGN.md 8.6 V1).
+
+`learn(root)` reads an existing repository and returns a `LearnResult`: a draft profile
+plus the evidence and coverage behind each inferred rule. `draft` turns that into a
+`.chipgraph.yml` and a naming-rules file; `try_run` runs chipgraph read-only against a
+repo; `init_from_learn` writes the reviewed draft into a project as its `.chipgraph.yml`.
+
+This package sits outside `chipgraph.core`: it reasons about chips, tools and file
+layouts, and imports checks/app freely.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from chipgraph.learn.draft import (
+    DRAFT_NAMING_RULES_NAME,
+    DRAFT_PROFILE_NAME,
+    build_naming_rules,
+    build_profile_dict,
+    dump_naming_rules_yaml,
+    dump_profile_yaml,
+    dump_yaml,
+    write_draft,
+)
+from chipgraph.learn.infer import DEFAULT_THRESHOLD, learn
+from chipgraph.learn.models import (
+    Coverage,
+    LayoutRule,
+    LearnResult,
+    NamingRule,
+    Observation,
+)
+from chipgraph.learn.try_run import TryReport, try_run
+
+_INIT_NAMING_RULES_REL = ".chipgraph/naming.yml"
+"""Where `init --from-learn` writes the learned naming rules, referenced as `path:...`."""
+
+
+class InitFromLearnError(Exception):
+    """Raised when `init --from-learn` cannot write (e.g. `.chipgraph.yml` exists)."""
+
+
+def init_from_learn(
+    root: Path, *, threshold: float = DEFAULT_THRESHOLD
+) -> tuple[Path, Path | None]:
+    """Write `.chipgraph.yml` (and a naming-rules file) into `root` from a fresh learn.
+
+    Refuses to overwrite an existing `.chipgraph.yml`. Returns `(profile_path,
+    naming_rules_path_or_None)`.
+    """
+    profile_path = root / ".chipgraph.yml"
+    if profile_path.is_file():
+        raise InitFromLearnError(
+            f"{profile_path} already exists; refusing to overwrite (remove it first)"
+        )
+
+    result = learn(root, threshold=threshold)
+    rules = build_naming_rules(result)
+    naming_path: Path | None = None
+    naming_ref: str | None = None
+    if rules is not None:
+        naming_path = root / _INIT_NAMING_RULES_REL
+        naming_path.parent.mkdir(parents=True, exist_ok=True)
+        naming_path.write_text(dump_naming_rules_yaml(rules), encoding="utf-8")
+        naming_ref = _INIT_NAMING_RULES_REL
+
+    data = build_profile_dict(result, naming_rules_ref=naming_ref)
+    header = (
+        "# chipgraph project profile written by `chipgraph init --from-learn` (DESIGN.md 8.6).\n"
+        "# Review it: each rule was inferred from the repo. Edit freely.\n"
+    )
+    profile_path.write_text(header + dump_yaml(data), encoding="utf-8")
+    return profile_path, naming_path
+
+
+__all__ = [
+    "DEFAULT_THRESHOLD",
+    "DRAFT_NAMING_RULES_NAME",
+    "DRAFT_PROFILE_NAME",
+    "Coverage",
+    "InitFromLearnError",
+    "LayoutRule",
+    "LearnResult",
+    "NamingRule",
+    "Observation",
+    "TryReport",
+    "build_naming_rules",
+    "build_profile_dict",
+    "dump_naming_rules_yaml",
+    "dump_profile_yaml",
+    "init_from_learn",
+    "learn",
+    "try_run",
+    "write_draft",
+]

chipgraph/learn/draft.py

@@ -0,0 +1,187 @@
+"""Turn a `LearnResult` into a draft `.chipgraph.yml` profile and a naming-rules file.
+
+The draft is what `chipgraph learn --out` writes and what `chipgraph try` / `chipgraph
+init --from-learn` consume. It is deliberately small: the layout templates, a `naming`
+adapter pointing at a written rules file, a `layout` and a `filelist` adapter, the block
+list, and a `paths:` exception per vendored directory. A human reviews it before use
+(DESIGN.md 8.6 V1).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from chipgraph.checks._naming_rules import KindRule, NamingRules
+from chipgraph.learn.models import LearnResult
+
+DRAFT_PROFILE_NAME = "chipgraph.draft.yml"
+"""File name `learn --out` writes the draft profile as (never `.chipgraph.yml`)."""
+
+DRAFT_NAMING_RULES_NAME = "chipgraph.draft.naming.yml"
+"""File name `learn --out` writes the learned naming rules as."""
+
+_NAMING_MESSAGES = {
+    "module": "does not match the learned module pattern",
+    "port": "does not match the learned port pattern",
+    "parameter": "does not match the learned parameter pattern",
+    "localparam": "does not match the learned localparam pattern",
+    "enum_value": "does not match the learned enum-value pattern",
+    "instance": "does not match the learned instance pattern",
+    "signal": "does not match the learned signal pattern",
+    "memory": "does not match the learned memory pattern",
+    "genvar": "does not match the learned genvar pattern",
+}
+
+
+def build_naming_rules(result: LearnResult) -> NamingRules | None:
+    """The `NamingRules` model for the emitted (threshold-meeting) naming patterns.
+
+    Returns `None` when no pattern met the threshold, so no rules file is written and the
+    draft omits the `naming` adapter entirely (an empty rule file would reject everything).
+    """
+    emitted = result.emitted_naming
+    if not emitted:
+        return None
+    identifiers = {
+        rule.kind: KindRule(
+            rule=f"learned.{rule.kind}",
+            pattern=rule.pattern,
+            message=_NAMING_MESSAGES.get(rule.kind, "does not match the learned pattern"),
+        )
+        for rule in emitted
+    }
+    return NamingRules(
+        document=result.naming_rules_document,
+        version="draft",
+        identifiers=identifiers,
+    )
+
+
+def build_profile_dict(result: LearnResult, *, naming_rules_ref: str | None) -> dict[str, Any]:
+    """The draft profile as a plain dict, ready to dump as YAML.
+
+    `naming_rules_ref` is the profile-relative path the naming-rules file will live at
+    (e.g. `chipgraph.draft.naming.yml` next to the draft, or `.chipgraph/naming.yml` for
+    `init --from-learn`); `None` when no naming rule met the threshold.
+    """
+    layout = {rule.kind: rule.template for rule in result.layout}
+    adapters: dict[str, Any] = {}
+
+    if layout:
+        scope = sorted({_scope_glob(rule.template) for rule in result.layout})
+        adapters["layout"] = {"use": "layout", "templates": layout, "scope": scope}
+
+    filelist_tmpl = layout.get("filelist")
+    rtl_tmpl = layout.get("rtl")
+    # The `filelist` check resolves listed paths relative to the filelist's own directory,
+    # so it only fits repos with that style. A root-relative repo (e.g. tinysoc, whose
+    # Makefile runs Verilator from the root) would fail every entry; the style is reported
+    # as an observation instead, and no `filelist` adapter is emitted.
+    if filelist_tmpl is not None and rtl_tmpl is not None and result.filelist_style == "filelist":
+        adapters["filelist"] = {
+            "use": "filelist",
+            "filelist": filelist_tmpl,
+            "sources": rtl_tmpl,
+        }
+
+    if naming_rules_ref is not None and rtl_tmpl is not None:
+        adapters["naming"] = {
+            "use": "naming",
+            "rules": f"path:{naming_rules_ref}",
+            "scope": [rtl_tmpl],
+        }
+
+    profile: dict[str, Any] = {
+        "schema_version": 1,
+        "project": result.project,
+        "packs": [],
+        "layout": layout,
+        "adapters": adapters,
+        "blocks": {block: {} for block in result.blocks},
+    }
+
+    paths = {
+        glob: {"checks": {"naming": "off", "layout": "off"}, "reason": "vendored, learned"}
+        for glob in result.vendor_paths
+    }
+    if paths:
+        profile["paths"] = paths
+
+    return profile
+
+
+def _scope_glob(template: str) -> str:
+    """A scope glob for a layout template: the placeholders become `*`.
+
+    The `layout` check scopes which files it inspects; a scope that mirrors the template
+    keeps the check from complaining about unrelated files (READMEs, scripts).
+    """
+    return template.replace("{block}", "*").replace("{BLOCK}", "*")
+
+
+class _NoAliasDumper(yaml.SafeDumper):
+    """A safe dumper that writes repeated values out in full, never as `&id001`/`*id001`.
+
+    The draft is read and edited by people, and YAML anchors make it hard to follow.
+    """
+
+    def ignore_aliases(self, data: object) -> bool:
+        return True
+
+
+def dump_yaml(data: object) -> str:
+    """`data` as block-style YAML, sorted keys, no anchors or aliases."""
+    return yaml.dump(data, Dumper=_NoAliasDumper, sort_keys=True, default_flow_style=False)
+
+
+def dump_profile_yaml(result: LearnResult, *, naming_rules_ref: str | None) -> str:
+    """The draft profile rendered as a YAML document string."""
+    header = (
+        "# chipgraph draft profile inferred by `chipgraph learn` (DESIGN.md 8.6 V1).\n"
+        "# Review before use: each rule was inferred from the repo with a coverage figure.\n"
+        # The directory name only: this file is committed, so no machine-local path.
+        f"# Learned from: {Path(result.root).name}/\n"
+    )
+    body = dump_yaml(build_profile_dict(result, naming_rules_ref=naming_rules_ref))
+    return header + body
+
+
+def dump_naming_rules_yaml(rules: NamingRules) -> str:
+    """The learned naming rules rendered as a YAML document string."""
+    header = "# chipgraph naming rules inferred by `chipgraph learn`. Review before use.\n"
+    body = dump_yaml(rules.model_dump(mode="json"))
+    return header + body
+
+
+def write_draft(result: LearnResult, out_dir: Path) -> tuple[Path, Path | None]:
+    """Write the draft profile (and naming-rules file) into `out_dir`.
+
+    Returns `(profile_path, naming_rules_path_or_None)`. `out_dir` is created if missing.
+    """
+    out_dir.mkdir(parents=True, exist_ok=True)
+    rules = build_naming_rules(result)
+    naming_path: Path | None = None
+    naming_ref: str | None = None
+    if rules is not None:
+        naming_path = out_dir / DRAFT_NAMING_RULES_NAME
+        naming_path.write_text(dump_naming_rules_yaml(rules), encoding="utf-8")
+        naming_ref = DRAFT_NAMING_RULES_NAME
+    profile_path = out_dir / DRAFT_PROFILE_NAME
+    profile_path.write_text(
+        dump_profile_yaml(result, naming_rules_ref=naming_ref), encoding="utf-8"
+    )
+    return profile_path, naming_path
+
+
+__all__ = [
+    "DRAFT_NAMING_RULES_NAME",
+    "DRAFT_PROFILE_NAME",
+    "build_naming_rules",
+    "build_profile_dict",
+    "dump_naming_rules_yaml",
+    "dump_profile_yaml",
+    "write_draft",
+]