Skip to content

Commit e5b8286

Browse files
avivkelleravivkeller
authored
Merge pull request #12 from webpack/cicd
feat(ci): add ci/cd
2 parents 2771c0e + 91fb4a7 commit e5b8286

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

57 files changed

+21185
-642
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
lint:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout code
16+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
17+
18+
- name: Setup Node.js
19+
uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
20+
with:
21+
node-version: lts/*
22+
cache: "npm"
23+
24+
- name: Install dependencies
25+
run: npm ci
26+
27+
- name: Lint & Format
28+
run: npm run lint && npm run format:check
29+
30+
docs-check:
31+
if: github.event_name == 'pull_request'
32+
runs-on: ubuntu-latest
33+
steps:
34+
- name: Checkout code
35+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
36+
37+
- name: Read HEAD_COMMIT
38+
id: webpack-ref
39+
run: echo "ref=$(cat HEAD_COMMIT)" >> "$GITHUB_OUTPUT"
40+
41+
- name: Checkout webpack
42+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
43+
with:
44+
repository: webpack/webpack
45+
ref: ${{ steps.webpack-ref.outputs.ref }}
46+
path: webpack
47+
48+
- name: Setup Node.js
49+
uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
50+
with:
51+
node-version: lts/*
52+
cache: "npm"
53+
54+
- name: Install dependencies
55+
run: npm ci
56+
57+
- name: Regenerate docs
58+
run: npm run generate-docs
59+
60+
- name: Check docs freshness
61+
run: |
62+
if ! git diff --quiet pages/; then
63+
echo "::error::The pages/ directory is out of date. Run 'npm run generate-docs' and commit the changes."
64+
git diff --stat pages/
65+
exit 1
66+
fi
67+
echo "pages/ is up to date."

‎.github/workflows/deploy.yml‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ on:
66
branches: [main]
77

88
permissions:
9-
contents: read
9+
contents: read
1010

1111
jobs:
1212
# Build job
@@ -17,17 +17,22 @@ jobs:
1717
- name: Checkout code
1818
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
1919

20-
- name: Checkout code
20+
- name: Read HEAD_COMMIT
21+
id: webpack-ref
22+
run: echo "ref=$(cat HEAD_COMMIT)" >> "$GITHUB_OUTPUT"
23+
24+
- name: Checkout webpack
2125
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
2226
with:
23-
repository: webpack/webpack
24-
path: webpack
27+
repository: webpack/webpack
28+
ref: ${{ steps.webpack-ref.outputs.ref }}
29+
path: webpack
2530

2631
- name: Setup Node.js
2732
uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
2833
with:
2934
node-version: lts/*
30-
cache: 'npm'
35+
cache: "npm"
3136

3237
- name: Install dependencies
3338
run: npm ci
@@ -39,7 +44,7 @@ jobs:
3944
uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
4045
with:
4146
path: out/
42-
47+
4348
deploy:
4449
needs: build
4550

@@ -55,4 +60,4 @@ jobs:
5560
steps:
5661
- name: Deploy to GitHub Pages
5762
id: deployment
58-
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
63+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

‎.github/workflows/sync.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: Sync Webpack
2+
3+
on:
4+
schedule:
5+
# Run every 24 hours at 04:00 UTC
6+
- cron: "0 4 * * *"
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: write
11+
12+
jobs:
13+
sync:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout code
17+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
18+
19+
- name: Get latest webpack commit
20+
id: latest
21+
run: |
22+
LATEST=$(git ls-remote https://github.com/webpack/webpack.git refs/heads/main | cut -f1)
23+
CURRENT=$(cat HEAD_COMMIT)
24+
echo "latest=$LATEST" >> "$GITHUB_OUTPUT"
25+
echo "current=$CURRENT" >> "$GITHUB_OUTPUT"
26+
echo "Latest webpack commit: $LATEST"
27+
echo "Current pinned commit: $CURRENT"
28+
29+
- name: Check for changes
30+
id: check
31+
run: |
32+
if [ "${{ steps.latest.outputs.latest }}" = "${{ steps.latest.outputs.current }}" ]; then
33+
echo "changed=false" >> "$GITHUB_OUTPUT"
34+
echo "No changes detected, skipping sync."
35+
else
36+
echo "changed=true" >> "$GITHUB_OUTPUT"
37+
echo "New webpack commit detected, syncing."
38+
fi
39+
40+
- name: Checkout webpack
41+
if: steps.check.outputs.changed == 'true'
42+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
43+
with:
44+
repository: webpack/webpack
45+
ref: ${{ steps.latest.outputs.latest }}
46+
path: webpack
47+
48+
- name: Setup Node.js
49+
if: steps.check.outputs.changed == 'true'
50+
uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
51+
with:
52+
node-version: lts/*
53+
cache: "npm"
54+
55+
- name: Install dependencies
56+
if: steps.check.outputs.changed == 'true'
57+
run: npm ci
58+
59+
- name: Update HEAD_COMMIT
60+
if: steps.check.outputs.changed == 'true'
61+
run: echo "${{ steps.latest.outputs.latest }}" > HEAD_COMMIT
62+
63+
- name: Regenerate docs
64+
if: steps.check.outputs.changed == 'true'
65+
run: npm run generate-docs
66+
67+
- name: Commit and push
68+
if: steps.check.outputs.changed == 'true'
69+
run: |
70+
git config user.name "github-actions[bot]"
71+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
72+
git add HEAD_COMMIT pages/
73+
git commit -m "chore: sync webpack docs to $(echo ${{ steps.latest.outputs.latest }} | cut -c1-7)"
74+
git push

‎.gitignore‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
node_modules
22
out
3-
generated-*
4-
webpack
3+
*.generated.*
4+
/webpack

‎.husky/pre-commit‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
npx lint-staged

‎.lintstagedrc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"**/*.{js,mjs,ts,tsx,md,mdx,json.yml}": [
3+
"eslint --fix",
4+
"prettier --check --write"
5+
]
6+
}

