Dependency version pinning behind VERYFRONT_DEPENDENCY_PINNING (Phase 0, #240)

[kojiwakayama]

Dependency version pinning (Phase 0 of veryfront/veryfront-issue-inbox#240)

Behind the new VERYFRONT_DEPENDENCY_PINNING env flag (default OFF; flag off is behavior-identical to current main).

• readProjectDependencyVersions exposes the full merged dependencies map only while pinning is enabled; flag-off reads retain the previous react/veryfront-only cache shape.
• Bare-import URL construction in the browser BareStrategy, SSR adapter, and dev-server esbuild plugin resolves versions in order: inline specifier version → exact package.json pin → cached npm-registry result for an undeclared package → current unversioned fallback.
• The npm resolution client is non-blocking and per-project: an exact declaration is cached synchronously; a package with no project declaration resolves dist-tags.latest in the background; failures never fail or block a render.
• A non-exact project declaration (range, dist-tag, alias, workspace reference, and similar) is never coerced to registry latest, because that could violate the declared constraint. It retains the current fallback until the platform/API update path normalizes it to an exact pin. A declaration change also invalidates older cached and in-flight results.
• Browser resolution reports a newly resolved exact pin to POST /projects/:projectId/dependencies/resolve best-effort/async; 404 and transport failures are tolerated.

Semver policy for this renderer phase: exact package.json versions win as-is; truly undeclared packages may resolve to latest; non-exact declarations are not locally normalized. Max-satisfying range normalization remains the explicit follow-up decision in issue #240 rather than adding a semver engine to renderer core in this PR.

Part of the staged plan in veryfront/veryfront-issue-inbox#240. This establishes the flag-gated lookup and write-back path while preserving current behavior whenever a safe exact pin is unavailable.

Known flag-off deviations (reviewed, intentional)

Three behavior changes apply regardless of the flag state. They are deliberate correctness improvements, disclosed here because the guarantee above otherwise reads as absolute:

• SSR adapter import coverage: landed on main via Extend SSR import rewriter to cover side-effect and dynamic import forms #3175 and merged back — the SSR import-coverage hunks are no longer part of this diff; this branch's ssr-adapter delta is now pure pinning plumbing.
• React version validation: isValidReactVersion accepts the same exact-SemVer forms as dependency pinning (v prefix, prerelease, build metadata) instead of bare X.Y.Z. Previously-rejected exact versions no longer silently fall back to the default React version.
• Unversioned-import warning: hasVersionSpecifier uses the package-specifier parser, so dist-tags (@next, @beta) count as version specifiers and no longer trigger the reproducibility warning. Logging-only.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c4f98ccc04

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[Copilot]

Pull request overview

Adds an opt-in (default off) dependency version pinning mechanism for bare npm imports, aiming to make esm.sh URLs deterministic by resolving versions from project package.json and (best-effort) npm registry metadata, while preserving current behavior when the flag is disabled.

Changes:

• Introduces VERYFRONT_DEPENDENCY_PINNING flag and a new in-process npm registry client with per-project caching and non-blocking background resolution.
• Expands project dependency detection to cache the full merged dependencies map (for synchronous pin lookups during rewriting).
• Updates multiple import-rewrite surfaces (browser bare strategy, SSR adapter, dev esbuild plugin, http bundler) to optionally inject pinned versions, with new/updated tests.

Verification

• Not run here (no runtime available). Suggested next step:
  • deno test --no-check --allow-all src/transforms/esm/npm-registry-client.test.ts src/transforms/import-rewriter/strategies/bare-strategy.test.ts src/transforms/esm/http-bundler.test.ts

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/transforms/import-rewriter/strategies/bare-strategy.ts	Adds optional pin resolution for browser bare imports under the env flag.
src/transforms/import-rewriter/strategies/bare-strategy.test.ts	Adds regression + pinning ladder tests for the bare strategy.
src/transforms/import-rewriter/ssr-adapter.ts	Adds optional pin injection for SSR bare import rewrites when projectDir is provided.
src/transforms/esm/package-registry.ts	Extends dependency cache to store full dependency map and adds sync accessor for rewriters.
src/transforms/esm/npm-registry-client.ts	New npm registry client with caching, background fetch, and optional write-back POST.
src/transforms/esm/npm-registry-client.test.ts	Unit tests for env flag behavior, cache semantics, and mocked background resolution.
src/transforms/esm/http-bundler.ts	Adds optional pin injection for esm.sh URL construction via a callback.
src/transforms/esm/http-bundler.test.ts	Adds unit tests for the new bare-specifier URL builder.
src/server/handlers/dev/files/esbuild-plugins.ts	Injects pinned versions into dev bundling bare import rewrites when available.
src/release-assets/constants.ts	Adds the DEPENDENCY_PINNING_ENV_FLAG constant.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (5)

src/transforms/esm/http-bundler.ts:73

• buildBareSpecifierEsmUrl() injects a pin even when the specifier already includes an inline version or dist-tag (e.g. "pkg@4.17.21" or "pkg@next"), which breaks the stated priority order (inline specifier must win). Only inject a pin when the parsed specifier has no version component.

    const parsed = parseBarePackageSpecifier(path);
    // Only inject a pin when the specifier has no inline version specifier.
    // An inline version (including dist-tags like @next) must be preserved as-is.
    if (parsed && parsed.version === null) {
      const pinVersion = getPinVersion(parsed.packageName);

src/transforms/esm/http-bundler.test.ts:116

• buildBareSpecifierEsmUrl() has tests for pin injection, but no regression test asserting that inline versions and dist-tags are preserved (and not overridden by the pin callback). Adding this test would prevent reintroducing the override bug.

    it("injects pin version for a simple package name", () => {
      assertEquals(
        buildBareSpecifierEsmUrl("lodash", () => "4.17.21"),
        "https://esm.sh/lodash@4.17.21",
      );

src/transforms/import-rewriter/ssr-adapter.ts:133

• When VERYFRONT_DEPENDENCY_PINNING is enabled and there is no exact package.json pin, resolveBareImportPin returns undefined without scheduling an npm registry lookup. This prevents the cache from ever warming for SSR rewrites. Schedule a background resolution on cache miss so subsequent renders can use the resolved pin.

  // semver — never strip range prefixes to manufacture a pin.
  if (rawPin && isExactSemver(rawPin)) return rawPin;

  return getCachedNpmVersion(parsed.packageName, projectDir);
}

src/server/handlers/dev/files/esbuild-plugins.ts:325

• buildPinnedEsmUrl falls back to an unversioned esm.sh URL when both the package.json exact pin and the npm version cache are missing, but it does not schedule a registry lookup. Without scheduling, the npm cache stays cold and pinning never activates for range-based dependencies. Schedule scheduleNpmVersionResolution() on cache miss.

      const version = (rawPin && isExactSemver(rawPin))
        ? rawPin
        : getCachedNpmVersion(parsed.packageName, projectDir);
      if (version) {

src/transforms/esm/npm-registry-client.ts:67

• The scheduleNpmVersionResolution() JSDoc says it stores an exact version "after stripping range chars", but the implementation intentionally does not strip range prefixes (it only short-circuits when the raw hint is already an exact semver). Update the comment to match the actual policy.

 * - If rangeHint is an exact semver (after stripping range chars), it is stored
 *   directly without a network fetch and onResolved fires synchronously.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (4)

src/transforms/esm/npm-registry-client.ts:151

• This implementation always resolves to npm's dist-tags.latest and does not attempt max-satisfying selection for semver ranges. That differs from the PR description ("dist-tags.latest / max-satisfying for ranges"). Either update the description/semver policy or extend the client to resolve ranges against the published versions list.

      headers: { Accept: "application/vnd.npm.install-v1+json" },
      signal: controller.signal,
    });

src/transforms/import-rewriter/ssr-adapter.ts:133

• When pinning is enabled, this path only checks package.json exact pins and the in-process npm cache, but it never schedules a background npm resolution when the cache is cold. That means the SSR adapter will never hit the "npm-registry resolution client" step unless some other code path has already warmed the cache for the same project.

function resolveBareImportPin(bareSpecifier: string, projectDir: string): string | undefined {
  const parsed = parseBarePackageSpecifier(bareSpecifier);
  if (!parsed || parsed.version) return undefined; // already versioned inline

  const allDeps = getProjectDependenciesSync(projectDir);
  const rawPin = allDeps?.[parsed.packageName];
  // Only use the raw package.json value as a pin when it is already an exact
  // semver — never strip range prefixes to manufacture a pin.
  if (rawPin && isExactSemver(rawPin)) return rawPin;

  return getCachedNpmVersion(parsed.packageName, projectDir);
}

src/server/handlers/dev/files/esbuild-plugins.ts:325

• When pinning is enabled, this plugin only reads package.json exact pins and the in-process npm cache; it never schedules a background npm lookup when both are cold. As a result, the dev-server esbuild path will not actually trigger npm resolution on its own (it can only benefit from cache warmed elsewhere).

function buildPinnedEsmUrl(path: string, projectDir: string | undefined): string {
  if (isDependencyPinningEnabled() && projectDir) {
    const parsed = parseBarePackageSpecifier(path);
    if (parsed && !parsed.version) {
      const allDeps = getProjectDependenciesSync(projectDir);
      const rawPin = allDeps?.[parsed.packageName];
      // Only use the raw package.json value when it is already an exact semver —
      // never strip range prefixes to manufacture a pin.
      const version = (rawPin && isExactSemver(rawPin))
        ? rawPin
        : getCachedNpmVersion(parsed.packageName, projectDir);
      if (version) {

src/transforms/import-rewriter/strategies/bare-strategy.test.ts:305

• This comment refers to "strip" behavior, but the current strategy intentionally does not strip semver ranges; it simply ignores non-exact pins via isExactSemver(). Updating the comment will keep the test aligned with the actual policy.

      // Compound ranges like ">=1.0.0 <2.0.0" strip to "1.0.0 <2.0.0" which is
      // not a valid semver and would produce a malformed esm.sh URL. The strategy
      // must skip it and fall through to the npm registry cache instead.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (4)

src/transforms/esm/npm-registry-client.ts:76

• The scheduleNpmVersionResolution() JSDoc still says the exact-version short-circuit happens "after stripping range chars", but the implementation intentionally does not strip ranges anymore (it only short-circuits when the raw hint is already an exact semver). Update the doc to match the actual policy so callers/tests don’t rely on the old behavior.

/**
 * Schedule a non-blocking npm registry lookup for the package.
 *
 * - If rangeHint is an exact semver (after stripping range chars), it is stored
 *   directly without a network fetch and onResolved fires synchronously.
 * - Otherwise a background fetch is started. The result is stored in the cache
 *   and onResolved is called when it completes.

src/transforms/esm/npm-registry-client.ts:117

• scheduleNpmVersionResolution() ignores rangeHint when doing a network lookup (it always fetches dist-tags.latest). For package.json ranges (for example "^1.2.3") or dist-tags (for example "next"), this can pin a version that does not satisfy the project’s declared constraint, which conflicts with the PR description (max-satisfying / dist-tag resolution) and can introduce breaking upgrades behind the flag.

  const resolution: Promise<void> = fetchLatestNpmVersion(packageName)
    .then((version) => {
      if (version) {
        setCachedVersion(projectDir, packageName, version);
        onResolved?.(version, packageName, projectDir);
      }

src/transforms/import-rewriter/strategies/bare-strategy.test.ts:236

• afterEach() should await _pendingResolutions() before restoring fetch/clearing caches. Otherwise, background npm lookups triggered by rewrite() can still be in flight when teardown completes, leading to flaky leak-sanitizer failures.

    afterEach(() => {
      setEnv(DEPENDENCY_PINNING_ENV_FLAG, originalFlag ?? "");
      _clearNpmVersionCache();
      clearReactVersionCache();
      globalThis.fetch = originalFetch;
    });

src/transforms/import-rewriter/ssr-adapter.ts:133

• resolveBareImportPin() can return getCachedNpmVersion(), but this file never schedules a background resolution when the cache is cold. In this PR, scheduleNpmVersionResolution() is only called from the browser BareStrategy, so SSR-only flows will never warm the npm cache and will always fall back to unversioned esm.sh URLs even when pinning is enabled.

function resolveBareImportPin(bareSpecifier: string, projectDir: string): string | undefined {
  const parsed = parseBarePackageSpecifier(bareSpecifier);
  if (!parsed || parsed.version) return undefined; // already versioned inline

  const allDeps = getProjectDependenciesSync(projectDir);
  const rawPin = allDeps?.[parsed.packageName];
  // Only use the raw package.json value as a pin when it is already an exact
  // semver — never strip range prefixes to manufacture a pin.
  if (rawPin && isExactSemver(rawPin)) return rawPin;

  return getCachedNpmVersion(parsed.packageName, projectDir);
}

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/transforms/esm/npm-registry-client.ts:176

• fetchLatestNpmVersion() always returns dist-tags.latest and scheduleNpmVersionResolution() does not use rangeHint to select a max-satisfying version for semver ranges. This conflicts with the PR description's "dist-tags.latest / max-satisfying for ranges" behavior. Either update the description/policy to state that ranges currently resolve to latest, or extend the implementation to resolve max-satisfying for ranges (requires fetching versions and applying semver range matching).

    const data = await res.json() as { "dist-tags"?: Record<string, string> };
    const latest = data["dist-tags"]?.latest ?? null;
    if (latest) logger.debug("npm registry resolved version", { packageName, version: latest });
    return latest;

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/transforms/esm/npm-registry-client.ts:130

• scheduleNpmVersionResolution accepts a rangeHint, but it is never used for non-exact values: the code always calls fetchLatestNpmVersion(packageName) and caches dist-tags.latest. This can pin a version that does not satisfy a package.json range (or dist-tag), and it diverges from the PR description’s “max-satisfying for ranges” behavior.

  const resolution: Promise<void> = fetchLatestNpmVersion(packageName)
    .then((version) => {
      if (version) {
        setCachedVersion(projectDir, packageName, version);
        onResolved?.(version, packageName, projectDir);
      }

[kojiwakayama]

⚠️ Auto-merge disabled — holding for a correctness fix. Please do not approve-and-merge until the follow-up commit lands.

Pre-merge verification against a real on-disk package.json (not the _primeDependenciesCache test helper) found that pins are silently ignored for a class of projects.

Probe, flag ON, temp project with dependencies: { lodash: "4.17.20" }:

Config	getProjectDependenciesSync	Emitted URL
config = null	{"lodash":"4.17.20"}	https://esm.sh/lodash@4.17.20 ✅
config = {react:{version:"19.2.4"}}	undefined	https://esm.sh/lodash ❌

Root cause: getProjectDependenciesSync (package-registry.ts:125) is a pure lookup over dependencyVersionCache, which is populated only by the async readProjectDependencyVersions. In the render path that runs only as a side effect of resolveProjectReactVersion, which early-returns at step 1 (config.react.version) and step 2 (config.client.cdn.versions.react) without ever reading package.json. The same hazard exists at build-app-route-renderer.ts:124-125, where explicitReactVersion ?? await resolveProjectReactVersion(...) skips the call whenever an explicit version is passed down.

Impact: any project that sets react.version in veryfront.config.ts gets its declared pins ignored, and the background resolver then caches dist-tags.latest — so the user's explicit pin is actively replaced by latest. That is precisely the failure mode this PR exists to eliminate.

Fix in progress: make dependency-cache warm-up explicit and flag-gated at the transform/render entry points (a shared ensureProjectDependenciesLoaded(projectDir)), independent of how reactVersion was obtained, covering the app route renderer (both branches), module server + batch handlers, SSR adapter callers, and the dev esbuild plugin. Regression tests will use a real temp package.json and assert pinned output in all three configurations — deliberately not using _primeDependenciesCache, since that helper is what masked this.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[kojiwakayama]

Merge readiness audit

Readiness: 54/100
Verdict: Not ready
Reviewed head: 4b4e028

The branch has strong test evidence, every check on the current head is green, no review threads remain, and the earlier page-module snapshot gap was fixed in 5ebb383. The default-off rollout and explicit snapshot model reduce immediate production exposure.

The PR is still draft, changes 243 files with 21,965 insertions, and conflicts with current main in 12 files across the lockfile, build pipeline, cache keys, HTML injection, release assets, RSC hydration, and generated bundles. Resolve those conflicts deliberately and rerun the full suite on the integrated head. Before enabling the flag, repeat flag-off equivalence checks plus flag-on staging for browser, SSR, build, cache, and RSC paths. The size and conflict surface require fresh code-owner review after integration.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[kojiwakayama]

Exact-head readiness update for 045b1fd:

• Current main was integrated with a normal merge; all 12 conflicts were resolved deliberately.
• Local focused dependency, build, cache, HTML, SSR, RSC, browser, audit, typecheck, format, and diff checks passed.
• Exact-head GitHub CI is fully green, including unit, integration, RSC browser E2E, binary E2E, npm smoke, coverage, CodeQL, and dependency audit.
• All 24 review threads are resolved.
• Independent integration review recommends approval.
• The PR is open, non-draft, and mergeable. No auto-merge or queue action is configured.

@kwakayama Please review and approve this exact head when ready. The protected-branch approval is the only remaining merge gate.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.