tan-cli 0.7.0__py3-none-any.whl

tan/core/doctor_libraries.py

@@ -0,0 +1,253 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`tan doctor`'s ADR-0018 curated-library verdict, ported out of alp-sdk.
+
+This is the port of `scripts/alp_cli/doctor.py::_check_libraries` (alp-sdk
+ADR-0020 end-state B: the user command surface is `tan`, so a user-facing
+check does not stay behind in alp-sdk as a second CLI). It answers one
+question about the SELECTED PROJECT -- for every curated library the
+project's `board.yaml` asks for, what TIER and LICENCE is it, and can it
+actually be wired on this target?
+
+## Why it resolves rather than merely lists
+
+Tier and licence could be read straight out of `metadata/libraries/<name>.yaml`
+with no planner at all. The compatibility half cannot: `requires:` constraints
+are checked against the project's SoC cores and per-core OSes, and a library
+with no `integration:` section for any OS this project runs is a build-time
+refusal. Reporting the first without the second is the failure mode a doctor
+exists to prevent -- a green "lvgl (tier A, MIT)" line on a project where the
+emitter will refuse it. So this routes through
+`tan.planner.libraries.resolve_selection`, the SAME function
+`tan.planner.buildplan` calls when it renders the plan; the report and the
+build can therefore never disagree about a selection.
+
+## WARN, never FAIL
+
+An incompatible selection is a WARN here because the hard gate is the emit:
+`tan build` refuses outright. `tan doctor` is a preflight report and a `fail`
+row from it costs exit 4, which would make an unbuildable-library selection
+indistinguishable from a missing toolchain. Same posture alp-sdk's original
+took, kept deliberately.
+
+alp-sdk's `alp doctor` had a second lever this port does not carry: `--strict`,
+which folded a WARN row into a nonzero exit (`n_warn` counted the libraries
+row same as any other). `tan doctor` has no `--strict` flag AT ALL -- it is
+not a libraries-specific gap, every WARN-worthy check in this module is
+already exit-0-only (`exit_code_for` above only inspects `fail`). Adding
+`--strict` scoped to just this one row would make it behave differently from
+every other check `tan doctor` reports; that is a real, pre-existing capability
+difference from `alp doctor`, not something this port introduces or reverses,
+and it is accepted deliberately: `tan build`'s own refusal is the actual gate
+a CI pipeline should script against, not a doctor exit code.
+
+## The defect fixed in the port, not carried across
+
+alp-sdk's version read the RAW `libraries:` list out of the YAML and passed
+each entry straight into `load_manifest()` and an f-string. board.yaml's
+`libraries:` entries are `{name, cores?}` OBJECTS as well as bare strings
+(`alp_orchestrate.loader._normalize_libraries`, and `tan.planner.loader`'s
+relocated twin), so a core-scoped entry reached `load_manifest` as a dict:
+
+    $ cd examples/peripheral-io/fmt-formatting
+    $ PYTHONPATH=<alp-sdk>/scripts python3 -m alp_cli doctor
+    ...
+    alp_orchestrate.models.OrchestratorError: unknown library
+    `{'name': 'fmt', 'cores': ['m55_hp']}` in `libraries:` -- no manifest at
+    metadata/libraries/{'name': 'fmt', 'cores': ['m55_hp']}.yaml.
+
+Measured, not reasoned: exit 1, the whole command down, on the SUCCESS path
+(`resolve_selection` had already passed, using the loader's normalised names;
+the raw re-read for the labels is what raised). All 42 in-tree alp-sdk
+examples that select libraries use that shape, so there was no shipped
+project the check worked on. alp-sdk's `docs/getting-started.md` carried it
+as a known open bug; the port is where it goes away.
+
+Names therefore come from `scoped_names(project)` -- the loader's own
+normalised, deduplicated, two-channel view -- not from the raw document. The
+dedup matters on its own: `libraries: [fmt, {name: fmt, cores: [m55_hp]}]` is
+schema-valid (`uniqueItems` compares whole entries) and the raw read reports
+`fmt` twice.
+
+The raw read survives only as the cheap "is anything selected at all" peek (a
+project selecting nothing must cost nothing and stay silent) and as the label
+fallback when the project could not be LOADED, which is the one path where no
+normalised view exists to take names from.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+__all__ = ["LibraryReport", "inspect_selection"]
+
+#: `outcome` values, and what each means for the caller's Check status.
+#:
+#: `ok`            every selection resolved and is wireable          -> pass
+#: `unresolved`    a name, a `requires:` or an `integration:` failed -> warn
+#: `unreadable`    `board.yaml` itself could not be parsed           -> warn
+#: `unverifiable`  libraries ARE selected but nothing could check    -> warn
+#:                 them (no SDK checkout resolved, or the planner is
+#:                 unavailable/already bound elsewhere in this process)
+OUTCOMES = ("ok", "unresolved", "unreadable", "unverifiable")
+
+
+@dataclass(frozen=True)
+class LibraryReport:
+    """One project's curated-library verdict.
+
+    `labels` are the rendered `name (tier X, LICENCE)` strings, in declaration
+    order -- built even on the `unresolved` path, where the offending entry
+    reads `name (unknown)`, because "which of my five libraries is the broken
+    one" is the question that report has to answer.
+
+    `detail` carries the underlying refusal verbatim on every non-`ok`
+    outcome: it is the emitter's OWN message (`OrchestratorError`), so the
+    warning a customer reads here is word-for-word the error `tan build`
+    will print, not a paraphrase of it.
+    """
+
+    outcome: str
+    names: tuple[str, ...]
+    labels: tuple[str, ...] = ()
+    detail: str = ""
+
+    def __post_init__(self) -> None:
+        if self.outcome not in OUTCOMES:
+            raise ValueError(f"unknown library-report outcome {self.outcome!r}; expected one of {OUTCOMES}")
+
+
+def _raw_names(document: Any) -> list[str]:
+    """The `libraries:` names as WRITTEN, for the two paths that have no
+    loaded project to ask (the emptiness peek, and the label fallback when
+    loading failed). Both entry shapes are accepted -- see the module
+    docstring for why reading only the string shape was a defect. NOT
+    deduplicated and NOT canonicalised: no loader has run on either path, so
+    what the customer wrote is all there is to report."""
+    if not isinstance(document, dict):
+        return []
+    entries = document.get("libraries") or []
+    if not isinstance(entries, list):
+        return []
+    names: list[str] = []
+    for entry in entries:
+        if isinstance(entry, str):
+            names.append(entry)
+        elif isinstance(entry, dict) and entry.get("name"):
+            names.append(str(entry["name"]))
+    return names
+
+
+def _labels(names, load_manifest, metadata_root: Path) -> tuple[str, ...]:
+    """`name (tier X, LICENCE)` per selection, in declaration order.
+
+    Per-name `try`, not one around the loop: on the `unresolved` path exactly
+    one entry is usually the broken one, and "which of my five" is the whole
+    question that report answers. A single guard would collapse all five to
+    `(unknown)` the moment any one of them failed to load."""
+    out: list[str] = []
+    for name in names:
+        try:
+            manifest = load_manifest(name, metadata_root)
+        except Exception:
+            out.append(f"{name} (unknown)")
+            continue
+        out.append(f"{name} (tier {manifest.get('tier', '?')}, {manifest.get('license', '?')})")
+    return tuple(out)
+
+
+def _unverifiable(names: list[str], detail: str) -> LibraryReport:
+    return LibraryReport(
+        "unverifiable", tuple(names), tuple(f"{n} (unverified)" for n in names), detail
+    )
+
+
+def _planner(sdk_root: Path):
+    """`(load_board_yaml, load_manifest, resolve_selection, scoped_names)`.
+
+    Binds BEFORE importing `tan.planner`: `tan/planner/paths.py` evaluates
+    `REPO = sdk_root()` at module scope and half the package freezes
+    `metadata_root` as a default argument, so an unbound import cannot be
+    repaired afterwards (`tan.planner_root`). A rebind to a DIFFERENT root in
+    an already-planner-bound process raises `PlannerRootError` by design --
+    doctor is a REPORT and must not be the thing that decides which SDK a
+    process is pointed at, so the caller turns that into `unverifiable`
+    rather than forcing it."""
+    from tan.planner_root import bind_sdk_root
+
+    bind_sdk_root(sdk_root)
+    from tan.planner import load_board_yaml
+    from tan.planner.libraries import load_manifest, resolve_selection, scoped_names
+
+    return load_board_yaml, load_manifest, resolve_selection, scoped_names
+
+
+def inspect_selection(
+    board_yaml: Path | None, sdk_root: Path | None
+) -> LibraryReport | None:
+    """Resolve the project's `libraries:` selection, or `None` for nothing to say.
+
+    `None` -- not a status, an ABSENCE -- for no `board.yaml` in scope and for
+    a `board.yaml` that selects no libraries; see `doctor_cmd.libraries_check`
+    for why a "0 selected" row is worse than no row. A project that DOES
+    select libraries always gets one, including when nothing could be
+    verified.
+
+    Never raises: every failure becomes an outcome, because this runs inside
+    `_collect`, whose stated invariant is that no probe may raise.
+    """
+    if board_yaml is None or not board_yaml.is_file():
+        return None
+    try:
+        import yaml
+
+        document = yaml.safe_load(board_yaml.read_text(encoding="utf-8")) or {}
+    except Exception as err:
+        # `boardYaml` owns the verdict on the file itself and runs immediately
+        # above this, so the wording here stays scoped to the library line.
+        return LibraryReport("unreadable", (), (), f"could not read {board_yaml}: {err}")
+
+    raw = _raw_names(document)
+    if not raw:
+        return None
+    if sdk_root is None:
+        return _unverifiable(
+            raw, "no alp-sdk checkout resolved, so metadata/libraries/*.yaml could not be read"
+        )
+    return _resolve(board_yaml, Path(sdk_root), raw)
+
+
+def _resolve(board_yaml: Path, sdk_root: Path, raw: list[str]) -> LibraryReport | None:
+    """The second half of `inspect_selection`: does what the customer asked
+    for actually resolve against THIS SDK checkout and THIS target? Split from
+    the first half at the point the planner is needed -- everything above it
+    is a read of the customer's own document and answers with no SDK at all.
+    """
+    try:
+        load_board_yaml, load_manifest, resolve_selection, scoped_names = _planner(sdk_root)
+    except Exception as err:
+        return _unverifiable(raw, f"the library metadata in {sdk_root} could not be read: {err}")
+
+    metadata_root = sdk_root / "metadata"
+    try:
+        project = load_board_yaml(board_yaml, metadata_root=metadata_root)
+    except Exception as err:
+        # No loaded project means no normalised name list to take -- the raw
+        # spelling is all there is on this one path.
+        return LibraryReport(
+            "unresolved", tuple(raw), _labels(raw, load_manifest, metadata_root), str(err)
+        )
+
+    # `scoped_names`, not the raw list: the loader's own view of the selection,
+    # covering BOTH declaration channels with aliases already applied -- see
+    # the module docstring for the defect that reading `raw` here produced.
+    names = tuple(scoped_names(project))
+    if not names:
+        return None
+    labels = _labels(names, load_manifest, metadata_root)
+    try:
+        resolve_selection(project, metadata_root)
+    except Exception as err:
+        return LibraryReport("unresolved", names, labels, str(err))
+    return LibraryReport("ok", names, labels)

