Skip to content

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

16.7 KB
Raw Blame
"""Contract tests for the catalog schema and source stack.

Mirrors contracts/bundle-catalog.schema.md: source precedence project > user >
built-in, install policy gating, payload parsing.
"""
from __future__ import annotations

import json
import tomllib
from pathlib import Path

import yaml

from specify_cli.bundles.catalogs import (
    BUILTIN_DEFAULT_STACK,
    CatalogSource,
    InstallPolicy,
    Scope,
    load_catalog_payload,
    load_source_stack,
)
from specify_cli.bundler import BundlerError
import pytest
from tests.specify_cli.bundles.helpers import catalog_entry_dict, catalog_payload, make_project


def test_non_integer_source_priority_raises_actionable_error():
    with pytest.raises(BundlerError, match="non-integer priority"):
        CatalogSource.from_dict(
            {"id": "corp", "url": "https://corp/catalog.json", "priority": "high"},
            Scope.PROJECT,
        )


def test_builtin_default_stack_when_no_config(tmp_path: Path):
    make_project(tmp_path)
    sources = load_source_stack(tmp_path)
    ids = [s.id for s in sources]
    assert ids == ["default", "community"]
    assert sources[0].install_policy is InstallPolicy.INSTALL_ALLOWED
    assert sources[1].install_policy is InstallPolicy.DISCOVERY_ONLY
    assert sources[1].priority == 20
    assert all(s.scope is Scope.BUILTIN for s in sources)


def test_non_list_catalogs_raises_actionable_error(tmp_path: Path):
    """A scalar ``catalogs:`` value raises a clean BundlerError, not a raw
    'int object is not iterable' TypeError β€” matching what the sibling reader
    (bundle catalog list) already reports for the same file."""
    make_project(tmp_path)
    (tmp_path / ".specify" / "bundle-catalogs.yml").write_text(
        "catalogs: 5\n", encoding="utf-8"
    )
    with pytest.raises(BundlerError, match="must be a list"):
        load_source_stack(tmp_path)


@pytest.mark.parametrize("value", ["false", "0", "''", "{}"])
def test_falsy_non_list_catalogs_still_raises(tmp_path: Path, value: str):
    """A *falsy* non-list ``catalogs:`` value (false/0/''/{}) must also raise β€”
    only an absent/``None`` value means "nothing to merge". A plain falsy check
    would silently swallow these, diverging from the sibling reader."""
    make_project(tmp_path)
    (tmp_path / ".specify" / "bundle-catalogs.yml").write_text(
        f"catalogs: {value}\n", encoding="utf-8"
    )
    with pytest.raises(BundlerError, match="must be a list"):
        load_source_stack(tmp_path)


@pytest.mark.parametrize(
    "body",
    [
        "- a\n- b\n",  # truthy list
        "42\n",        # truthy scalar
        "[]\n",        # falsy list
        "false\n",     # falsy bool
        "0\n",         # falsy int
        "''\n",        # falsy empty string
        "null\n",      # explicit null scalar (safe_load -> None, but a real node)
        "~\n",         # explicit null scalar (alt spelling)
    ],
)
def test_toplevel_non_mapping_raises(tmp_path: Path, body: str):
    """A top-level non-mapping bundle-catalogs.yml (list/scalar/null) must raise,
    matching the sibling reader (catalog_config._read) β€” not silently fall back
    to the built-in default stack. This includes FALSY non-mappings ([], false,
    0, '') and an explicit null (null/~); the shared load_yaml would coerce those
    to {} and hide them, so it distinguishes them from a truly empty document."""
    make_project(tmp_path)
    (tmp_path / ".specify" / "bundle-catalogs.yml").write_text(body, encoding="utf-8")
    with pytest.raises(BundlerError, match="expected a mapping at the top level"):
        load_source_stack(tmp_path)


@pytest.mark.parametrize(
    "body",
    [
        "catalogs:\n",       # present key, null value
        "catalogs: []\n",    # present key, empty list
        "",                  # truly empty document
        "# only a comment\n",  # comment-only == empty document
    ],
)
def test_absent_or_empty_catalogs_is_noop(tmp_path: Path, body: str):
    """An empty document, comment-only file, or absent/empty-list ``catalogs:``
    is valid: it contributes no project sources and falls back to the built-in
    default stack (must not be confused with an explicit top-level null)."""
    make_project(tmp_path)
    (tmp_path / ".specify" / "bundle-catalogs.yml").write_text(body, encoding="utf-8")
    # Does not raise; still yields the built-in defaults.
    sources = load_source_stack(tmp_path)
    assert len(sources) > 0


