feature(envs) - support new "extends" field in env.jsonc

[GiladShoham]

Proposed Changes

• With this feature, you can now add new "extends" field in your env.jsonc
• You can use extends to extends an env.jsonc that extends another env.jsonc
• The value for extends should be the package name of the env you want to extend.
• You need to make sure to have that env you extend as a dependency of your env.

Merge strategy

patterns

In the patterns object, each key will be overridden by the child as is (no internal merge of the arrays).
If you have a key in the parent that doesn't exist on the child it will be taken as is from the parent.

policy

For each type of dependency (dev/peer/runtime), each object will be taken from the child by the name.
so if you have a dependency on peers in the parent like this:

// parent's env.jsonc
peers: [
    {
      name: 'react',
      version: '^18.0.0',
      supportedRange: '^18.0.0',
    },
]

and in the child

// parent's env.jsonc
peers: [
    {
      name: 'react',
      version: '^17.0.0',
      supportedRange: '^17.0.0,
    },
]

The final result will be the child, as they have the same value for name, and the same type (peers)

If an entry with a given name exists only in one of the env.jsonc, it will be taken as is.
So the final array will have entries from both the child and the parent.

In case you want to just remove some dep from the parent you can use "-" as the version value.
This will not remove the dependency from the component, rather then will remove it from the env policy.
(in most cases it will, in that case, change the behavior so bit will be using the auto-resolve algorithm to resolve the version of a dependency rather than remove it (unless you don't use that dependency)

This way you can also use it in order move something from one type to another.
see the following example:

// parent's env.jsonc
runtime: [
    {
      name: 'lodash',
      version: '1.0.0',
      force: true
    },
]

and you want to move lodash to be a dev dependency

// child's env.jsonc
runtime: [
    {
      name: 'lodash',
      version: '-,
      force: true
    },
],
dev: [
    {
      name: 'lodash',
      version: '1.0.0',
      force: true
    },
]

you are using "-" to remove it from runtime, and add it again in dev.

Full example:

Let's assume we have 3 envs one extends another as below.
And we configure env-level3 for our component.

// @my-org/envs.env-level1
{
  "policy": {
    "peers": [
      {
        "name": "react",
        "version": "^18.0.0",
        "supportedRange": "^17.0.0 || ^18.0.0"
      },
      {
        "name": "react-dom",
        "version": "^18.0.0",
        "supportedRange": "^17.0.0 || ^18.0.0"
      }
    ],
    "dev": [
      {
        "name": "is-positive",
        "version": "3.1.0",
        "hidden": false,
        "force": true
      }
    ],
    "runtime": [
      {
        "name": "is-string",
        "version": "1.0.7",
        "force": true
      }
    ]
  },
  "patterns": {
    "compositions": [
      "**/*.composition.*",
      "**/*.preview.*"
    ],
    "docs": [
      "**/*.docs.*"
    ],
    "tests": [
      "**/*.spec.*",
      "**/*.test.*"
    ]
  }
}

// @my-org/envs.env-level2
{
  "extends": "@my-org/envs.env-level1"
  "policy": {
    "peers": [
      {
        "name": "react",
        "version": "^16.0.0",
        "supportedRange": "^17.0.0 || ^16.0.0"
      }
    ],
    "runtime": [
      {
        "name": "is-odd",
        "version": "3.0.1",
        "force": true
      },
      {
        "name": "is-negative",
        "version": "2.1.0",
        "force": true
      }
    ]
  },
  "patterns": {
    "compositions": [
      "**/*.composition.*",
      "**/*.preview.*",
      "**/*.preview-level2.*"
    ],
    "docs": [
      "**/*.docs.*",
      "**/*.docs-level2.*"
    ]
  }
}

// @my-org/envs.env-level3
{
  "extends": "@my-org/envs.env-level2"
  "policy": {
    "dev": [
      {
        "name": "is-negative",
        "version": "2.1.0",
        "force": true
      }
    ],
    "runtime": [
      {
        "name": "is-negative",
        "version": "-",
        "force": true
      },
      {
        "name": "is-string",
        "version": "1.0.6",
        "force": true
      }
    ]
  },
  "patterns": {
    "compositions": [
      "**/*.composition.*",
      "**/*.preview.*",
      "**/*.preview-level3.*"
    ],
    "level3": [
      "**/*.level3.*"
    ]
  }
}

Final merged config:

{
  "policy": {
    "peers": [
      {
        "name": "react-dom",
        "version": "^18.0.0",
        "supportedRange": "^17.0.0 || ^18.0.0"
      },
      {
        "name": "react",
        "version": "^16.0.0",
        "supportedRange": "^17.0.0 || ^16.0.0"
      }
    ],
    "dev": [
      {
        "name": "is-positive",
        "version": "3.1.0",
        "hidden": false,
        "force": true
      },
      {
        "name": "is-negative",
        "version": "2.1.0",
        "force": true
      }
    ],
    "runtime": [
      {
        "name": "is-odd",
        "version": "3.0.1",
        "force": true
      },
      {
        "name": "is-string",
        "version": "1.0.6",
        "force": true
      }
    ]
  },
  "patterns": {
    "compositions": [
      "**/*.composition.*",
      "**/*.preview.*",
      "**/*.preview-level3.*"
    ],
    "docs": [
      "**/*.docs.*",
      "**/*.docs-level2.*"
    ],
    "tests": [
      "**/*.spec.*",
      "**/*.test.*"
    ],
    "level3": [
      "**/*.level3.*"
    ]
  }
}

[leimonio]

@GiladShoham I believe in the last example you mean this configuration instead.

// child's env.jsonc
runtime: [
    {
      name: 'lodash',
      version: '-,
      force: true
    },
],
dev: [
    {
      name: 'lodash',
      version: '1.0.0',
      force: true
    },
]