fix: resolve awaited Worker path helpers and return unions

[proggeramlug]

OpenCode's TUI computes its worker filename with const file = await target(), where target is async and contains several if/return branches. Perry rejected both the await and the helper body, leaving the Worker constructor as a runtime throw. Module discovery and codegen also required exactly one filename.

Follow awaits and collect the union of return paths from sync/async helpers with const path bindings and if/return bodies. Conditions are inspected for direct mutation but never evaluated; opaque awaited probes are allowed. Returned opaque calls, unsupported statements, generators, recursion, URL coercion, and expansion limits remain guarded.

Skip missing candidates with a warning, deduplicate worker entries by canonical file, and dispatch multiple candidates using the runtime string or URL filename. A missing selection throws instead of starting another candidate. Eval-source Worker behavior is unchanged.

Validation (Linux lane only):

• cargo test -p perry-hir: 663 passed, 3 ignored.
• Release compiler, runtime/stdlib static archives, and perry-ext-net built together successfully.
• cargo test --release -p perry with the new Worker path helper: resolve await helper() and if/return helper bodies (OpenCode TUI worker: const file = await target(); new Worker(file)) #10236 regression and the five existing worker-related test targets: 23 passed, 1 pre-existing cluster test ignored. Covers both runtime choices, URL filenames with spaces, absent candidates, opaque returns, and recursion.
• cargo fmt --all -- --check, scripts/check_file_size.sh, and Node version consistency check passed.
• Actual OpenCode src/cli/cmd/tui.ts, from the package directory with its perry.json, using --platform bun --no-link --no-cache:

Worker entry: /root/claude-opencode/opencode/packages/opencode/src/cli/tui/worker.ts
Warning: worker_threads Worker in module tui.ts: skipping candidate "./cli/tui/worker.js": file not found

The unsupported-expression warning is gone. This check was intentionally stopped after worker discovery; the full OpenCode graph compile remains with the coordinator.

Refs #10107.

Fixes #10236

Summary by CodeRabbit

• New Features

  • Worker paths can now be resolved through awaited or asynchronous helpers, conditional return chains, and multiple candidate paths.
  • Workers dynamically select among existing compiled entries at runtime, while missing candidates are skipped or reported with clear errors.
  • URL-based worker paths and distribution-layout fallbacks are handled consistently.

• Bug Fixes

  • Prevented incorrect worker compilation when only partial candidate paths resolve.
  • Preserved validation, safety checks, and candidate/work limits for complex helpers.

• Tests

  • Added coverage for awaited helpers, conditional returns, missing candidates, runtime selection, URL paths, and invalid helper patterns.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 41873740-4042-4d88-9f62-dcdebf689c91

📥 Commits

Reviewing files that changed from the base of the PR and between d8bfa28 and a5ca9ee.

📒 Files selected for processing (9)

• changelog.d/10236-worker-path-await-helper.md
• crates/perry-codegen/src/expr/dyn_extern_i18n.rs
• crates/perry-codegen/src/expr/worker_new.rs
• crates/perry-hir/src/dynamic_import/worker_paths.rs
• crates/perry-hir/src/dynamic_import/worker_paths/tests.rs
• crates/perry/src/commands/compile/collect_modules.rs
• crates/perry/src/commands/compile/collect_modules/worker.rs
• crates/perry/src/commands/compile/run_pipeline.rs
• crates/perry/tests/issue_10236_worker_path_await_helper.rs

Included review availability: Your plan provides up to 8 included reviews per hour; 4 remain after this review.

---

📝 Walkthrough

Walkthrough

Worker path discovery now supports awaited sync and async helpers, conditional return unions, missing-candidate skipping, and runtime filename dispatch. Compilation preserves URL and path aliases, while runtime construction throws when no compiled candidate matches.

Changes

Worker path resolution

Layer / File(s)	Summary
Helper analysis and validation crates/perry-hir/src/dynamic_import/worker_paths.rs, crates/perry-hir/src/dynamic_import/worker_paths/tests.rs	Awaited expressions and async helpers are supported. Conditional returns produce bounded path unions. Generator helpers, mutations, opaque returned calls, fall-through paths, and expansion-limit violations remain rejected.
Compile-time candidate resolution crates/perry/src/commands/compile/collect_modules.rs, crates/perry/src/commands/compile/collect_modules/worker.rs, crates/perry/src/commands/compile/run_pipeline.rs	Non-eval workers resolve candidate paths, skip missing files with warnings, deduplicate resolved entries, and preserve URL spellings for dynamic imports.
Runtime candidate dispatch crates/perry-codegen/src/expr/dyn_extern_i18n.rs, crates/perry-codegen/src/expr/worker_new.rs	Multiple worker candidates compile into filename-based dispatch. URLs are normalized before comparison. An unmatched runtime filename throws an error.
Integration validation and changelog crates/perry/tests/issue_10236_worker_path_await_helper.rs, changelog.d/10236-worker-path-await-helper.md	Integration tests cover awaited helpers, conditional returns, missing candidates, runtime selection errors, and preserved warnings. The changelog documents the behavior.

Priority: ⬆️ High

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix · Severity of issue fixed: High

Sequence Diagram(s)

sequenceDiagram
  participant WorkerPathHelper
  participant collect_modules
  participant resolve_candidates
  participant lower_candidates
  participant WorkerRuntime
  WorkerPathHelper->>collect_modules: return awaited and conditional path candidates
  collect_modules->>resolve_candidates: resolve candidate files
  resolve_candidates-->>collect_modules: compiled entries and skipped missing candidates
  collect_modules->>lower_candidates: lower multiple worker paths
  lower_candidates->>WorkerRuntime: dispatch by normalized runtime filename
  WorkerRuntime-->>lower_candidates: matched worker or runtime error

Loading

Merge Risk: ⚪ Minimal · up to a5ca9

The worker-path changes and their cross-layer behavior are covered without a concrete merge-blocking issue.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 47.83% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 8 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main changes: support for awaited Worker path helpers and unions of returned paths.
Description check	✅ Passed	The description provides a clear summary, detailed changes, related issues, test results, validation commands, and runtime output. It does not reproduce the template headings or checklist, but it cont…
Linked Issues check	✅ Passed	The changes satisfy the coding requirements in [#10236]. Expr::Await now resolves its operand. Sync and async helpers now support const bindings, if branches, and multiple returns, and they coll…
Out of Scope Changes check	✅ Passed	The changes stay within [#10236]. HIR resolution, compile-time worker discovery, code generation for multiple candidates, pipeline integration, tests, and the changelog directly support the linked wor…

Full details: Docstring Coverage

Explanation

Docstring coverage is 47.83% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 8 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[proggeramlug]

Landed via merge train 186r (#10247) at eb13fa1 on main.