chore(release): align next with beta.23 release

[elrrrrrrr]

What

Bring the branch that was used to publish v4.1.2-beta.23 back into next so the source baseline matches the npm beta release.

This includes:

• the beta.21, beta.22, and beta.23 release version commits
• the tegg vitest module-importer setup change used by the published beta
• the dal transaction hook guard used by the published beta

Why

The successful manual release run checked out codex/release-beta22-module-importer even though the Actions run page shows headBranch=next. As a result, npm beta packages advanced to 4.1.2-beta.23, but next stayed behind at 4.1.2-beta.20.

Merging this PR first realigns next with the already-published beta line before any further beta release is cut.

Validation

• Confirmed v4.1.2-beta.23 points at origin/codex/release-beta22-module-importer
• Confirmed Git can auto-merge origin/next with origin/codex/release-beta22-module-importer using git merge-tree --write-tree

Summary by CodeRabbit

• New Features

  • Added Vitest setup support for dynamic module loading and automatic test initialization.
  • Exposed the new Vitest setup entry for easier test configuration.

• Bug Fixes

  • Improved transaction hook handling when no data source is configured.
  • Prevented unnecessary transaction setup in unsupported configurations.

• Chores

  • Published updated beta releases across the project’s packages and tools, advancing versions to the latest beta iteration.

[coderabbitai]

📝 Walkthrough

Walkthrough

Package manifests are updated to beta.23, with egg-bundler moving to beta.13. Vitest adds an exported setup module and global ESM/CommonJS importer, egg-bin injects that setup when applicable, and DAL transaction setup skips modules without configured data sources.

Changes

Release metadata and runtime behavior

Layer / File(s)	Summary
Package version bumps package.json, packages/*/package.json, plugins/*/package.json, tegg/*/package.json, tools/*/package.json	Package versions are advanced across the monorepo, including beta.23 releases and the egg-bundler beta.13 release.
Vitest module importer tegg/core/vitest/package.json, tegg/core/vitest/src/setup.ts, tegg/core/vitest/vitest.config.ts, tegg/core/vitest/test/fixture_app.test.ts, tools/egg-bin/src/commands/test.ts	Vitest exposes and loads a setup module that classifies files as ESM or CommonJS, provides globalThis.__EGG_MODULE_IMPORTER__, and is injected by egg-bin when the tegg runner is available.
DAL transaction datasource guard tegg/plugin/dal/src/lib/TransactionPrototypeHook.ts, tegg/plugin/dal/test/TransactionPrototypeHook.test.ts	preCreate precomputes data sources, returns early when none exist, and tests empty or missing datasource configurations.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• Use monorepo start from v4 #5434 — The PR updates package versions across the monorepo, matching the issue’s package consolidation and migration scope.

Possibly related PRs

• eggjs/egg#5830: Both changes modify egg-bin’s Vitest runner and setup-file resolution logic.
• eggjs/egg#5989: Both changes use the __EGG_MODULE_IMPORTER__ module-loading hook.
• eggjs/egg#5992: The related module-loading utility consumes the importer hook introduced here.

Suggested labels: chore: gitAction

Suggested reviewers: fengmk2, killagu, jerryliang64, akitaSummer

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: merging release work to align next with the beta.23 release.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/release-beta22-module-importer

---

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.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.18%. Comparing base (3ddbbe4) to head (86ae141).
⚠️ Report is 2 commits behind head on next.

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #6032      +/-   ##
==========================================
+ Coverage   81.98%   82.18%   +0.19%     
==========================================
  Files         678      678              
  Lines       20838    20844       +6     
  Branches     4154     4156       +2     
==========================================
+ Hits        17085    17130      +45     
+ Misses       3235     3206      -29     
+ Partials      518      508      -10     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[elrrrrrrr]

Superseded by #6033 because beta.24 was published from codex/release-beta24-patchless after this PR was opened.

[Copilot]

Pull request overview

Realigns next branch source with the already-published v4.1.2-beta.23 beta line by bringing in the intervening beta version bumps plus the specific tegg vitest module-importer setup and DAL transaction hook guard shipped in that beta.

Changes:

• Bump monorepo + package versions from *-beta.20 to *-beta.23 (and related tool betas).
• Auto-inject @eggjs/tegg-vitest/setup into egg-bin test runs when the tegg vitest runner is detected; add a tegg-vitest setup module and wire it into tegg vitest config.
• Guard DAL transaction hook when a module has no/empty dataSource config and add regression tests for that behavior.

