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

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`:

Start with the affected package.json#overrides section at the linked documentation URL, then compare the existing explanation with the supplied examples. Done means clearly documenting that a matching parent version range also overrides the parent version, including how the proposed child override reference affects the result.