bookhoard/scripts

Project Guidelines Verification

Quick Start

Run the verification script:

make verify-guidelines
# or
./scripts/verify-quick.sh

What It Checks (In Order of PROJECT_GUIDELINES.md)

🚨 CRITICAL PROHIBITIONS

Backend & Database

1. No local server binaries - Checks for bookhoard or server binaries

   • Guideline: "NEVER build server binaries locally - all builds through Dockerfile/docker-compose"

2. No new migration files - Ensures only one migration file exists

   • Guideline: "NEVER create new migration files - merge changes into current one until release"

Frontend & Styling

3. No custom CSS - Detects <style> tags in templates

   • Guideline: "NEVER use custom CSS - TailwindCSS classes only"

4. No JavaScript source files - Finds .js files outside build artifacts

   • Guideline: "NEVER use JavaScript - convert all to TypeScript"
   • Excludes: node_modules/, docs/, .git/, web/static/ (compiled output)

5. OOP pattern detection - Warns if structs have >10 methods

   • Guideline: "NEVER use object-oriented programming patterns - use functional/other paradigms"

General

6. No secrets committed - Checks for .env, credentials.json in repo and git history

   • Guideline: "NEVER commit files with secrets (.env, credentials.json, etc.)"

7. Dockerfile proliferation - Warns if multiple Dockerfiles exist

   • Guideline: "NEVER add new Dockerfiles without user confirmation"

✅ MANDATORY REQUIREMENTS

Build & Deployment

8. Code compiles - Verifies go build succeeds

   • Guideline: "Post-Edit Verification (MANDATORY) - must compile after each file edit"

9. Database driver version - Checks for pgx v5 usage

   • Guideline: "Follow pgx v5 standards for all database operations"

Frontend & Styling

10. TailwindCSS usage - Verifies TailwindCSS is being used
    • Guideline: "Always use TailwindCSS classes for all styling"

Code Modification Safety

11. Commit quality - Warns if recent commits changed >15 files
    • Guideline: "Use multiple, logical git commits with clear messages"

Configuration & Environment

12. .env template exists - Checks for .env.example

    • Guideline: "If .env is missing, auto-generate secure values"

13. .gitignore protects secrets - Verifies .env is in .gitignore

    • Guideline: "Never commit secrets to repository"

Understanding Results

• ✅ PASS: Guideline followed correctly
• ⚠️ WARNING: Minor issue, should fix soon
• ❌ ERROR: Critical violation of PROJECT_GUIDELINES.md

Exit Codes

• 0: All checks passed (or only warnings)
• 1: Errors found - fix before committing

Pre-commit Integration

Add to .git/hooks/pre-commit:

#!/bin/bash
./scripts/verify-quick.sh

CI/CD Integration

Add to your CI pipeline:

verify-guidelines:
  script: make verify-guidelines

Current Codebase Status

✅ Passing Checks (10/13)

• No server binaries
• Migration structure OK
• No JavaScript source files (TypeScript used)
• Struct methods within reasonable range
• No secrets in repository
• Single Dockerfile structure
• Code compiles successfully
• Using pgx v5 driver
• TailwindCSS is being used
• Recent commits are well-scoped
• .env.example exists
• .env is in .gitignore

❌ Failing Checks (3/13)

• 12 templates with custom CSS - Legacy templates (admin, dashboard, analytics, etc.) need TailwindCSS conversion

⚠️ Warnings (0/13)

• None at this time

Notes

• Excluded directories: node_modules/, docs/, .git/, web/static/ (build artifacts)
• Hard to verify automatically:
  • "No backend modifications for frontend tasks" (requires task context)
  • "No git checkout on schema files" (requires manual review)
• • "Git hooks, force push" (historical checks)
• Partially verified: OOP patterns (checked struct method counts as proxy)

How This Ensures Guideline Compliance

Before AI Work

# User says: "Implement feature X, follow guidelines"
AI runs: make verify-guidelines

After AI Work (But Before Commit)

# AI says: "Done, ready to commit"
User runs: make verify-guidelines
# User sees actual proof of compliance, not just AI's promise

Continuous Verification

# Optional: Add to pre-commit hook
# Now even if AI forgets, the hook prevents violations