tan-cli 0.7.0__py3-none-any.whl

tan/core/board_validator_compat.py

@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: Apache-2.0
+"""board.yaml SoC-capability pass (ALP-B010).
+
+PORTED from alp-sdk `scripts/alp_cli/validator.py` (`_compat_pass` and its
+SoC-capability helpers). Directories are passed in by the caller (the bound
+SDK checkout's `metadata/`); nothing here derives a root from `__file__`.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from tan.core.board_diagnostic import Diagnostic, DiagnosticCollector
+
+
+# Local on purpose: tan has no importable equivalent. `tan.planner.*` cannot be
+# imported before an SDK root is bound (and this module must load without one),
+# and `som_metadata.resolve_soc_path` is the metadata-root-rooted resolver the
+# SDK file's own comment says NOT to reuse here (this site roots at a
+# caller-injected `soc_dir`, alp-sdk#1096).
+def split_silicon_ref(silicon: str | None) -> tuple[str, str, str] | None:
+    """Split a `vendor:family:part` `silicon:` key into its three slugs.
+
+    None when *silicon* is falsy or not exactly 3 colon-separated parts
+    (alp-sdk `alp_project_loader.split_silicon_ref`).
+    """
+    if not silicon:
+        return None
+    parts = silicon.split(":")
+    if len(parts) != 3:
+        return None
+    return parts[0], parts[1], parts[2]
+
+
+def _compat_pass(
+    data: dict[str, Any],
+    path: Path,
+    collector: DiagnosticCollector,
+    *,
+    som_dir: Path,
+    soc_dir: Path,
+) -> None:
+    som = data.get("som")
+    sku = som.get("sku") if isinstance(som, dict) else None
+    silicon_ref = _silicon_ref_for_sku(sku, som_dir=som_dir)
+    if silicon_ref is None:
+        return
+    soc_caps = _load_soc_caps(silicon_ref, soc_dir=soc_dir)
+    if soc_caps is None:
+        return
+
+    # #602: `cores:` failing schema validation (wrong type, e.g. a string
+    # or list instead of a mapping) is already reported as ALP-B004 --
+    # guard here too instead of crashing on `.items()`.
+    cores = data.get("cores")
+    cores = cores if isinstance(cores, dict) else {}
+    for core_name, core in cores.items():
+        if not isinstance(core, dict):
+            continue
+        peripherals = core.get("peripherals") or []
+        if not isinstance(peripherals, list):
+            continue
+        for idx, periph in enumerate(peripherals):
+            # The board.yaml schema defines peripherals as an array of
+            # strings (e.g. ["can", "i2c"]).  The schema pass already
+            # rejects non-string entries, so skip anything unexpected.
+            if not isinstance(periph, str):
+                continue
+            kind = periph
+            if _soc_has_kind(soc_caps, kind):
+                continue
+            # Best-effort line: the sequence loader only attaches position
+            # metadata to dict items; strings carry no __line__.  Fall back
+            # to the core block's opening position.
+            line = core.get("__line__", 1)
+            col = core.get("__column__", 1)
+            collector.add(
+                Diagnostic(
+                    # warning, not error: SoC peripherals JSON ingestion is
+                    # incomplete for some parts, and some peripheral
+                    # categories surface board-side rather than directly on
+                    # the SoC (emmc / flash / ethernet via I/O controllers).
+                    # A false-positive ALP-B010 must not block the build —
+                    # surface the discrepancy and let the customer decide.
+                    severity="warning",
+                    path=path,
+                    line=line,
+                    col=col,
+                    span=len(kind),
+                    code="ALP-B010",
+                    message=(
+                        f"core '{core_name}': peripheral kind '{kind}' is not "
+                        f"listed on silicon '{silicon_ref}' (SoC JSON may be "
+                        f"incomplete or the peripheral is board-side)"
+                    ),
+                    hint=(
+                        f"verify the SoC truly lacks {kind} before removing "
+                        f"this entry; if the SoC has it but the metadata is "
+                        f"stale, update metadata/socs/.../*.json"
+                    ),
+                )
+            )
+
+
+def _silicon_ref_for_sku(sku: str | None, *, som_dir: Path) -> str | None:
+    if not sku:
+        return None
+    for som_path in som_dir.rglob(f"{sku}.yaml"):
+        text = som_path.read_text(encoding="utf-8")
+        doc = yaml.safe_load(text) or {}
+        ref = doc.get("silicon")
+        if isinstance(ref, str):
+            return ref
+    return None
+
+
+def _load_soc_caps(silicon_ref: str, *, soc_dir: Path) -> dict[str, int] | None:
+    # split_silicon_ref(), not resolve_soc_path(): this site roots at the
+    # caller-injected `soc_dir`, not at a metadata root. Rebuilding it as
+    # `resolve_soc_path(ref, soc_dir.parent)` happens to be exact today only
+    # because every caller passes `<root>/socs` -- it would silently resolve
+    # somewhere else the first time one didn't (#1096).
+    parts = split_silicon_ref(silicon_ref)
+    if parts is None:
+        return None
+    vendor, family, part = parts
+    fp = soc_dir / vendor / family / f"{part}.json"
+    if not fp.is_file():
+        return None
+    doc = json.loads(fp.read_text(encoding="utf-8"))
+    peripherals = doc.get("peripherals", {}) if isinstance(doc, dict) else {}
+    return peripherals if isinstance(peripherals, dict) else {}
+
+
+# Map user-facing board.yaml peripheral kind names to the SoC JSON key
+# prefixes that represent the underlying silicon capability.  Entries
+# here are only needed when the user-facing name differs from the SoC
+# JSON key (e.g. 'counter' is a Zephyr driver-model class that maps to
+# the SoC's timer_* counters; 'sensor' is a driver-model class with no
+# silicon peripheral equivalent so it is always considered present).
+_PERIPHERAL_KIND_ALIASES: dict[str, tuple[str, ...]] = {
+    # Zephyr COUNTER driver class backed by hardware timers.
+    "counter": ("timer",),
+    # Zephyr PWM driver class backed by hardware timers / PWM units.
+    "pwm": ("timer", "pwm"),
+    # Zephyr SENSOR driver class: software abstraction over various
+    # I2C/SPI sensors; no dedicated silicon peripheral block required.
+    # Always allow it -- the I2C/SPI bus is the actual constraint.
+    "sensor": (),  # empty tuple = unconditionally present
+}
+
+
+def _soc_has_kind(caps: dict[str, int], kind: str) -> bool:
+    """Map a peripheral 'kind' onto SoC capability keys.
+
+    'kind' is the user-facing peripheral category (i2c, spi, can, ...).
+    The SoC JSON uses the same names plus _lp suffixes for low-power
+    variants; presence in EITHER counts.  Some peripherals also have
+    variant suffixes (e.g. can_fd) -- if the base name matches a key
+    whose value > 0 that also counts.
+
+    High-level Zephyr driver classes (counter, pwm, sensor) that do not
+    map 1-to-1 to SoC JSON keys are resolved via ``_PERIPHERAL_KIND_ALIASES``.
+    """
+    # Alias table: if the kind has a (possibly empty) alias list, check
+    # those SoC key prefixes instead.  An empty alias list means the kind
+    # is always considered present (software-only abstraction).
+    if kind in _PERIPHERAL_KIND_ALIASES:
+        aliases = _PERIPHERAL_KIND_ALIASES[kind]
+        if not aliases:
+            return True  # unconditionally present (e.g. 'sensor')
+        for alias_prefix in aliases:
+            direct_keys = (alias_prefix, f"{alias_prefix}_lp")
+            if any((caps.get(k, 0) or 0) > 0 for k in direct_keys):
+                return True
+            for key, count in caps.items():
+                if key == alias_prefix or key.startswith(f"{alias_prefix}_"):
+                    if (count or 0) > 0:
+                        return True
+        return False
+
+    # Direct and LP-suffixed match.
+    direct_keys = (kind, f"{kind}_lp")
+    if any((caps.get(k, 0) or 0) > 0 for k in direct_keys):
+        return True
+    # Variant-suffixed match: e.g. user writes 'can', SoC JSON has 'can_fd'.
+    for key, count in caps.items():
+        if key == kind or key.startswith(f"{kind}_"):
+            if (count or 0) > 0:
+                return True
+    return False
+

tan/core/board_validator_run.py

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`validate_board_yaml.py`, in-process: the default engine behind `tan validate`.
+
+PORTED from alp-sdk `scripts/validate_board_yaml.py` (tan-cli#270), pinned by
+`tests/gates/test_planner_relocation_freshness.py::HAND_PORT_HASHES`.
+The function returns what that script's process would have produced -- an exit
+status, a stdout and a stderr -- so `tan.commands.validate_cmd` feeds it through
+the SAME `analyze_validator_output` it always fed a spawned script's output
+through, and the exit-code map, the issue codes and the envelope shape do not
+move. `tests/parity/test_board_validator_parity.py` runs both engines over a
+fixture corpus and asserts the three values are identical.
+
+Two stages, as in the script:
+
+1. the rich diagnostic validator (`board_validator`), whose findings are
+   rendered to stderr; any error ends the run at status 1;
+2. the orchestrator's `load_board_yaml` -- here `tan.planner.loader`, already
+   in-process for `tan build` -- for the hard cross-field checks and the three
+   hw_rev refusals, which keep the script's own exit statuses 3, 4 and 5.
+
+`metadata/**` is read from the bound SDK checkout (ADR-0017); the script's
+`--metadata-root` / `--no-presets` / `--no-color` flags are not ported because
+`tan validate` never passed them (the SDK-side script keeps serving
+west wrappers and MCP).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from tan.core.board_diagnostic import render
+from tan.core.board_validator import PlannerFacts, validate_board_yaml
+
+#: The script's own exit statuses (`validate_board_yaml.py`), unchanged.
+EXIT_SDK_REVISION_UNSUPPORTED = 3
+EXIT_SDK_REVISION_UNKNOWN = 4
+EXIT_SDK_REVISION_NOT_BUILDABLE = 5
+
+
+@dataclass(frozen=True)
+class ValidatorRun:
+    """What the script's process would have left behind."""
+
+    status: int
+    stdout: str
+    stderr: str
+
+
+def _traceback_stderr(exc: BaseException) -> str:
+    """An uncaught exception, in the one shape `analyze_validator_output`
+    recognises as a crash (`Traceback ...` header, `Type: message` last line),
+    so a tan-side fault is never read as a verdict about the customer's board."""
+    return (
+        "Traceback (most recent call last):\n"
+        f"{type(exc).__name__}: {exc}\n"
+    )
+
+
+def run_board_validator(board_path: str, sdk_root: Path) -> ValidatorRun:
+    """Validate *board_path* against the metadata of the SDK at *sdk_root*."""
+    try:
+        return _run(board_path, Path(sdk_root))
+    except Exception as exc:  # the script's uncaught-exception exit 1
+        return ValidatorRun(1, "", _traceback_stderr(exc))
+
+
+def _run(board_path: str, sdk_root: Path) -> ValidatorRun:
+    path = Path(board_path)
+    if not path.is_file():
+        return ValidatorRun(1, "", f"FAIL {path}: file not found\n")
+
+    # Read first, as the script does: an undecodable board is its uncaught
+    # exception, and must not bind the planner to a root on the way.
+    source_text = path.read_text(encoding="utf-8")
+
+    # `tan.planner` freezes its metadata paths at import, so the SDK root is
+    # bound BEFORE anything below imports it (see `tan.planner_root`).
+    from tan.planner_root import bind_sdk_root
+
+    bind_sdk_root(sdk_root)
+    from tan.planner.camera_owner import plan_cameras, resolve_cores
+    from tan.planner.slugs import _BLOCK_SLUGS
+
+    collector = validate_board_yaml(
+        path,
+        metadata_root=sdk_root / "metadata",
+        facts=PlannerFacts(
+            repo_root=sdk_root,
+            block_slugs=_BLOCK_SLUGS,
+            plan_cameras=plan_cameras,
+            resolve_cores=resolve_cores,
+        ),
+    )
+    stderr = "".join(
+        render(diag, source_text=source_text, color=False) + "\n"
+        for diag in collector
+    )
+    if collector.has_errors():
+        return ValidatorRun(1, "", stderr)
+
+    from tan.planner import (
+        OrchestratorError,
+        SdkRevisionNotBuildable,
+        SdkRevisionUnknown,
+        SdkRevisionUnsupported,
+        load_board_yaml,
+    )
+
+    try:
+        load_board_yaml(path)
+    except SdkRevisionUnknown as exc:
+        return ValidatorRun(
+            EXIT_SDK_REVISION_UNKNOWN, "", f"{stderr}FAIL sdk-compat: {exc}\n"
+        )
+    except SdkRevisionNotBuildable as exc:
+        return ValidatorRun(
+            EXIT_SDK_REVISION_NOT_BUILDABLE, "", f"{stderr}FAIL sdk-compat: {exc}\n"
+        )
+    except SdkRevisionUnsupported as exc:
+        return ValidatorRun(
+            EXIT_SDK_REVISION_UNSUPPORTED, "", f"{stderr}FAIL sdk-compat: {exc}\n"
+        )
+    except OrchestratorError as exc:
+        return ValidatorRun(1, "", f"{stderr}FAIL consistency: {exc}\n")
+
+    warnings = sum(1 for diag in collector if diag.severity == "warning")
+    verdict = f"{path}: clean ({warnings} warning(s))" if warnings else f"{path}: clean"
+    return ValidatorRun(0, verdict + "\n", stderr)

