tan-cli 0.7.0__py3-none-any.whl

tan/planner_root.py

@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Where the relocated planner finds the SDK -- bound once, before import.
+
+`tan.planner` is alp-sdk's `scripts/alp_orchestrate/` relocated verbatim. In
+alp-sdk its `paths.py` derived the repo root by walking up from its own
+`__file__`; inside `tan` that walk lands on the `tan` package and every
+`metadata/**` path would be wrong. So the root becomes an explicit binding.
+
+**Binding must happen before `tan.planner` is imported.** `paths.py` evaluates
+`REPO = sdk_root()` at module scope, and half the package takes
+`metadata_root: Path = METADATA_ROOT` as a *default argument* -- both freeze at
+import time. An unbound import therefore raises `PlannerRootError` loudly
+rather than silently resolving `metadata/**` against the wrong tree; that is
+the same refuse-don't-degrade posture the executor's token substitution takes
+(`tan/commands/build/token_substitution.py`).
+
+`metadata/**` stays in alp-sdk (ADR-0017): what relocated is the generators,
+never the facts. The fact READERS relocated with them -- `resolve_memory_map`,
+`resolve_capabilities`, `silicon_to_kconfig` and `som_unpopulated_capabilities`
+now live in `tan/planner/som_metadata.py`, `peripheral_kconfig` in
+`tan/planner/slugs.py`, `iter_schema_errors` in `tan/planner/loader.py`, the
+SKU/board/pad-route resolvers in `tan/planner/project_loader.py`, and the
+`alp_project.py`-owned emitters in `tan/planner/project_emit/` +
+`tan/planner/zephyr_board.py` -- and every one of them reads the same files out
+of the bound checkout. **No `tan.planner` module imports anything under
+`<sdk_root>/scripts` any more**, which is what makes an in-process emit load zero
+of alp-sdk's Python
+(`tests/parity/test_planner_emit_parity.py::test_the_in_process_path_loads_none_of_the_sdks_python`
+is the measurement, per mode across all twelve).
+
+**Binding does NOT put `<sdk_root>/scripts` on `sys.path`, deliberately.** Nothing
+in `tan`'s own execution needs it: every `tan generate` target renders
+in-process, `tan build` plans in-process, and the one remaining SDK script --
+`alp_project.py` under `TAN_GENERATE_EXECUTOR=subprocess` -- is SPAWNED, and a
+spawned interpreter gets its own script directory regardless of this
+process's `sys.path`. (The Kconfig dumper Zephyr's `EXTRA_KCONFIG_TARGET`
+hook spawns is no longer an SDK edge either: `tan.planner.kconfig_symbols`
+renders it into the run's own scratch tree.)
+
+Removing the entry is what turns the zero closure from **measured** into
+**structural**. With `<sdk_root>/scripts` importable, a re-introduced
+`from alp_project import ...` would silently work and only a closure measurement
+would catch it; without it, that import fails loudly at the moment it is written.
+The measurement
+(`tests/parity/test_planner_emit_parity.py::test_the_in_process_path_loads_none_of_the_sdks_python`)
+stays as the belt to this braces.
+
+A caller that genuinely needs an SDK module by name in tan's own process must put
+the path there itself and own it. Exactly one does: the parity harness's oracle,
+whose `planners` fixture inserts `<sdk>/scripts` explicitly so it can import
+`alp_project` and diff the relocated planner against the original. That is a test
+comparing two implementations, not `tan` depending on one.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+__all__ = ["PlannerRootError", "bind_sdk_root", "sdk_root", "emit"]
+
+
+class PlannerRootError(RuntimeError):
+    """The planner's SDK root is unbound, or a rebind came too late."""
+
+
+_BOUND: Path | None = None
+
+
+def bind_sdk_root(root: Path | str) -> Path:
+    """Point the relocated planner at an alp-sdk checkout. Idempotent.
+
+    Rebinding to a *different* root once `tan.planner` is imported is an error,
+    not a no-op: the already-frozen module constants and default arguments would
+    keep reading the first root's `metadata/**` while callers believed the
+    second -- a silent wrong-SDK build, which is precisely the split-brain the
+    plan's `sdkCommit` guard exists to catch.
+
+    Binding touches `sys.path` not at all -- see the module docstring. The root is
+    a value the relocated planner reads, not an import route.
+    """
+    global _BOUND
+    resolved = Path(root).resolve()
+    if (
+        _BOUND is not None
+        and _BOUND != resolved
+        and "tan.planner" in sys.modules
+    ):
+        raise PlannerRootError(
+            f"the planner is already bound to `{_BOUND}` and imported; "
+            f"cannot rebind to `{resolved}` in the same process.")
+    _BOUND = resolved
+    return resolved
+
+
+def sdk_root() -> Path:
+    """The bound alp-sdk checkout root. Raises if unbound."""
+    if _BOUND is None:
+        raise PlannerRootError(
+            "tan.planner was imported before `bind_sdk_root(<alp-sdk root>)`; "
+            "its metadata paths freeze at import time, so an unbound import "
+            "cannot be repaired -- bind first, then import.")
+    return _BOUND
+
+
+def emit(mode: str, *, root: Path | str, board_yaml: Path,
+         build_root: Path = Path("build"), core: str | None = None) -> str:
+    """Bind, load `board_yaml`, and return one emit artefact as text.
+
+    The in-process twin of `python -m tan.planner --emit <mode>`; both route
+    through the same `tan.planner.cli.emit_artefact` dispatch so a mode can
+    never render differently depending on how it was reached.
+    """
+    bind_sdk_root(root)
+    from tan.planner import load_board_yaml
+    from tan.planner.cli import emit_artefact
+    project = load_board_yaml(Path(board_yaml))
+    return emit_artefact(project, mode, board_yaml=Path(board_yaml),
+                         build_root=Path(build_root), core=core)

