Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

14.4 KB
Raw Blame
"""Installed-bundle records β€” requirements and ownership for list/remove/update.

Records are stored as JSON at ``.specify/bundle-records.json``. Each record
stores every required component for conflict detection and separately records
which components the bundle contributed, so removal never touches independently
installed components (FR-022, SC-004). Known installed
versions are stored separately from requested pins to make patch substitutions
visible without changing bundle ownership or manifest identity.
"""
from __future__ import annotations

from dataclasses import dataclass, field, replace
from datetime import datetime, timezone
from pathlib import Path
from typing import Any

from . import BundlerError
from .yamlio import dump_json, ensure_within, load_json
from .manifest import COMPONENT_KINDS, BundleRef, ComponentRef, _text

RECORDS_FILENAME = "bundle-records.json"
RECORDS_SCHEMA_VERSION = "1.0"


@dataclass(frozen=True)
class InstalledBundleRecord:
    bundle_id: str
    version: str
    contributed_components: tuple[ComponentRef, ...]
    required_components: tuple[ComponentRef, ...]
    installed_at: str
    installed_versions: dict[str, str] = field(default_factory=dict)
    bundle_references: tuple[BundleRef, ...] = ()

    @classmethod
    def create(
        cls,
        bundle_id: str,
        version: str,
        components: list[ComponentRef],
        installed_at: str | None = None,
        required_components: list[ComponentRef] | None = None,
        installed_versions: dict[str, str] | None = None,
        bundle_references: list[BundleRef] | None = None,
    ) -> "InstalledBundleRecord":
        return cls(
            bundle_id=bundle_id,
            version=version,
            contributed_components=tuple(components),
            required_components=tuple(
                components if required_components is None else required_components
            ),
            installed_at=installed_at or _utc_now(),
            installed_versions=(
                dict(installed_versions) if installed_versions is not None else {}
            ),
            bundle_references=(
                tuple(bundle_references) if bundle_references is not None else ()
            ),
        )

    def to_dict(self) -> dict[str, Any]:
        data: dict[str, Any] = {
            "bundle_id": self.bundle_id,
            "version": self.version,
            "installed_at": self.installed_at,
            "contributed_components": [
                _component_to_dict(c) for c in self.contributed_components
            ],
            "required_components": [
                _component_to_dict(c) for c in self.required_components
            ],
        }
        if self.installed_versions:
            data["installed_versions"] = dict(self.installed_versions)
        if self.bundle_references:
            data["bundle_references"] = [
                _bundle_reference_to_dict(reference)
                for reference in self.bundle_references
            ]
        return data

    @classmethod
    def from_dict(cls, data: Any) -> "InstalledBundleRecord":
        if not isinstance(data, dict):
            raise BundlerError("Each installed-bundle record must be a mapping.")
        components_raw = data.get("contributed_components")
        if components_raw is None:
            components_raw = []
        elif not isinstance(components_raw, list):
            # `or []` would coerce a FALSY non-list (0, '', False, {}) to []
            # before this guard, silently accepting a corrupt record; only an
            # absent/None value means "no components".
            raise BundlerError(
                "Corrupt record: 'contributed_components' must be a list."
            )
        # Older records contain only contributed components. Retain those
        # known pins until a successful reinstall writes the full requirements.
        required_raw = data.get("required_components", components_raw)
        if not isinstance(required_raw, list):
            raise BundlerError(
                "Corrupt record: 'required_components' must be a list."
            )
        # ``.get(key, "")`` defaults only a *missing* key. A key that is
        # present but null -- how a hand-edited or corrupt record spells an
        # empty field -- yields ``None``, and ``str(None)`` is the non-empty
        # literal ``"None"``, which sails past the required-field checks
        # below. Reuse the manifest's ``_text`` so records and bundle.yml
        # agree on what an explicit null means.
        bundle_id = _text(data.get("bundle_id"))
        version = _text(data.get("version"))
        if not bundle_id:
            raise BundlerError(
                "Corrupt records file: an installed-bundle record is missing "
                "its 'bundle_id'."
            )
        if not version:
            raise BundlerError(
                f"Corrupt records file: record for bundle '{bundle_id}' is "
                "missing its 'version'."
            )
        contributed = tuple(_component_from_dict(c) for c in components_raw)
        required = tuple(
            _component_from_dict(c, label="required") for c in required_raw
        )
        if not set(contributed).issubset(required):
            raise BundlerError(
                "Corrupt record: 'required_components' must include all "
                "'contributed_components'."
            )
        installed_versions = data.get("installed_versions", {})
        if not isinstance(installed_versions, dict):
            raise BundlerError("Corrupt record: 'installed_versions' must be a mapping.")
        bundle_references_raw = data.get("bundle_references")
        if bundle_references_raw is None:
            bundle_references: tuple[BundleRef, ...] = ()
        elif not isinstance(bundle_references_raw, list):
            raise BundlerError("Corrupt record: 'bundle_references' must be a list.")
        else:
            bundle_references = tuple(
                _bundle_reference_from_dict(reference)
                for reference in bundle_references_raw
            )
        keys = {f"{c.kind}:{c.id}" for c in required}
        for key, actual in installed_versions.items():
            if key not in keys or not isinstance(actual, str) or not actual.strip():
                raise BundlerError(
                    "Corrupt record: 'installed_versions' must map required "
                    "component keys (kind:id) to non-empty version strings."
                )
        return cls(
            bundle_id=bundle_id,
            version=version,
            installed_at=_text(data.get("installed_at")),
            contributed_components=contributed,
            required_components=required,
            installed_versions=dict(installed_versions),
            bundle_references=bundle_references,
        )