tan/core/doctor_render.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure text-mode rendering for `tan doctor`.
+
+`doctor_cmd.py`'s text branch used to be one `print` per check, with `detail`
+and `fix` as unwrapped strings: on a real terminal that wraps at column 0, a
+long `fix:` body visually merges into the next `[   pass]` row, and there is
+no colour to tell `fail` from `pass` at a glance. This module fixes both,
+plus adds a failures-only footer so a customer with several failures gets an
+action list without re-reading the whole log.
+
+v2 (three changes, bundled because they interact -- see
+`doctor-v2-brief.md`): (1) one FIXED continuation indent for both `detail`
+and `fix` bodies, replacing the old per-check-name-length indent, which is
+also what makes (3) possible -- a check can be rendered without knowing any
+other check's name length; (2) the failures footer now names the start of
+each fix, not just the bare check name; (3) `render_check_lines` (one
+check) and `render_doctor_footer` (everything after the checks) are exposed
+separately so `doctor_cmd`'s streaming path can print each check as it
+completes and call the footer once, at the end, instead of only ever having
+the all-at-once `render_doctor_lines` this module used to expose.
+
+Pure and IO-free -- no terminal probe, no `print` -- so it is testable
+without one; `doctor_cmd.doctor` is the only caller, and reads `width` off
+`shutil.get_terminal_size()` and `color` off `tan.env.use_color` before
+calling in.
+"""
+from __future__ import annotations
+
+from tan.core.text_layout import wrap_block
+
+# colorama Fore/Style literals, matching `tan.core.size`'s and
+# `tan.core.faultdecode`'s convention rather than a new dependency.
+_GREEN = "\x1b[32m"
+_YELLOW = "\x1b[33m"
+_RED = "\x1b[31m"
+_CYAN = "\x1b[36m"
+_RESET = "\x1b[0m"
+
+_STATUS_HUE: dict[str, str] = {
+    "pass": _GREEN,
+    "warn": _YELLOW,
+    "fail": _RED,
+    "unknown": _CYAN,
+}
+
+#: Every continuation line -- wrapped `detail` text AND the `fix:` block --
+#: lands on this ONE column now (review O-2: the old code re-derived the
+#: detail indent from `len(prefix)`, so it drifted with name length (15 for
+#: `sdk`, 23 for `pythonFloor`), while the fix block used its own separate
+#: fixed 9 -- two rails that agreed with neither each other nor themselves
+#: down the report). 10 is `len("[   fail] ")`, the bracket+status prefix
+#: every check shares regardless of its name -- the floor a continuation can
+#: never sit left of without reading as a new entry rather than one -- so a
+#: continuation lands exactly under where the check's own name starts, for
+#: every check, independent of that name's length.
+_CONTINUATION_INDENT = 10
+
+#: `fix: ` printed at `_CONTINUATION_INDENT`, like a second paragraph under
+#: the check -- its own wrapped continuation lines land back on that SAME
+#: column, not indented further under the label, which is the "same rail
+#: for detail and fix" this task's change 1 asks for.
+_FIX_PREFIX = " " * _CONTINUATION_INDENT + "fix: "
+
+#: ~75 characters of a failing check's `fix` text in the footer row (review
+#: range: 70-80). A CHARACTER budget, not a sentence split -- the `sdk`
+#: check's own fix (its longest) is one comma-joined clause with no sentence
+#: break, so first-sentence extraction would not shorten it at all.
+_FOOTER_FIX_BUDGET = 75
+
+
+def _truncate_fix(fix: str, budget: int = _FOOTER_FIX_BUDGET) -> str:
+    """`fix`, cut to `budget` characters on a word boundary where the budget
+    lands inside one, with a single `…` appended -- never a mid-word cut,
+    never a bare truncation with no marker. Returns `fix` byte-for-byte when
+    it already fits, with no trailing `…` added to text that was not cut."""
+    if len(fix) <= budget:
+        return fix
+    cut = fix[:budget]
+    boundary = cut.rfind(" ")
+    if boundary > 0:
+        cut = cut[:boundary]
+    return f"{cut}…"
+
+
+def render_check_lines(check: dict, width: int, color: bool) -> list[str]:
+    """`[status] name: detail`, wrapped, plus an indented `fix:` block when
+    the check carries one -- ONE check's lines. `render_doctor_lines` below
+    (the batch path) and `doctor_cmd`'s streaming path (print the moment a
+    check completes, change 3) both call this SAME function, so the two
+    never fork into separate formatting code. The status token's OWN width
+    (`:>7`, matching `unknown`, the longest status word) is computed on the
+    plain text first, so a painted token never throws off the hanging
+    indent's alignment -- the ANSI bytes are invisible and must not count as
+    columns.
+    """
+    status = check["status"]
+    name = check["name"]
+    prefix = f"[{status:>7}] {name}: "
+    indent = " " * _CONTINUATION_INDENT
+    lines = wrap_block(check["detail"], width, prefix, indent)
+
+    hue = _STATUS_HUE.get(status)
+    if color and hue:
+        painted = f"[{hue}{status:>7}{_RESET}] {name}: "
+        lines[0] = painted + lines[0][len(prefix) :]
+
+    fix = check.get("fix")
+    if fix is not None:
+        lines.extend(wrap_block(fix, width, _FIX_PREFIX, indent))
+    return lines
+
+
+def render_doctor_footer(
+    checks: list[dict], summary: dict, extra_issue_lines: list[str], width: int
+) -> list[str]:
+    """Everything AFTER the per-check blocks, in order:
+
+    1. `extra_issue_lines` verbatim (already filtered by the caller against
+       `checked_codes`, tan-cli#375), each wrapped through `wrap_block` at
+       `width` -- the same seam every check block above already goes
+       through. Measured before this wrapping existed: a real
+       `doctor.fix-suppressed` line ran to 262 columns, unwrapped, inside
+       the very report this whole task exists to wrap.
+    2. A failures-only footer, omitted entirely when nothing failed -- each
+       row names the START of its own fix, truncated to
+       `_FOOTER_FIX_BUDGET`, then wrapped the same way as (1): truncation
+       keeps the row SHORT, wrapping keeps whatever survives that cut
+       actually on screen. Measured unwrapped: `4 + len(name) + 2 +
+       _FOOTER_FIX_BUDGET + 1` (the trailing `+ 1` is `_truncate_fix`'s own
+       `…`) = 107 columns for `zephyrSdkAvailableForHost` (25 chars). A
+       failing check with no `fix` falls back to the bare `- <name>` row.
+    3. The summary line, last, never wrapped -- one short, fixed sentence.
+
+    `width` is the SAME value `doctor_cmd.doctor` resolves for the per-check
+    blocks above -- never a second, independently floored number. Every
+    continuation in (1)/(2) lands at `_CONTINUATION_INDENT`, the same rail
+    check `detail`/`fix` continuations already use.
+
+    Split out from `render_doctor_lines` so `doctor_cmd`'s streaming path
+    can print each check as it completes and call this once, for the tail.
+    """
+    hanging = " " * _CONTINUATION_INDENT
+    lines: list[str] = []
+    for issue_line in extra_issue_lines:
+        lines.extend(wrap_block(issue_line, width, "", hanging))
+
+    failed = [c for c in checks if c["status"] == "fail"]
+    if failed:
+        lines.append("")
+        lines.append("Failed checks:")
+        for c in failed:
+            fix = c.get("fix")
+            body = f"{c['name']}: {_truncate_fix(fix)}" if fix else c["name"]
+            lines.extend(wrap_block(body, width, "  - ", hanging))
+
+    lines.append("")
+    lines.append(
+        f"{summary['pass']} passed, {summary['warn']} warning(s), {summary['fail']} failed."
+    )
+    return lines
+
+
+def render_doctor_lines(
+    checks: list[dict],
+    summary: dict,
+    extra_issue_lines: list[str],
+    width: int,
+    color: bool,
+) -> list[str]:
+    """The lines `doctor_cmd.doctor`'s text branch prints, in order: one
+    block per check (`render_check_lines`, SAME order `checks` arrives in --
+    the order is a diagnostic progression, `hostPrerequisites` failing is why
+    `west` fails too, and reordering would hide that), then the tail
+    (`render_doctor_footer`).
+
+    The one-call batch form, for a caller holding the full check list up
+    front (this module's own tests); the streaming caller in `doctor_cmd`
+    calls `render_check_lines`/`render_doctor_footer` directly instead, see
+    their docstrings for why.
+    """
+    lines: list[str] = []
+    for check in checks:
+        lines.extend(render_check_lines(check, width, color))
+    lines.extend(render_doctor_footer(checks, summary, extra_issue_lines, width))
+    return lines

tan/core/doctor_scope.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The `scope` every `tan doctor` check carries on the wire (tan-cli#549).
+
+A consumer rendering the doctor report has to split HOST rows from PROJECT
+rows -- the dependency panel in `alp-sdk-vscode` shows the host half with no
+folder open. Before this field the only handle was `checks[].name`, so the
+split was a hand-written list of another program's identifiers. That list went
+stale across two pin bumps and shipped `zephyrSdkHost`, an id this CLI stopped
+emitting when the check was renamed `zephyrSdkAvailableForHost`; nothing
+failed, the row was simply never admitted, and a missing row reads to a user
+as "not a problem" rather than "not asked" (alp-sdk-vscode#472, patched
+downstream in alp-sdk-vscode#487 with the caveat that a re-derived hand-list
+rots again).
+
+## The two values, and the rule that decides between them
+
+The question is **what the check's verdict is ABOUT** -- its subject -- not
+which inputs it happened to read on the way to that verdict.
+
+`host`
+    The subject is THIS MACHINE: a tool on PATH, an OS setting, the host
+    interpreter, the home directory, whether the pinned Zephyr SDK publishes a
+    build for this OS/arch. A project or SDK fact may refine the threshold or
+    the wording (`hostPython`'s floor is the higher of the SDK manifest's and
+    the workspace Zephyr's), but the thing being verdicted is the host, and
+    the row is worth rendering with no folder open.
+
+`project`
+    The subject is the SELECTED PROJECT and the alp-sdk checkout / Zephyr
+    workspace resolved for it: whether a `board.yaml` is there, whether a
+    workspace resolved, whether that workspace's Zephyr matches the SDK's own
+    pin, where this venv or SDK came from. With nothing selected these still
+    report -- honestly, against "nothing selected" -- but they answer a
+    question the user has not asked yet.
+
+The one judgement call worth naming: `sdk` and `pythonFloor` are `project`.
+`sdk`'s top resolution tier is the machine-global `~/.alp/sdk-default`, which
+argues for `host`; its subject is still "which checkout will THIS project
+build against", and its lower tiers (`.alp/sdk-path`, the positional walk) are
+directory-dependent. `pythonFloor` reads as a host fact from its name, but
+both its arms verdict a DECLARATION -- the SDK manifest's `pythonMinVersion`
+against the workspace Zephyr's, or the absence of a manifest to read -- and
+its remedy in the no-SDK arm is "resolve an alp-sdk checkout". The host-side
+half of that pair is `hostPython`, which is `host`.
+
+## Why the vocabulary lives here rather than beside `Check`
+
+Nothing in this module imports typer or touches IO, so the gate that walks
+every `Check(...)` call site (`python/tests/gates/test_doctor_check_scope.py`)
+and `tan/commands/support_bundle_cmd.py`, which builds a doctor-shaped report
+of its own, can both read the vocabulary without importing a command module.
+"""
+from __future__ import annotations
+
+#: The check verdicts a fact about this machine. See the module docstring.
+HOST = "host"
+
+#: The check verdicts a fact about the selected project/SDK/workspace.
+PROJECT = "project"
+
+#: The complete wire vocabulary, in the order the contract documents it. A
+#: value outside this tuple is refused at construction (`Check.__post_init__`)
+#: rather than shipped: a consumer filtering on `scope` cannot tell an
+#: unrecognised value from a row it should hide, which is the same fail-open
+#: silence the name-matching seam had.
+CHECK_SCOPES: tuple[str, ...] = (HOST, PROJECT)