Reviewed changes

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

Show a summary per file

File	Description
tools/scripts/package.json	Version bump to match beta.23 line.
tools/egg-bundler/package.json	Version bump (beta.10 → beta.13).
tools/egg-bin/src/commands/test.ts	Auto-add tegg vitest setup when tegg runner is resolvable.
tools/egg-bin/package.json	Version bump to beta.23 line.
tools/create-egg/package.json	Version bump to beta.23 line.
tegg/standalone/standalone/package.json	Version bump to beta.23 line.
tegg/plugin/tegg/package.json	Version bump to beta.23 line.
tegg/plugin/schedule/package.json	Version bump to beta.23 line.
tegg/plugin/orm/package.json	Version bump to beta.23 line.
tegg/plugin/mcp-proxy/package.json	Version bump to beta.23 line.
tegg/plugin/mcp-client/package.json	Version bump to beta.23 line.
tegg/plugin/langchain/package.json	Version bump to beta.23 line.
tegg/plugin/eventbus/package.json	Version bump to beta.23 line.
tegg/plugin/dns-cache/package.json	Version bump to beta.23 line.
tegg/plugin/dal/test/TransactionPrototypeHook.test.ts	New regression tests for “skip when no/empty dataSource config”.
tegg/plugin/dal/src/lib/TransactionPrototypeHook.ts	Skip transaction hook when module has no configured dataSources.
tegg/plugin/dal/package.json	Version bump to beta.23 line.
tegg/plugin/controller/package.json	Version bump to beta.23 line.
tegg/plugin/config/package.json	Version bump to beta.23 line.
tegg/plugin/common/package.json	Version bump to beta.23 line.
tegg/plugin/aop/package.json	Version bump to beta.23 line.
tegg/plugin/ajv/package.json	Version bump to beta.23 line.
tegg/core/vitest/vitest.config.ts	Register new tegg-vitest setup file before existing test setup.
tegg/core/vitest/test/fixture_app.test.ts	Add assertion that __EGG_MODULE_IMPORTER__ resolves the same module instance.
tegg/core/vitest/src/setup.ts	New module-importer setup that switches between import() and require() based on ESM/CJS.
tegg/core/vitest/package.json	Version bump and export new ./setup entry.
tegg/core/types/package.json	Version bump to beta.23 line.
tegg/core/transaction-decorator/package.json	Version bump to beta.23 line.
tegg/core/tegg/package.json	Version bump to beta.23 line.
tegg/core/standalone-decorator/package.json	Version bump to beta.23 line.
tegg/core/schedule-decorator/package.json	Version bump to beta.23 line.
tegg/core/runtime/package.json	Version bump to beta.23 line.
tegg/core/orm-decorator/package.json	Version bump to beta.23 line.
tegg/core/metadata/package.json	Version bump to beta.23 line.
tegg/core/mcp-client/package.json	Version bump to beta.23 line.
tegg/core/loader/package.json	Version bump to beta.23 line.
tegg/core/lifecycle/package.json	Version bump to beta.23 line.
tegg/core/langchain-decorator/package.json	Version bump to beta.23 line.
tegg/core/eventbus-runtime/package.json	Version bump to beta.23 line.
tegg/core/eventbus-decorator/package.json	Version bump to beta.23 line.
tegg/core/dynamic-inject/package.json	Version bump to beta.23 line.
tegg/core/dynamic-inject-runtime/package.json	Version bump to beta.23 line.
tegg/core/dal-runtime/package.json	Version bump to beta.23 line.
tegg/core/dal-decorator/package.json	Version bump to beta.23 line.
tegg/core/core-decorator/package.json	Version bump to beta.23 line.
tegg/core/controller-decorator/package.json	Version bump to beta.23 line.
tegg/core/common-util/package.json	Version bump to beta.23 line.
tegg/core/background-task/package.json	Version bump to beta.23 line.
tegg/core/aop-runtime/package.json	Version bump to beta.23 line.
tegg/core/aop-decorator/package.json	Version bump to beta.23 line.
tegg/core/ajv-decorator/package.json	Version bump to beta.23 line.
tegg/core/agent-runtime/package.json	Version bump to beta.23 line.
plugins/watcher/package.json	Version bump to beta.23 line.
plugins/view/package.json	Version bump to beta.23 line.
plugins/view-nunjucks/package.json	Version bump to beta.23 line.
plugins/typebox-validate/package.json	Version bump to beta.23 line.
plugins/tracer/package.json	Version bump to beta.23 line.
plugins/static/package.json	Version bump to beta.23 line.
plugins/session/package.json	Version bump to beta.23 line.
plugins/security/package.json	Version bump to beta.23 line.
plugins/schedule/package.json	Version bump to beta.23 line.
plugins/redis/package.json	Version bump to beta.23 line.
plugins/onerror/package.json	Version bump to beta.23 line.
plugins/multipart/package.json	Version bump to beta.23 line.
plugins/mock/package.json	Version bump to beta.23 line.
plugins/logrotator/package.json	Version bump to beta.23 line.
plugins/jsonp/package.json	Version bump to beta.23 line.
plugins/i18n/package.json	Version bump to beta.23 line.
plugins/development/package.json	Version bump to beta.23 line.
packages/utils/package.json	Version bump to beta.23 line.
packages/typings/package.json	Version bump to beta.23 line.
packages/tsconfig/package.json	Version bump to beta.23 line.
packages/supertest/package.json	Version bump to beta.23 line.
packages/skills/package.json	Version bump to beta.23 line.
packages/router/package.json	Version bump to beta.23 line.
packages/path-matching/package.json	Version bump to beta.23 line.
packages/logger/package.json	Version bump to beta.23 line.
packages/loader-fs/package.json	Version bump to beta.23 line.
packages/koa/package.json	Version bump to beta.23 line.
packages/koa-static-cache/package.json	Version bump to beta.23 line.
packages/extend2/package.json	Version bump to beta.23 line.
packages/errors/package.json	Version bump to beta.23 line.
packages/egg/package.json	Version bump to beta.23 line.
packages/core/package.json	Version bump to beta.23 line.
packages/cookies/package.json	Version bump to beta.23 line.
packages/cluster/package.json	Version bump to beta.23 line.
package.json	Monorepo root version bump to beta.23 line.

