feat(ci): add ci/cd

.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: lts/*
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint & Format
+        run: npm run lint && npm run format:check
+
+  docs-check:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Read HEAD_COMMIT
+        id: webpack-ref
+        run: echo "ref=$(cat HEAD_COMMIT)" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout webpack
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: webpack/webpack
+          ref: ${{ steps.webpack-ref.outputs.ref }}
+          path: webpack
+
+      - name: Setup Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: lts/*
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Regenerate docs
+        run: npm run generate-docs
+
+      - name: Check docs freshness
+        run: |
+          if ! git diff --quiet pages/; then
+            echo "::error::The pages/ directory is out of date. Run 'npm run generate-docs' and commit the changes."
+            git diff --stat pages/
+            exit 1
+          fi
+          echo "pages/ is up to date."

.github/workflows/deploy.yml

@@ -6,7 +6,7 @@ on:
     branches: [main]
 
 permissions:
-    contents: read
+  contents: read
 
 jobs:
   # Build job
@@ -17,17 +17,22 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Checkout code
+      - name: Read HEAD_COMMIT
+        id: webpack-ref
+        run: echo "ref=$(cat HEAD_COMMIT)" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout webpack
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-            repository: webpack/webpack
-            path: webpack
+          repository: webpack/webpack
+          ref: ${{ steps.webpack-ref.outputs.ref }}
+          path: webpack
 
       - name: Setup Node.js
         uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version: lts/*
-          cache: 'npm'
+          cache: "npm"
 
       - name: Install dependencies
         run: npm ci
@@ -39,7 +44,7 @@ jobs:
         uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
         with:
           path: out/
-          
+
   deploy:
     needs: build
 
@@ -55,4 +60,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.github/workflows/sync.yml

@@ -0,0 +1,74 @@
+name: Sync Webpack
+
+on:
+  schedule:
+    # Run every 24 hours at 04:00 UTC
+    - cron: "0 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Get latest webpack commit
+        id: latest
+        run: |
+          LATEST=$(git ls-remote https://github.com/webpack/webpack.git refs/heads/main | cut -f1)
+          CURRENT=$(cat HEAD_COMMIT)
+          echo "latest=$LATEST" >> "$GITHUB_OUTPUT"
+          echo "current=$CURRENT" >> "$GITHUB_OUTPUT"
+          echo "Latest webpack commit: $LATEST"
+          echo "Current pinned commit: $CURRENT"
+
+      - name: Check for changes
+        id: check
+        run: |
+          if [ "${{ steps.latest.outputs.latest }}" = "${{ steps.latest.outputs.current }}" ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "No changes detected, skipping sync."
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "New webpack commit detected, syncing."
+          fi
+
+      - name: Checkout webpack
+        if: steps.check.outputs.changed == 'true'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: webpack/webpack
+          ref: ${{ steps.latest.outputs.latest }}
+          path: webpack
+
+      - name: Setup Node.js
+        if: steps.check.outputs.changed == 'true'
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: lts/*
+          cache: "npm"
+
+      - name: Install dependencies
+        if: steps.check.outputs.changed == 'true'
+        run: npm ci
+
+      - name: Update HEAD_COMMIT
+        if: steps.check.outputs.changed == 'true'
+        run: echo "${{ steps.latest.outputs.latest }}" > HEAD_COMMIT
+
+      - name: Regenerate docs
+        if: steps.check.outputs.changed == 'true'
+        run: npm run generate-docs
+
+      - name: Commit and push
+        if: steps.check.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add HEAD_COMMIT pages/
+          git commit -m "chore: sync webpack docs to $(echo ${{ steps.latest.outputs.latest }} | cut -c1-7)"
+          git push

.gitignore

@@ -1,4 +1,4 @@
 node_modules
 out
-generated-*
-webpack
+*.generated.*
+/webpack

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

.lintstagedrc

@@ -0,0 +1,6 @@
+{
+  "**/*.{js,mjs,ts,tsx,md,mdx,json.yml}": [
+    "eslint --fix",
+    "prettier --check --write"
+  ]
+}