def test_load_source_stack_rejects_unknown_schema_version(tmp_path: Path):
    """A bundle-catalogs.yml with an unsupported MAJOR schema_version must raise
    on the resolution path (load_source_stack -> _merge_config), matching the
    sibling reader commands_impl/catalog_config._read. Without this a file
    written by a newer/incompatible Spec Kit was silently parsed under v1
    assumptions on the install/search path, while the other reader rejected it."""
    make_project(tmp_path)
    config = {
        "schema_version": "2.0",
        "catalogs": [{"id": "corp", "url": "https://corp/catalog.json",
                      "priority": 1, "install_policy": "install-allowed"}],
    }
    (tmp_path / ".specify" / "bundle-catalogs.yml").write_text(
        yaml.safe_dump(config), encoding="utf-8"
    )
    with pytest.raises(BundlerError, match="Unsupported catalog config schema version"):
        load_source_stack(tmp_path)


def test_load_source_stack_accepts_matching_or_absent_schema_version(tmp_path: Path):
    """A matching major version (1.x) and an absent schema_version both stay
    valid β€” the guard rejects only a different major, so existing configs that
    omit the key are unaffected."""
    make_project(tmp_path)
    cfg = tmp_path / ".specify" / "bundle-catalogs.yml"
    cfg.write_text(yaml.safe_dump({
        "schema_version": "1.5",  # same major as CONFIG_SCHEMA_VERSION (1.0)
        "catalogs": [{"id": "corp", "url": "https://corp/catalog.json",
                      "priority": 1, "install_policy": "install-allowed"}],
    }), encoding="utf-8")
    assert "corp" in {s.id for s in load_source_stack(tmp_path)}
    cfg.write_text(yaml.safe_dump({  # no schema_version key
        "catalogs": [{"id": "corp2", "url": "https://corp2/catalog.json",
                      "priority": 1, "install_policy": "install-allowed"}],
    }), encoding="utf-8")
    assert "corp2" in {s.id for s in load_source_stack(tmp_path)}


def test_project_config_overrides_same_id(tmp_path: Path):
    make_project(tmp_path)
    config = {
        "schema_version": "1.0",
        "catalogs": [
            {"id": "default", "url": "file://local", "priority": 1,
             "install_policy": "install-allowed"},
            {"id": "corp", "url": "https://corp/catalog.json", "priority": 0,
             "install_policy": "install-allowed"},
        ],
    }
    (tmp_path / ".specify" / "bundle-catalogs.yml").write_text(
        yaml.safe_dump(config), encoding="utf-8"
    )
    sources = load_source_stack(tmp_path)
    by_id = {s.id: s for s in sources}
    assert by_id["default"].scope is Scope.PROJECT
    assert by_id["default"].url == "file://local"
    # Highest precedence (lowest priority number) sorts first.
    assert sources[0].id == "corp"


def test_user_scope_between_builtin_and_project(tmp_path: Path):
    make_project(tmp_path)
    user_dir = tmp_path / "userconf"
    user_dir.mkdir()
    (user_dir / "bundle-catalogs.yml").write_text(
        yaml.safe_dump(
            {"catalogs": [
                {"id": "community", "url": "https://u", "priority": 2,
                 "install_policy": "install-allowed"}
            ]}
        ),
        encoding="utf-8",
    )
    sources = load_source_stack(tmp_path, user_config_dir=user_dir)
    by_id = {s.id: s for s in sources}
    # User overrode the built-in community policy to install-allowed.
    assert by_id["community"].scope is Scope.USER
    assert by_id["community"].install_allowed is True


def test_load_payload_parses_entries():
    payload = catalog_payload({"demo-bundle": catalog_entry_dict()})
    entries = load_catalog_payload(payload)
    assert "demo-bundle" in entries
    assert entries["demo-bundle"].version == "1.2.0"
    assert entries["demo-bundle"].provides["presets"] == 1


def test_builtin_default_stack_constant_shape():
    ids = {raw["id"] for raw in BUILTIN_DEFAULT_STACK}
    assert ids == {"default", "community"}


