feat(GHA): workflow file creation onboarding (#577)

* fix: make command type more specific * refactor: consolidate `key` opt definition * fix: stricter type definition * chore: small copy change * refactor: small function change doing this so we can preserve the `this` scope * fix: lint * feat: first pass at GHA generation * feat: add `--github` flag * fix: allow user to not pass in spec path * chore: small copy change * fix: cleaning up a type, adding a smol doc * test: add coverage for if user says no * refactor: new function signature, better typings * test: smol refactor * test: remove unused mock * fix: better type * fix: remove unused async * refactor: remove github API fetch after thinking about it some more, this doesn't feel necessary since we can just grab it from the current package. it also might cause issues if we create a broken workflow file due to breaking changes. instead we should add a dependabot config. * refactor: better command string construction i like this way just in case the opts string is empty (which is unlikely but w/e) * chore: some base file copy updates * refactor: make isGitHub file more generic * refactor: consolidate CI checks into shared function * feat: prevent user from running --github in CI env * feat: first pass at git detection * test: add some test cases not sure why these are failing 🤔 * chore: skip failing tests to see if CI passes * fix: move regex to inside function Tests were failing because we had defined our regex expressions globally * test:: smol refactor * test: refactor to describe.each() this will be a lot faster when writing tests for other suites * test: add test for git check failure * feat: add openapi command extension also some basic tests * fix: shorten github search * test: oops * test: add workflow file schema validation * test: reorganizing test bed a bit * chore: better test coverage, smol nits * fix: better filename input validation also adding some small nits and a few more tests * chore: clean up unused interfaces i really don't understand what's going on here lol * fix(openapi): add `update` param to ignored params * fix: use `.yml` instead of `.yaml` Maybe I'm overthinking this, but I feel like GitHub likes `.yml` more than `.yaml`... my evidence: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file https://docs.github.com/en/actions/using-workflows/about-workflows#create-an-example-workflow In all of these examples, GitHub uses `.yml` either first or exclusively :monocle: * test: more CI tests * refactor: move helper function to separate file * chore: different language updating tests and snapshots * test: stronger test * chore: smol refactor * test(validate): e2e tests * chore: rename function * fix: use JS string instead of YAML file wrote about why we're doing this in the comments, but yay for snapshot testing because this yields the exact same results! * fix: handle directory creation * chore: smol link comment * feat: configstore to ensure we don't ask user too many times * test: fix tests * chore: command comment * chore(openapi): update args * chore: clean up some comments * refactor: stricter types also slightly updating file name question per feedback from @RyanGWU82 * feat: support for docs/index * feat: add GHA functionality for docs-adjacent cmds * fix: clean up command name prior to using as YAML keys g*d bless tests y'all * test: add tests for docs-adjacent cmds * test: consolidate certain test mocks * fix(openapi): parameter logic fixes this also includes E2E tests that ended up exposing some cracks in the `ignoredGHAParameters` logic I had originally written. * fix: lint * fix: console.log that i forgot to commit lol * test: smol refactor * feat: do major version check for configstore * fix: separate out package version retrieval into function this way we can mock out our package version easily and we don't need to update our snapshots every time we bump our package version 😬 * chore: error message language * docs: github **actions** workflow, not github action (singular) * docs: better intro language * docs: better success language * chore: fix snapshot, de-localize docs link * chore: smol language update per Spang * test: don't fetch schema from URL #577 (comment) * test: update broken test * test(GHA): extract setup/teardowns into common lib Feedback: #577 (comment) * test: better describe.each signature Feedback: #577 (comment) Co-Authored-By: Jon Ursenbach <[email protected]> * chore: debug statements * fix: weird flaky TS error * refactor: use decorator unfortunately this isn't exactly where we want it to be—we still have to manually add the `--github` arg to the command definitions. also adding some tests for this new functionality. feedback: #577 (comment) Co-Authored-By: Jon Ursenbach <[email protected]> * chore(mock/fs): clearer var names also removed the unnecessary boolean return value since it's a void function Co-authored-by: Jon Ursenbach <[email protected]>
readmeio · Sep 6, 2022 · 9ee808e · 9ee808e
1 parent 625a9d8
commit 9ee808e
Show file tree

Hide file tree

Showing 49 changed files with 5,699 additions and 514 deletions.
diff --git a/.github/workflows/retag-release.yaml b/.github/workflows/retag-release.yaml
@@ -1,7 +1,7 @@
 # This script adds a "vX.Y.Z" tag to every new release.
 #
 # Our releases are tagged like "1.2.3" but we want people to be able to write
-# GitHub Action workflows to say "uses: readmeio/[email protected]" because that's
+# GitHub Actions workflows to say "uses: readmeio/[email protected]" because that's
 # the usual GitHub convention.
 
 name: retag-release

diff --git a/__tests__/__snapshots__/index.test.ts.snap b/__tests__/__snapshots__/index.test.ts.snap
@@ -15,10 +15,11 @@ Options
                               uploading an existing API definition.                                 
   --version string            Project version. If running command in a CI environment and this      
                               option is not passed, the main project version will be used.          
-  --create                    Bypasses the create/update prompt and creates a new API definition.   
   --useSpecVersion            Uses the version listed in the \`info.version\` field in the API        
                               definition for the project version parameter.                         
+  --github                    Create a new GitHub Actions workflow for this command.                
   --workingDirectory string   Working directory (for usage with relative external references)       
+  --create                    Bypasses the create/update prompt and creates a new API definition.   
   --update                    Automatically update an existing API definition in ReadMe if it's the 
                               only one associated with the current version.                         
   -h, --help                  Display this usage guide                                              
@@ -45,10 +46,11 @@ Options
                               uploading an existing API definition.                                 
   --version string            Project version. If running command in a CI environment and this      
                               option is not passed, the main project version will be used.          
-  --create                    Bypasses the create/update prompt and creates a new API definition.   
   --useSpecVersion            Uses the version listed in the \`info.version\` field in the API        
                               definition for the project version parameter.                         
+  --github                    Create a new GitHub Actions workflow for this command.                
   --workingDirectory string   Working directory (for usage with relative external references)       
+  --create                    Bypasses the create/update prompt and creates a new API definition.   
   --update                    Automatically update an existing API definition in ReadMe if it's the 
                               only one associated with the current version.                         
   -h, --help                  Display this usage guide                                              
@@ -75,10 +77,11 @@ Options
                               uploading an existing API definition.                                 
   --version string            Project version. If running command in a CI environment and this      
                               option is not passed, the main project version will be used.          
-  --create                    Bypasses the create/update prompt and creates a new API definition.   
   --useSpecVersion            Uses the version listed in the \`info.version\` field in the API        
                               definition for the project version parameter.                         
+  --github                    Create a new GitHub Actions workflow for this command.                
   --workingDirectory string   Working directory (for usage with relative external references)       
+  --create                    Bypasses the create/update prompt and creates a new API definition.   
   --update                    Automatically update an existing API definition in ReadMe if it's the 
                               only one associated with the current version.                         
   -h, --help                  Display this usage guide                                              

diff --git a/__tests__/cmds/__snapshots__/validate.test.ts.snap b/__tests__/cmds/__snapshots__/validate.test.ts.snap
@@ -1,5 +1,153 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (github flag enabled) 1`] = `
+"
+Your GitHub Actions workflow file has been created! ✨
+
+Almost done! Push your newly created file (.github/workflows/validate-test-opt-spec-github-file.yml) to GitHub and you're all set 🚀
+
+🦉 If you have any more questions, feel free to drop us a line! [email protected]
+"
+`;
+
+exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (github flag enabled) 2`] = `
+"# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
+# You can view our full documentation here: https://docs.readme.com/docs/rdme
+name: ReadMe GitHub Action 🦉
+
+on:
+  push:
+    branches:
+      # This workflow will run every time you push code to the following branch: \`validate-test-opt-spec-github-branch\`
+      # Check out GitHub's docs for more info on configuring this:
+      # https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
+      - validate-test-opt-spec-github-branch
+
+jobs:
+  rdme-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo 📚
+        uses: actions/checkout@v3
+
+      - name: Run \`validate\` command 🚀
+        uses: readmeio/[email protected]
+        with:
+          rdme: validate __tests__/__fixtures__/petstore-simple-weird-version.json
+"
+`;
+
+exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (including workingDirectory) 1`] = `
+"
+Your GitHub Actions workflow file has been created! ✨
+
+Almost done! Push your newly created file (.github/workflows/validate-test-opt-spec-workdir-file.yml) to GitHub and you're all set 🚀
+
+🦉 If you have any more questions, feel free to drop us a line! [email protected]
+"
+`;
+
+exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (including workingDirectory) 2`] = `
+"# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
+# You can view our full documentation here: https://docs.readme.com/docs/rdme
+name: ReadMe GitHub Action 🦉
+
+on:
+  push:
+    branches:
+      # This workflow will run every time you push code to the following branch: \`validate-test-opt-spec-github-branch\`
+      # Check out GitHub's docs for more info on configuring this:
+      # https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
+      - validate-test-opt-spec-github-branch
+
+jobs:
+  rdme-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo 📚
+        uses: actions/checkout@v3
+
+      - name: Run \`validate\` command 🚀
+        uses: readmeio/[email protected]
+        with:
+          rdme: validate petstore.json --workingDirectory=./__tests__/__fixtures__/relative-ref-oas
+"
+`;
+
+exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt 1`] = `
+"
+Your GitHub Actions workflow file has been created! ✨
+
+Almost done! Push your newly created file (.github/workflows/validate-test-opt-spec-file.yml) to GitHub and you're all set 🚀
+
+🦉 If you have any more questions, feel free to drop us a line! [email protected]
+"
+`;
+
+exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt 2`] = `
+"# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
+# You can view our full documentation here: https://docs.readme.com/docs/rdme
+name: ReadMe GitHub Action 🦉
+
+on:
+  push:
+    branches:
+      # This workflow will run every time you push code to the following branch: \`validate-test-opt-spec-branch\`
+      # Check out GitHub's docs for more info on configuring this:
+      # https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
+      - validate-test-opt-spec-branch
+
+jobs:
+  rdme-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo 📚
+        uses: actions/checkout@v3
+
+      - name: Run \`validate\` command 🚀
+        uses: readmeio/[email protected]
+        with:
+          rdme: validate __tests__/__fixtures__/petstore-simple-weird-version.json
+"
+`;
+
+exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via prompts 1`] = `
+"
+Your GitHub Actions workflow file has been created! ✨
+
+Almost done! Push your newly created file (.github/workflows/validate-test-file.yml) to GitHub and you're all set 🚀
+
+🦉 If you have any more questions, feel free to drop us a line! [email protected]
+"
+`;
+
+exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via prompts 2`] = `
+"# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
+# You can view our full documentation here: https://docs.readme.com/docs/rdme
+name: ReadMe GitHub Action 🦉
+
+on:
+  push:
+    branches:
+      # This workflow will run every time you push code to the following branch: \`validate-test-branch\`
+      # Check out GitHub's docs for more info on configuring this:
+      # https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
+      - validate-test-branch
+
+jobs:
+  rdme-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo 📚
+        uses: actions/checkout@v3
+
+      - name: Run \`validate\` command 🚀
+        uses: readmeio/[email protected]
+        with:
+          rdme: validate __tests__/__fixtures__/petstore-simple-weird-version.json
+"
+`;
+
 exports[`rdme validate error handling should throw an error if an invalid OpenAPI 3.1 definition is supplied 1`] = `
 [SyntaxError: OpenAPI schema validation failed.
 

diff --git a/__tests__/cmds/docs/__snapshots__/index.test.ts.snap b/__tests__/cmds/docs/__snapshots__/index.test.ts.snap
@@ -0,0 +1,124 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`rdme docs GHA onboarding E2E tests should create GHA workflow with version passed as opt (github flag enabled) 1`] = `
+"
+Your GitHub Actions workflow file has been created! ✨
+
+Almost done! Just a couple more steps:
+1. Push your newly created file (.github/workflows/docs-test-file-github-flag.yml) to GitHub 🚀
+2. Create a GitHub secret called README_API_KEY and populate the value with your ReadMe API key (••••••••••••I_KEY) 🔑
+
+🔐 Check out GitHub's docs for more info on creating encrypted secrets (https://docs.github.com/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)
+
+🦉 If you have any more questions, feel free to drop us a line! [email protected]
+"
+`;
+
+exports[`rdme docs GHA onboarding E2E tests should create GHA workflow with version passed as opt (github flag enabled) 2`] = `
+"# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
+# You can view our full documentation here: https://docs.readme.com/docs/rdme
+name: ReadMe GitHub Action 🦉
+
+on:
+  push:
+    branches:
+      # This workflow will run every time you push code to the following branch: \`docs-test-branch-github-flag\`
+      # Check out GitHub's docs for more info on configuring this:
+      # https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
+      - docs-test-branch-github-flag
+
+jobs:
+  rdme-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo 📚
+        uses: actions/checkout@v3
+
+      - name: Run \`docs\` command 🚀
+        uses: readmeio/[email protected]
+        with:
+          rdme: docs ./__tests__/__fixtures__/docs/new-docs --key=\${{ secrets.README_API_KEY }} --version=1.0.0
+"
+`;
+
+exports[`rdme docs GHA onboarding E2E tests should create GHA workflow with version passed in via opt 1`] = `
+"
+Your GitHub Actions workflow file has been created! ✨
+
+Almost done! Just a couple more steps:
+1. Push your newly created file (.github/workflows/docs-test-file.yml) to GitHub 🚀
+2. Create a GitHub secret called README_API_KEY and populate the value with your ReadMe API key (••••••••••••I_KEY) 🔑
+
+🔐 Check out GitHub's docs for more info on creating encrypted secrets (https://docs.github.com/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)
+
+🦉 If you have any more questions, feel free to drop us a line! [email protected]
+"
+`;
+
+exports[`rdme docs GHA onboarding E2E tests should create GHA workflow with version passed in via opt 2`] = `
+"# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
+# You can view our full documentation here: https://docs.readme.com/docs/rdme
+name: ReadMe GitHub Action 🦉
+
+on:
+  push:
+    branches:
+      # This workflow will run every time you push code to the following branch: \`docs-test-branch\`
+      # Check out GitHub's docs for more info on configuring this:
+      # https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
+      - docs-test-branch
+
+jobs:
+  rdme-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo 📚
+        uses: actions/checkout@v3
+
+      - name: Run \`docs\` command 🚀
+        uses: readmeio/[email protected]
+        with:
+          rdme: docs ./__tests__/__fixtures__/docs/new-docs --key=\${{ secrets.README_API_KEY }} --version=1.0.0
+"
+`;
+
+exports[`rdme docs GHA onboarding E2E tests should create GHA workflow with version passed in via prompt 1`] = `
+"
+Your GitHub Actions workflow file has been created! ✨
+
+Almost done! Just a couple more steps:
+1. Push your newly created file (.github/workflows/docs-test-file.yml) to GitHub 🚀
+2. Create a GitHub secret called README_API_KEY and populate the value with your ReadMe API key (••••••••••••I_KEY) 🔑
+
+🔐 Check out GitHub's docs for more info on creating encrypted secrets (https://docs.github.com/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)
+
+🦉 If you have any more questions, feel free to drop us a line! [email protected]
+"
+`;
+
+exports[`rdme docs GHA onboarding E2E tests should create GHA workflow with version passed in via prompt 2`] = `
+"# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
+# You can view our full documentation here: https://docs.readme.com/docs/rdme
+name: ReadMe GitHub Action 🦉
+
+on:
+  push:
+    branches:
+      # This workflow will run every time you push code to the following branch: \`docs-test-branch\`
+      # Check out GitHub's docs for more info on configuring this:
+      # https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
+      - docs-test-branch
+
+jobs:
+  rdme-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo 📚
+        uses: actions/checkout@v3
+
+      - name: Run \`docs\` command 🚀
+        uses: readmeio/[email protected]
+        with:
+          rdme: docs ./__tests__/__fixtures__/docs/new-docs --key=\${{ secrets.README_API_KEY }} --version=1.0.1
+"
+`;