tan/core/board_validator_schema.py

@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: Apache-2.0
+"""board.yaml JSON-Schema pass -> rich diagnostics (ALP-B001..B004, B099).
+
+PORTED from alp-sdk `scripts/alp_cli/validator.py` (`_schema_pass` and its
+helpers). The schema file is read from the BOUND SDK checkout's
+`metadata/schemas/` (ADR-0017: facts stay in alp-sdk) -- the caller passes the
+path; nothing here derives a root from `__file__`.
+"""
+
+from __future__ import annotations
+
+import json
+import re as _re
+from difflib import get_close_matches
+from pathlib import Path
+from typing import Any
+
+import jsonschema
+
+from tan.core.board_diagnostic import Diagnostic, DiagnosticCollector
+from tan.core.board_yaml_pos import node_position
+
+
+def load_board_schema(schema_path: Path) -> dict[str, Any]:
+    """Load board.schema.json from *schema_path*."""
+    return json.loads(schema_path.read_text(encoding="utf-8"))
+
+
+def iter_schema_errors(
+    data: dict[str, Any], schema_path: Path
+) -> list[jsonschema.ValidationError]:
+    """Validate *data* against board.schema.json; errors sorted by path.
+
+    One schema file, one draft dialect (2020-12, matching the schema's own
+    `$schema` declaration), one error ordering.
+    """
+    validator = jsonschema.Draft202012Validator(load_board_schema(schema_path))
+    # Stringify path parts: absolute_path mixes ints (array indices) and
+    # strs (keys); a raw list comparison would TypeError across siblings.
+    return sorted(validator.iter_errors(data),
+                  key=lambda e: [str(p) for p in e.absolute_path])
+
+
+def _schema_pass(
+    data: dict[str, Any],
+    path: Path,
+    collector: DiagnosticCollector,
+    *,
+    schema_path: Path,
+) -> None:
+    # Strip __pos__ keys before handing to jsonschema (they're not in the schema).
+    clean = _strip_pos(data)
+    for err in iter_schema_errors(clean, schema_path):
+        diag = _schema_error_to_diagnostic(err, data, path)
+        if diag is not None:
+            collector.add(diag)
+
+
+def _strip_pos(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            k: _strip_pos(v)
+            for k, v in value.items()
+            if not (isinstance(k, str) and k.startswith("__"))
+        }
+    if isinstance(value, list):
+        return [_strip_pos(v) for v in value]
+    return value
+
+
+def _walk(data: dict[str, Any], path_seq: list[Any]) -> dict[str, Any] | None:
+    """Walk a path through the position-augmented document."""
+    cursor: Any = data
+    for step in path_seq:
+        if isinstance(cursor, dict) and step in cursor:
+            cursor = cursor[step]
+        elif isinstance(cursor, list) and isinstance(step, int) and step < len(cursor):
+            cursor = cursor[step]
+        else:
+            return None
+    return cursor if isinstance(cursor, dict) else None
+
+
+def _schema_error_to_diagnostic(
+    err: jsonschema.ValidationError, data: dict[str, Any], path: Path
+) -> Diagnostic | None:
+    abs_path = list(err.absolute_path)
+    parent = _walk(data, abs_path[:-1]) if abs_path else data
+    line = parent.get("__line__", 1) if parent else 1
+    col = parent.get("__column__", 1) if parent else 1
+    span = 1
+
+    if err.validator == "required":
+        missing = err.message.split("'")[1] if "'" in err.message else "?"
+        return Diagnostic(
+            severity="error",
+            path=path,
+            line=line,
+            col=col,
+            span=span,
+            code="ALP-B001",
+            message=f"required key '{missing}' is missing",
+            hint=f"add a '{missing}:' entry to this block",
+        )
+
+    if err.validator == "additionalProperties":
+        # jsonschema reports additionalProperties errors AT the object that
+        # rejected the extra key: `abs_path` is that object's OWN path, not
+        # the offending key's -- so the offending key is only ever
+        # recoverable from the message text, never from `abs_path[-1]`.
+        # (Nested case: a `server:` block with `additionalProperties:
+        # false` rejecting `tls_ca_bundle` reports `abs_path ==
+        # ["ota", "server"]`; `abs_path[-1]` is `"server"`, the block
+        # itself, not the unknown key -- which used to surface as the
+        # misleading "unknown key 'server'".)
+        _m = _re.search(r"'([^']+)'", err.message)
+        bad_key = _m.group(1) if _m else "?"
+        offending = _walk(data, abs_path) if abs_path else data
+        if offending and "__keys__" in offending and bad_key in offending["__keys__"]:
+            parent = offending
+            line, col = node_position(parent, bad_key, target="key")
+            span = len(str(bad_key))
+        allowed = list(err.schema.get("properties", {}).keys())
+
+        suggestion = get_close_matches(str(bad_key), allowed, n=1)
+        hint = f"did you mean '{suggestion[0]}'?" if suggestion else None
+        return Diagnostic(
+            severity="error",
+            path=path,
+            line=line,
+            col=col,
+            span=span,
+            code="ALP-B002",
+            message=f"unknown key '{bad_key}'",
+            hint=hint,
+        )
+
+    if err.validator in {"enum", "pattern"}:
+        if abs_path and parent and "__keys__" in parent:
+            key = abs_path[-1]
+            if key in parent["__keys__"]:
+                line, col = node_position(parent, key, target="value")
+                span = max(1, len(str(parent.get(key, ""))))
+        if err.validator == "enum":
+            allowed = err.schema.get("enum", [])
+            hint = f"expected one of: {', '.join(map(repr, allowed))}"
+        else:
+            hint = f"value must match pattern: {err.schema.get('pattern')}"
+        return Diagnostic(
+            severity="error",
+            path=path,
+            line=line,
+            col=col,
+            span=span,
+            code="ALP-B003",
+            message=err.message,
+            hint=hint,
+        )
+
+    if err.validator == "type":
+        if abs_path and parent and "__keys__" in parent:
+            key = abs_path[-1]
+            if key in parent["__keys__"]:
+                line, col = node_position(parent, key, target="value")
+        return Diagnostic(
+            severity="error",
+            path=path,
+            line=line,
+            col=col,
+            span=1,
+            code="ALP-B004",
+            message=err.message,
+            hint=f"expected type: {err.schema.get('type')}",
+        )
+
+    # Fallback for any validator we haven't mapped yet.
+    return Diagnostic(
+        severity="error",
+        path=path,
+        line=line,
+        col=col,
+        span=1,
+        code="ALP-B099",
+        message=err.message,
+        hint=None,
+    )