def test_repository_community_bundle_catalog_matches_contract():
    catalog_path = Path(__file__).parents[2] / "bundles" / "catalog.community.json"
    payload = json.loads(catalog_path.read_text(encoding="utf-8"))

    assert payload["schema_version"] == "1.0"
    assert payload["catalog_url"].endswith("/bundles/catalog.community.json")
    entries = load_catalog_payload(payload)
    assert all(entry.verified is False for entry in entries.values())


def test_wheel_packages_community_bundle_catalog():
    repo_root = Path(__file__).parents[2]
    with (repo_root / "pyproject.toml").open("rb") as pyproject_file:
        pyproject = tomllib.load(pyproject_file)

    force_include = pyproject["tool"]["hatch"]["build"]["targets"]["wheel"][
        "force-include"
    ]
    assert force_include["bundles/catalog.community.json"] == (
        "specify_cli/core_pack/bundles/catalog.community.json"
    )


def test_wheel_packages_firstparty_bundle_catalog():
    repo_root = Path(__file__).parents[2]
    with (repo_root / "pyproject.toml").open("rb") as pyproject_file:
        pyproject = tomllib.load(pyproject_file)

    force_include = pyproject["tool"]["hatch"]["build"]["targets"]["wheel"][
        "force-include"
    ]
    assert force_include["bundles/catalog.json"] == (
        "specify_cli/core_pack/bundles/catalog.json"
    )


def test_catalog_entry_rejects_string_tags():
    from specify_cli.bundles.catalogs import CatalogEntry

    data = catalog_entry_dict("demo")
    data["tags"] = "not-a-list"
    with pytest.raises(BundlerError, match="'tags' must be a list"):
        CatalogEntry.from_dict(data)


def test_catalog_entry_rejects_non_string_tag_members():
    from specify_cli.bundles.catalogs import CatalogEntry

    data = catalog_entry_dict("demo")
    data["tags"] = ["valid", 1]
    with pytest.raises(BundlerError, match="'tags' must be a list of strings"):
        CatalogEntry.from_dict(data)


def test_catalog_entry_rejects_non_boolean_verified():
    from specify_cli.bundles.catalogs import CatalogEntry

    data = catalog_entry_dict("demo")
    data["verified"] = "false"  # truthy string must not mark the entry verified
    with pytest.raises(BundlerError, match="'verified' must be a boolean"):
        CatalogEntry.from_dict(data)


@pytest.mark.parametrize(
    "field",
    [
        "name",
        "version",
        "role",
        "description",
        "author",
        "license",
        "download_url",
    ],
)
def test_catalog_entry_explicit_null_field_reads_as_empty(field: str):
    """An explicitly null field must read as "", not the literal "None".

    `str(data.get(key, ""))` only defaults for a *missing* key. A key present
    but null β€” how YAML spells an empty field (`author:` with nothing after
    it) β€” yields `None`, and `str(None)` is the truthy string `"None"`. The
    same constructor already guards `sha256` and `repository` against exactly
    this.
    """
    from specify_cli.bundles.catalogs import CatalogEntry

    data = catalog_entry_dict("demo")
    data[field] = None

    entry = CatalogEntry.from_dict(data)

    assert getattr(entry, field) == ""


def test_catalog_source_rejects_an_explicitly_null_id():
    """`id: null` must be refused, not registered as a source named "None".

    The `if not source_id` guard was defeated by the truthy literal, so the
    source was accepted and carried the name `"None"` into the stack.
    """
    from specify_cli.bundles.catalogs import CatalogSource, Scope

    with pytest.raises(BundlerError, match="missing its 'id'"):
        CatalogSource.from_dict(
            {
                "id": None,
                "url": "https://example.test/catalog.json",
                "priority": 5,
                "install_policy": "install-allowed",
            },
            Scope.PROJECT,
        )


def test_catalog_source_rejects_an_explicitly_null_url():
    from specify_cli.bundles.catalogs import CatalogSource, Scope

    with pytest.raises(BundlerError, match="missing its 'url'"):
        CatalogSource.from_dict(
            {
                "id": "demo",
                "url": None,
                "priority": 5,
                "install_policy": "install-allowed",
            },
            Scope.PROJECT,
        )