[gemini-code-assist]

Code Review

This pull request updates package versions across the monorepo and introduces a new setup script for @eggjs/tegg-vitest to handle ESM and CommonJS file imports in Vitest. Additionally, it optimizes the transaction hook in the DAL plugin to skip processing early when no data sources are configured. Feedback on the changes highlights a potential crash in the test runner if an older version of @eggjs/tegg-vitest is installed, suggesting a try-catch block around the setup file resolution to ensure backward compatibility.

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]

If @eggjs/tegg-vitest/runner is resolved but the installed version of @eggjs/tegg-vitest is older and does not export /setup, importResolve('@eggjs/tegg-vitest/setup') will throw an ImportResolveError. Since there is no try-catch block here, this will crash the test runner. Wrapping this in a try-catch block ensures backward compatibility with older versions of @eggjs/tegg-vitest.

    } else {
      try {
        const teggSetup = importResolve('@eggjs/tegg-vitest/setup', {
          paths: [flags.base, import.meta.dirname],
        });
        setupFiles.unshift(teggSetup);
        debug('auto add @eggjs/tegg-vitest/setup: %o', teggSetup);
      } catch (err) {
        if (!(err instanceof ImportResolveError)) throw err;
        debug('skip @eggjs/tegg-vitest/setup: not resolvable');
      }
    }

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

tegg/plugin/dal/src/lib/TransactionPrototypeHook.ts (1)

31-33: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider logging when the datasource guard skips transaction setup.

When dataSources.length === 0, the hook returns silently. If a developer misconfigures datasource settings, @Transactional methods will silently have no transaction behavior with no diagnostic output. A debug-level log here would aid troubleshooting.

