Skip to content

Stub registry + first-call runtime diagnostic for no-op stubs #464

@proggeramlug

Description

@proggeramlug

Spun out of #455 (DX feedback from @justin0mcateer); companion to #463.

Problem

Some symbols exist in Perry's runtime but are intentional no-ops — for example the harmonyos perry_ui_* / perry_system_* / perry_updater_* direct-call stubs added in #399 / #477 / #513, or the cross-platform UI symbols that are stubbed on the wrong host. Compile-time erroring on these is wrong (the call is intentional and the platform-specific build will resolve to a real impl), but silently doing nothing at runtime is the same DX cliff #455 describes — the program runs and produces wrong output with no signal.

Proposal

A stub-registry layer in the runtime:

  1. Manifest of stub symbols — assembled from direct_call_stubs in crates/perry-runtime/build.rs plus any other code paths that emit no-op fallbacks. Each entry knows the symbol name, the reason ("not implemented on macos build of harmonyos crate", etc.), and ideally a tracking issue.

  2. First-call diagnostic — wrap each stub so that the first invocation prints once to stderr:

    [perry] warning: `notificationSchedule` is a no-op stub on this platform
                     (harmonyos-only; tracking: #399)
    

    Subsequent calls stay silent (or are gated behind PERRY_STUB_DIAG=verbose for the every-call mode).

  3. perry check <entry.ts> subcommand — static scan of imports against the stub manifest. Surfaces the warnings before the user even runs the binary. Same machinery Compile-time error for unimplemented Node / Web APIs #463 uses for unimplemented-API resolution can power this.

Why a separate diagnostic from #463

#463 errors on symbols Perry doesn't have. This issue warns on symbols Perry has-but-stubs. Both flow from the same manifest infrastructure but target different audiences (compile-time hard fail vs. runtime soft warning).

Acceptance

  • Calling a stubbed symbol prints exactly one warning per symbol per process.
  • PERRY_STUB_DIAG=off silences; =verbose prints every call.
  • perry check app.ts reports the same warnings statically.
  • Stub manifest is derived from direct_call_stubs (no hand-maintenance).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesttoolingDeveloper tooling and CI

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions