build(docs-infra): ensure the locally built packages exist and are up-to-date in `yarn setup-local` (#31985)

The `setup-local` npm script uses `NgPackagesInstaller` to replace the
Angular packages with the locally built ones. Previously, it would (a)
assume that the packages were built and (b) it would do anything if the
currently installed versions already correspond to locally built
packages (even if not the latest version).
This could lead to all sorts of errors, such as:
- Confusing error messages, `dist/packages-dist/` was missing.
- Using outdated build artifacts from `dist/packages-dist/` without a
  warning.
- Not installing the latest locally built packages, because the ones
  installed already corresponded to locally built (but older) ones.

This commit fixes these issues by ensuring that:
- The local packages are always built before being used by
  `NgPackagesInstaller`.
- The local packages are installed, even if the ones install already
  correspond to local packages.

NOTE: Special `*-ci` scripts are introduced (for use on CI) that skip
      building the local packages, since that step would have been taken
      care of (in a more efficient way) in a previous CI step.

PR Close #31985

.circleci/config.yml

@@ -321,7 +321,7 @@ jobs:
       - *attach_workspace
       - *init_environment
         # Build aio (with local Angular packages)
-      - run: yarn --cwd aio build-local --progress=false
+      - run: yarn --cwd aio build-local-ci
         # Run unit tests
       - run: yarn --cwd aio test --progress=false --watch=false
         # Run e2e tests
@@ -340,7 +340,7 @@ jobs:
       - *attach_workspace
       - *init_environment
         # Build aio with Ivy (using local Angular packages)
-      - run: yarn --cwd aio build-with-ivy --progress=false
+      - run: yarn --cwd aio build-with-ivy-ci
         # Run unit tests
       - run: yarn --cwd aio test --progress=false --watch=false
         # Run e2e tests

aio/README.md

@@ -14,10 +14,12 @@ Here are the most important tasks you might need to use:
 
 * `yarn` - install all the dependencies.
 * `yarn setup` - install all the dependencies, boilerplate, stackblitz, zips and run dgeni on the docs.
-* `yarn setup-local` - same as `setup`, but use the locally built Angular packages for aio and docs examples boilerplate.
+* `yarn setup-local` - same as `setup`, but build the Angular packages from the source code and use these locally built versions (instead of the ones fetched from npm) for aio and docs examples boilerplate.
 
 * `yarn build` - create a production build of the application (after installing dependencies, boilerplate, etc).
 * `yarn build-local` - same as `build`, but use `setup-local` instead of `setup`.
+* `yarn build-with-ivy` - same as `build-local`, but in addition also turns on `ivy` mode in aio.
+                          (Note: To turn on `ivy` mode in examples, see `yarn boilerplate:add` below.)
 
 * `yarn start` - run a development web server that watches the files; then builds the doc-viewer and reloads the page, as necessary.
 * `yarn serve-and-sync` - run both the `docs-watch` and `start` in the same console.
@@ -31,7 +33,10 @@ Here are the most important tasks you might need to use:
 * `yarn docs-lint` - check that the doc gen code follows our style rules.
 * `yarn docs-test` - run the unit tests for the doc generation code.
 
-* `yarn boilerplate:add` - generate all the boilerplate code for the examples, so that they can be run locally. Add the option `--local` to use your local version of Angular contained in the "dist" folder.
+* `yarn boilerplate:add` - generate all the boilerplate code for the examples, so that they can be run locally.
+  - Add the option `--local` to use your local version of Angular contained in the "dist" folder.
+  - Add the option `--ivy` to turn on `ivy` mode.
+
 * `yarn boilerplate:remove` - remove all the boilerplate code that was added via `yarn boilerplate:add`.
 * `yarn generate-stackblitz` - generate the stackblitz files that are used by the `live-example` tags in the docs.
 * `yarn generate-zips` - generate the zip files from the examples. Zip available via the `live-example` tags in the docs.

aio/package.json

@@ -8,7 +8,7 @@
   "scripts": {
     "preinstall": "node ../tools/yarn/check-yarn.js",
     "postinstall": "node tools/cli-patches/patch.js",
-    "aio-use-local": "node tools/ng-packages-installer overwrite . --debug",
+    "aio-use-local": "node tools/ng-packages-installer overwrite . --debug --force --build-packages",
     "aio-use-npm": "node tools/ng-packages-installer restore .",
     "aio-check-local": "node tools/ng-packages-installer check .",
     "ng": "yarn check-env && ng",
@@ -17,18 +17,22 @@
     "build": "yarn ~~build",
     "prebuild-local": "yarn setup-local",
     "build-local": "yarn ~~build",
+    "prebuild-local-ci": "yarn setup-local --no-build-packages",
+    "build-local-ci": "yarn ~~build --progress=false",
     "prebuild-with-ivy": "yarn setup-local && node scripts/switch-to-ivy",
     "build-with-ivy": "yarn ~~build",
+    "prebuild-with-ivy-ci": "yarn setup-local --no-build-packages && node scripts/switch-to-ivy",
+    "build-with-ivy-ci": "yarn ~~build --progress=false",
     "extract-cli-command-docs": "node tools/transforms/cli-docs-package/extract-cli-commands.js 403bcb01c",
     "lint": "yarn check-env && yarn docs-lint && ng lint && yarn example-lint && yarn tools-lint",
     "test": "yarn check-env && ng test",
     "pree2e": "yarn check-env && yarn update-webdriver",
     "e2e": "ng e2e --no-webdriver-update",
     "presetup": "yarn --cwd .. install && yarn install --frozen-lockfile && yarn ~~check-env && yarn ~~clean-generated && yarn boilerplate:remove",
-    "setup": "yarn aio-use-npm && yarn example-use-npm",
+    "setup": "yarn example-use-npm && yarn aio-use-npm",
     "postsetup": "yarn boilerplate:add && yarn extract-cli-command-docs && yarn docs",
     "presetup-local": "yarn presetup",
-    "setup-local": "yarn aio-use-local && yarn example-use-local",
+    "setup-local": "yarn example-use-local && yarn aio-use-local",
     "postsetup-local": "yarn postsetup",
     "set-opensearch-url": "node --eval \"const sh = require('shelljs'); sh.set('-e'); sh.sed('-i', /PLACEHOLDER_URL/g, process.argv[1], 'dist/assets/opensearch.xml');\"",
     "presmoke-tests": "yarn update-webdriver",
@@ -39,7 +43,7 @@
     "test-pwa-score-localhost": "run-p --race \"~~light-server -s dist -p 4200 --quiet\" \"test-pwa-score http://localhost:4200 {1} {2}\" --",
     "example-e2e": "yarn example-check-local && node ./tools/examples/run-example-e2e",
     "example-lint": "tslint --config \"content/examples/tslint.json\" \"content/examples/**/*.ts\" --exclude \"content/examples/styleguide/**/*.avoid.ts\"",
-    "example-use-local": "node tools/ng-packages-installer overwrite ./tools/examples/shared --debug",
+    "example-use-local": "node tools/ng-packages-installer overwrite ./tools/examples/shared --debug --force",
     "example-use-npm": "node tools/ng-packages-installer restore ./tools/examples/shared",
     "example-check-local": "node tools/ng-packages-installer check ./tools/examples/shared",
     "deploy-production": "scripts/deploy-to-firebase.sh",

aio/tools/examples/run-example-e2e.js

@@ -46,6 +46,8 @@ if (argv.ivy) {
  *    Must be used in conjunction with --setup as this is when the packages are copied.
  *    e.g. --setup --local
  *
+ *  --ivy to turn on `ivy` mode
+ *
  *  --shard to shard the specs into groups to allow you to run them in parallel
  *    e.g. --shard=0/2 // the even specs: 0, 2, 4, etc
  *    e.g. --shard=1/2 // the odd specs: 1, 3, 5, etc