💡 Optional: add a debug log

 if (dataSources.length === 0) {
+  this.logger.info(`skip transaction hook for module ${moduleName} because no dataSource config found`);
   return;
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tegg/plugin/dal/src/lib/TransactionPrototypeHook.ts` around lines 31 - 33, In
the dataSources.length === 0 guard within the transaction hook, add a
debug-level log before returning to indicate that transaction setup was skipped
because no datasources are configured. Keep the existing early-return behavior
unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tegg/plugin/dal/test/TransactionPrototypeHook.test.ts`:
- Around line 1-64: Add a MultiApp regression test alongside the existing
`TransactionPrototypeHook` cases, creating two concurrent app/module
configurations with distinct dataSource or transaction settings and invoking
`preCreate` for each. Assert each hook uses only its own app’s configuration and
transaction setup, with no cross-talk, while preserving the existing single-app
skip cases.

In `@tools/egg-bin/src/commands/test.ts`:
- Around line 255-260: Wrap the `@eggjs/tegg-vitest/setup` importResolve call in
the same ImportResolveError handling pattern used by the runner resolution
above. When setup resolution fails, continue without unshifting a setup file,
while preserving the existing successful-resolution behavior and debug logging.

---

Nitpick comments:
In `@tegg/plugin/dal/src/lib/TransactionPrototypeHook.ts`:
- Around line 31-33: In the dataSources.length === 0 guard within the
transaction hook, add a debug-level log before returning to indicate that
transaction setup was skipped because no datasources are configured. Keep the
existing early-return behavior unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 93e180c9-60df-4a4d-a058-b90063b26225

📥 Commits

Reviewing files that changed from the base of the PR and between dfd102c and 86ae141.

📒 Files selected for processing (87)

• package.json
• packages/cluster/package.json
• packages/cookies/package.json
• packages/core/package.json
• packages/egg/package.json
• packages/errors/package.json
• packages/extend2/package.json
• packages/koa-static-cache/package.json
• packages/koa/package.json
• packages/loader-fs/package.json
• packages/logger/package.json
• packages/path-matching/package.json
• packages/router/package.json
• packages/skills/package.json
• packages/supertest/package.json
• packages/tsconfig/package.json
• packages/typings/package.json
• packages/utils/package.json
• plugins/development/package.json
• plugins/i18n/package.json
• plugins/jsonp/package.json
• plugins/logrotator/package.json
• plugins/mock/package.json
• plugins/multipart/package.json
• plugins/onerror/package.json
• plugins/redis/package.json
• plugins/schedule/package.json
• plugins/security/package.json
• plugins/session/package.json
• plugins/static/package.json
• plugins/tracer/package.json
• plugins/typebox-validate/package.json
• plugins/view-nunjucks/package.json
• plugins/view/package.json
• plugins/watcher/package.json
• tegg/core/agent-runtime/package.json
• tegg/core/ajv-decorator/package.json
• tegg/core/aop-decorator/package.json
• tegg/core/aop-runtime/package.json
• tegg/core/background-task/package.json
• tegg/core/common-util/package.json
• tegg/core/controller-decorator/package.json
• tegg/core/core-decorator/package.json
• tegg/core/dal-decorator/package.json
• tegg/core/dal-runtime/package.json
• tegg/core/dynamic-inject-runtime/package.json
• tegg/core/dynamic-inject/package.json
• tegg/core/eventbus-decorator/package.json
• tegg/core/eventbus-runtime/package.json
• tegg/core/langchain-decorator/package.json
• tegg/core/lifecycle/package.json
• tegg/core/loader/package.json
• tegg/core/mcp-client/package.json
• tegg/core/metadata/package.json
• tegg/core/orm-decorator/package.json
• tegg/core/runtime/package.json
• tegg/core/schedule-decorator/package.json
• tegg/core/standalone-decorator/package.json
• tegg/core/tegg/package.json
• tegg/core/transaction-decorator/package.json
• tegg/core/types/package.json
• tegg/core/vitest/package.json
• tegg/core/vitest/src/setup.ts
• tegg/core/vitest/test/fixture_app.test.ts
• tegg/core/vitest/vitest.config.ts
• tegg/plugin/ajv/package.json
• tegg/plugin/aop/package.json
• tegg/plugin/common/package.json
• tegg/plugin/config/package.json
• tegg/plugin/controller/package.json
• tegg/plugin/dal/package.json
• tegg/plugin/dal/src/lib/TransactionPrototypeHook.ts
• tegg/plugin/dal/test/TransactionPrototypeHook.test.ts
• tegg/plugin/dns-cache/package.json
• tegg/plugin/eventbus/package.json
• tegg/plugin/langchain/package.json
• tegg/plugin/mcp-client/package.json
• tegg/plugin/mcp-proxy/package.json
• tegg/plugin/orm/package.json
• tegg/plugin/schedule/package.json
• tegg/plugin/tegg/package.json
• tegg/standalone/standalone/package.json
• tools/create-egg/package.json
• tools/egg-bin/package.json
• tools/egg-bin/src/commands/test.ts
• tools/egg-bundler/package.json
• tools/scripts/package.json

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check for existing multi-app tests in the DAL plugin
fd -i "MultiApp" tegg/plugin/dal/

Repository: eggjs/egg

Length of output: 147

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Map the relevant files and look for multi-app coverage in the DAL plugin and related lifecycle tests.
printf '\n== Files ==\n'
git ls-files 'tegg/plugin/dal/**' | sed -n '1,200p'

printf '\n== MultiApp references under tegg/plugin/dal ==\n'
rg -n --hidden --glob 'tegg/plugin/dal/**' 'MultiApp|multi-app|multi app|multiApp'

printf '\n== TransactionPrototypeHook sources/tests ==\n'
fd -a 'TransactionPrototypeHook' tegg/plugin/dal

Repository: eggjs/egg

Length of output: 1889

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== TransactionPrototypeHook ==\n'
sed -n '1,220p' tegg/plugin/dal/src/lib/TransactionPrototypeHook.ts

printf '\n== transaction tests ==\n'
sed -n '1,260p' tegg/plugin/dal/test/transaction.test.ts

printf '\n== dal tests ==\n'
sed -n '1,260p' tegg/plugin/dal/test/dal.test.ts

printf '\n== MultiApp tests in tegg ==\n'
rg -n --hidden --glob 'tegg/**' 'MultiApp|multi-app|multi app|multiApp'

Repository: eggjs/egg

Length of output: 10228

---

Add MultiApp regression coverage for TransactionPrototypeHook
tegg/plugin/dal/test/TransactionPrototypeHook.test.ts only covers single-app cases. Since this changes a lifecycle hook, add a MultiApp test to ensure two concurrent apps don’t cross-talk through module config or transaction setup.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tegg/plugin/dal/test/TransactionPrototypeHook.test.ts` around lines 1 - 64,
Add a MultiApp regression test alongside the existing `TransactionPrototypeHook`
cases, creating two concurrent app/module configurations with distinct
dataSource or transaction settings and invoking `preCreate` for each. Assert
each hook uses only its own app’s configuration and transaction setup, with no
cross-talk, while preserving the existing single-app skip cases.

Source: Coding guidelines

[coderabbitai]

🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Add error handling for @eggjs/tegg-vitest/setup resolution.

The runner resolution above (lines 241–251) wraps importResolve in try/catch for ImportResolveError, but the setup resolution on lines 256–258 does not. If an older @eggjs/tegg-vitest version is cached that has the ./runner export but not the new ./setup export, this will throw unhandled and crash egg-bin test.

🛡️ Proposed fix: mirror the runner resolution pattern

     } else {
-      const teggSetup = importResolve('`@eggjs/tegg-vitest/setup`', {
-        paths: [flags.base, import.meta.dirname],
-      });
-      setupFiles.unshift(teggSetup);
-      debug('auto add `@eggjs/tegg-vitest/setup`: %o', teggSetup);
+      try {
+        const teggSetup = importResolve('`@eggjs/tegg-vitest/setup`', {
+          paths: [flags.base, import.meta.dirname],
+        });
+        setupFiles.unshift(teggSetup);
+        debug('auto add `@eggjs/tegg-vitest/setup`: %o', teggSetup);
+      } catch (err) {
+        if (!(err instanceof ImportResolveError)) throw err;
+        debug('skip `@eggjs/tegg-vitest/setup`: not resolvable');
+      }
     }

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	} else {
	const teggSetup = importResolve('@eggjs/tegg-vitest/setup', {
	paths: [flags.base, import.meta.dirname],
	});
	setupFiles.unshift(teggSetup);
	debug('auto add @eggjs/tegg-vitest/setup: %o', teggSetup);
	} else {
	try {
	const teggSetup = importResolve('`@eggjs/tegg-vitest/setup`', {
	paths: [flags.base, import.meta.dirname],
	});
	setupFiles.unshift(teggSetup);
	debug('auto add `@eggjs/tegg-vitest/setup`: %o', teggSetup);
	} catch (err) {
	if (!(err instanceof ImportResolveError)) throw err;
	debug('skip `@eggjs/tegg-vitest/setup`: not resolvable');
	}
	}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tools/egg-bin/src/commands/test.ts` around lines 255 - 260, Wrap the
`@eggjs/tegg-vitest/setup` importResolve call in the same ImportResolveError
handling pattern used by the runner resolution above. When setup resolution
fails, continue without unshifting a setup file, while preserving the existing
successful-resolution behavior and debug logging.