Skip to content

Commit c36f9be

Browse files
testac974testac974
committed
Consolidate validation scripts into unified validate.sh
Major improvements: - Create validate.sh that runs all checks in one command - Add colored output with clear pass/fail indicators - Continue through failures to show all issues at once - Update package.json: npm run validate and npm test - Simplify GitHub workflows to use unified script - Update pre-commit hook to use unified script - Add comprehensive scripts/README.md documentation Benefits: - Single command runs all validations (npm run validate) - Easier to run locally and in CI - Consistent validation everywhere (local, pre-commit, CI) - Better developer experience with colored output and summaries - Individual scripts still available for specific needs Environment variables: - CHECK_EXTERNAL=true for external link validation - CHECK_TRACEABILITY=true for traceability checks
1 parent 4c52ac1 commit c36f9be

File tree

5 files changed

+255
-37
lines changed

5 files changed

+255
-37
lines changed

‎.github/workflows/validate-pr.yml‎

Lines changed: 5 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -28,29 +28,16 @@ jobs:
2828
sudo apt-get update
2929
sudo apt-get install -y chromium-browser libgbm1
3030
31-
- name: Markdown lint
32-
run: npx markdownlint --config .markdownlint.json 'book/**/*.md'
33-
34-
# TODO: Fix markdown-link-check ESM dependency issue
35-
# - name: Validate internal links
36-
# run: ./scripts/validate-links.sh
37-
# env:
38-
# CHECK_EXTERNAL: false
39-
40-
- name: Validate frontmatter schema
41-
run: ./scripts/validate-frontmatter.sh
42-
4331
- name: Setup Python
4432
uses: actions/setup-python@v5
4533
with:
4634
python-version: '3.11'
4735

48-
# TODO: Enable once book content is written
49-
# - name: Check requirement traceability
50-
# run: python3 ./scripts/check-traceability.py
51-
52-
- name: Test Mermaid rendering
53-
run: npm run build:mermaid
36+
- name: Run all validations
37+
run: npm run validate
38+
env:
39+
CHECK_EXTERNAL: false
40+
CHECK_TRACEABILITY: false
5441

5542
- name: Comment PR with results
5643
if: always()

‎.github/workflows/validate.yml‎

Lines changed: 5 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -28,26 +28,13 @@ jobs:
2828
sudo apt-get update
2929
sudo apt-get install -y chromium-browser libgbm1
3030
31-
- name: Markdown lint
32-
run: npx markdownlint --config .markdownlint.json 'book/**/*.md'
33-
34-
# TODO: Fix markdown-link-check ESM dependency issue
35-
# - name: Validate links
36-
# run: ./scripts/validate-links.sh
37-
# env:
38-
# CHECK_EXTERNAL: false
39-
40-
- name: Validate frontmatter schema
41-
run: ./scripts/validate-frontmatter.sh
42-
4331
- name: Setup Python
4432
uses: actions/setup-python@v5
4533
with:
4634
python-version: '3.11'
4735

