[eas-cli][build-tools][steps] Validate local composite functions referenced from workflow hooks; extract the shared loader into steps

[sswrk]

Why

Workflow validation already checks local composite functions referenced from job steps, but hooks can also use uses: ./..... eas workflow:validate don't catch problems with composite functions in hooks.

This PR also includes an extraction of duplicated (eas-cli and build-tools) composite function loader to @expo/steps.

How

Validation of workflows in eas-cli now reads each job's hooks steps too, not just job.steps.

Removed a duplicate loader from eas-cli and build-tools, moved it to steps.

Test Plan

Added unit tests.

[linear-code]

ENG-22387

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.42%. Comparing base (94f473b) to head (da1ec6a).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4064      +/-   ##
==========================================
- Coverage   62.43%   62.42%   -0.00%     
==========================================
  Files        1009     1008       -1     
  Lines       45737    45712      -25     
  Branches     9622     9622              
==========================================
- Hits        28550    28530      -20     
+ Misses      15726    15721       -5     
  Partials     1461     1461              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sswrk]

Also, moving an open discussion from the previous eas-cli PR in the stack: #4064

[github-actions]

🤖 AI code review

Decision: Approve with comments

Overall PR risk: Medium. The change moves composite-function loading logic from eas-cli and build-tools into the shared @expo/steps package, and updates all call sites to new function names and option-object argument shapes. It also extends workflow validation to check job hooks, not just job steps. The affected surface is the composite-function resolution path used by build job runners and by eas workflow:validate, bounded but touched on every build that references local composite functions. One warning-level finding survived review: the new shared loader throws a bare Error instead of BuildConfigError, which causes StepsConfigParser to wrap an already-clear error message in a redundant, doubled message for the user. This is a message-quality regression, not a functional break, and the change is straightforward to revert if a problem appears.

🟡 Warning (1)

• Loader throws bare Error instead of BuildConfigError, breaking StepsConfigParser message handling — packages/steps/src/utils/localCompositeFunctions.ts:159 (quality) · id:17dbd9389c62
  Confidence: High — the trace through StepsConfigParser.ts shows the exact instanceof BuildConfigError branch this new code defeats.
  Impact if shipped: Medium — hook load failures for a missing or invalid composite function show a doubled, unclear error message instead of the clear message the code already built.
  Suggested remediation: Throw BuildConfigError (from ../errors) instead of bare Error in all four failure branches of loadLocalCompositeFunctionConfigAsync. This matches the pattern in this file and in CompositeFunctionExpander.ts.

  Evidence and reasoning

  Every other error in this file and package uses BuildConfigError for user config problems. Examples: parseLocalCompositeFunctionPath (line 28-31), collectLocalCompositeFunctionPathsFromSteps (line 188), and the near-identical "composite function does not exist" check in CompositeFunctionExpander.lookupCompositeFunction (packages/steps/src/CompositeFunctionExpander.ts:190-193).

  The new loadLocalCompositeFunctionConfigAsync throws plain Error for all four of its failure cases: read failure, YAML parse failure, zod validation failure, and "no such composite function exists".

  This is not just a style issue. StepsConfigParser.ts:305-324 calls this loader through extendCompositeFunctionCatalogFromStepsAsync. It checks err instanceof BuildConfigError. If true, it keeps the inner message as-is (line 314-317). If false, it wraps the message in a generic "Failed to load a local composite function referenced from ..." prefix (line 319-323). Because the new loader never throws BuildConfigError, every failure takes the generic-wrap branch. This includes the well-written "was referenced by a step but no such composite function exists" message. The user then sees a doubled message instead of the clean one already built.

---

This review is advisory — it never blocks a merge and never auto-approves.

[sswrk]

Re. AI review:

Validation skips jobs with a custom project root

That's a deliberate skip. Validating it would need injecting the vcs client. Will change it if human reviewers advise doing so

Invalid function config uses the wrong error type

Not specific to this PR, worth considering as a follow up

Path text can inject terminal control characters

not specific to this PR, a general pattern

Validation loads composites from ignored hooks

It does hold up, but it was deliberate: we can only do static verification here, so that's the only way we can check those functions within workflow:validate. Will change it if human reviewers advise doing so.

[github-actions]

Subscribed to pull request

File Patterns	Mentions
packages/eas-cli/**	@douglowder

Generated by CodeMention

Warning: The preamble and epilogue options in commentConfiguration are deprecated. Use template instead.

[hSATAC]

Left two comments.

[hSATAC]

Looking good. 👍

[github-actions]

✅ Thank you for adding the changelog entry!