[DOCS] package.json overrides parent keySpec overrides parent version

[stabpd]

Is there an existing issue for this?

• I have searched the existing issues

This is a CLI Docs Problem, not another kind of Docs Problem.

• This is a CLI Docs Problem.

Description of Problem

For overrides, I was surprised to find that the parent key version range is not just a matcher / condition, but also an applied override to the parent. (if it matches the parent)

It fits the docs, once you understood. I needed some testing around, reading code and docs again to get there.

Example: Sub-dependency foo version 19 gets overridden to version 20 for the following overrides:

{ "overrides": {
  "foo@<=20": {
    "bar": "1.2.3"
  }
}}

Potential Solution

How about stating more clearly that parent key version ranges apply overrides too, adding the following?

Parent keys with version ranges override that parent's version too, if matching. Add child override `".": "$foo"` to prevent that.

This seems to do what I actually want:

{ "overrides": {
  ".": "$foo",
  "foo@<=20": {
    "bar": "1.2.3"
  }
}}

❗ I do not know though, if I should actually use reference $foo if it is a sub-dependency itself. Docs state [...] overrides may also be defined as a reference to a spec for a direct dependency [...].

Affected URL

This is regarding https://docs.npmjs.com/cli/v11/configuring-npm/package-json#overrides

The key of an override can also include a version, or range of versions. To override `@npm/foo` to `1.0.0`, but only when it's a child of `@npm/bar@2.0.0`:

[stabpd]

There seems to be code that explicitly falls back to the local package, if a reference is not found in root package.

cli/workspaces/arborist/lib/edge.js

Lines 215 to 219 in 21ea382

	// If the package isn't found in the root package, fall back to the local package.
	if (!specValue) {
	pkg = this.#from?.package
	specValue = this.#calculateReferentialOverrideSpec(ref, pkg)
	}

So, maybe documentation could be extended to state that sub-dependencies can be referenced that way, too? That would allow not only documenting that parent keySpecs trigger overrides too, but also that it can be prevented via reference. (as already suggested above)