fix: fail loudly when a fan-out 'items' expression does not resolve to a list

[doquanghuy]

Description

Fixes #2956.

FanOutStep.execute silently coerced any non-list items result to [], so a mis-wired or unresolvable items: expression produced a vacuous zero-instance run with no error anywhere near the cause. This PR makes the step fail loudly instead, with an error naming the expression and the resolved type. An explicit empty list remains valid input (legitimately-empty data still completes with item_count: 0).

The previous behavior was pinned by test_execute_non_list_items_resolves_empty; that test is updated to the fail-loud contract, and a new test_execute_empty_list_items_is_valid locks the empty-list-stays-valid distinction. If silent-empty was intentional for some use case, happy to rework this as an opt-in knob (allow_empty:/strict:) with fail-loud as default — see the issue for that alternative.

The failure output keeps the step's four output keys (items/max_concurrency/step_template/item_count) so downstream readers of a failed run's state don't hit missing keys.

Testing

• Ran existing tests with uv sync && uv run pytest — 208 passed (the new non-list test fails red against current main, passes with the fix; verified both directions)
• uvx ruff check src/ — clean
• Tested locally with uv run specify --help
• Tested with a sample project (covered by the unit tests above; the repro workflow from [Bug]: fan-out silently coerces a non-list 'items' to [] — zero-instance runs with no error #2956 now fails at the fan-out step with the new error)

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

Code, tests, and this description were authored with AI assistance (Claude), driven by a real-pipeline failure investigation; everything was verified by running the repo's test suite and ruff locally in both red (unfixed) and green (fixed) directions.

[doquanghuy]

@mnriem when you have a moment, would appreciate a review — happy to adjust anything.

[Copilot]

✅ Ready to approve

The change is narrowly scoped, improves correctness and debuggability, and is covered by updated and new unit tests.

Note: this review does not count toward required approvals for merging.

Pull request overview

This PR updates the workflow engine’s fan-out step to fail with a clear error when the configured items: expression does not evaluate to a list, preventing silent “zero-instance” runs caused by miswired templates (Fixes #2956).

Changes:

• Make FanOutStep.execute() return FAILED with an informative error when items resolves to a non-list, while still emitting the usual output keys.
• Update the existing unit test to assert the new fail-loud contract for non-list items values.
• Add a new unit test to ensure an explicitly empty list remains a valid items input and completes successfully with item_count: 0.

File summaries

File	Description
src/specify_cli/workflows/steps/fan_out/__init__.py	Fail-loud behavior for non-list items resolutions, preserving output shape on failure.
tests/test_workflows.py	Adjusts the prior test to expect failure and adds coverage for the empty-list valid case.

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 0

Note

Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.

---

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