‎.prettierignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules
2+
out
3+
*.generated.*
4+
/webpack
5+
pages
6+
.husky

‎HEAD_COMMIT‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
214f361891d8f51f41bafb2e760cb3240d6014be

‎README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# webpack-doc-kit
2+
3+
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.
4+
5+
## How It Works
6+
7+
1. **TypeDoc** reads webpack's TypeScript type definitions
8+
2. Custom plugins process the output (namespace merging, type mapping, themed rendering)
9+
3. **@node-core/doc-kit** converts Markdown to HTML
10+
4. GitHub Actions deploys the result to GitHub Pages
11+
12+
### Webpack Version Tracking
13+
14+
The `HEAD_COMMIT` file pins the exact webpack/webpack commit used for doc generation. A scheduled GitHub Action runs every 24 hours to:
15+
16+
1. Fetch the latest webpack `main` branch HEAD
17+
2. Update `HEAD_COMMIT`
18+
3. Regenerate documentation
19+
4. Push the changes to this repository
20+
21+
This ensures documentation stays in sync with upstream webpack without manual intervention.
22+
23+
## Project Structure
24+
25+
```
26+
├── generate-md.mjs # TypeDoc entry point
27+
├── plugins/
28+
│ ├── processor.mjs # Namespace merging + type-map generation
29+
│ └── theme/ # Custom doc-kit theme
30+
├── HEAD_COMMIT # Pinned webpack commit SHA
31+
├── .github/workflows/
32+
│ ├── ci.yml # Lint + doc generation check
33+
│ ├── deploy.yml # Build HTML + deploy to GitHub Pages
34+
│ └── sync.yml # Daily webpack sync
35+
└── package.json
36+
```
37+
38+
## Scripts
39+
40+
| Script | Description |
41+
| ----------------------- | ------------------------------------ |
42+
| `npm run generate-docs` | Generate Markdown from webpack types |
43+
| `npm run build-html` | Convert Markdown to HTML |
44+
| `npm run build` | Generate docs + build HTML |
45+
| `npm run lint` | Run ESLint |
46+
| `npm run format:check` | Check Prettier formatting |
47+
48+
## Contributing
49+
50+
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.
51+
52+
## License
53+
54+
See the [webpack project](https://github.com/webpack/webpack) for license details.

‎eslint.config.mjs‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import js from "@eslint/js";
2+
import globals from "globals";
3+
4+
export default [
5+
js.configs.recommended,
6+
{
7+
languageOptions: {
8+
ecmaVersion: "latest",
9+
sourceType: "module",
10+
globals: globals.node,
11+
},
12+
},
13+
{
14+
ignores: ["node_modules/", "out/", "webpack/"],
15+
},
16+
];

0 commit comments

Comments
 (0)