traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/validate/config.py

@@ -0,0 +1,410 @@
+"""The validation graph: stages, checks, policy profiles, limits and reviewer settings.
+
+The packaged ``default.yaml`` is the base. A project layers
+``.traceforge/validate.yaml`` on top, and ``--config FILE`` layers once more.
+Each layer either starts with ``extends: default`` (merge into what is there)
+or replaces the graph outright. Checks merge by id; ``disable: [ids]`` drops
+checks; ``policy``, ``limits`` and ``reviewer`` merge key by key.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import asdict, dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+SEVERITIES = ("P0", "P1", "P2", "P3")
+CONFIDENCE = {"low": 0, "medium": 1, "high": 2}
+GATES = ("stage", "full", "strict")
+SCOPES = ("project", "per_part", "per_sheet", "per_netclass")
+INPUT_KINDS = ("sch", "pcb", "pro", "libs", "intent", "outputs", "all")
+KINDS = ("builtin", "review")
+PROJECT_CONFIG = Path(".traceforge") / "validate.yaml"
+
+
+class ConfigError(ValueError):
+    """The graph is invalid (exit code 2)."""
+
+
+@dataclass
+class Stage:
+    id: str
+    title: str
+    question: str = ""
+
+
+@dataclass
+class CheckSpec:
+    id: str
+    stage: str
+    kind: str  # builtin | review
+    title: str
+    prompt: str = ""
+    needs: list[str] = field(default_factory=list)  # hard prerequisites ("requires")
+    after: list[str] = field(default_factory=list)  # ordering only
+    gate: str = "blocking"  # blocking | advisory
+    builtin: str = ""  # builtin implementation name (defaults to the id)
+    scope: str = "project"
+    batch: int = 4
+    repeat: int = 1
+    inputs: list[str] = field(default_factory=lambda: ["all"])
+    effort: str | None = None
+    enabled: bool = True
+
+    @property
+    def requires(self) -> list[str]:
+        return self.needs
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["requires"] = data.pop("needs")
+        return {k: v for k, v in data.items() if v not in (None, "", [])}
+
+
+@dataclass
+class Profile:
+    fail_on: list[str]
+    min_confidence: str = "medium"
+
+
+@dataclass
+class ReviewerSettings:
+    preamble: str = ""
+    timeout_s: int = 1800
+    max_repairs: int = 2
+
+
+@dataclass
+class ValidationConfig:
+    stages: dict[str, str]  # id -> title, in order (kept as a dict for compatibility)
+    checks: list[CheckSpec]
+    profiles: dict[str, dict]
+    default_profile: str
+    questions: dict[str, str] = field(default_factory=dict)
+    error_blocks_dependents: bool = True
+    limits: dict[str, Any] = field(default_factory=dict)
+    reviewer: ReviewerSettings = field(default_factory=ReviewerSettings)
+
+    def stage_index(self) -> dict[str, int]:
+        return {stage: position for position, stage in enumerate(self.stages)}
+
+    def check(self, check_id: str) -> CheckSpec:
+        for check in self.checks:
+            if check.id == check_id:
+                return check
+        raise KeyError(check_id)
+
+    def enabled_checks(self) -> list[CheckSpec]:
+        return [check for check in self.checks if check.enabled]
+
+    def profile(self, name: str | None) -> tuple[str, Profile]:
+        chosen = name or self.default_profile
+        if chosen not in self.profiles:
+            raise ConfigError(f"unknown profile {chosen!r}; choose from {sorted(self.profiles)}")
+        raw = self.profiles[chosen]
+        return chosen, Profile(
+            [str(s).upper() for s in raw.get("fail_on", ["P0"])],
+            str(raw.get("min_confidence", raw.get("min_confidence_to_fail", "medium"))).lower(),
+        )
+
+
+# ----------------------------------------------------------------------- loading
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    try:
+        loaded = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{path}: invalid YAML: {exc}") from exc
+    except OSError as exc:
+        raise ConfigError(f"{path}: {exc}") from exc
+    if loaded is None:
+        return {}
+    if not isinstance(loaded, dict):
+        raise ConfigError(f"{path}: the graph must be a mapping at the top level")
+    return loaded
+
+
+def default_raw() -> dict[str, Any]:
+    text = resources.files("traceforge.validate").joinpath("default.yaml").read_text("utf-8")
+    return yaml.safe_load(text)
+
+
+def _stage_list(raw: Any) -> list[dict[str, Any]]:
+    """Stages may be a mapping ``{S0: Intake}`` or a list of ``{id, title, question}``."""
+    if raw is None:
+        return []
+    if isinstance(raw, dict):
+        return [
+            {"id": str(k), **(v if isinstance(v, dict) else {"title": str(v)})}
+            for k, v in raw.items()
+        ]
+    if isinstance(raw, list):
+        out = []
+        for item in raw:
+            if not isinstance(item, dict) or not item.get("id"):
+                raise ConfigError("every stage entry needs an id")
+            out.append(dict(item))
+        return out
+    raise ConfigError("stages must be a mapping or a list")
+
+
+def _merge_by_id(base: list[dict], overrides: list[Any], label: str) -> list[dict]:
+    result = [copy.deepcopy(item) for item in base]
+    positions = {item["id"]: index for index, item in enumerate(result)}
+    for item in overrides:
+        if not isinstance(item, dict) or not item.get("id"):
+            raise ConfigError(f"every {label} entry needs an id")
+        if item["id"] in positions:
+            result[positions[item["id"]]].update(copy.deepcopy(item))
+        else:
+            positions[item["id"]] = len(result)
+            result.append(copy.deepcopy(item))
+    return result
+
+
+def _deep_merge(base: dict, overrides: dict) -> dict:
+    result = copy.deepcopy(base)
+    for key, value in overrides.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = copy.deepcopy(value)
+    return result
+
+
+def _normalise(raw: dict[str, Any]) -> dict[str, Any]:
+    raw = dict(raw)
+    raw["stages"] = _stage_list(raw.get("stages"))
+    raw["checks"] = list(raw.get("checks") or [])
+    return raw
+
+
+def apply_layer(base: dict[str, Any], layer: dict[str, Any], source: str) -> dict[str, Any]:
+    layer = dict(layer)
+    extends = layer.pop("extends", None)
+    disabled = set(layer.pop("disable", []) or [])
+    if extends is None and ("checks" in layer and "stages" in layer):
+        result = _normalise(layer)  # a complete graph of its own
+    else:
+        if extends not in (None, "default", "none", False):
+            raise ConfigError(f"{source}: extends must be 'default' or 'none', got {extends!r}")
+        result = copy.deepcopy(base)
+        if extends in ("none", False):  # keep stages, policy and limits; start with no checks
+            result["checks"] = []
+        for key, value in layer.items():
+            if key == "checks":
+                if not isinstance(value, list):
+                    raise ConfigError(f"{source}: checks must be a list")
+                result["checks"] = _merge_by_id(result["checks"], value, "check")
+            elif key == "stages":
+                result["stages"] = _merge_by_id(result["stages"], _stage_list(value), "stage")
+            elif key in {"policy", "limits", "reviewer"} and isinstance(value, dict):
+                result[key] = _deep_merge(result.get(key) or {}, value)
+            else:
+                result[key] = copy.deepcopy(value)
+    if disabled:
+        unknown = disabled - {c.get("id") for c in result["checks"]}
+        if unknown:
+            raise ConfigError(f"{source}: disable names unknown checks {sorted(unknown)}")
+        result["checks"] = [c for c in result["checks"] if c.get("id") not in disabled]
+    return result
+
+
+def load_raw(workspace: Path, config_path: Path | None = None) -> dict[str, Any]:
+    raw = _normalise(default_raw())
+    project = Path(workspace) / PROJECT_CONFIG
+    if project.is_file():
+        raw = apply_layer(raw, _read_yaml(project), str(project))
+    if config_path is not None:
+        if not Path(config_path).is_file():
+            raise ConfigError(f"config file not found: {config_path}")
+        raw = apply_layer(raw, _read_yaml(Path(config_path)), str(config_path))
+    return raw
+
+
+def _as_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    return [str(v) for v in value]
+
+
+def build_config(raw: dict[str, Any]) -> ValidationConfig:
+    stages = _stage_list(raw.get("stages"))
+    policy = raw.get("policy") or {}
+    profiles = policy.get("profiles") or {"dev": {"fail_on": ["P0"]}}
+    reviewer_raw = raw.get("reviewer") or {}
+    unknown_reviewer = set(reviewer_raw) - {"preamble", "timeout_s", "max_repairs"}
+    if unknown_reviewer:
+        raise ConfigError(f"reviewer: unknown keys {sorted(unknown_reviewer)}")
+    specs: list[CheckSpec] = []
+    known = {
+        "id",
+        "stage",
+        "kind",
+        "title",
+        "prompt",
+        "needs",
+        "requires",
+        "after",
+        "gate",
+        "builtin",
+        "scope",
+        "batch",
+        "repeat",
+        "inputs",
+        "effort",
+        "enabled",
+    }
+    for item in raw.get("checks") or []:
+        if not isinstance(item, dict) or not item.get("id"):
+            raise ConfigError("every check needs an id")
+        extra = set(item) - known
+        if extra:
+            raise ConfigError(f"check {item['id']!r}: unknown keys {sorted(extra)}")
+        if "stage" not in item:
+            raise ConfigError(f"check {item['id']!r}: needs a stage")
+        kind = str(item.get("kind", "review"))
+        if kind == "agent":  # accept the other common spelling
+            kind = "review"
+        specs.append(
+            CheckSpec(
+                id=str(item["id"]),
+                stage=str(item["stage"]),
+                kind=kind,
+                title=str(item.get("title", item["id"])),
+                prompt=str(item.get("prompt") or ""),
+                needs=_as_list(item.get("needs")) + _as_list(item.get("requires")),
+                after=_as_list(item.get("after")),
+                gate=str(item.get("gate", "blocking")),
+                builtin=str(item.get("builtin") or (item["id"] if kind == "builtin" else "")),
+                scope=str(item.get("scope", "project")),
+                batch=int(item.get("batch", 4)),
+                repeat=int(item.get("repeat", 1)),
+                inputs=_as_list(item.get("inputs")) or ["all"],
+                effort=item.get("effort"),
+                enabled=bool(item.get("enabled", True)),
+            )
+        )
+    config = ValidationConfig(
+        stages={s["id"]: str(s.get("title", s["id"])) for s in stages},
+        checks=specs,
+        profiles=profiles,
+        default_profile=str(policy.get("default_profile", "dev")),
+        questions={s["id"]: str(s.get("question", "")) for s in stages},
+        error_blocks_dependents=bool(policy.get("error_blocks_dependents", True)),
+        limits=dict(raw.get("limits") or {}),
+        reviewer=ReviewerSettings(
+            preamble=str(reviewer_raw.get("preamble", "")),
+            timeout_s=int(reviewer_raw.get("timeout_s", 1800)),
+            max_repairs=int(reviewer_raw.get("max_repairs", 2)),
+        ),
+    )
+    validate_graph(config)
+    return config
+
+
+def load_config(workspace: Path, config_path: Path | None = None) -> ValidationConfig:
+    return build_config(load_raw(Path(workspace), config_path))
+
+
+# -------------------------------------------------------------------- validation
+
+
+def validate_graph(config: ValidationConfig) -> None:
+    """Reject graphs that cannot run; every message names the offending check."""
+    from traceforge.validate.builtins import BUILTINS
+
+    order = config.stage_index()
+    if not order:
+        raise ConfigError("the graph defines no stages")
+    if config.default_profile not in config.profiles:
+        raise ConfigError(f"default profile {config.default_profile!r} is not defined")
+    for name, profile in config.profiles.items():
+        bad = [s for s in profile.get("fail_on", []) if str(s).upper() not in SEVERITIES]
+        if bad:
+            raise ConfigError(f"profile {name!r}: unknown severities {bad}")
+        conf = str(profile.get("min_confidence", "medium")).lower()
+        if conf not in CONFIDENCE:
+            raise ConfigError(f"profile {name!r}: min_confidence must be one of {list(CONFIDENCE)}")
+    seen: set[str] = set()
+    for check in config.checks:
+        if check.id in seen:
+            raise ConfigError(f"check {check.id!r}: duplicate id")
+        seen.add(check.id)
+    by_id = {check.id: check for check in config.checks}
+    for check in config.checks:
+        where = f"check {check.id!r}"
+        if check.stage not in order:
+            raise ConfigError(f"{where}: unknown stage {check.stage!r}")
+        if check.kind not in KINDS:
+            raise ConfigError(f"{where}: kind must be builtin or review")
+        if check.gate not in {"blocking", "advisory"}:
+            raise ConfigError(f"{where}: gate must be blocking or advisory")
+        if check.scope not in SCOPES:
+            raise ConfigError(f"{where}: scope must be one of {list(SCOPES)}")
+        bad_inputs = [i for i in check.inputs if i not in INPUT_KINDS]
+        if bad_inputs:
+            raise ConfigError(f"{where}: unknown inputs {bad_inputs}; use {list(INPUT_KINDS)}")
+        if check.batch < 1 or check.repeat < 1:
+            raise ConfigError(f"{where}: batch and repeat must be at least 1")
+        for label, refs in (("needs", check.needs), ("after", check.after)):
+            for other in refs:
+                if other == check.id:
+                    raise ConfigError(f"{where}: depends on itself")
+                if other not in by_id:
+                    raise ConfigError(f"{where}: {label} unknown check {other!r}")
+                if order[by_id[other].stage] > order[check.stage]:
+                    raise ConfigError(
+                        f"{where}: {label} {other!r} runs in the later stage {by_id[other].stage}"
+                    )
+        if check.kind == "review":
+            if not check.prompt.strip():
+                raise ConfigError(f"{where}: review checks need a prompt")
+            if check.scope != "project" and "{items}" not in check.prompt:
+                raise ConfigError(f"{where}: scope {check.scope} needs an {{items}} placeholder")
+        elif check.builtin not in BUILTINS:
+            raise ConfigError(
+                f"{where}: unknown builtin {check.builtin!r}; known: {', '.join(sorted(BUILTINS))}"
+            )
+    _reject_cycles(config)
+
+
+def _reject_cycles(config: ValidationConfig) -> None:
+    edges = {check.id: [*check.needs, *check.after] for check in config.checks}
+    state: dict[str, int] = {}
+    stack: list[str] = []
+
+    def visit(node: str) -> None:
+        state[node] = 1
+        stack.append(node)
+        for other in edges.get(node, []):
+            if state.get(other) == 1:
+                cycle = [*stack[stack.index(other) :], other]
+                raise ConfigError(f"check {node!r}: dependency cycle {' -> '.join(cycle)}")
+            if other not in state:
+                visit(other)
+        stack.pop()
+        state[node] = 2
+
+    for check_id in edges:
+        if check_id not in state:
+            visit(check_id)
+
+
+def prerequisites(config: ValidationConfig, check_ids: set[str]) -> set[str]:
+    """Close ``check_ids`` over hard prerequisites (``needs``), transitively."""
+    result = set(check_ids)
+    queue = list(check_ids)
+    while queue:
+        for other in config.check(queue.pop()).needs:
+            if other not in result:
+                result.add(other)
+                queue.append(other)
+    return result

traceforge/validate/default.yaml

@@ -0,0 +1,113 @@
+# Default traceforge validation graph. A project can extend or override it in
+# .traceforge/validate.yaml:
+#   extends: default
+#   disable: [dfa.assembly]
+#   checks:
+#     - {id: custom.usb, stage: S6, kind: review, title: USB 2.0 routing, prompt: "..."}
+version: 1
+
+stages:
+  S0: Intake
+  S1: Architecture
+  S2: Parts
+  S3: Schematic
+  S4: Schematic to board
+  S5: Placement
+  S6: Routing, power and signal integrity
+  S7: Manufacturing and assembly
+  S8: Release
+
+policy:
+  default_profile: dev
+  profiles:
+    dev: {fail_on: [P0], min_confidence: medium}
+    release: {fail_on: [P0, P1], min_confidence: low}
+
+checks:
+  - {id: intake.tools, stage: S0, kind: builtin, gate: advisory, title: KiCad tooling is available}
+  - {id: intake.project, stage: S0, kind: builtin, title: Project files are present and readable, needs: [intake.tools]}
+  - {id: intake.intent, stage: S0, kind: builtin, gate: advisory, inputs: [intent, sch, pcb], title: Design intent is recorded and matches the design}
+  - id: arch.review
+    stage: S1
+    kind: review
+    title: System architecture
+    needs: [intake.project]
+    prompt: |
+      Review the system architecture. Reconstruct the power tree from the schematic: every input source,
+      regulator and rail, with each rail's consumers and an estimate of its current. Check that each
+      regulator can supply its load with margin and that its input range, dropout and thermal dissipation
+      work at the worst-case input. Check interfaces (USB, UART, I2C, SPI, CAN, debug) for completeness:
+      pull-ups, termination, level compatibility between connected parts, ESD protection at connectors.
+      Check reset, boot and programming paths of every processor.
+  - {id: parts.builtin, stage: S2, kind: builtin, title: "Footprints, values and part numbers", needs: [intake.project], inputs: [sch]}
+  - {id: parts.footprints, stage: S2, kind: builtin, title: "Footprint matches symbol, part number and package", needs: [intake.project], inputs: [sch, pcb]}
+  - {id: parts.verified, stage: S2, kind: builtin, title: "Every BOM part verified (catalogue, package, pinout)", needs: [intake.project], inputs: [sch, pcb]}
+  - {id: parts.lcsc, stage: S2, kind: builtin, gate: advisory, title: "LCSC parts exist, match the MPN and are stocked", needs: [intake.project], inputs: [sch]}
+  - id: parts.review
+    stage: S2
+    kind: review
+    title: Part selection and ratings
+    needs: [parts.builtin]
+    prompt: |
+      Review part selection. For each non-trivial part, check that the chosen symbol and footprint match the
+      intended package and pinout (compare symbol pin numbers to footprint pad numbers), that voltage,
+      current and power ratings have margin (capacitor voltage derating, resistor power, connector current),
+      and that the part numbers in LCSC/MPN fields match the values. Flag parts that are obsolete,
+      unusual or hard to source when a common equivalent exists. Use part_lookup and datasheet_fetch
+      for evidence (package drawing, absolute maximum ratings, pinout) rather than recalling values.
+  - {id: sch.erc, stage: S3, kind: builtin, title: KiCad electrical rules check, needs: [intake.project], inputs: [sch, libs]}
+  - {id: sch.circuit_rules, stage: S3, kind: builtin, title: "LED, USB-C CC, button, decoupling and regulator rules", needs: [intake.project], inputs: [sch, pcb]}
+  - id: sch.circuits
+    stage: S3
+    kind: review
+    title: Circuit correctness
+    needs: [intake.project]
+    prompt: |
+      Check every circuit block against its datasheet's reference design and against first principles:
+      decoupling at each IC supply pin, bulk capacitance per rail, feedback dividers and their computed
+      output, timing components and their computed frequency, LED and transistor bias currents, pull-ups and
+      pull-downs on inputs that could float, polarity of polarized parts and diodes, and enable/reset pins.
+      Show the arithmetic for every computed value you rely on.
+  - {id: pcb.parity, stage: S4, kind: builtin, title: Schematic and board agree, needs: [intake.project]}
+  - {id: pcb.rules, stage: S4, kind: builtin, title: Board rules and net classes meet fab limits, needs: [intake.project], inputs: [pro]}
+  - {id: pcb.dfm, stage: S4, kind: builtin, title: "Fab limits, outline, courtyards and routing completeness", needs: [intake.project]}
+  - {id: pcb.ipc2221, stage: S4, kind: builtin, gate: advisory, title: "IPC-2221 conductor width and spacing for declared currents and voltages", needs: [intake.project]}
+  - {id: pcb.multilayer, stage: S6, kind: builtin, gate: advisory, title: "Layer usage, reference planes, return paths, via stubs, copper balance and fab stackup", needs: [intake.project], inputs: [pcb, pro]}
+  - {id: pcb.models3d, stage: S4, kind: builtin, gate: advisory, title: "Every footprint has a resolved 3D model", needs: [intake.project], inputs: [pcb]}
+  - {id: pcb.drc, stage: S4, kind: builtin, title: KiCad design rules check, needs: [intake.project]}
+  - id: pcb.placement
+    stage: S5
+    kind: review
+    title: Placement
+    needs: [pcb.parity]
+    prompt: |
+      Review component placement using the board coordinates. Decoupling capacitors should sit next to the
+      supply pin they serve; crystals next to their oscillator pins; regulators and their capacitors in a
+      compact loop; connectors at board edges with sensible orientation; switches, LEDs and test points where
+      a user can reach or see them; heat sources away from temperature-sensitive parts. Quote coordinates or
+      distances for each finding.
+  - id: pcb.routing
+    stage: S6
+    kind: review
+    title: Power and signal routing
+    needs: [pcb.dfm]
+    prompt: |
+      Review routing: track widths on power nets against their expected current (state the current and the
+      width you would require), via count on high-current paths, ground return paths (pours, stitching vias,
+      splits under signals), loop area of switching regulators, and routing of clocks, USB and other fast or
+      sensitive signals (length, layer changes, reference plane). Use kicad_board with pads=true to read
+      geometry when needed.
+  - id: dfa.assembly
+    stage: S7
+    kind: review
+    title: Assembly readiness
+    needs: [parts.builtin, pcb.dfm]
+    prompt: |
+      Review assembly readiness for the selected fab: every BOM line has an orderable part number, footprint
+      rotations and polarity marks are unambiguous on silkscreen, fine-pitch parts have enough clearance for
+      rework, fiducials exist when the board will be machine assembled, and through-hole parts are limited to
+      what the assembly service supports.
+  - {id: pcb.refdes, stage: S7, kind: builtin, title: Reference designators visible on silkscreen, needs: [intake.project], inputs: [pcb]}
+  - {id: release.outputs, stage: S8, kind: builtin, title: Fabrication outputs can be generated, needs: [intake.project], after: [pcb.dfm], inputs: [pcb, pro]}
+  - {id: release.repo, stage: S8, kind: builtin, title: Repository is portable, needs: [intake.project]}
+  - {id: release.cpl, stage: S8, kind: builtin, title: BOM and placement are assembler-ready, needs: [intake.project]}