feat: support devEngines.packageManager detection

[pi0x]

Summary

Adds support for detecting the package manager from the devEngines.packageManager field in package.json.

Detection precedence is now:

1. packageManager field
2. devEngines.packageManager field (new)
3. Known lock files and other files

Details

• devEngines.packageManager may be a single object or an array of objects — the first entry is used.
• Its version is a semver range (e.g. ^9.0.0) rather than a pinned version, so the major version is derived from the first numeric segment (correctly resolving e.g. Yarn berry vs classic).
• The existing packageManager field still takes precedence when both are present.
• Names are sanitized the same way as the packageManager field, emitting a warnings entry for abnormal characters.

Tests

• Unit tests for parseDevEnginesPackageManager (object/array/no-version/sanitization/empty cases).
• Detection tests covering object entries, array entries, range-derived major version, and packageManager precedence.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Package manager detection now also recognizes devEngines.packageManager from package.json.
  • Handles multiple devEngines input shapes (including array-first-entry behavior) and parses semver-range versions to derive a majorVersion.
• Bug Fixes
  • Improved validation of package manager names, including warnings and sanitization for invalid characters.
  • Preserves priority for the top-level packageManager when both sources are present.
• Documentation
  • Updated the auto-detect documentation to reflect the new detection step/order.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Adds parseDevEnginesPackageManager and wires devEngines.packageManager into detectPackageManager as a fallback source. Updates the documentation and adds unit and integration tests for parsing and detection behavior.

devEngines.packageManager detection

Layer / File(s)	Summary
parseDevEnginesPackageManager helper and shared regex src/_utils.ts	Extracts VALID_PM_NAME_RE as a shared constant, updates parsePackageManagerField to use it, and adds parseDevEnginesPackageManager that normalizes array/object input, validates names, and returns sanitized name/version with optional warnings.
detectPackageManager devEngines fallback src/package-manager.ts, README.md	Imports the new helper and adds a fallback branch in the findup traversal: parses devEngines.packageManager, derives majorVersion from the first numeric segment of the version range, resolves matching packageManagers entries, and returns structured results. README step list updated accordingly.
Unit and integration tests test/_utils.test.ts, test/detect.test.ts	Unit tests cover object, array, missing version, sanitization, and invalid inputs for parseDevEnginesPackageManager. Integration tests cover devEngines detection, version-range handling, array precedence, and top-level packageManager priority.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• unjs/nypm#240: Updates the shared packageManagers registry that the new devEngines.packageManager fallback resolves against.

Poem

🐇 I sniffed a field both new and neat,
in devEngines I found a treat.
Array or object, hop by hop,
I trace the name and never stop.
With tests aloft, the path is яс? ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding support for devEngines.packageManager detection.
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 feat/devengines

---

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

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

test/detect.test.ts (1)

53-60: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Let the helper keep lockfile detection configurable.

Hard-coding ignoreLockFile: true means this suite can't cover the regression where an unsupported devEngines.packageManager.name should fall through to implicit file detection. Accepting per-test overrides here would make that case easy to pin down.

🤖 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 `@test/detect.test.ts` around lines 53 - 60, The detectFrom helper in
detect.test.ts hard-codes ignoreLockFile, which prevents tests from covering
lockfile-based fallback behavior. Update the helper so individual tests can
override detectPackageManager options, especially ignoreLockFile, while still
defaulting includeParentDirs and the temporary directory setup. This will let
the suite pin down the devEngines.packageManager.name fallback case using
detectPackageManager and detectFrom.

🤖 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 `@src/_utils.ts`:
- Around line 325-340: The `parsePackageManagerField` helper in `src/_utils.ts`
is still allowing a bare hyphen through the `VALID_PM_NAME_RE` path, so treat
`"-"` as invalid before returning a package manager name. Update the early
validation in `parsePackageManagerField` so `"-"` is rejected the same way as
other invalid values, and make sure the sanitizing branch still handles it
consistently without returning `{ name: "-" }`.

In `@src/package-manager.ts`:
- Around line 129-145: The devEngines handling in package-manager.ts is
returning too early even when the resolved name is not one of the supported
entries in packageManagers. Update the logic around the devEngines.name branch
so it only returns a package manager result when a matching supported manager is
found via packageManagers.find, and otherwise falls through to the later
detection/lockfile logic instead of returning { name, command: name } for an
unsupported manager.

---

Nitpick comments:
In `@test/detect.test.ts`:
- Around line 53-60: The detectFrom helper in detect.test.ts hard-codes
ignoreLockFile, which prevents tests from covering lockfile-based fallback
behavior. Update the helper so individual tests can override
detectPackageManager options, especially ignoreLockFile, while still defaulting
includeParentDirs and the temporary directory setup. This will let the suite pin
down the devEngines.packageManager.name fallback case using detectPackageManager
and detectFrom.

🪄 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: 8823889d-df12-4abc-b695-4c2ec8d43c5c

📥 Commits

Reviewing files that changed from the base of the PR and between 057b812 and c182381.

📒 Files selected for processing (5)

• README.md
• src/_utils.ts
• src/package-manager.ts
• test/_utils.test.ts
• test/detect.test.ts