Files

T

john-okeefe 6d6640e23b docs: clarify OOP guideline - applies to TypeScript, not Go

Updated PROJECT_GUIDELINES.md and verification script to clarify:

1. OOP restriction applies to FRONTEND (TypeScript) only
2. Go methods are fine and encouraged
3. Avoid classes, inheritance, and OOP bloat in TypeScript

Changed verification script:
- Removed Go struct methods check (was incorrect)
- Added TypeScript class declaration check instead
- Now checks for 'class ' keyword in web/*.ts files

This clarifies the guideline was never about Go backend code,
only about avoiding OOP patterns in TypeScript frontend code.

Verification now shows: 13/13 checks passing, 0 warnings
Only 1 error remains: 12 legacy templates with custom CSS.

2026-02-02 10:12:41 -05:00

README.md

docs: reorganize verification script to match PROJECT_GUIDELINES.md order

2026-02-02 10:08:31 -05:00

verify-guidelines.sh

Add project guidelines verification script

2026-02-02 09:55:39 -05:00

verify-quick.sh

docs: clarify OOP guideline - applies to TypeScript, not Go

2026-02-02 10:12:41 -05:00

README.md

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

No local server binaries - Checks for bookhoard or server binaries
- Guideline: "NEVER build server binaries locally - all builds through Dockerfile/docker-compose"
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

No custom CSS - Detects <style> tags in templates
- Guideline: "NEVER use custom CSS - TailwindCSS classes only"
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)
OOP pattern detection - Warns if structs have >10 methods
- Guideline: "NEVER use object-oriented programming patterns - use functional/other paradigms"

General

No secrets committed - Checks for .env, credentials.json in repo and git history
- Guideline: "NEVER commit files with secrets (.env, credentials.json, etc.)"
Dockerfile proliferation - Warns if multiple Dockerfiles exist
- Guideline: "NEVER add new Dockerfiles without user confirmation"

✅ MANDATORY REQUIREMENTS

Build & Deployment

Code compiles - Verifies go build succeeds
- Guideline: "Post-Edit Verification (MANDATORY) - must compile after each file edit"
Database driver version - Checks for pgx v5 usage
- Guideline: "Follow pgx v5 standards for all database operations"

Frontend & Styling

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

Code Modification Safety

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

Configuration & Environment

.env template exists - Checks for .env.example
- Guideline: "If .env is missing, auto-generate secure values"
.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