Generate CommonJS provider values and shrink deps.ts #229

New issue

Closed

opened 2026-06-02 13:35:10 +00:00 by steve · 0 comments

steve commented

2026-06-02 13:35:10 +00:00

Owner

Problem

Phase 10 of the original dual ESM/CJS loader plan called for shrinking
packages/workspace/src/lib/deps.ts to generated compatibility data and
explicit legacy overrides. The current resolver uses generated provider
metadata, but it still imports a large manual deps.ts object for actual
CommonJS provider values. That means adding or changing official plugin
dependencies can still require manual workspace dependency-map edits.

Goal

Move CommonJS provider value generation to a single catalogue/config source so
official plugin dependencies do not require expanding the manual deps.ts
object.

Scope

Generate CommonJS provider values from the same host-module catalogue or a
clearly documented adjacent config used by pnpm plugin-host:check.
Keep explicit legacy overrides available for deprecated/private compatibility
cases.
Update the workspace dependency resolver to consume the generated provider
values and legacy overrides without depending on a broad manual deps.ts
map.
Update package/spec documentation to describe the new source of truth and
transition behavior.

Non-goals

Removing compatibility for currently installed or historical plugins that
still rely on supported CommonJS host modules.
Changing the public host-module names exposed to plugins.
Replacing the broader plugin runtime dependency resolver architecture.

Acceptance Criteria

packages/workspace/src/lib/deps.ts no longer contains the large manual list
of official CommonJS dependency imports.
Adding a stable official host module requires updating one catalogue/config
source and regenerating derived provider artifacts, not hand-editing
workspace dependency maps.
Legacy/deprecated/private CommonJS overrides remain explicit and easy to
audit.
pnpm plugin-host:check validates the generated provider metadata and the
generated provider values stay in sync.
Tests cover resolver behavior for generated official providers and explicit
legacy overrides.
The plugin runtime spec reflects that generated provider values, not manual
deps.ts, are the current source of truth.

Implementation Notes

Inspect packages/workspace/src/lib/plugin-runtime/workspace-plugin-dependency-resolver.ts
and the generated provider metadata before deciding where generated value
artifacts should live.
Prefer preserving existing resolver APIs while changing their source data.
If generation output changes, make sure workspace package validation includes
a stale-generation failure path.

Suggested Files or Specs To Inspect

spec/src/30-cross-package-contracts/plugin-runtime.md
packages/workspace/src/lib/deps.ts
packages/workspace/src/lib/plugin-runtime/workspace-plugin-dependency-resolver.ts
packages/workspace/src/lib/plugin-runtime/generated-plugin-commonjs-providers.ts
Host-module catalogue and generation scripts used by pnpm plugin-host:check
packages/api/src/lib/plugin-distribution/runtime-validation.ts

Validation Commands

pnpm plugin-host:check
pnpm --filter @lapis-notes/workspace check:all
pnpm --filter @lapis-notes/api check:all
make spec-lint
mdbook build spec

Follow-up to #215 — [loader] Replace renderer CommonJS dependency handling with catalogue resolver

Follow-up Tasks

Implementation Summary

Generated CommonJS provider values from the host-module catalogue, shrank deps.ts to explicit legacy/private overrides and browser fallbacks, updated the workspace resolver and generator checks, and added resolver/spec coverage.

## Problem Phase 10 of the original dual ESM/CJS loader plan called for shrinking `packages/workspace/src/lib/deps.ts` to generated compatibility data and explicit legacy overrides. The current resolver uses generated provider metadata, but it still imports a large manual `deps.ts` object for actual CommonJS provider values. That means adding or changing official plugin dependencies can still require manual workspace dependency-map edits. ## Goal Move CommonJS provider value generation to a single catalogue/config source so official plugin dependencies do not require expanding the manual `deps.ts` object. ## Scope - Generate CommonJS provider values from the same host-module catalogue or a clearly documented adjacent config used by `pnpm plugin-host:check`. - Keep explicit legacy overrides available for deprecated/private compatibility cases. - Update the workspace dependency resolver to consume the generated provider values and legacy overrides without depending on a broad manual `deps.ts` map. - Update package/spec documentation to describe the new source of truth and transition behavior. ## Non-goals - Removing compatibility for currently installed or historical plugins that still rely on supported CommonJS host modules. - Changing the public host-module names exposed to plugins. - Replacing the broader plugin runtime dependency resolver architecture. ## Acceptance Criteria - `packages/workspace/src/lib/deps.ts` no longer contains the large manual list of official CommonJS dependency imports. - Adding a stable official host module requires updating one catalogue/config source and regenerating derived provider artifacts, not hand-editing workspace dependency maps. - Legacy/deprecated/private CommonJS overrides remain explicit and easy to audit. - `pnpm plugin-host:check` validates the generated provider metadata and the generated provider values stay in sync. - Tests cover resolver behavior for generated official providers and explicit legacy overrides. - The plugin runtime spec reflects that generated provider values, not manual `deps.ts`, are the current source of truth. ## Implementation Notes - Inspect `packages/workspace/src/lib/plugin-runtime/workspace-plugin-dependency-resolver.ts` and the generated provider metadata before deciding where generated value artifacts should live. - Prefer preserving existing resolver APIs while changing their source data. - If generation output changes, make sure workspace package validation includes a stale-generation failure path. ## Suggested Files or Specs To Inspect - `spec/src/30-cross-package-contracts/plugin-runtime.md` - `packages/workspace/src/lib/deps.ts` - `packages/workspace/src/lib/plugin-runtime/workspace-plugin-dependency-resolver.ts` - `packages/workspace/src/lib/plugin-runtime/generated-plugin-commonjs-providers.ts` - Host-module catalogue and generation scripts used by `pnpm plugin-host:check` - `packages/api/src/lib/plugin-distribution/runtime-validation.ts` ## Validation Commands - `pnpm plugin-host:check` - `pnpm --filter @lapis-notes/workspace check:all` - `pnpm --filter @lapis-notes/api check:all` - `make spec-lint` - `mdbook build spec` ## Related Issues - Follow-up to #215 — [[loader] Replace renderer CommonJS dependency handling with catalogue resolver](../closed/215-loader-replace-renderer-commonjs-dependency-handling-with-catalogue-resolver.md) ## Follow-up Tasks ## Implementation Summary Generated CommonJS provider values from the host-module catalogue, shrank deps.ts to explicit legacy/private overrides and browser fallbacks, updated the workspace resolver and generator checks, and added resolver/spec coverage.

steve added this to the Dual ESM/CJS plugin loader milestone

2026-06-02 13:35:10 +00:00

steve

2026-06-02 13:35:10 +00:00