dx: improve local docs quickstart with bootstrap + smart pipeline runner

README.md

@@ -37,13 +37,114 @@ This ensures documentation stays in sync with upstream webpack without manual in
 
 ## 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            |
+| 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 bootstrap:webpack` | Clone/update local webpack source at `HEAD_COMMIT`                |
+| `npm run docs:quickstart`   | Run bootstrap + markdown generation + HTML build with smart skips |
+| `npm run docs:doctor`       | Run quickstart pipeline in verbose mode                           |
+| `npm run lint`              | Run ESLint                                                        |
+| `npm run format:check`      | Check Prettier formatting                                         |
+
+## Local Quickstart
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Bootstrap local webpack source to the commit pinned in `HEAD_COMMIT`:
+
+```bash
+npm run bootstrap:webpack
+```
+
+Generate markdown docs:
+
+```bash
+npm run generate-docs
+```
+
+Build HTML output:
+
+```bash
+npm run build-html
+```
+
+Or run everything in one command:
+
+```bash
+npm run docs:quickstart
+```
+
+Useful flags for the quickstart runner:
+
+- `--force` reruns every step
+- `--verbose` prints detailed diagnostics
+- `--no-html` skips the HTML build
+
+Example:
+
+```bash
+node scripts/docs-pipeline.mjs --force --verbose
+```
+
+## Troubleshooting
+
+### Missing webpack folder
+
+If `npm run generate-docs` fails with "Webpack source not found", run:
+
+```bash
+npm run bootstrap:webpack
+```
+
+### Wrong webpack commit
+
+If local webpack is out of sync with `HEAD_COMMIT`, run:
+
+```bash
+npm run bootstrap:webpack
+```
+
+This updates `./webpack` and checks out the exact pinned commit.
+
+### Stale output
+
+If you need to regenerate everything regardless of skip checks:
+
+```bash
+node scripts/docs-pipeline.mjs --force
+```
+
+## Contributor Workflow
+
+1. Bootstrap webpack source:
+
+```bash
+npm run bootstrap:webpack
+```
+
+2. Regenerate markdown docs:
+
+```bash
+npm run generate-docs
+```
+
+3. Build HTML output:
+
+```bash
+npm run build-html
+```
+
+Output locations:
+
+- Markdown: `pages/vX.x/`
+- Type map: `pages/vX.x/type-map.json`
+- HTML site: `out/`
 
 ## Contributing
 

generate-md.mjs

@@ -1,6 +1,21 @@
 import { Application } from 'typedoc';
-import webpack from './webpack/package.json' with { type: 'json' };
 import { major } from 'semver';
+import { existsSync, readFileSync } from 'node:fs';
+
+if (!existsSync('./webpack')) {
+  throw new Error('Webpack source not found. Run: npm run bootstrap:webpack');
+}
+
+if (
+  !existsSync('./webpack/package.json') ||
+  !existsSync('./webpack/types.d.ts')
+) {
+  throw new Error(
+    'Webpack source is incomplete. Run: npm run bootstrap:webpack'
+  );
+}
+
+const webpack = JSON.parse(readFileSync('./webpack/package.json', 'utf8'));
 
 const app = await Application.bootstrapWithPlugins({
   entryPoints: ['./webpack/types.d.ts'],

package.json

@@ -3,6 +3,9 @@
     "generate-docs": "node generate-md.mjs",
     "build-html": "doc-kit generate -t web --config-file ./doc-kit.config.mjs",
     "build": "npm run generate-docs && npm run build-html",
+    "bootstrap:webpack": "node scripts/bootstrap-webpack.mjs",
+    "docs:quickstart": "node scripts/docs-pipeline.mjs",
+    "docs:doctor": "node scripts/docs-pipeline.mjs --verbose",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "format": "prettier --write .",

scripts/bootstrap-webpack.mjs

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const ROOT = process.cwd();
+const WEBPACK_DIR = resolve(ROOT, 'webpack');
+const HEAD_COMMIT_FILE = resolve(ROOT, 'HEAD_COMMIT');
+const WEBPACK_REPO_URL = 'https://github.com/webpack/webpack.git';
+
+const log = message => {
+  console.log(`[bootstrap:webpack] ${message}`);
+};
+
+const run = (command, args, options = {}) => {
+  const result = spawnSync(command, args, {
+    cwd: ROOT,
+    stdio: 'inherit',
+    ...options,
+  });
+
+  if (result.status !== 0) {
+    const fullCommand = [command, ...args].join(' ');
+    throw new Error(`Command failed: ${fullCommand}`);
+  }
+};
+
+const runCapture = (command, args, options = {}) => {
+  const result = spawnSync(command, args, {
+    cwd: ROOT,
+    encoding: 'utf8',
+    ...options,
+  });
+
+  if (result.status !== 0) {
+    const fullCommand = [command, ...args].join(' ');
+    throw new Error(`Command failed: ${fullCommand}`);
+  }
+
+  return result.stdout.trim();
+};
+
+if (!existsSync(HEAD_COMMIT_FILE)) {
+  throw new Error('Missing HEAD_COMMIT file.');
+}
+
+const targetCommit = readFileSync(HEAD_COMMIT_FILE, 'utf8').trim();
+
+if (!/^[a-f0-9]{40}$/i.test(targetCommit)) {
+  throw new Error(`Invalid commit SHA in HEAD_COMMIT: ${targetCommit}`);
+}
+
+let currentCommit = null;
+
+if (existsSync(WEBPACK_DIR)) {
+  if (!existsSync(resolve(WEBPACK_DIR, '.git'))) {
+    throw new Error('webpack directory exists but is not a git repository.');
+  }
+
+  currentCommit = runCapture('git', ['-C', WEBPACK_DIR, 'rev-parse', 'HEAD']);
+}
+
+if (currentCommit === targetCommit) {
+  log(`Already up to date at ${targetCommit}.`);
+  process.exit(0);
+}
+
+if (!existsSync(WEBPACK_DIR)) {
+  log('Cloning webpack repository...');
+  run('git', ['clone', WEBPACK_REPO_URL, WEBPACK_DIR]);
+} else {
+  log('Updating existing webpack repository...');
+}
+
+run('git', ['-C', WEBPACK_DIR, 'fetch', '--all', '--tags', '--prune']);
+run('git', ['-C', WEBPACK_DIR, 'checkout', '--detach', targetCommit]);
+
+const checkedOutCommit = runCapture('git', [
+  '-C',
+  WEBPACK_DIR,
+  'rev-parse',
+  'HEAD',
+]);
+log(`Checked out ${checkedOutCommit}.`);