Merge pull request #180 from akd-io/feature/add-jest-and-sort-orders

Add Jest and sort orders

Author: akd-io

CONTRIBUTING.md

@@ -70,19 +70,33 @@ Make sure you are set up locally by following the [Getting Started](#getting-sta
 
    - `git checkout -b feature/support-my-favorite-technology`
 
-2. Add a new .ts file for your plugin in the plugins directory at `packages\create-next-stack\src\main\plugins`
+2. Useful npm scripts of `packages/create-next-stack` to run during development:
+
+   - `check-types:watch` - Runs TypeScript in watch mode to check types as you make changes. You can run this instead of `build:watch` while working on the CLI, as the e2e tests do just-in-time compilation via `ts-node`.
+   - `jest:watch` - Runs Jest in watch mode to run unit tests as you make changes.
+     - These tests were specifically made to ease the plugin authoring process, so don't forget this one.
+   - `test` - Runs e2e tests. Note that this will run all e2e tests, which can take quite a while.
+   - `lint` - Runs ESLint to lint the project.
+   - `test:manual`
+     - For example, `pnpm run test:manual --package-manager=pnpm --styling=emotion`.
+     - Sets up a new directory for a test run of the CLI, runs the CLI with the specified flags, and builds the generated Next app, and checks formatting and linting.
+     - This is useful for manually testing the CLI. Pass whatever flags to the CLI that you want to test. The `app_name` argument will be set automatically.
+   - `test:raw` - Runs the binary directly. Rarely used, but can be useful for manual tests where you want to be able to specify the `app_name` argument yourself.
+   - `clean` - Removes all generated files, including build files and the `create-next-stack-tests` directory created by the e2e tests.
+
+3. Add a new .ts file for your plugin in the plugins directory at `packages\create-next-stack\src\main\plugins`
 
    - See the [Writing a plugin section](#writing-a-plugin) below to learn how to write a Create Next Stack plugin.
 
-3. Add new flags to the `create-next-stack` command in [`create-next-stack.ts`](packages\create-next-stack\src\main\commands\create-next-stack.ts).
-4. Add the plugin to the `plugins` array in [`setup.ts`](packages/create-next-stack/src/main/setup/setup.ts).
-5. Add potential plugin steps to the `steps` array in [`setup.ts`](packages/create-next-stack/src/main/setup/setup.ts). Steps are run top-to-bottom.
-6. Update the [`README.md`](README.md):
+4. Add new flags to the `create-next-stack` command in [`create-next-stack.ts`](packages\create-next-stack\src\main\commands\create-next-stack.ts).
+5. Add the plugin to the `plugins` array in [`setup.ts`](packages/create-next-stack/src/main/setup/setup.ts).
+6. Add potential plugin steps to the `steps` array in [`setup.ts`](packages/create-next-stack/src/main/setup/setup.ts). Steps are run top-to-bottom.
+7. Update the [`README.md`](README.md):
    - Add the technology to the technology list
    - Update the `Usage` section by copy pasting the output of running `yarn print:help`
-7. Consider expanding some of the e2e tests to include the new technology. See [`test.ts`](packages\create-next-stack\src\tests\e2e\test.ts) for current tests.
-8. Run tests using `yarn test` to ensure they all pass.
-9. Submit a Pull Request on GitHub.
+8. Consider expanding some of the e2e tests to include the new technology. See [`test.ts`](packages\create-next-stack\src\tests\e2e\test.ts) for current tests.
+9. Run tests using `yarn test` to ensure they all pass.
+10. Submit a Pull Request on GitHub.
 
 ## Writing a Plugin
 
@@ -92,6 +106,7 @@ See the [Framer Motion plugin](packages/create-next-stack/src/main/plugins/emoti
 
 ```typescript
 export const framerMotionPlugin = createPlugin({
+  id: "framer-motion",
   name: "Framer Motion",
   description: "Adds support for Framer Motion",
   active: ({ flags }) => Boolean(flags["framer-motion"]),
@@ -103,6 +118,7 @@ export const framerMotionPlugin = createPlugin({
   },
   technologies: [
     {
+      id: "framerMotion",
       name: "Framer Motion",
       description:
         "Framer Motion is a popular React animation library. It allows users to create both simple animations and complex gesture-based interactions. The library implements a declarative API, otherwise known as spring animations, which lets the developer define the animation's end state, letting the library handle the rest.",

packages/create-next-stack/jest.config.js

@@ -0,0 +1,7 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+// eslint-disable-next-line no-undef
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testPathIgnorePatterns: ["/node_modules/", "/lib/", "/src/tests/"],
+}

packages/create-next-stack/package.json

@@ -48,10 +48,14 @@
   "scripts": {
     "prepack": "pnpm build",
     "check-types": "tsc --noEmit",
+    "check-types:watch": "tsc --noEmit --watch",
     "build": "rimraf lib && tsc --build",
+    "build:watch": "rimraf lib && tsc --build --watch",
     "clean": "rimraf lib && pnpm run clean-tests-dir",
     "clean-tests-dir": "ts-node src/tests/e2e/clean-tests-dir.ts",
-    "test": "pnpm build && ts-node src/tests/e2e/test.ts",
+    "test": "pnpm build && pnpm run jest && ts-node src/tests/e2e/test.ts",
+    "jest": "jest",
+    "jest:watch": "jest --watch",
     "test:manual": "pnpm build && ts-node src/tests/e2e/test-manual.ts --debug",
     "test:small": "pnpm build && ts-node src/tests/e2e/test-manual.ts --debug --package-manager=pnpm --styling=css-modules",
     "test:large": "pnpm build && ts-node src/tests/e2e/test-manual.ts --debug --package-manager=pnpm --styling=emotion --react-hook-form --formik --prettier --formatting-pre-commit-hook --chakra --framer-motion --github-actions",
@@ -74,6 +78,7 @@
     "validate-npm-package-name": "^5.0.0"
   },
   "devDependencies": {
+    "@jest/globals": "^29.5.0",
     "@types/inquirer": "^9.0.3",
     "@types/node": "^18.15.13",
     "@types/uuid": "^9.0.1",
@@ -82,7 +87,9 @@
     "@typescript-eslint/parser": "^5.59.0",
     "eslint": "^8.39.0",
     "eslint-config-prettier": "^8.8.0",
+    "jest": "^29.5.0",
     "next": "^13.3.1",
+    "ts-jest": "^29.1.0",
     "ts-node": "^10.9.1",
     "uuid": "^9.0.0"
   }

packages/create-next-stack/src/main/helpers/sort-by-order.ts

@@ -0,0 +1,20 @@
+import { logDebug } from "../logging"
+
+/**
+ * Compares two string values by their order in an array.
+ * @param a a string value
+ * @param b a string value
+ * @param order an array of string values specifying the order
+ * @returns a negative number if `a` comes before `b` in `order`, a positive number if `b` comes before `a` in `order`, or `0` if `a` and `b` are equal in `order` or if either `a` or `b` are not in `order`
+ */
+export const compareByOrder = (a: string, b: string, order: string[]) => {
+  const aIndex = order.indexOf(a)
+  const bIndex = order.indexOf(b)
+  if (aIndex === -1 || bIndex === -1) {
+    logDebug(
+      `WARNING: One or both of the values being compared are not in the order array. This should be caught by a test.`
+    )
+    return 0
+  }
+  return aIndex - bIndex
+}

packages/create-next-stack/src/main/plugin.ts

@@ -3,6 +3,8 @@ import { ValidCNSInputs } from "./create-next-stack-types"
 import { DeeplyReadonly } from "./helpers/deeply-readonly"
 
 type PluginConfig = DeeplyReadonly<{
+  /** ID that uniquely identifies the plugin */
+  id: string
   /** Name of the plugin */
   name: string
   /** Description of the plugin */
@@ -55,7 +57,9 @@ export type Package = {
   version: string
 }
 
-type Technology = {
+export type Technology = {
+  /** ID that uniquely identified the technology across all plugins' technologies. */
+  id: string
   /** The name of the technology. */
   name: string
   /** Description of a technology. This is displayed in the generated README.md file, as well as in the landing page's list of technologies. */
@@ -91,6 +95,9 @@ type Script = {
 }
 
 type RawStep = {
+  /** ID that uniquely identified the technology across all plugins' steps. */
+  id: string
+
   /**
    * `description` should be written in present continuous tense, without punctuation, and with a lowercase first letter unless the description starts with a name or similar.
    *

packages/create-next-stack/src/main/plugins/chakra-ui/chakra-ui.ts

@@ -4,6 +4,7 @@ import { createPlugin } from "../../plugin"
 import { chakraTheme } from "./setup/chakra-theme"
 
 export const chakraUIPlugin = createPlugin({
+  id: "chakra-ui",
   name: "Chakra UI",
   description: "Adds support for Chakra UI",
   active: ({ flags }) => Boolean(flags.chakra),
@@ -19,6 +20,7 @@ export const chakraUIPlugin = createPlugin({
   },
   technologies: [
     {
+      id: "chakraUI",
       name: "Chakra UI",
       description:
         "Chakra UI is a simple, modular, and accessible React component library that provides all the building blocks needed to build React user interfaces. It uses Emotion under the hood and includes components ranging from basic buttons and form input fields to tooltips and modals.",
@@ -30,7 +32,8 @@ export const chakraUIPlugin = createPlugin({
     },
   ],
   steps: {
-    setup: {
+    setUpChakraUI: {
+      id: "setUpChakraUI",
       description: "setting up Chakra UI",
       run: async () => {
         await writeFile("chakra-theme.ts", chakraTheme)

packages/create-next-stack/src/main/plugins/create-next-stack/add-content/templates/LandingPage/generate-technologies.ts

@@ -2,24 +2,20 @@ import endent from "endent"
 import { ValidCNSInputs } from "../../../../../create-next-stack-types"
 import { DeeplyReadonly } from "../../../../../helpers/deeply-readonly"
 import { stringify } from "../../../../../helpers/stringify"
-import { filterPlugins } from "../../../../../setup/setup"
-
-// TODO: Add a technologies sort order here. Use TypeScript to force setting all plugin technologies.
+import { getTechnologies } from "../../../sort-orders/technologies"
 
 // This type should match the one in the template below.
-export type Technology = {
+export type Technology = DeeplyReadonly<{
   name: string
   description: string
   links: Array<{
     title: string
     url: string
   }>
-}
+}>
 
 export const generateTechnologies = (inputs: ValidCNSInputs): string => {
-  const pluginTechnologies = filterPlugins(inputs).flatMap(
-    (plugin): DeeplyReadonly<Technology[]> => plugin.technologies ?? []
-  )
+  const technologies: Technology[] = getTechnologies(inputs)
 
   return endent`
     export type Technology = {
@@ -30,6 +26,6 @@ export const generateTechnologies = (inputs: ValidCNSInputs): string => {
         url: string;
       }>;
     };
-    export const technologies: Technology[] = ${stringify(pluginTechnologies)};
+    export const technologies: Technology[] = ${stringify(technologies)};
   `
 }

packages/create-next-stack/src/main/plugins/create-next-stack/add-readme/generate-script-table-rows.ts

@@ -1,16 +1,12 @@
 import { ValidCNSInputs } from "../../../create-next-stack-types"
-import { filterPlugins } from "../../../setup/setup"
+import { getSortedFilteredScripts } from "../sort-orders/scripts"
 
 export const generateScriptTableRows = async (
   inputs: ValidCNSInputs
 ): Promise<string> => {
-  const pluginScripts = filterPlugins(inputs).flatMap(
-    (plugin) => plugin.scripts ?? []
-  )
-
-  const scriptRowsString = pluginScripts
+  const scripts = getSortedFilteredScripts(inputs)
+  const scriptRowsString = scripts
     .map((script) => `|\`${script.name}\`|${script.description}|`)
     .join("\n")
-
   return scriptRowsString
 }

packages/create-next-stack/src/main/plugins/create-next-stack/add-readme/generate-technology-table-rows.ts

@@ -1,26 +1,13 @@
 import { ValidCNSInputs } from "../../../create-next-stack-types"
-import { filterPlugins } from "../../../setup/setup"
+import { getTechnologies } from "../sort-orders/technologies"
 
 export const generateTechnologyTableRows = async (
   inputs: ValidCNSInputs
 ): Promise<string> => {
-  type TechnologyTableRow = {
-    name: string
-    links: string
-  }
-
-  const technologies: TechnologyTableRow[] = filterPlugins(inputs).flatMap(
-    ({ technologies }) => {
-      if (!technologies) return []
-      return technologies.map((technology) => ({
-        name: technology.name,
-        links: technology.links
-          .map((l) => `[${l.title}](${l.url})`)
-          .join(" - "),
-      }))
-    }
-  )
-
+  const technologies = getTechnologies(inputs).map((technology) => ({
+    name: technology.name,
+    links: technology.links.map((l) => `[${l.title}](${l.url})`).join(" - "),
+  }))
   return technologies
     .map((technology) => `| ${technology.name} | ${technology.links} |`)
     .join("\n")

packages/create-next-stack/src/main/plugins/create-next-stack/create-next-stack.ts

@@ -22,23 +22,22 @@ import { generateIndexPage } from "./add-content/pages/generate-index"
 import { generateLandingPageTemplate } from "./add-content/templates/LandingPage/generate-LandingPageTemplate"
 import { generateTechnologies } from "./add-content/templates/LandingPage/generate-technologies"
 import { generateReadme } from "./add-readme/generate-readme"
+import { getSortedFilteredScripts } from "./sort-orders/scripts"
 
 const gitAttributesFilename = ".gitattributes"
 
 export const createNextStackPlugin = createPlugin({
+  id: "create-next-stack",
   name: "Create Next Stack",
   description:
     "Adds various miscellaneous steps. Some necessities, some niceties.",
   active: true,
   steps: {
     addScripts: {
+      id: "addScripts",
       description: "adding scripts to package.json",
       run: async (inputs) => {
-        const scripts = filterPlugins(inputs).flatMap(
-          (plugin) => plugin.scripts ?? []
-        )
-
-        // TODO: Add a scripts sort order here. Use TypeScript to force setting all plugin scripts.
+        const scripts = getSortedFilteredScripts(inputs)
 
         await modifyJsonFile("package.json", (packageJson) => ({
           ...packageJson,
@@ -56,6 +55,7 @@ export const createNextStackPlugin = createPlugin({
       },
     },
     copyAssets: {
+      id: "copyAssets",
       description: "copying static assets",
       run: async (): Promise<void> => {
         const createNextStackDir = getCreateNextStackDir()
@@ -65,6 +65,7 @@ export const createNextStackPlugin = createPlugin({
       },
     },
     addContent: {
+      id: "addContent",
       description: "adding content",
       run: async (inputs) => {
         await makeDirectory("components")
@@ -84,6 +85,7 @@ export const createNextStackPlugin = createPlugin({
       },
     },
     addReadme: {
+      id: "addReadme",
       description: "adding Readme",
       run: async (inputs) => {
         const readmeFileName = "README.md"
@@ -93,6 +95,7 @@ export const createNextStackPlugin = createPlugin({
       },
     },
     initialCommit: {
+      id: "initialCommit",
       description: "adding initial commit",
       shouldRun: async () => {
         if (!(await isGitInitialized())) {
@@ -113,6 +116,7 @@ export const createNextStackPlugin = createPlugin({
       },
     },
     installDependencies: {
+      id: "installDependencies",
       description: "installing dependencies",
       run: async (inputs) => {
         const { flags } = inputs
@@ -143,6 +147,7 @@ export const createNextStackPlugin = createPlugin({
       },
     },
     uninstallTemporaryDependencies: {
+      id: "uninstallTemporaryDependencies",
       description: "uninstalling temporary dependencies",
       run: async (inputs) => {
         const tmpDeps = filterPlugins(inputs).flatMap((plugin) => {
@@ -157,6 +162,7 @@ export const createNextStackPlugin = createPlugin({
       },
     },
     formatProject: {
+      id: "formatProject",
       description: "formatting project",
       run: async () => {
         await runCommand("npx", [
@@ -167,6 +173,7 @@ export const createNextStackPlugin = createPlugin({
       },
     },
     addGitAttributes: {
+      id: "addGitAttributes",
       description: `adding ${gitAttributesFilename}`,
       shouldRun: async () => {
         if (!(await isGitInitialized())) {