fix: resolve local helper chains for Worker entry URLs

[proggeramlug]

Bun standalone bundles commonly put a Worker entry URL behind small local helper functions. Collection ran before inlining, left those calls unresolved, and emitted a constructor that threw instead of starting the worker. Resolve bounded helper chains while collecting Worker entries, then decode static file URLs before normal file lookup and --bunfs-root mapping. The original filename expression still executes at construction.

The Worker-only resolver supports function declarations, const closures/aliases, concise arrows and single-return bodies with exact simple string/URL arguments. It reuses the existing static path operations and registry convention, distinguishes URL carriers from strings, rejects reassigned bindings/effectful bodies/opaque calls/recursion, and bounds candidates, depth, work and path length. Dynamic imports and eval-mode Worker source resolution keep their existing behavior; each Worker must still resolve to one entry. The supported subset and limits are documented.

Validation:

• Original Bun repro: compiled, embedded the worker source, and printed ready.
• HIR unit suite: 391 passed, 1 ignored, including source-level positive/negative helper cases and resolution limits.
• New executable integration suite: 3/3 passed (Bun embedded URL, Node helper chain, percent-encoded file URL).
• Node Worker parity fixture: 1/1 passed; existing Worker integration suite: 3/3 passed.
• Quick pre-tag checks, formatting, file-size and test-registration checks passed. Documentation lint: passed.
• Canonical affected-crate run: runtime 3137 passed, 4 ignored; compiler 1083 passed and the existing PERRY_CONCAT_SITE_CACHE registry test failed. That baseline failure is fixed separately by fix(cache): register concat switch and explain codegen inputs #9748.

Fixes #9744. No version bump.

Summary by CodeRabbit

• Bug Fixes

  • Fixed Worker entry-point discovery when paths are generated through supported local helper functions.
  • Improved compatibility with Bun embedded file URLs and Node.js worker constructors.
  • Correctly handles static file: URLs, including paths containing spaces.
  • Provides clearer diagnostics for unsupported, recursive, mutable, or overly complex helper expressions.

• Documentation

  • Documented supported Worker path helper patterns, resolution limits, and runtime behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 23457342-068d-419d-b16c-7be5f2b287ee

📥 Commits

Reviewing files that changed from the base of the PR and between 12efed1 and e3d0a93.

📒 Files selected for processing (10)

• changelog.d/9759-static-worker-url-helpers.md
• crates/perry-hir/src/dynamic_import.rs
• crates/perry-hir/src/dynamic_import/worker_paths.rs
• crates/perry-hir/src/dynamic_import/worker_paths/tests.rs
• crates/perry-hir/src/lib.rs
• crates/perry/src/commands/compile/collect_modules.rs
• crates/perry/tests/issue_9744_static_worker_helpers.rs
• docs/src/stdlib/other.md
• test-files/_helpers/static_worker_9744.ts
• test-files/test_gap_9744_static_worker_helpers.ts

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

---

📝 Walkthrough

Walkthrough

This change resolves bounded module-local helper chains used as Worker entry URLs. It integrates static helper evaluation into Worker collection, decodes valid file: URLs, and adds compiler, runtime, documentation, and changelog coverage.

Changes

Worker URL resolution

Layer / File(s)	Summary
Bounded helper interpreter crates/perry-hir/src/dynamic_import/..., crates/perry-hir/src/lib.rs	Adds resolve_worker_path and a bounded interpreter for static strings, URLs, path operations, registries, aliases, and helper calls. It rejects effects, mutation, recursion, opaque calls, unsupported selectors, URL coercion, and limit violations. Tests cover successful resolution, diagnostics, and all resolution limits.
Worker collection integration crates/perry/src/commands/compile/collect_modules.rs	Uses helper resolution for non-eval Workers. It decodes resolved file: URLs before recording import edges and worker paths, and reports invalid URLs.
Runtime validation and documentation crates/perry/tests/issue_9744_static_worker_helpers.rs, test-files/..., docs/src/stdlib/other.md, changelog.d/...	Adds Bun and Node integration tests, worker fixtures, documentation for the supported helper subset and limits, and a changelog entry.

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

Merge Risk: ⚪ Minimal · up to e3d0a

The Worker helper-resolution change is bounded and covered across compiler and runtime paths, with no concrete issue blocking merge.

Sequence Diagram(s)

sequenceDiagram
  participant WorkerCollector
  participant resolve_worker_path
  participant WorkerPaths
  participant HIRModule
  WorkerCollector->>resolve_worker_path: resolve Worker filename
  resolve_worker_path->>WorkerPaths: evaluate helper chain
  WorkerPaths->>HIRModule: inspect bindings and helper bodies
  HIRModule-->>WorkerPaths: return static path candidates
  WorkerPaths-->>resolve_worker_path: return Resolution
  resolve_worker_path-->>WorkerCollector: provide Worker path

Loading

sequenceDiagram
  participant collect_modules
  participant resolve_worker_path
  participant Url
  participant WorkerGraph
  collect_modules->>resolve_worker_path: resolve non-eval Worker filename
  resolve_worker_path-->>collect_modules: return path or file URL
  collect_modules->>Url: parse and decode file URL
  Url-->>collect_modules: return filesystem path
  collect_modules->>WorkerGraph: record import edge and Worker path

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 45.16% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 31 functions across 8 files. (2 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 and concisely describes the main change: resolving local helper chains for Worker entry URLs.
Description check	✅ Passed	The description explains the change, scope, linked issue, implementation behavior, testing, documentation, and known baseline failure. It omits the template headings and checklist, but the required in…
Linked Issues check	✅ Passed	The changes satisfy issue #9744. They resolve bounded module-local helper chains, support concise arrows and single-return functions, enforce safety limits, reject unsafe cases, decode static file URL…
Out of Scope Changes check	✅ Passed	The code, tests, documentation, changelog entry, and fixtures directly support Worker helper resolution and its regression coverage. No unrelated implementation changes are evident.

Full details: Docstring Coverage

Explanation

Docstring coverage is 45.16% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 31 functions across 8 files. (2 skipped: 2 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 on main via merge train #9798 (rebase-merged, so your commits keep their authorship). Thanks!