What Validation Scripts Run in CI for rohitg00/ai-engineering-from-scratch Before Merging?

What Validation Scripts Run in CI for rohitg00/ai-engineering-from-scratch Before Merging?

Two mandatory Python scripts run in CI before merging: scripts/audit_lessons.py validates lesson structure and content integrity, while scripts/check_readme_counts.py ensures README statistics match the authoritative catalog.json.

When you open a pull request against the main branch of the rohitg00/ai-engineering-from-scratch repository, the GitHub Actions workflow defined in .github/workflows/curriculum.yml automatically executes validation scripts to maintain curriculum quality. These checks ensure every lesson adheres to structural standards and that repository-wide statistics remain accurate.

CI Workflow Architecture

The continuous integration pipeline triggers on every pull request and push to main. According to the source code, the workflow relies on pure-Python scripts that use only the standard library, keeping execution fast and deterministic. The validation scripts examine both file system structure and data consistency before allowing a merge to proceed.

Mandatory Pre-Merge Validation Scripts

Two specific jobs block merging if they report failures. These constitute the complete set of validation scripts run in CI for rohitg00/ai-engineering-from-scratch before code reaches the main branch.

Lesson Structure Audit (audit_lessons.py)

The audit job executes scripts/audit_lessons.py to enforce curriculum invariants. This script performs comprehensive checks on every lesson directory:

• Naming conventions: Validates directory naming standards
• Documentation presence: Confirms existence and quality of docs/en.md files
• Source code validation: Verifies that expected source code files exist
• Quiz schema integrity: Checks that quiz files follow the proper schema
• Link resolution: Ensures internal Markdown links resolve correctly

If any lesson violates these structural rules, the script exits with a non-zero status and the pull request cannot be merged.

README Count Drift Check (check_readme_counts.py)

The readme-counts-drift job runs scripts/check_readme_counts.py to prevent documentation decay. This script internally loads catalog.json via scripts/build_catalog.py and compares the authoritative totals against hard-coded counts in README.md. Specifically, it validates:

• Lesson count accuracy
• Phase totals
• Skill counts
• Prompt statistics

When counts diverge, the CI job fails and blocks the merge. This ensures the repository statistics displayed to users always reflect the actual curriculum content.

Post-Merge Automation (Non-Blocking)

While not a validation script that runs before merging, the workflow includes a site-rebuild job that executes site/build.js to regenerate site/data.js. This job triggers only on pushes to main—meaning it runs immediately after a successful merge, not during the PR validation phase. It does not affect the ability to merge a pull request.

Running Validation Scripts Locally

Developers can execute these same checks locally to catch issues before submitting a pull request.

Run the lesson audit to verify curriculum structure:

python3 scripts/audit_lessons.py

An exit code of 0 indicates no issues. To check README count alignment:

python3 scripts/check_readme_counts.py

For machine-readable output suitable for CI parsing:

python3 scripts/check_readme_counts.py --json

If the README counts drift, fix them automatically using the same script the CI uses for synchronization:

python3 scripts/check_readme_counts.py --fix

To simulate the post-merge site generation locally:

node site/build.js

Summary

• Lesson audit: scripts/audit_lessons.py validates directory structure, documentation quality, and link integrity for every lesson.
• Count verification: scripts/check_readme_counts.py ensures README statistics match catalog.json totals, preventing documentation drift.
• Workflow location: Both mandatory scripts execute via .github/workflows/curriculum.yml on every pull request.
• Zero dependencies: All validation scripts use only Python standard library modules.
• Local execution: Run python3 scripts/audit_lessons.py and python3 scripts/check_readme_counts.py before pushing to verify compliance.

Frequently Asked Questions

What happens if the audit script fails?

If scripts/audit_lessons.py detects naming convention violations, missing docs/en.md files, broken internal links, or invalid quiz schemas, it exits with a non-zero status code. This causes the GitHub Actions audit job to fail, blocking the pull request from merging until you fix the underlying curriculum structure issues.

Can I automatically fix README count mismatches?

Yes. Run python3 scripts/check_readme_counts.py --fix locally to automatically update the hard-coded counts in README.md to match the authoritative totals in catalog.json. This corresponds to the readme-counts-sync job that runs on pushes to main, though you should commit these fixes before merging to ensure CI passes.

Does the site rebuild block my pull request?

No. The site-rebuild job that runs site/build.js triggers only on pushes to the main branch, not on pull requests. It executes immediately after a successful merge to regenerate site/data.js for the public curriculum site, but it never prevents PR approval or merging.

Are external dependencies required to run these scripts locally?

No. Both scripts/audit_lessons.py and scripts/check_readme_counts.py rely exclusively on the Python standard library and the repository's own data files. You do not need to install third-party packages to run the pre-merge validation checks locally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}