.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+out
+*.generated.*
+/webpack
+pages
+.husky

HEAD_COMMIT

@@ -0,0 +1 @@
+214f361891d8f51f41bafb2e760cb3240d6014be

README.md

@@ -0,0 +1,54 @@
+# webpack-doc-kit
+
+Automated TypeScript API documentation generator for [webpack](https://github.com/webpack/webpack). Extracts type definitions from webpack's `types.d.ts` and produces Markdown and HTML documentation, deployed to GitHub Pages.
+
+## How It Works
+
+1. **TypeDoc** reads webpack's TypeScript type definitions
+2. Custom plugins process the output (namespace merging, type mapping, themed rendering)
+3. **@node-core/doc-kit** converts Markdown to HTML
+4. GitHub Actions deploys the result to GitHub Pages
+
+### Webpack Version Tracking
+
+The `HEAD_COMMIT` file pins the exact webpack/webpack commit used for doc generation. A scheduled GitHub Action runs every 24 hours to:
+
+1. Fetch the latest webpack `main` branch HEAD
+2. Update `HEAD_COMMIT`
+3. Regenerate documentation
+4. Push the changes to this repository
+
+This ensures documentation stays in sync with upstream webpack without manual intervention.
+
+## Project Structure
+
+```
+├── generate-md.mjs          # TypeDoc entry point
+├── plugins/
+│   ├── processor.mjs         # Namespace merging + type-map generation
+│   └── theme/                # Custom doc-kit theme
+├── HEAD_COMMIT               # Pinned webpack commit SHA
+├── .github/workflows/
+│   ├── ci.yml                # Lint + doc generation check
+│   ├── deploy.yml            # Build HTML + deploy to GitHub Pages
+│   └── sync.yml              # Daily webpack sync
+└── package.json
+```
+
+## Scripts
+
+| Script                  | Description                          |
+| ----------------------- | ------------------------------------ |
+| `npm run generate-docs` | Generate Markdown from webpack types |
+| `npm run build-html`    | Convert Markdown to HTML             |
+| `npm run build`         | Generate docs + build HTML           |
+| `npm run lint`          | Run ESLint                           |
+| `npm run format:check`  | Check Prettier formatting            |
+
+## Contributing
+
+When making changes to documentation generation (plugins, `generate-md.mjs`, `tsconfig.json`), ensure the docs can still be generated successfully. CI will verify this on every pull request.
+
+## License
+
+See the [webpack project](https://github.com/webpack/webpack) for license details.

eslint.config.mjs

@@ -0,0 +1,16 @@
+import js from "@eslint/js";
+import globals from "globals";
+
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: globals.node,
+    },
+  },
+  {
+    ignores: ["node_modules/", "out/", "webpack/"],
+  },
+];

generate-md.mjs

@@ -1,27 +1,29 @@
-import { Application } from 'typedoc';
+import { Application } from "typedoc";
+import webpack from "./webpack/package.json" with { type: "json" };
+import { major } from "semver";
 
 const app = await Application.bootstrapWithPlugins({
-  entryPoints: ['./webpack/types.d.ts'],
-  out: 'generated-api',
+  entryPoints: ["./webpack/types.d.ts"],
+  out: `pages/v${major(webpack.version)}.x`,
 
   // Plugins
   plugin: [
-    'typedoc-plugin-markdown',
-    './plugins/processor.mjs',
-    './plugins/theme/index.mjs',
+    "typedoc-plugin-markdown",
+    "./plugins/processor.mjs",
+    "./plugins/theme/index.mjs",
   ],
-  theme: 'doc-kit',
+  theme: "doc-kit",
 
   // Formatting
   hideGroupHeadings: true,
   hideBreadcrumbs: true,
   hidePageHeader: true,
   disableSources: true,
 
-  router: 'module',
-  entryFileName: 'index',
+  router: "module",
+  entryFileName: "index",
 
-  tsconfig: 'tsconfig.json',
+  tsconfig: "tsconfig.json",
 });
 
 const project = await app.convert();