fix(bundler): correct load_yaml so only empty documents become {} (not falsy non-mappings)

Address review (Copilot re-review of #3659): the previous fix duplicated
YAML parsing + exception wrapping inline in two readers, bypassing the
centralized yamlio helper. Instead, correct the root cause in load_yaml.

load_yaml did `yaml.safe_load(...) or {}`, which coerced ANY falsy result
(None empty-doc, but also [], false, 0, '') to {} — contradicting its own
docstring ("{} for an empty document") and hiding malformed non-mapping
configs from callers' shape guards. Change to `{} if data is None else data`
so only an empty document becomes {}; a non-mapping top level is returned
as-parsed.

Revert the inline raw-parse in models/catalog._merge_config and
commands_impl/catalog_config._read back to the centralized load_yaml; their
existing `isinstance(data, dict)` guards now correctly reject falsy
non-mappings too. All three load_yaml callers (these two + manifest.from_dict)
already guard the top-level shape, so none regresses. Falsy-case tests for
both readers retained.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jawwad-ali

src/specify_cli/bundler/commands_impl/catalog_config.py

@@ -10,10 +10,8 @@
 from urllib.parse import urlparse
 import re
 
-import yaml
-
 from .. import BundlerError
-from ..lib.yamlio import dump_yaml, ensure_within
+from ..lib.yamlio import dump_yaml, ensure_within, load_yaml
 from ..models.catalog import (
     CONFIG_FILENAME,
     BUILTIN_DEFAULT_STACK,
@@ -42,17 +40,11 @@ def _read(project_root: Path) -> list[dict]:
     path = ensure_within(project_root, _config_path(project_root))
     if not path.exists():
         return []
-    # Parse the RAW document, not the shared ``load_yaml`` (whose ``… or {}``
-    # coerces a falsy top-level value to ``{}``): an empty document is a no-op,
-    # but a falsy non-mapping (``[]``/``false``/``0``/``''``) is malformed and
-    # must raise like a truthy one, staying consistent with the other reader of
-    # this file (models/catalog._merge_config).
-    try:
-        data = yaml.safe_load(path.read_text(encoding="utf-8"))
-    except yaml.YAMLError as exc:
-        raise BundlerError(f"Invalid YAML in {path}: {exc}") from exc
-    except OSError as exc:
-        raise BundlerError(f"Could not read {path}: {exc}") from exc
+    # ``load_yaml`` returns ``{}`` only for an empty document and the raw parse
+    # otherwise, so a falsy non-mapping (``[]``/``false``/``0``/``''``) is caught
+    # by the isinstance guard below and raised like a truthy one, staying
+    # consistent with the other reader of this file (models/catalog._merge_config).
+    data = load_yaml(path)
     if data is None:
         return []
     if not isinstance(data, dict):

src/specify_cli/bundler/lib/yamlio.py

@@ -39,17 +39,25 @@ def ensure_within(root: Path, candidate: Path) -> Path:
 
 
 def load_yaml(path: Path) -> Any:
-    """Parse a YAML file, returning ``{}`` for an empty document."""
+    """Parse a YAML file, returning ``{}`` for an empty document.
+
+    Only an *empty* document (``yaml.safe_load`` -> ``None``) becomes ``{}``.
+    A non-empty document is returned exactly as parsed — including a falsy
+    non-mapping such as ``[]``, ``false``, ``0``, or ``''`` — so callers can
+    validate the top-level shape (e.g. reject a non-mapping config) instead of
+    having it silently coerced to an empty mapping.
+    """
     path = Path(path)
     if not path.exists():
         raise BundlerError(f"File not found: {path}")
     try:
         with path.open("r", encoding="utf-8") as handle:
-            return yaml.safe_load(handle) or {}
+            data = yaml.safe_load(handle)
     except yaml.YAMLError as exc:
         raise BundlerError(f"Invalid YAML in {path}: {exc}") from exc
     except OSError as exc:
         raise BundlerError(f"Could not read {path}: {exc}") from exc
+    return {} if data is None else data
 
 
 def dump_yaml(path: Path, data: Any, *, within: Path | None = None) -> Path:

src/specify_cli/bundler/models/catalog.py

@@ -11,10 +11,8 @@
 from pathlib import Path
 from typing import Any
 
-import yaml
-
 from .. import BundlerError
-from ..lib.yamlio import ensure_within
+from ..lib.yamlio import ensure_within, load_yaml
 
 CONFIG_FILENAME = "bundle-catalogs.yml"
 
@@ -251,21 +249,12 @@ def load_source_stack(project_root: Path, user_config_dir: Path | None = None) -
 def _merge_config(by_id: dict[str, CatalogSource], config_path: Path, scope: Scope) -> None:
     if not config_path.exists():
         return
-    # Parse the RAW document rather than the shared ``load_yaml`` helper, whose
-    # ``… or {}`` coerces a falsy top-level value to ``{}``: an empty document
-    # (``None``) is a no-op, but every non-mapping top-level — including the
-    # falsy ones ``[]``/``false``/``0``/``''`` that ``load_yaml`` would hide —
-    # is malformed and must raise, matching the sibling reader
-    # commands_impl/catalog_config._read (which does the same). #3623 already
+    # ``load_yaml`` returns ``{}`` only for an empty document and the raw parse
+    # otherwise, so a non-mapping top level (a YAML list or scalar, including
+    # the falsy ``[]``/``false``/``0``/``''``) is caught here and raised —
+    # matching the sibling reader commands_impl/catalog_config._read. #3623
     # aligned the inner non-list ``catalogs`` value between the two readers.
-    try:
-        data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
-    except yaml.YAMLError as exc:
-        raise BundlerError(f"Invalid YAML in {config_path}: {exc}") from exc
-    except OSError as exc:
-        raise BundlerError(f"Could not read {config_path}: {exc}") from exc
-    if data is None:
-        return
+    data = load_yaml(config_path)
     if not isinstance(data, dict):
         raise BundlerError(
             f"Malformed catalog config at {config_path}: expected a mapping at "