tan/soc_ref.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure `silicon:` ref -> SoC-JSON path resolution.
+
+A leaf module: no imports of `tan.planner` or anything else that reads real
+files at import time. `tan.planner.som_metadata` imports `resolve_soc_path`
+from here and re-exports it (its own four call sites keep working
+unchanged); `tan.model.targets` imports it from here directly so that
+`tan.model` stays importable without a bound alp-sdk checkout -- importing
+`tan.planner` pulls in `tan/planner/__init__.py`, which transitively reads
+real `metadata/registries/*` content at import time (`tan/planner/slugs.py`'s
+module-scope `_PERIPHERAL_KCONFIG = peripheral_kconfig()`), a dependency
+`tan.model` never had in alp-sdk and should not gain here.
+
+One definition, re-exported -- alp-sdk spent issues #997/#1004/#1096
+collapsing this resolution to a single source; do not create a second copy.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_soc_path(silicon: str | None, metadata_root: Path) -> Path | None:
+    """Resolve a `vendor:family:part` `silicon:` key to the SoC-JSON path
+    it names: `metadata/socs/<vendor>/<family>/<part>.json`.
+
+    Returns None when `silicon` is falsy or not exactly 3 colon-separated
+    parts -- does NOT check the path exists, callers decide what an
+    unresolved/missing SoC spec means for them (e.g. a SoM preset with no
+    `silicon:` at all is a valid, if incomplete, state; a `silicon:` that
+    names a spec that isn't on disk is not).
+
+    alp-sdk keeps its own copies of this resolution behind differing failure
+    shapes (`OrchestratorError`, `ZephyrBoardEmitError`, a diagnostic list);
+    `loader._silicon_to_soc_path` is the planner's raising variant. This is the
+    soft-fail one `tan.planner.som_metadata` and `tan.model.targets` share.
+    """
+    if not isinstance(silicon, str) or not silicon:
+        # A non-string `silicon:` (e.g. a hand-authored `silicon: 7`) is
+        # "not exactly 3 colon-separated parts" exactly as much as a falsy
+        # one is -- the docstring above already promises None for that
+        # shape, `silicon.split(":")` below just didn't deliver on it
+        # (`AttributeError: 'int' object has no attribute 'split'`,
+        # tan-cli#967 review). This is a SHARED leaf (re-exported by
+        # `tan.planner.som_metadata`, imported directly by
+        # `tan.model.targets`) -- fixing it here, once, fixes every caller
+        # identically rather than needing a matching guard at each call
+        # site. Every existing caller already treats a None return as
+        # "unresolved" and reports it through its own error message
+        # (`_load_soc_spec` -> `ZephyrBoardEmitError("... is not a
+        # triple-colon string")`, `resolve_targets` -> `ValueError`), so
+        # this changes a crash into the SAME clean diagnostic those callers
+        # already produce for a malformed-but-string ref, not a new
+        # behaviour.
+        return None
+    parts = silicon.split(":")
+    if len(parts) != 3:
+        return None
+    return metadata_root / "socs" / parts[0] / parts[1] / f"{parts[2]}.json"

tan/templates/__init__.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+"""tan's OWN copy of the SDK scaffold trees `tan init` lays down.
+
+``vendored/`` is ``alp-sdk --emit scaffold`` output captured byte-for-byte (LF,
+no retouching) -- a verbatim copy of ``crates/tan-core/src/wizard/vendored/``,
+which the Rust binary bakes in with ``include_str!``. It is checked in for the
+same reason it is checked in there: **I-32 -- `tan init` is SDK-free.** A
+customer's first command must work with no alp-sdk checkout anywhere on the
+machine, so the scaffold content cannot be fetched, and shelling the SDK's
+scaffold emit would hand `tan init` a dependency it deliberately does not have.
+
+Two consequences worth stating where the bytes live:
+
+* **Re-vendor by re-running the emit, never by hand-editing these files.**
+  ``vendored/MANIFEST.md`` carries the exact source commit and the template x
+  SKU matrix. ``tests/core/test_scaffold.py`` byte-diffs this tree against the
+  Rust one, so a re-vendor that updates only one language fails there.
+* **LF is load-bearing.** These bytes are written to the customer's files
+  verbatim, and the byte-diff above compares them to an LF capture. The repo
+  root's ``.gitattributes`` pins ``text eol=lf`` for this path; without it a
+  Windows checkout with ``autocrlf=true`` silently rewrites every one.
+
+The tree ships in the frozen binary via ``--add-data`` (``scripts/
+build_binary.sh``). It is data, not code, so PyInstaller's static import graph
+does NOT pull it in on its own -- when it is missing, `tan init` reports
+``init.template-unreadable`` rather than raising (``tan.core.scaffold``).
+"""
+from pathlib import Path
+
+#: Root of the vendored scaffold trees: ``vendored/<sdk-template-id>/<SKU>/``.
+#: Derived from ``__file__`` so it resolves both from source and from a frozen
+#: onefile bundle, where PyInstaller sets ``__file__`` under ``sys._MEIPASS``
+#: and ``--add-data`` has placed the tree at the same package-relative path.
+VENDORED_ROOT = Path(__file__).resolve().parent / "vendored"