{"id":31952709,"url":"https://github.com/thedaviddias/codekeeper","last_synced_at":"2026-04-20T19:32:13.756Z","repository":{"id":311221621,"uuid":"1042808531","full_name":"thedaviddias/codekeeper","owner":"thedaviddias","description":"🧠 Essential guardrails to prevent AI from going sideways in development projects","archived":false,"fork":false,"pushed_at":"2025-08-31T06:22:36.000Z","size":160,"stargazers_count":6,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-23T16:47:03.445Z","etag":null,"topics":["ai","ai-gents","eslint","guardrails","lefthook","llms","vibe-coding","vibecoding"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thedaviddias.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-22T15:57:12.000Z","updated_at":"2025-09-25T06:00:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"682437be-88d5-4806-b535-7d4df4f624fb","html_url":"https://github.com/thedaviddias/codekeeper","commit_stats":null,"previous_names":["thedaviddias/codekeeper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thedaviddias/codekeeper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thedaviddias%2Fcodekeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thedaviddias%2Fcodekeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thedaviddias%2Fcodekeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thedaviddias%2Fcodekeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thedaviddias","download_url":"https://codeload.github.com/thedaviddias/codekeeper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thedaviddias%2Fcodekeeper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32062344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T11:35:06.609Z","status":"ssl_error","status_checked_at":"2026-04-20T11:34:48.899Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-gents","eslint","guardrails","lefthook","llms","vibe-coding","vibecoding"],"created_at":"2025-10-14T13:23:30.001Z","updated_at":"2026-04-20T19:32:13.750Z","avatar_url":"https://github.com/thedaviddias.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodeKeeper - AI Development Guardrails\n\n\u003cdiv align=\"center\"\u003e\n\n  **Stop AI from breaking your React/Next.js code. Start shipping with confidence.**\n\n  [![Tests](https://github.com/thedaviddias/codekeeper/workflows/Test%20CodeKeeper%20Validation%20Scripts/badge.svg)](https://github.com/thedaviddias/codekeeper/actions)\n  [![GitHub Stars](https://img.shields.io/github/stars/thedaviddias/codekeeper?style=social)](https://github.com/thedaviddias/codekeeper)\n  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/thedaviddias/codekeeper/pulls)\n  [![React](https://img.shields.io/badge/React-18+-blue)](https://reactjs.org/)\n  [![Next.js](https://img.shields.io/badge/Next.js-13+-black)](https://nextjs.org/)\n\n  [Quick Start](#-quick-start-2-minutes) • [Documentation](./docs/) • [Examples](./docs/EXAMPLES.md) • [Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n**CodeKeeper** is a battle-tested (yes, I'm using it in production) collection of validation scripts that prevent AI assistants from introducing bugs, security issues, and bad practices into your React and Next.js projects. Works with **any** development workflow you're already using.\n\n### 🛠️ **Works With Your Existing Tools**\n✅ **ESLint** • ✅ **Husky** • ✅ **Lefthook** • ✅ **pre-commit** • ✅ **lint-staged** • ✅ **GitHub Actions** • ✅ **GitLab CI** • ✅ **Jenkins** • ✅ **Vercel** • ✅ **Netlify**\n\n## 🚨 The Problem\n\nAI coding assistants are powerful but can introduce subtle bugs in React/Next.js projects:\n- **Type assertions** that hide runtime errors (`as any` everywhere)\n- **Barrel files** that destroy tree-shaking and slow builds\n- **Component mega-files** with 500+ lines that become unmaintainable\n- **Missing JSDoc** that leaves your team confused about props and hooks\n- **Security vulnerabilities** from unsafe patterns and exposed secrets\n\n## ✅ The Solution\n\nCodeKeeper provides pre-built validation scripts that catch these issues before they hit production:\n\n| Guardrail | Prevents | Impact |\n|-----------|----------|---------|\n| **Type Safety** | `as any`, unsafe casts | -90% runtime errors |\n| **Import Quality** | Barrel file chaos | 3x faster builds |\n| **Complexity Limits** | 1000+ line files | 50% easier maintenance |\n| **Documentation** | Missing JSDoc | 2x faster onboarding |\n| **Architecture** | Messy file structure | Clean, scalable codebase |\n\n## 🚀 Quick Start (Choose Your Tools)\n\n### Option A: Lefthook + Validation Scripts (Recommended for Flow State)\n```bash\n# Install lefthook\nnpm install -g lefthook\n\n# Copy CodeKeeper scripts and config\ncurl -fsSL https://raw.githubusercontent.com/thedaviddias/codekeeper/main/install.sh | bash\n\n# Auto-configured! lefthook.yml is ready to use\nlefthook install\n\n# Now code freely - validation happens on commit! 🎉\n```\n\n### Option B: Other Git Hook Managers\n\nPick your favorite:\n\n#### With Husky (Most Popular)\n```bash\n# Install husky and lint-staged\nnpm install --save-dev husky lint-staged\nnpx husky-init\n\n# Copy CodeKeeper scripts\ncurl -fsSL https://raw.githubusercontent.com/thedaviddias/codekeeper/main/install.sh | bash\n\n# Add to package.json\n{\n  \"lint-staged\": {\n    \"*.{ts,tsx}\": [\n      \"eslint --fix\",\n      \"node scripts/validate-all.js\"\n    ]\n  }\n}\n\n# Update .husky/pre-commit\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\nnpx lint-staged\n```\n\n#### With Lefthook (My Favorite and the one I use)\n```bash\n# Install lefthook\nnpm install -g lefthook\n\n# Copy CodeKeeper scripts and config\ncurl -fsSL https://raw.githubusercontent.com/thedaviddias/codekeeper/main/install.sh | bash\n\n# Auto-configured! lefthook.yml is ready to use\nlefthook install\n```\n\n#### With pre-commit (Python)\n```yaml\n# .pre-commit-config.yaml\nrepos:\n  - repo: local\n    hooks:\n      - id: codekeeper-validation\n        name: CodeKeeper Validation\n        entry: node scripts/validate-all.js\n        language: node\n        files: \\.(ts|tsx)$\n```\n\n## 💡 Real Examples\n\n### Before CodeKeeper ❌\n```tsx\n// AI often generates this in React components\nconst UserProfile = ({ data }: any) =\u003e {\n  const user = data as any;  // Runtime bomb!\n  return \u003cdiv\u003e{user.naem.toUpperCase()}\u003c/div\u003e; // Typo crashes in production\n}\n```\n\n### After CodeKeeper ✅\n```tsx\n// Guardrails force proper typing\ninterface UserProfileProps {\n  data: User;\n}\n\nconst UserProfile = ({ data }: UserProfileProps) =\u003e {\n  return \u003cdiv\u003e{data.name.toUpperCase()}\u003c/div\u003e; // TypeScript catches typos\n}\n```\n\n### More Examples:\n- **[Try interactive examples →](./examples/)** - Working projects you can test immediately\n- **[See all React/Next.js examples →](./docs/EXAMPLES.md)**\n\n## 🔧 What's Included\n\n### ESLint Plugin Rules\n- `no-unsafe-as-casts` - Blocks `as any` and unsafe type assertions\n- `no-barrel-files` - Prevents slow barrel file exports\n- `max-file-complexity` - Limits file size and complexity\n- `require-jsdoc` - Enforces documentation standards\n\n### Standalone Validation Scripts\n- `check-as-casts.js` - TypeScript type safety validation\n- `check-barrel-files.js` - Import performance checks\n- `check-directory-structure.js` - Architecture enforcement\n- `check-file-complexity.js` - Complexity limits\n- `check-jsdoc.js` - Documentation requirements\n- `check-relative-imports.js` - Import consistency\n\n### Configuration\n- `lefthook.yml` - Git hooks for automatic validation\n- `.eslintrc.js` - ESLint integration examples\n\n## 🎯 The \"Vibe Coding\" Workflow\n\nCodeKeeper is designed for developers who want to **code in flow state** without constant interruptions:\n\n1. **🚀 Code freely** - Focus on building features, don't worry about perfect code\n2. **⚡ Quick validation** - Let Lefthook catch issues with specific, educational messages on commit\n3. **🤖 AI-assisted fixes** - Use LLMs (like Claude, ChatGPT) to fix the issues CodeKeeper found\n4. **✅ Ship with confidence** - Your code is clean and follows best practices\n\nThis approach lets you stay in creative flow while ensuring code quality.\n\n### 🤖 AI-Assisted Fixing Example\n\nWhen CodeKeeper finds issues, copy them to your AI assistant:\n\n```bash\ngit commit -m \"add user profile feature\"\n# 🔍 Checking for unsafe 'any' types...\n# ❌ COMMIT BLOCKED: Found 'any' types in UserProfile.tsx!\n# 💡 Replace 'any' with specific types for better type safety\n\n# 🔍 Checking React component complexity...\n# ❌ COMMIT BLOCKED: Components exceed complexity limits!\n# 💡 Split large components into smaller, focused ones\n```\n\n**Prompt to AI:** \"Fix these CodeKeeper issues: [paste output]\"\n\n**AI Response:** Provides proper TypeScript interfaces, splits complex components, and removes barrel files.\n\n**Result:** Clean, maintainable code without breaking your flow state!\n\n## 🔄 CI/CD Integration\n\nCodeKeeper works with any CI/CD pipeline:\n\n### GitHub Actions\n```yaml\n# .github/workflows/validation.yml\nname: CodeKeeper Validation\non: [push, pull_request]\njobs:\n  validate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '18'\n      - run: npm install\n      - run: npm run lint  # ESLint + CodeKeeper plugin\n      - run: node scripts/validate-all.js  # Standalone validation\n```\n\n### GitLab CI\n```yaml\n# .gitlab-ci.yml\nstages:\n  - validate\n\ncode-validation:\n  stage: validate\n  script:\n    - npm install\n    - npm run lint\n    - node scripts/validate-all.js\n  only:\n    - merge_requests\n    - main\n```\n\n### Jenkins\n```groovy\n// Jenkinsfile\npipeline {\n  agent any\n  stages {\n    stage('Install') {\n      steps {\n        sh 'npm install'\n      }\n    }\n    stage('Validate') {\n      steps {\n        sh 'npm run lint'\n        sh 'node scripts/validate-all.js'\n      }\n    }\n  }\n}\n```\n\n### Vercel/Netlify Build\n```json\n// package.json\n{\n  \"scripts\": {\n    \"build\": \"npm run validate \u0026\u0026 next build\",\n    \"validate\": \"eslint . \u0026\u0026 node scripts/validate-all.js\"\n  }\n}\n```\n\n## 🔌 Tool Compatibility Matrix\n\n| Tool | ESLint Plugin | Standalone Scripts | Setup Difficulty | Performance |\n|------|--------------|-------------------|------------------|-------------|\n| **ESLint** | ✅ Native | ✅ Via npm scripts | 🟢 Easy | 🟢 Fast |\n| **Husky + lint-staged** | ✅ Perfect fit | ✅ Perfect fit | 🟢 Easy | 🟢 Fast |\n| **Lefthook** | ✅ Works great | ✅ Built-in support | 🟢 Easy | 🟢 Fast |\n| **pre-commit** | ✅ Via ESLint hook | ✅ Custom hook | 🟡 Moderate | 🟢 Fast |\n| **GitHub Actions** | ✅ Standard workflow | ✅ Custom step | 🟢 Easy | 🟢 Fast |\n| **GitLab CI** | ✅ Standard job | ✅ Custom job | 🟢 Easy | 🟢 Fast |\n| **VS Code** | ✅ Real-time errors | ❌ Terminal only | 🟢 Easy | 🟢 Instant |\n| **WebStorm/IntelliJ** | ✅ Built-in support | ⚠️ Terminal integration | 🟢 Easy | 🟡 Good |\n\n**🎯 Quick Recommendations:**\n- **Love flow state coding?** → Lefthook + CodeKeeper scripts (our favorite!)\n- **Already use Husky?** → Add CodeKeeper to your lint-staged config\n- **Team uses ESLint heavily?** → ESLint plugin for real-time feedback\n- **Want maximum speed?** → Lefthook's parallel execution wins\n\n## 🚀 Installation\n\n### Prerequisites\n\n- **Node.js**: Version 18.0.0 or higher (check with `node --version`)\n- **npm**: Version 8.0.0 or higher\n- Use the recommended version from `.nvmrc` for best compatibility:\n  ```bash\n  nvm use  # If you have nvm installed\n  # or check the recommended version\n  cat .nvmrc\n  ```\n\n1. **Verify Node.js compatibility**:\n   ```bash\n   npm run check:node\n   ```\n\n2. **Install lefthook** (if not already installed):\n   ```bash\n   npm install -g lefthook\n   # or\n   yarn global add lefthook\n   ```\n\n3. **Copy the files**:\n   ```bash\n   # Copy validation scripts\n   mkdir -p scripts/validation\n   cp scripts/validation/*.js scripts/validation/\n\n   # Copy lefthook config\n   cp lefthook.yml ./\n   ```\n\n4. **Install lefthook in your repo**:\n   ```bash\n   lefthook install\n   ```\n\n## 🎯 What Each Guardrail Does\n\n### Type Safety (`check-as-casts.js`)\n- **Blocks**: `as any`, `as unknown`, unsafe type assertions\n- **Allows**: `as const`, test files, migration scripts\n- **Why**: Prevents runtime type errors and maintains type safety\n\n### Import Quality (`check-barrel-files.js`)\n- **Blocks**: Barrel files (`index.ts` that re-exports everything)\n- **Enforces**: Explicit imports from specific files\n- **Why**: Better tree-shaking, faster builds, clearer dependencies\n\n### Architecture (`check-directory-structure.js`)\n- **Enforces**: Clean, domain-driven directory structure\n- **Prevents**: Messy file organization and anti-patterns\n- **Why**: Maintainable codebase and clear separation of concerns\n\n### Complexity (`check-file-complexity.js`)\n- **Limits**: File size, function count, nesting depth\n- **Suggests**: Refactoring when limits are exceeded\n- **Why**: Prevents unmaintainable code and cognitive overload\n\n### Documentation (`check-jsdoc.js`)\n- **Requires**: JSDoc comments on functions and components\n- **Enforces**: Parameter and return type documentation\n- **Why**: Better code understanding and AI assistance\n\n### Import Patterns (`check-relative-imports.js`)\n- **Enforces**: Consistent import aliases (`@/` instead of `../`)\n- **Prevents**: Deep relative imports that break on refactoring\n- **Why**: Maintainable import paths and easier refactoring\n\n## 📚 Documentation\n\nFor detailed guides and examples, check out the [documentation](./docs/):\n\n- **[Quick Start Guide](./docs/QUICK-START.md)** - Get up and running in 5 minutes\n- **[Why Guardrails Matter](./docs/WHY-GUARDRAILS.md)** - The reasoning behind each guardrail\n- **[Real Examples](./docs/EXAMPLES.md)** - Before/after scenarios with AI-generated code\n\n## 🔧 Customization\n\n### Adjust Limits\nEdit the constants in each validation script:\n\n```javascript\n// In check-file-complexity.js\nconst COMPLEXITY_LIMITS = {\n  lines: 500,        // Max lines per file\n  functions: 15,     // Max functions per file\n  dependencies: 20,  // Max import statements\n  nestingDepth: 10,  // Max nesting depth\n}\n```\n\n### Add Exclusions\nModify the exclusion patterns in each script:\n\n```javascript\n// In check-as-casts.js\nconst ALLOWED_PATTERNS = [\n  /\\bas\\s+const\\b/g,\n  /\\.test\\.(ts|tsx)$/,\n  /\\.spec\\.(ts|tsx)$/,\n  // Add your own patterns here\n]\n```\n\n### Skip Checks Temporarily\nUse environment variables to skip checks during development:\n\n```bash\nNODE_ENV=development git commit -m \"WIP\"\n```\n\n## 🎯 Best Practices\n\n1. **Start Strict**: Begin with all guardrails enabled, this will avoid you nightmarish debugging sessions.\n2. **Customize Gradually**: Adjust limits based on your team's needs, you can start with the defaults and then adjust them to your needs.\n3. **Document Exceptions**: Add comments when you need to bypass rules, this will help you and your team to understand the reasons behind the exceptions.\n4. **Review Regularly**: Update guardrails as your project evolves, this will help you to keep your codebase clean and maintainable.\n5. **Team Alignment**: Ensure everyone understands the rules and their benefits, this will help you to have a more consistent codebase.\n\n## 🚨 Common Issues \u0026 Solutions\n\n### \"Too many violations to fix all at once\"\n- Temporarily increase limits in the scripts\n- Fix violations incrementally\n- Use `NODE_ENV=development` to bypass checks temporarily\n\n### \"Some files need exceptions\"\n- Add specific patterns to the `ALLOWED_PATTERNS` arrays\n- Use file-specific exclusions in the validation logic\n- Document why exceptions are needed\n\n### \"Checks are too slow\"\n- Optimize the validation scripts\n- Add more specific file filters\n- Consider running some checks only on pre-push\n\n## 🌟 Who's Using CodeKeeper?\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://github.com/thedaviddias/codekeeper/issues/new?title=Add%20my%20company\u0026body=Company:%20YOUR_COMPANY%0AWebsite:%20YOUR_WEBSITE\"\u003e\n        \u003cimg src=\"https://via.placeholder.com/100x100/f0f0f0/666?text=Your+Logo\" width=\"100px;\" alt=\"Your Company\"/\u003e\n        \u003cbr /\u003e\n        \u003csub\u003e\u003cb\u003eYour Company?\u003c/b\u003e\u003c/sub\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n[Add your company](https://github.com/thedaviddias/codekeeper/issues/new?title=Add%20my%20company)\n\n## 🧪 Testing Your Setup\n\nEnsure your CodeKeeper rules work correctly:\n\n```bash\n# Test all validation scripts\nnpm test\n\n# Quick development check\nnode tests/quick-test.js\n\n# Test individual validators\nnpm run test:as-casts\nnpm run test:barrel-files\nnpm run test:relative-imports\n```\n\nThe test suite includes fixtures with known violations to verify each guardrail catches what it should. See [`tests/README.md`](./tests/README.md) for details.\n\n## 🤝 Contributing\n\nWe welcome contributions! Whether it's:\n- 🐛 Bug fixes\n- ✨ New guardrail types\n- 📚 Documentation improvements\n- 🌍 Translations\n- 💡 Feature ideas\n\n**Before submitting changes:**\n1. Run tests to ensure everything works: `npm test`\n2. Add test fixtures for new validation rules\n3. Update documentation if needed\n\n### 📚 Contributing Resources\n\n- [Contributing Guide](./CONTRIBUTING.md) - General contribution guidelines\n- [Adding New Validation Rules](./docs/CONTRIBUTING-NEW-RULES.md) - Comprehensive step-by-step guide for adding new rules\n- [Examples](./docs/EXAMPLES.md) - Usage examples and patterns\n\n## 📊 Stats \u0026 Community\n\n- 🌟 **0+ GitHub Stars** - [Star us!](https://github.com/thedaviddias/codekeeper)\n- 👥 **0+ Contributors** - [Join us!](https://github.com/thedaviddias/codekeeper/graphs/contributors)\n- 🏢 **0+ Companies** using in production\n- 💬 **[Discussions](https://github.com/thedaviddias/codekeeper/discussions)** - Ask questions, share ideas\n- 🐦 **[Follow updates](https://twitter.com/thedaviddias)** - Latest features and tips\n\n\n## 📄 License\n\nMIT License - feel free to use these guardrails in any project!\n\n## 🙏 Acknowledgments\n\nCreated by [David Dias](https://github.com/thedaviddias), author of [Front-End Checklist](https://github.com/thedaviddias/Front-End-Checklist) (75k+ stars).\n\nInspired by the need to maintain code quality when working with AI assistants. These guardrails help ensure that AI-generated code meets the same standards as human-written code.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**⭐ Star this repo** if it helped you ship better code with AI!\n\n[Report Bug](https://github.com/thedaviddias/codekeeper/issues) • [Request Feature](https://github.com/thedaviddias/codekeeper/issues) • [Join Discord](#)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthedaviddias%2Fcodekeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthedaviddias%2Fcodekeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthedaviddias%2Fcodekeeper/lists"}