def records_path(project_root: Path) -> Path:
    return Path(project_root) / ".specify" / RECORDS_FILENAME


def _check_schema_version(value: Any, *, path: Path, required: bool) -> None:
    """Reject a records file whose schema version we cannot safely parse.

    A future incompatible format (or a corrupted file) must fail fast with an
    actionable error rather than being silently mis-parsed, which could lead to
    incorrect bundle attribution or removal. Forward-compatible minor bumps that
    keep the same major version are accepted.
    """
    if value is None:
        if required:
            raise BundlerError(
                f"Corrupt records file: {path} β€” missing 'schema_version'. "
                f"Expected version {RECORDS_SCHEMA_VERSION}."
            )
        return
    seen = str(value).strip()
    if seen.split(".")[0] != RECORDS_SCHEMA_VERSION.split(".")[0]:
        raise BundlerError(
            f"Unsupported records schema version '{seen}' at {path}; this "
            f"Spec Kit understands version {RECORDS_SCHEMA_VERSION}. The file may "
            "have been written by a newer version or is corrupt."
        )


def load_records(project_root: Path) -> list[InstalledBundleRecord]:
    # Defense in depth (mirrors the write path's within= confinement): refuse to
    # read through a symlinked or traversal-escaping ``.specify`` that resolves
    # outside project_root.
    path = ensure_within(project_root, records_path(project_root))
    if not path.exists():
        return []
    data = load_json(path)
    if not isinstance(data, dict):
        raise BundlerError(f"Corrupt records file: {path}")
    _check_schema_version(data.get("schema_version"), path=path, required=True)
    bundles = data.get("bundles")
    if bundles is None:
        bundles = []
    elif not isinstance(bundles, list):
        # `or []` would coerce a FALSY non-list (0, '', False, {}) to [] before
        # this guard, silently treating a corrupt file as "no bundles"; only an
        # absent/None value means empty.
        raise BundlerError(
            f"Corrupt records file: {path} β€” 'bundles' must be a list."
        )
    return [InstalledBundleRecord.from_dict(item) for item in bundles]


def save_records(project_root: Path, records: list[InstalledBundleRecord]) -> None:
    payload = {
        "schema_version": RECORDS_SCHEMA_VERSION,
        "updated_at": _utc_now(),
        "bundles": [r.to_dict() for r in records],
    }
    dump_json(records_path(project_root), payload, within=project_root)


def find_record(
    records: list[InstalledBundleRecord], bundle_id: str
) -> InstalledBundleRecord | None:
    for record in records:
        if record.bundle_id == bundle_id:
            return record
    return None


def upsert_record(
    records: list[InstalledBundleRecord], record: InstalledBundleRecord
) -> list[InstalledBundleRecord]:
    """Return a new list with *record* replacing any same-id record (append otherwise)."""
    updated = [r for r in records if r.bundle_id != record.bundle_id]
    updated.append(record)
    return updated


