Skip to content

Commit 6a4e860

Browse files
brandonkachenbrandonkachen
committed
feat(web): add documentation testing and linting infrastructure
- Add content integrity tests (frontmatter, links, slugs, content quality) - Add E2E Playwright tests for doc pages (rendering, navigation, accessibility, SEO) - Add Vale linting with custom Codebuff vocabulary and style rules - Add warning-level rules (RepeatWords, TodoComments) for meaningful CI validation - Configure Vale to treat MDX as Markdown for proper parsing - Add npm scripts: test:docs, test:docs:integrity, e2e:docs, lint:docs - Rename nightly-agents-e2e.yml to nightly-e2e.yml - Add docs quality checks to nightly workflow (Vale + content integrity + E2E) - Add gray-matter dependency for MDX frontmatter parsing
1 parent 201a298 commit 6a4e860

File tree

11 files changed

+573
-3
lines changed

11 files changed

+573
-3
lines changed

.github/workflows/nightly-agents-e2e.yml renamed to .github/workflows/nightly-e2e.yml

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Nightly Agents E2E Tests
1+
name: Nightly E2E Tests
22

33
on:
44
schedule:
@@ -7,9 +7,9 @@ on:
77
workflow_dispatch: # Allow manual triggering
88

99
jobs:
10-
agents-e2e-tests:
10+
e2e-tests:
1111
runs-on: ubuntu-latest
12-
timeout-minutes: 30
12+
timeout-minutes: 45
1313
steps:
1414
- name: Checkout repository
1515
uses: actions/checkout@v4
@@ -51,3 +51,31 @@ jobs:
5151

5252
- name: Run .agents e2e tests
5353
run: cd .agents && bun run test:e2e --timeout=120000
54+
55+
# Documentation quality checks
56+
- name: Install Vale
57+
run: |
58+
wget -q https://github.com/errata-ai/vale/releases/download/v3.13.0/vale_3.13.0_Linux_64-bit.tar.gz
59+
tar -xzf vale_3.13.0_Linux_64-bit.tar.gz
60+
sudo mv vale /usr/local/bin/
61+
vale --version
62+
63+
- name: Run Vale docs linting
64+
run: cd web && vale src/content/ --minAlertLevel=warning
65+
66+
- name: Run documentation content integrity tests
67+
run: cd web && bun run test:docs:integrity
68+
69+
- name: Install Playwright browsers
70+
run: cd web && bunx playwright install --with-deps chromium
71+
72+
- name: Run documentation E2E tests
73+
run: cd web && bun run e2e:docs --project=chromium
74+
75+
- name: Upload Playwright report on failure
76+
if: failure()
77+
uses: actions/upload-artifact@v4
78+
with:
79+
name: playwright-docs-report
80+
path: debug/playwright-report/
81+
retention-days: 7

