fix(workflows): report a falsy non-mapping overlay manifest as a shape error

[jawwad-ali]

Problem

ProjectOverlaySource.collect in src/specify_cli/workflows/overlays/layer_sources.py reads an overlay manifest with:

data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}

validate_overlay_yaml opens with if not isinstance(data, dict): return None, ["Overlay manifest must be a mapping."] — so a wrong-shaped manifest is meant to be reported as exactly that. But or {} replaces every falsy non-mapping with an empty mapping before that check runs, so those files are misreported.

Reproduction on current main (81bf741)

Whole-document overlay manifests, same code path:

'- a'    -> ['Overlay manifest must be a mapping.']          <-- correct
'hello'  -> ['Overlay manifest must be a mapping.']          <-- correct
'[]'     -> ["Overlay 'id' is required and must be a non-empty string.",
             "Overlay 'extends' is required and must be a non-empty string.",
             "Overlay 'edits' is required and must be a list."]
'false'  -> same three
'0'      -> same three
"''"     -> same three

So [], false, 0 and '' produce three misleading "required field" errors, sending the author looking for missing keys in a document that has the wrong shape entirely. Their truthy twins get the right answer.

Precedent

The sibling reader for these same files, in the same package — _read_overlay in overlays/_commands.py:160 — does not coerce:

data = yaml.safe_load(content)

So the two readers of one file format disagree, and the coercing one is the outlier.

Fix

Drop or {}; normalise only an empty document:

data = yaml.safe_load(path.read_text(encoding="utf-8"))
...
if data is None:
    data = {}

No breaking change. None (an empty file) still becomes {}, so a genuinely empty overlay still reports its missing fields — pinned by a second new test. Every mapping is unaffected. The only inputs whose behaviour changes are the four falsy non-mappings, which move from three wrong errors to one right one.

Verification

• Fail-before / pass-after: the four parametrized cases fail on unpatched src and pass with the fix — 8 failed → 4 failed, and those remaining 4 are Windows symlink-privilege tests that fail on clean main.
• Scoped regression over tests/workflows: failure set identical to the clean-main baseline captured on 81bf741 (10 pre-existing in scope).
• uvx ruff@0.15.0 check src tests → clean

New class sits next to the existing TestProjectOverlaySourceFileReadErrors, which covers the other failure modes of this same read.

---

Written with assistance from Claude Code. Bug found, reproduced, and verified by me on current main.

[Copilot]

Pull request overview

Fixes overlay validation so falsy non-mapping manifests report a shape error.

Changes:

• Removes broad falsy-value coercion.
• Preserves empty-document handling.
• Adds regression tests for falsy manifests.

Show a summary per file

File	Description
src/specify_cli/workflows/overlays/layer_sources.py	Narrows manifest normalization to None.
tests/workflows/test_overlay_layer_sources.py	Tests falsy manifests and empty documents.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Balanced