tan/core/board_validator_skew.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Is the bound alp-sdk checkout's validator newer than the one tan ported?
+
+`tan validate` runs a PORT of the SDK's board.yaml validator in-process, so a
+checkout whose validator sources moved past the audited commit may carry rules
+tan does not apply (a clean verdict that the SDK's own script would reject).
+The four sources the port was cut from are hashed here; a differing hash in the
+bound checkout is reported as a non-fatal warning. The hashes are kept equal to
+`tests/gates/test_planner_relocation_freshness.py::HAND_PORT_HASHES` by
+`tests/gates/test_board_validator_skew_pins.py`, so a re-port moves both.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+#: alp-sdk-relative source -> sha256 at the commit the port was audited against.
+PORTED_SOURCE_HASHES: dict[str, str] = {
+    "scripts/alp_cli/validator.py": "ce44ba907c411f763e39b07c168f959dd4455da20d3ffba9f8c28eaa5a1f810d",
+    "scripts/alp_cli/diagnostic.py": "6a96eb120d73640196cefbd30d13e40a515d00d11368e440123594189cd16d96",
+    "scripts/alp_cli/yaml_pos.py": "c83580d86a8f2bc575e20b44f4893847a6a08f765774861f2d29a8bd61ae5b74",
+    "scripts/validate_board_yaml.py": "91e06880f068447f98a2c68f1ffb4b6da29c18d2fcadfa0232d982e6612557d4",
+}
+
+
+def _digest(path: Path) -> str:
+    # CRLF -> LF so a Windows autocrlf checkout of identical sources is not "newer".
+    return hashlib.sha256(path.read_bytes().replace(b"\r\n", b"\n")).hexdigest()
+
+
+def skewed_sources(sdk_root: Path) -> tuple[str, ...]:
+    """SDK-relative validator sources whose bytes differ from the audited ones.
+
+    A source absent from the checkout (or unreadable) is skipped: an SDK that
+    dropped the script has no newer rules for tan to miss.
+    """
+    skewed: list[str] = []
+    for rel, pinned in PORTED_SOURCE_HASHES.items():
+        path = Path(sdk_root, *rel.split("/"))
+        try:
+            if path.is_file() and _digest(path) != pinned:
+                skewed.append(rel)
+        except OSError:
+            continue
+    return tuple(skewed)