48-
# TODO: Enable once book content is written
49-
# - name: Check requirement traceability
50-
# run: python3 ./scripts/check-traceability.py
51-
52-
- name: Test Mermaid rendering
53-
run: npm run build:mermaid
36+
- name: Run all validations
37+
run: npm run validate
38+
env:
39+
CHECK_EXTERNAL: false
40+
CHECK_TRACEABILITY: false

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,12 @@
66
"scripts": {
77
"build:pdf": "./scripts/build-pdf.sh",
88
"build:mermaid": "node scripts/render-mermaid.js",
9+
"validate": "./scripts/validate.sh",
910
"validate:links": "./scripts/validate-links.sh",
1011
"validate:frontmatter": "./scripts/validate-frontmatter.sh",
1112
"validate:traceability": "python3 scripts/check-traceability.py",
1213
"generate:toc": "./scripts/generate-toc.sh",
13-
"test": "npm run validate:links && npm run validate:frontmatter"
14+
"test": "./scripts/validate.sh"
1415
},
1516
"keywords": [
1617
"agentic-coding",

‎scripts/README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Scripts
2+
3+
This directory contains build and validation scripts for the Agentic Coding Book.
4+
5+
## Quick Start
6+
7+
**Run all validations:**
8+
9+
```bash
10+
npm run validate
11+
# or
12+
npm test
13+
```
14+
15+
**Build PDF:**
16+
17+
```bash
18+
npm run build:pdf
19+
```
20+
21+
## Validation Scripts
22+
23+
### Unified Validation (`validate.sh`)
24+
25+
**Primary script** that runs all validation checks in one command.
26+
27+
```bash
28+
./scripts/validate.sh
29+
30+
# Or via npm:
31+
npm run validate
32+
npm test
33+
```
34+
35+
**Features:**
36+
- ✅ Runs all checks with colored output
37+
- ✅ Shows summary of passed/failed checks
38+
- ✅ Continues through failures to show all issues
39+
- ✅ Returns non-zero exit code if any check fails
40+
41+
**Environment variables:**
42+
- `CHECK_EXTERNAL=true` - Enable external link checking (default: false)
43+
- `CHECK_TRACEABILITY=true` - Enable traceability checking (default: false)
44+
45+
**Checks performed:**
46+
1. Markdown linting (markdownlint)
47+
2. Frontmatter schema validation
48+
3. Link validation (internal only by default)
49+
4. Mermaid diagram rendering
50+
5. Requirements traceability (optional)
51+
52+
### Individual Validation Scripts
53+
54+
You can still run individual checks if needed:
55+
56+
**`validate-links.sh`** - Check for broken links
57+
58+
```bash
59+
npm run validate:links
60+
61+
# Check external links too:
62+
CHECK_EXTERNAL=true npm run validate:links
63+
```
64+
65+
**`validate-frontmatter.sh`** - Validate YAML frontmatter
66+
67+
```bash
68+
npm run validate:frontmatter
69+
```
70+
71+
**`check-traceability.py`** - Check requirement traceability
72+
73+
```bash
74+
npm run validate:traceability
75+
```
76+
77+
## Build Scripts
78+
79+
**`build-pdf.sh`** - Build PDF from markdown
80+
81+
```bash
82+
npm run build:pdf
83+
84+
# Dry run (validation only, no PDF):
85+
./scripts/build-pdf.sh --dry-run
86+
```
87+
88+
**`render-mermaid.js`** - Render Mermaid diagrams to PNG
89+
90+
```bash
91+
npm run build:mermaid
92+
```
93+
94+
**`generate-toc.sh`** - Generate table of contents
95+
96+
```bash
97+
npm run generate:toc
98+
```
99+
100+
## Pre-commit Hook
101+
102+
A pre-commit hook is installed at `.git/hooks/pre-commit` that automatically runs all validations before each commit.
103+
104+
**To install manually:**
105+
106+
```bash
107+
cp scripts/install-hooks.sh .git/hooks/
108+
./scripts/install-hooks.sh
109+
```
110+
111+
**To bypass (not recommended):**
112+
113+
```bash
114+
git commit --no-verify
115+
```
116+
117+
## CI/CD Integration
118+
119+
GitHub Actions workflows use the unified validation script:
120+
121+
- **`validate.yml`** - Runs on push to main
122+
- **`validate-pr.yml`** - Runs on pull requests
123+
- **`build-pdf.yml`** - Builds and releases PDF
124+
125+
All workflows use `npm run validate` for consistency.
126+
127+
## Troubleshooting
128+
129+
**Markdownlint failures:**
130+
131+
```bash
132+
# Auto-fix formatting issues:
133+
npx markdownlint --config .markdownlint.json 'book/**/*.md' --fix
134+
```
135+
136+
**Link check failures:**
137+
138+
Check the reported file and line number. Common issues:
139+
- Links to non-existent files
140+
- Broken anchor links
141+
- Typos in file paths
142+
143+
**Frontmatter failures:**
144+
145+
Ensure all chapter files have valid YAML frontmatter with required fields:
146+
- title, part, chapter, version, date, status, author, tags, abstract
147+
148+
**Mermaid rendering failures:**
149+
150+
Ensure Chrome/Chromium is installed:
151+
152+
```bash
153+
# Ubuntu/Debian:
154+
sudo apt-get install chromium-browser libgbm1
155+
156+
# macOS:
157+
brew install chromium
158+
```

‎scripts/validate.sh‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
#!/bin/bash
2+
# Unified validation script for the Agentic Coding Book
3+
# Runs all validation checks in one command
4+
5+
set -e
6+
7+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
8+
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
9+
cd "$PROJECT_ROOT"
10+
11+
# Color output
12+
RED='\033[0;31m'
13+
GREEN='\033[0;32m'
14+
YELLOW='\033[1;33m'
15+
BLUE='\033[0;34m'
16+
NC='\033[0m' # No Color
17+
18+
# Track failures
19+
FAILED_CHECKS=()
20+
21+
# Helper function to run a check
22+
run_check() {
23+
local name="$1"
24+
local command="$2"
25+
26+
echo -e "\n${BLUE}==>${NC} ${name}..."
27+
28+
if eval "$command"; then
29+
echo -e "${GREEN}✓${NC} ${name} passed"
30+
else
31+
echo -e "${RED}✗${NC} ${name} failed"
32+
FAILED_CHECKS+=("$name")
33+
# Don't exit immediately, continue with other checks
34+
return 1
35+
fi
36+
}
37+
38+
echo -e "${BLUE}========================================${NC}"
39+
echo -e "${BLUE}Running all validation checks...${NC}"
40+
echo -e "${BLUE}========================================${NC}"
41+
42+
# 1. Markdown linting
43+
run_check "Markdown linting" \
44+
"npx markdownlint --config .markdownlint.json 'book/**/*.md'" || true
45+
46+
# 2. Frontmatter validation
47+
run_check "Frontmatter schema validation" \
48+
"./scripts/validate-frontmatter.sh" || true
49+
50+
# 3. Link validation (internal only by default)
51+
export CHECK_EXTERNAL=${CHECK_EXTERNAL:-false}
52+
run_check "Link validation" \
53+
"./scripts/validate-links.sh" || true
54+
55+
# 4. Mermaid diagram rendering test
56+
run_check "Mermaid diagram rendering" \
57+
"npm run build:mermaid" || true
58+
59+
# 5. Traceability check (optional - only if enabled)
60+
if [ "$CHECK_TRACEABILITY" = "true" ]; then
61+
if [ -f "./scripts/check-traceability.py" ]; then
62+
run_check "Requirements traceability" \
63+
"python3 ./scripts/check-traceability.py" || true
64+
else
65+
echo -e "${YELLOW}⚠${NC} Traceability check skipped (script not found)"
66+
fi
67+
else
68+
echo -e "${YELLOW}⚠${NC} Traceability check skipped (set CHECK_TRACEABILITY=true to enable)"
69+
fi
70+
71+
# Summary
72+
echo -e "\n${BLUE}========================================${NC}"
73+
echo -e "${BLUE}Validation Summary${NC}"
74+
echo -e "${BLUE}========================================${NC}"
75+
76+
if [ ${#FAILED_CHECKS[@]} -eq 0 ]; then
77+
echo -e "${GREEN}✓ All validation checks passed!${NC}"
78+
exit 0
79+
else
80+
echo -e "${RED}✗ ${#FAILED_CHECKS[@]} check(s) failed:${NC}"
81+
for check in "${FAILED_CHECKS[@]}"; do
82+
echo -e " ${RED}-${NC} $check"
83+
done
84+
exit 1
85+
fi

0 commit comments

Comments
 (0)