Suggested changes for CI and release automation

.github/workflows/ci.yaml

@@ -23,9 +23,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
       - name: Run Linter
-        run: npm run eslint
+        run: npm run _lint:check
       - name: Run Formatter
-        run: npm run prettier -- --check
+        run: npm run _format:check
 
   test:
     name: Test - ${{ matrix.node-version }}
@@ -62,19 +62,11 @@ jobs:
         run: npm ci
       - name: Build
         run: npm run build
+      - name: Check API
+        run: npm run _api:check
       - name: Generate docs
-        run: npm run docs:ci
-      - name: Ensure API and doc changes have been committed
-        run: |
-          git add --renormalize .
-          if (( "$(git diff HEAD --ignore-space-at-eol --ignore-cr-at-eol | wc -l)" != 0 )); then
-            cat << EOF >> $GITHUB_STEP_SUMMARY
-          ### Detected uncommitted changes
-
-          \`\`\`shell
-          $(git diff HEAD)
-          \`\`\`
-          EOF
-            git diff HEAD
-            exit 1
-          fi
+        # there is a bug in api-documenter that causes it not to respect 'lf' endings
+        # so we need to run prettier via `_docs:fix` as a workaround
+        run: npm run _docs:generate && npm run _docs:fix
+      - name: Validated generated API and doc changes have been committed
+        run: ./validate-generated-files.sh

.github/workflows/integration.yaml

@@ -40,7 +40,7 @@ jobs:
         run: |
           npm ci
           npm run build
-          echo "tough_cookie_tarball=$(npm pack)" >> "$GITHUB_OUTPUT"
+          echo "tough_cookie_tarball=$(npm pack | tail -1)" >> "$GITHUB_OUTPUT"
         working-directory: ./tough-cookie
       - name: Setup HOSTS file for Web Platform Test server
         run: ./test/web-platform-tests/tests/wpt make-hosts-file | sudo tee -a /etc/hosts
@@ -76,7 +76,7 @@ jobs:
         run: |
           npm ci
           npm run build
-          echo "tough_cookie_tarball=$(npm pack)" >> "$GITHUB_OUTPUT"
+          echo "tough_cookie_tarball=$(npm pack | tail -1)" >> "$GITHUB_OUTPUT"
         working-directory: ./tough-cookie
       - name: Setup HOSTS file for Web Platform Test server
         run: ./test/web-platform-tests/tests/wpt make-hosts-file | sudo tee -a /etc/hosts

.github/workflows/publish.yaml

@@ -19,27 +19,13 @@ jobs:
         with:
           node-version: lts/*
           cache: npm
-      - run: npm ci
-      - run: npm run prettier -- --check
-      - run: npm run lint
-      - run: npm run build
-      - run: npm run docs:ci
-      - name: Validate up-to-date documentation
-        run: |
-          git add --renormalize .
-          if (( "$(git diff HEAD --ignore-space-at-eol --ignore-cr-at-eol | wc -l)" != 0 )); then
-            cat << EOF >> $GITHUB_STEP_SUMMARY
-          ### Detected uncommitted changes
-
-          \`\`\`shell
-          $(git diff HEAD)
-          \`\`\`
-          EOF
-            git diff HEAD
-            exit 1
-          fi
-
-      - run: npm test
-      - run: npm publish --provenance
+      - name: Install dependencies
+        run: npm ci
+      - name: Rebuild generated files
+        run: npm run prepare-pr
+      - name: Validated generated API and doc changes have been committed
+        run: ./validate-generated-files.sh
+      - name: Publish
+        run: npm publish --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package.json

@@ -92,23 +92,25 @@
     "!__tests__"
   ],
   "scripts": {
-    "docs": "npm run build && npm run docs:ci",
-    "docs:ci": "npm run docs:extract -- --local && npm run docs:generate",
-    "docs:generate": "api-documenter markdown --input-folder ./tmp --output-folder ./api/docs",
-    "docs:extract": "api-extractor run --verbose",
-    "build": "npm run clean && tsc",
-    "clean": "rm -rf dist",
-    "version:version-file": "genversion --template version-template.ejs --force lib/version.ts",
-    "version": "npm run version:version-file && npm run docs && git add ./lib/version.ts ./api/docs",
-    "test": "npm run test:ts && npm run test:legacy",
-    "test:ts": "jest",
-    "test:legacy": "npm run build -- --declaration false && ./test/scripts/vows.js test/*_test.js",
-    "typecheck": "tsc --noEmit",
-    "cover": "jest --coverage",
-    "lint": "eslint .",
-    "eslint": "eslint .",
-    "prettier": "prettier .",
-    "format": "npm run eslint -- --fix"
+    "build": "npm run _build:clean && npm run _build:compile",
+    "lint": "npm run _lint:check",
+    "prepack": "npm run build",
+    "prepare-pr": "npm test && npm run _api:update && npm run _docs:generate && npm run _format:fix && npm run _lint:fix",
+    "test": "npm run build && npm run _test:ts && npm run _test:legacy",
+    "version": "npm run _version:generate && npm run prepare-pr && git add --renormalize .",
+    "_api:check": "api-extractor run --verbose",
+    "_api:update": "api-extractor run --verbose --local",
+    "_build:clean": "rm -rf dist",
+    "_build:compile": "tsc",
+    "_docs:generate": "api-documenter markdown --input-folder ./tmp --output-folder ./api/docs",
+    "_docs:fix": "prettier ./api/docs --write",
+    "_format:check": "prettier . --check",
+    "_format:fix": "prettier . --write",
+    "_lint:check": "eslint .",
+    "_lint:fix": "eslint . --fix",
+    "_test:legacy": "./test/scripts/vows.js test/*_test.js",
+    "_test:ts": "jest",
+    "_version:generate": "genversion --template version-template.ejs --force lib/version.ts"
   },
   "//": "We only support node 18+, but v16 still works. We won't block v16 until it becomes a burden.",
   "engines": {

validate-generated-files.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+git add --renormalize .
+
+if (( "$(git diff HEAD | wc -l)" != 0 )); then
+  summary=$(cat << EOF
+### Detected uncommitted changes from generated files
+
+Use \`npm run precommit\` to ensure that all generated content is up-to-date.
+
+\`\`\`shell
+$(git diff HEAD)
+\`\`\`
+EOF
+)
+  if [ -n "$GITHUB_STEP_SUMMARY" ]; then
+    echo "$summary" >> "$GITHUB_STEP_SUMMARY"
+  fi
+  git --no-pager diff HEAD
+  exit 1
+fi