Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity
Files
0a6ef46927c4fc47235663e9b5f65ef95615516e
bookhoard/scripts/README.md
T
john-okeefe 0a6ef46927 docs: reorganize verification script to match PROJECT_GUIDELINES.md order 
Updated verify-quick.sh to follow PROJECT_GUIDELINES.md structure:
- Added comments for each check showing which guideline it verifies
- Reordered checks to match guideline document order
- Expanded from 5 checks to 13 comprehensive checks

New checks added:
- Backend & Database: migration files, pgx v5 driver version
- Frontend & Styling: OOP pattern detection, TailwindCSS usage
- General: git history for secrets, Dockerfile proliferation
- Build & Deployment: code compilation (post-edit verification)
- Configuration: .env.example, .gitignore validation
- Code Modification Safety: commit quality check (no large commits)

Updated scripts/README.md to document all 13 checks with their
corresponding guidelines.

Current status: 12/13 checks passing
- Only 1 error: 12 legacy templates with custom CSS (need Tailwind conversion)
- 1 warning: some Go files have >10 methods (potential OOP, needs manual review)
2026-02-02 10:08:31 -05:00

4.3 KiB
Raw Blame History

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

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

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

  2. 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)

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

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

General

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

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

  2. Dockerfile proliferation - Warns if multiple Dockerfiles exist

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

✅ MANDATORY REQUIREMENTS

Build & Deployment

  1. Code compiles - Verifies go build succeeds

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

  2. Database driver version - Checks for pgx v5 usage

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

Frontend & Styling

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

Code Modification Safety

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

Configuration & Environment

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

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

  2. .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
Reference in New Issue View Git Blame Copy Permalink