def test_catalog_entry_preserves_sha256_through_provenance():
    digest = "a" * 64
    payload = catalog_payload(
        {"demo": catalog_entry_dict("demo", sha256=f"sha256:{digest}")}
    )

    entry = load_catalog_payload(payload)["demo"]
    source = CatalogSource(
        id="team",
        url="https://example.com/catalog.json",
        priority=10,
        install_policy=InstallPolicy.INSTALL_ALLOWED,
        scope=Scope.PROJECT,
    )

    assert entry.sha256 == f"sha256:{digest}"
    assert entry.with_provenance(source).sha256 == f"sha256:{digest}"


def test_load_payload_rejects_id_key_mismatch():
    # The enclosing key is authoritative; an entry whose own id disagrees with
    # the key must be rejected so a catalog can't list a spoofed/unresolvable id.
    payload = catalog_payload({"demo-bundle": catalog_entry_dict("other-id")})
    with pytest.raises(BundlerError, match="id mismatch"):
        load_catalog_payload(payload)


def test_load_payload_rejects_missing_entry_id():
    entry = catalog_entry_dict("demo-bundle")
    entry["id"] = ""
    payload = catalog_payload({"demo-bundle": entry})
    with pytest.raises(BundlerError, match="missing its 'id'"):
        load_catalog_payload(payload)


def test_catalog_entry_rejects_non_mapping_requires():
    from specify_cli.bundles.catalogs import CatalogEntry

    data = catalog_entry_dict("demo")
    data["requires"] = "speckit>=0.1"
    with pytest.raises(BundlerError, match="'requires' must be a mapping"):
        CatalogEntry.from_dict(data)


def test_catalog_entry_rejects_non_mapping_provides():
    from specify_cli.bundles.catalogs import CatalogEntry

    data = catalog_entry_dict("demo")
    data["provides"] = "extensions"
    with pytest.raises(BundlerError, match="'provides' must be a mapping"):
        CatalogEntry.from_dict(data)


def test_load_payload_rejects_unsupported_schema_version():
    payload = catalog_payload({"demo": catalog_entry_dict("demo")})
    payload["schema_version"] = "2.0"

    with pytest.raises(BundlerError, match="Unsupported catalog schema version"):
        load_catalog_payload(payload)


def test_load_payload_accepts_matching_or_absent_schema_version():
    payload = catalog_payload({"demo": catalog_entry_dict("demo")})
    payload["schema_version"] = "1.5"
    assert "demo" in load_catalog_payload(payload)

    payload.pop("schema_version")
    assert "demo" in load_catalog_payload(payload)


@pytest.mark.parametrize("field", ["requires", "provides"])
@pytest.mark.parametrize("bad", [[], "", 0, False])
def test_catalog_entry_rejects_falsy_non_mapping(field, bad):
    # `or {}` coerced a FALSY non-mapping ([], '', 0, False) to {} before the
    # isinstance guard, silently accepting a corrupt entry; only absent/None
    # means "not present". Mirrors the manifest requires/provides guard.
    from specify_cli.bundles.catalogs import CatalogEntry

    data = catalog_entry_dict("demo")
    data[field] = bad
    with pytest.raises(BundlerError, match=f"'{field}' must be a mapping"):
        CatalogEntry.from_dict(data)


def test_catalog_entry_explicit_null_id_reports_missing_id():
    """`id: null` must surface as the missing-id error, not an id mismatch.

    `entry_id` was still computed with `str(data.get("id", ""))`, so an explicit
    null became the literal "None". That is truthy, so `load_catalog_payload`
    compared it against the mapping key and reported
    "id mismatch: key 'demo' != entry id 'None'" instead of the accurate
    missing-id error.
    """
    from specify_cli.bundles.catalogs import CatalogEntry

    data = catalog_entry_dict("demo")
    data["id"] = None
    assert CatalogEntry.from_dict(data).id == ""

    with pytest.raises(BundlerError, match="missing its 'id' field"):
        load_catalog_payload(catalog_payload({"demo": data}))


def test_catalog_entry_explicit_null_requires_speckit_version_reads_as_empty():
    """The nested `requires.speckit_version` branch is covered too.

    It was switched to `_text` alongside the top-level fields, but only the
    top-level attributes were exercised β€” so this branch could regress while
    the suite still passed.
    """
    from specify_cli.bundles.catalogs import CatalogEntry

    data = catalog_entry_dict("demo")
    data["requires"] = {"speckit_version": None}

    assert CatalogEntry.from_dict(data).requires_speckit_version == ""