feat: update lab 1 to nx 19.7 (#36)

.github/CONTRIBUTING.md

@@ -4,7 +4,7 @@
 
 ## Local Package Publishing
 
-When iterating on the `@nrwl/nx-workshop-e2e` package, it's often helpful to test out a published
+When iterating on the `@nrwl/nx-react-workshop-e2e` package, it's often helpful to test out a published
 version of the package locally. This can be done by starting the local registry, `verdaccio`, and using the `nx release` command.
 
 To start the local registry, run the `local-registry` target for the root workspace project:
@@ -13,7 +13,7 @@ To start the local registry, run the `local-registry` target for the root worksp
 nx local-registry
 ```
 
-In another terminal, you can then trigger deployment to that registry by running the `release` target for the `nx-workshop-e2e` project:
+In another terminal, you can then trigger deployment to that registry by running the `release` target for the `nx-react-workshop-e2e` project:
 
 ```bash
 nx release version prerelease && nx release publish
@@ -22,7 +22,7 @@ nx release version prerelease && nx release publish
 nx release-dev nx-react-workshop
 ```
 
-Once your dev version has been published, you can then update the `nx-workshop-e2e` package in your consuming project to the version you just published.
+Once your dev version has been published, you can then update the `nx-react-workshop-e2e` package in your consuming project to the version you just published.
 
 Since verdaccio configures itself in the `~/.npmrc` file, you can simply install using your standard package manager commands:
 
@@ -31,3 +31,38 @@ npm add --save-dev @nrwl/nx-react-workshop@latest
 # or alternatively with yarn
 yarn add -D @nrwl/nx-react-workshop@latest
 ```
+
+## Updating workshop content
+
+The workshop content is stored in the `docs` directory. The content is written in markdown and is organized by lab. Each lab has its own directory with a `LAB.md` and `SOLUTION.md`.
+
+When updating:
+
+1. Use the migration generator to jump to the lab before the being updating
+
+   ```sh
+   nx generate @nrwl/nx-react-workshop:complete-labs --from=1 --to=<the-prior-lab-number>
+   nx migrate --run-migrations=migrations.json --verbose
+   ```
+
+2. Manually run through the lab and verify:
+
+   - The instructions in LAB.md and language reflect the current state of the nx
+   - The contents of SOLUTION.md match 1:1 with the steps in the lab
+   - Any screenshots or prompt examples accurately reflect the output from the lab
+
+3. Verify the completion migration reflects the steps outlined in the solution
+
+   ```sh
+   # After manually following the lab in step #2
+
+   # git commit
+   git add . && git commit -m 'manually run through completion steps'
+
+   # reset repo state and migrate to end of lab:
+   nx generate @nrwl/nx-react-workshop:complete-labs --from=1 --to=<the-lab-being-updated>
+   nx migrate --run-migrations=migrations.json --verbose
+
+   # Verify there are no differences
+   git status # should show no changes
+   ```

apps/nx-workshop-e2e/tests/nx-workshop.spec.ts

@@ -1,31 +1,51 @@
 import { execSync, ExecSyncOptionsWithStringEncoding } from 'child_process';
 import { join, dirname } from 'path';
 import { mkdirSync, rmSync } from 'fs';
+import { copy } from 'fs-extra';
+import { compareSync, Result as DirCompareResult } from 'dir-compare';
+import { stripIndents } from '@nx/devkit';
 
 // TODO: Update to 22 once all labs are updated/fixed
 // const LAB_COUNT = 22;
-const LAB_COUNT = 3;
-const LABS_TO_TEST = Array.from({ length: LAB_COUNT }, (_, i) => ({
-  labNumber: i + 1,
+const LAB_COUNT = 2;
+
+// We iterate from lab 2 to LAB_COUNT since lab 1 is a special case that resets the project
+// which we test explicitly at the end of the test suite
+const LABS_TO_TEST = Array.from({ length: LAB_COUNT - 1 }, (_, i) => ({
+  labNumber: i + 2,
 }));
 
 describe('nx-react-workshop', () => {
   let projectDirectory: string;
+  let emptyProjectDirectory: string;
 
-  beforeAll(() => {
+  beforeAll(async () => {
     projectDirectory = createTestProject();
 
     // The plugin has been built and published to a local registry in the jest globalSetup
     // Install the plugin built with the latest source code into the test repo
-    execSync(`npm install @nrwl/nx-react-workshop@e2e`, {
+    execSync(`npm install --save-dev @nrwl/nx-react-workshop@e2e`, {
       cwd: projectDirectory,
       stdio: 'inherit',
       env: process.env,
     });
-  });
+
+    // A noop to verify generator works and setup project in an "initial state"
+    runNxCommand(
+      `generate @nrwl/nx-react-workshop:complete-labs --lab=0`,
+      projectDirectory
+    );
+
+    // Make a copy of the initial project state so we can compare against it later
+    emptyProjectDirectory = join(process.cwd(), 'tmp', 'empty-project');
+    await copy(projectDirectory, emptyProjectDirectory, {
+      filter: (src) => !src.includes('node_modules'),
+    });
+  }, 120000);
 
   afterAll(() => {
     // Cleanup the test project
+    rmSync(emptyProjectDirectory, { recursive: true, force: true });
     try {
       rmSync(projectDirectory, { recursive: true, force: true });
     } catch {
@@ -66,10 +86,41 @@ describe('nx-react-workshop', () => {
           );
         }
       );
+
+      // NOTE: this test assumes that the current test project is in the final lab completed state
+      it('complete-lab-1 migration should match an empty create-nx-workspace', () => {
+        // Reset the test project to it's initial state using the "complete-lab-1" migration
+        runNxCommand(
+          `generate @nrwl/nx-react-workshop:complete-labs --lab=1 --option=${option}`,
+          projectDirectory
+        );
+        runNxCommand(
+          'migrate --run-migrations=migrations.json --verbose',
+          projectDirectory
+        );
+
+        const result = compareSync(projectDirectory, emptyProjectDirectory, {
+          excludeFilter: [
+            '*.env',
+            '.git',
+            '.DS_Store',
+            '.nx',
+            '.vscode',
+            'dist',
+            'node_modules',
+            'tmp',
+          ].join(','),
+        });
+
+        if (!result.same) {
+          logProjectDifferences(result);
+        }
+
+        expect(result.same).toBeTruthy();
+      });
     });
 
-    // TODO: fix this as a part of updating lab 2
-    it.todo('should support migrating from one version to another'); /*, () => {
+    it('should support migrating from one version to another', () => {
       runNxCommand(
         `generate @nrwl/nx-react-workshop:complete-labs --from=1 --to=${LAB_COUNT}`,
         projectDirectory
@@ -83,16 +134,15 @@ describe('nx-react-workshop', () => {
         projectDirectory
       );
       runNxCommand('run-many --target=lint --parallel=false', projectDirectory);
-    }); */
+    });
   });
 });
 
 /**
  * Creates a test project with create-nx-workspace and installs the plugin
  * @returns The directory where the test project was created
  */
-function createTestProject() {
-  const projectName = 'test-project';
+function createTestProject(projectName = 'test-project') {
   const projectDirectory = join(process.cwd(), 'tmp', projectName);
 
   // Ensure projectDirectory is empty
@@ -122,3 +172,30 @@ function runNxCommand(command: string, projectDirectory: string): string {
 
   return execSync(`npx nx ${command}`, execSyncOptions);
 }
+
+function logProjectDifferences(result: DirCompareResult) {
+  console.error(
+    stripIndents`
+      Empty project and reset project do not match:
+      %s
+    `,
+    result.diffSet
+      .filter(({ state }) => state !== 'equal')
+      .map((dif) => {
+        switch (dif.state) {
+          case 'distinct':
+            return `  ${dif.name1}: expected migration to reset this files content`;
+
+          case 'left':
+            return `  ${dif.name1}: expected migration to delete this path`;
+
+          case 'right':
+            return `  ${dif.name1} expected migration to retain this path`;
+
+          default:
+            throw new Error(`Unexpected diff state: ${dif.state}`);
+        }
+      })
+      .join('\n')
+  );
+}

docs/lab1/LAB.md

@@ -10,19 +10,19 @@
 
 <details>
   <summary>File structure</summary>
-  <img src="../assets/lab1_directory-structure.png" height="700" alt="lab7 file structure">
+  <img src="../assets/lab1_directory-structure.png" height="300" alt="lab7 file structure">
 </details>
 
 ## 🏋️‍♀️ Steps:
 
 1. Generate an empty Nx workspace for a fictional company called "The Board Game Hoard"
-   <br />
 
 2. The workspace name should be `bg-hoard`
-   <br />
 
-3. Make sure you select `None` as Stack (we will create apps manually), an `Integrated` workspace layout and `No to NxCloud` when asked
-   <br />
+3. When prompted, select:
+   - `None` as Stack (we will create apps manually)
+   - An `Integrated` workspace layout
+   - And `skip` configuring a `CI Provider` and `Remote Caching` for now (we'll set those up in a later lab)
 
 ---
 

docs/lab1/SOLUTION.md

@@ -1,5 +1,5 @@
 ##### To create a new Nx workspace:
 
 ```shell
-npx create-nx-workspace bg-hoard --preset=empty --no-nx-cloud
+npx create-nx-workspace bg-hoard --preset=apps --nx-cloud=skip
 ```

libs/nx-react-workshop/generators.json

@@ -3,11 +3,6 @@
   "name": "nx-react-workshop",
   "version": "0.0.1",
   "generators": {
-    "nx-react-workshop": {
-      "factory": "./src/generators/nx-react-workshop/generator",
-      "schema": "./src/generators/nx-react-workshop/schema.json",
-      "description": "nx-react-workshop generator"
-    },
     "complete-labs": {
       "factory": "./src/generators/complete-labs/generator",
       "schema": "./src/generators/complete-labs/schema.json",

libs/nx-react-workshop/package.json

@@ -3,7 +3,6 @@
   "version": "0.0.0",
   "main": "src/index.js",
   "generators": "./generators.json",
-  "executors": "./executors.json",
   "nx-migrations": {
     "migrations": "./migrations.json"
   },