feat(config): enum-as-shorthand backend resolution (#386 Phase 5)

[apotema]

Phase 5 — enum-as-shorthand backend resolution

Completes the Phase-5 resolver seam so a built-in .backend enum tag is a shorthand for a provider, not a hardwired bundled slot. This is the backward-compatibility hinge that lets a backend be extracted out-of-tree (Phase 6c) without breaking existing .backend = .bgfx projects (Flying Platform).

What it adds

• config.builtinProvider(Backend) ?PluginDep — the extraction table. Every built-in maps to null (bundled) today.
• config.effectiveBackendPackage() = backend_package orelse builtinProvider(backend) — the single place that composes an explicit external package with the enum-shorthand. backendName(), isExternal(), and backend_registry.resolveBackendPackage all route through it, so they can't disagree about whether a backend is external or which package it is.

Effect today: none (by design)

builtinProvider returns null for all six built-ins, so .backend = .<tag> resolves to the bundled backends/<tag> slot exactly as before — generated output is byte-identical (golden suites green).

What it unblocks

Extracting a backend (Phase 6c) becomes a one-line entry here:

.bgfx => .{ .name = "bgfx", .repo = "github.com/labelle-toolkit/labelle-bgfx", .version = "X.Y.Z" },

After that, .backend = .bgfx transparently fetches the provider package — isExternal() ⇒ true, so the manifest path + the #386 Phase-6b contract guard + self-contained staging all activate — with zero change to existing project configs.

Deferred to the actual extraction PR

The bgfx repo move itself, and handling the shared ../sdl_gamepad / ../android_gamepad sub-packages (bgfx/raylib/sokol share them in-tree; an external bgfx can't reference ../). That sub-package decision is the open item gating Phase 6c — intentionally not in this PR.

Tests

• Every built-in tag is still bundled (!isExternal(), no effective package, named by enum tag) — a behavior-preservation guard that flips visibly the moment a tag is extracted.
• An explicit backend_package still wins over the enum at the seam.
• Full zig build test green.

Summary by CodeRabbit

• New Features
  • Improved backend selection so an explicit backend package now takes priority when both a built-in backend and a package are configured.
  • Built-in backends continue to be treated as local by default, with backend naming aligned to the selected configuration.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 86f6a0fe-ac15-4563-b70c-8399d33dbc14

📥 Commits

Reviewing files that changed from the base of the PR and between 023bc16 and b26dbdf.

📒 Files selected for processing (2)

• src/backend_registry.zig
• src/config.zig

 ___________________________________________________________________________
< Your code and I are going to be best friends. Very critical best friends. >
 ---------------------------------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/386-enum-as-shorthand

---

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

[gemini-code-assist]

Code Review

This pull request introduces the "enum-as-shorthand" seam (Phase 5 of epic #386) to allow built-in backend enum tags to eventually resolve to external provider packages. It introduces builtinProvider and effectiveBackendPackage methods on ProjectConfig and updates backendName, isExternal, and resolveBackendPackage to use them. A critical issue was identified in src/config.zig where calling builtinProvider directly without qualifying it with the struct name ProjectConfig will cause a compile-time error in Zig.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

In Zig, struct-level namespace declarations (associated functions/static methods) are not automatically in scope as bare identifiers within the struct's methods. Calling builtinProvider(self.backend) directly will result in a compile-time error (use of undeclared identifier 'builtinProvider').\n\nTo fix this, qualify the call with the struct name: ProjectConfig.builtinProvider(self.backend).

    pub fn effectiveBackendPackage(self: ProjectConfig) ?PluginDep {\n        return self.backend_package orelse ProjectConfig.builtinProvider(self.backend);\n    }

[apotema]

This is a false positive. In Zig, declarations within a container (struct) are in scope as bare identifiers from that container's other declarations — builtinProvider is a decl of ProjectConfig, so a sibling method (effectiveBackendPackage) calls it by bare name without a ProjectConfig. qualifier. Evidence: this exact code compiles — zig build + zig build test are green locally and all five CI build/test jobs (build-and-test ubuntu+macos, bgfx macOS + Android, Examples integration) passed on this commit. A genuine use of undeclared identifier would have failed every one. Leaving as-is.