def remove_record(
    records: list[InstalledBundleRecord], bundle_id: str
) -> list[InstalledBundleRecord]:
    return [r for r in records if r.bundle_id != bundle_id]


def transfer_contributions(
    records: list[InstalledBundleRecord],
    released: list[ComponentRef] | tuple[ComponentRef, ...],
) -> list[InstalledBundleRecord]:
    """Keep a bundle-installed component attributed while another bundle needs it."""
    updated = list(records)
    owned = {
        (component.kind, component.id)
        for record in updated
        for component in record.contributed_components
    }
    for component in released:
        key = component.kind, component.id
        if key in owned:
            continue
        for index, record in enumerate(updated):
            required = next(
                (
                    ref for ref in record.required_components
                    if (ref.kind, ref.id) == key
                ),
                None,
            )
            if required is not None:
                updated[index] = replace(
                    record,
                    contributed_components=(*record.contributed_components, required),
                )
                owned.add(key)
                break
    return updated


def components_still_needed(
    records: list[InstalledBundleRecord], exclude_bundle_id: str
) -> set[tuple[str, str]]:
    """Set of ``(kind, id)`` component keys required by bundles other than the excluded one."""
    needed: set[tuple[str, str]] = set()
    for record in records:
        if record.bundle_id == exclude_bundle_id:
            continue
        for component in record.required_components:
            needed.add((component.kind, component.id))
    return needed


def _component_to_dict(ref: ComponentRef) -> dict[str, Any]:
    data: dict[str, Any] = {"kind": ref.kind, "id": ref.id}
    if ref.version is not None:
        data["version"] = ref.version
    if ref.source is not None:
        data["source"] = ref.source
    if ref.priority is not None:
        data["priority"] = ref.priority
    if ref.strategy is not None:
        data["strategy"] = ref.strategy
    return data


def _bundle_reference_to_dict(reference: BundleRef) -> dict[str, Any]:
    return {
        "id": reference.id,
        "version": reference.version,
        "source": reference.source,
    }


def _bundle_reference_from_dict(data: Any) -> BundleRef:
    if not isinstance(data, dict):
        raise BundlerError(
            "Corrupt record: 'bundle_references' entries must be mappings."
        )
    bundle_id = data.get("id")
    version = data.get("version")
    if (
        not isinstance(bundle_id, str)
        or not bundle_id.strip()
        or not isinstance(version, str)
        or not version.strip()
    ):
        raise BundlerError(
            "Corrupt record: 'bundle_references' entries must have non-empty "
            "string 'id' and 'version'."
        )
    source = data.get("source")
    if source == "":
        source = None
    elif source is not None and not isinstance(source, str):
        raise BundlerError(
            "Corrupt record: 'bundle_references' entry 'source' must be a string."
        )
    return BundleRef(
        id=bundle_id,
        version=version,
        source=source,
    )


def _component_from_dict(data: Any, *, label: str = "contributed") -> ComponentRef:
    if not isinstance(data, dict):
        raise BundlerError(f"Each {label} component must be a mapping.")
    kind = _text(data.get("kind"))
    cid = _text(data.get("id"))
    if kind not in COMPONENT_KINDS:
        raise BundlerError(
            f"Corrupt records file: component 'kind' must be one of "
            f"{list(COMPONENT_KINDS)}, got {kind or '<missing>'!r}."
        )
    if not cid:
        raise BundlerError(
            f"Corrupt records file: a {label} component is missing its 'id'."
        )
    return ComponentRef(
        kind=kind,
        id=cid,
        version=(str(data["version"]) if data.get("version") else None),
        source=(str(data["source"]) if data.get("source") else None),
        priority=_parse_priority(data.get("priority")),
        strategy=(str(data["strategy"]) if data.get("strategy") else None),
    )


def _parse_priority(raw: Any) -> int | None:
    if raw is None:
        return None
    if isinstance(raw, bool) or not isinstance(raw, (int, str)):
        raise BundlerError(f"Component priority must be an integer, got {raw!r}.")
    try:
        return int(raw)
    except (TypeError, ValueError):
        raise BundlerError(
            f"Component priority must be an integer, got {raw!r}."
        ) from None


def _utc_now() -> str:
    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")