‎bun.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎web/.vale.ini‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Vale Configuration for Codebuff Documentation
2+
# https://vale.sh/docs/
3+
#
4+
# To use Vale, install it first:
5+
# brew install vale
6+
#
7+
# Then run:
8+
# vale src/content/
9+
10+
StylesPath = .vale/styles
11+
12+
# Minimum alert level to display (suggestion, warning, error)
13+
MinAlertLevel = suggestion
14+
15+
# Treat MDX as Markdown for parsing
16+
[formats]
17+
mdx = md
18+
19+
# File types to lint
20+
[*.{md,mdx}]
21+
BasedOnStyles = Codebuff
22+
23+
# Ignore code blocks
24+
BlockIgnores = (?s)(`{3}.*?`{3})
25+
26+
# Ignore inline code
27+
TokenIgnores = (`[^`]+`)
28+
29+
# Ignore JSX/MDX component tags
30+
BlockIgnores = (?s)(<[A-Z][^>]*>.*?</[A-Z][^>]*>)|(<[A-Z][^/>]*/?>)

‎web/.vale/styles/Codebuff/HeadingCase.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Headings should use sentence case (not Title Case)
2+
extends: capitalization
3+
message: "Use sentence case for headings: '%s'"
4+
level: suggestion
5+
match: $sentence
6+
scope: heading

‎web/.vale/styles/Codebuff/RepeatWords.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Flag common consecutively repeated words
2+
extends: existence
3+
message: "Repeated word: '%s'"
4+
level: warning
5+
ignorecase: true
6+
tokens:
7+
- 'the the'
8+
- 'a a'
9+
- 'an an'
10+
- 'is is'
11+
- 'are are'
12+
- 'was was'
13+
- 'were were'
14+
- 'be be'
15+
- 'been been'
16+
- 'have have'
17+
- 'has has'
18+
- 'had had'
19+
- 'do do'
20+
- 'does does'
21+
- 'did did'
22+
- 'will will'
23+
- 'would would'
24+
- 'can can'
25+
- 'could could'
26+
- 'should should'
27+
- 'to to'
28+
- 'of of'
29+
- 'in in'
30+
- 'for for'
31+
- 'on on'
32+
- 'with with'
33+
- 'and and'
34+
- 'or or'
35+
- 'but but'
36+
- 'that that'
37+
- 'this this'
38+
- 'it it'
39+
- 'you you'
40+
- 'we we'
41+
- 'they they'

‎web/.vale/styles/Codebuff/TodoComments.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Flag TODO/FIXME comments that shouldn't be in published docs
2+
extends: existence
3+
message: "Found '%s' - remove before publishing"
4+
level: warning
5+
ignorecase: true
6+
tokens:
7+
- 'TODO'
8+
- 'FIXME'
9+
- 'XXX'
10+
- 'HACK'
11+
- 'WIP'

‎web/.vale/styles/Codebuff/Wordiness.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Flag wordy phrases that can be simplified
2+
extends: substitution
3+
message: "Consider using '%s' instead of '%match'."
4+
level: suggestion
5+
swap:
6+
in order to: to
7+
due to the fact that: because
8+
at this point in time: now
9+
in the event that: if
10+
prior to: before
11+
subsequent to: after
12+
a large number of: many
13+
a majority of: most
14+
at the present time: now
15+
for the purpose of: to
16+
in spite of the fact that: although
17+
on a daily basis: daily
18+
in close proximity to: near
19+
with regard to: about
20+
in reference to: about
21+
make use of: use

‎web/.vale/styles/Vocab/Codebuff/accept.txt‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
Codebuff
2+
codebuff
3+
Buffy
4+
CLI
5+
SDK
6+
API
7+
APIs
8+
MDX
9+
ISR
10+
npm
11+
npx
12+
pnpm
13+
bun
14+
tsx
15+
jsx
16+
async
17+
await
18+
frontmatter
19+
webhook
20+
webhooks
21+
codebase
22+
subagent
23+
subagents
24+
stdout
25+
stderr
26+
localhost
27+
env
28+
dotenv
29+
config
30+
configs
31+
monorepo
32+
runtime
33+
runtimes

‎web/package.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,17 @@
1717
"contentlayer": "contentlayer build",
1818
"lint": "next lint",
1919
"lint:fix": "next lint --fix",
20+
"lint:docs": "vale src/content/",
2021
"format:check": "prettier --check \"**/*.{ts,tsx,mdx}\" --cache",
2122
"format:write": "prettier --write \"**/*.{ts,tsx,mdx}\" --cache",
2223
"typecheck": "tsc --noEmit -p .",
2324
"test": "jest",
2425
"test:watch": "jest --watchAll",
26+
"test:docs": "jest --testPathPattern=docs/",
27+
"test:docs:integrity": "jest --testPathPattern=content-integrity",
2528
"e2e": "playwright test",
2629
"e2e:ui": "playwright test --ui",
30+
"e2e:docs": "playwright test --grep @docs src/__tests__/e2e/docs.spec.ts",
2731
"discord:start": "bun run scripts/discord/index.ts",
2832
"discord:register": "bun run scripts/discord/register-commands.ts",
2933
"clean": "rm -rf .next"
@@ -112,6 +116,7 @@
112116
"eslint-config-prettier": "^9.1.0",
113117
"eslint-plugin-prettier": "^5.2.6",
114118
"eslint-plugin-tailwindcss": "^3.18.0",
119+
"gray-matter": "^4.0.3",
115120
"husky": "^9.1.7",
116121
"jest": "^29.7.0",
117122
"jest-environment-jsdom": "^29.7.0",

0 commit comments

Comments
 (0)