pumuki-ast-hooks 5.3.1

package/docs/BRANCH_PROTECTION_GUIDE.md

@@ -0,0 +1,236 @@
+# GitHub Branch Protection Rules - Configuration Guide
+
+This guide explains how to configure branch protection rules for `ast-intelligence-hooks` to enable safe contributions from the community.
+
+## Recommended Settings for `main` Branch
+
+### Access Level: `Contribute`
+
+For an open-source project where we want contributions, use these settings:
+
+---
+
+## Branch Protection Rules Configuration
+
+### 1. **Require a pull request before merging**
+
+✅ **Enable this**
+
+**Required number of approvals:**
+- **Set to: 1** (minimum)
+- This ensures at least one maintainer reviews PRs
+
+**Dismiss stale pull request approvals when new commits are pushed:**
+- ✅ **Enable** (recommended)
+- Ensures reviewers see the latest code
+
+**Require review from Code Owners:**
+- ⚠️ **Optional** (enable if you have CODEOWNERS file)
+- Useful if you have specific maintainers for certain areas
+
+---
+
+### 2. **Require status checks to pass before merging**
+
+✅ **Enable this**
+
+**Required status checks:**
+Add these checks (if you have GitHub Actions):
+
+- `test` - All tests pass
+- `lint` - Linting passes
+- `typecheck` - TypeScript type checking
+
+**Require branches to be up to date before merging:**
+- ✅ **Enable** (recommended)
+- Ensures PR is based on latest main branch
+
+---
+
+### 3. **Require conversation resolution before merging**
+
+✅ **Enable this**
+- Ensures all review comments are addressed
+
+---
+
+### 4. **Require signed commits**
+
+⚠️ **Optional** (recommended for security)
+- Requires contributors to sign their commits
+- More secure but adds friction for new contributors
+
+**Recommendation:** Enable for organizations, optional for personal projects
+
+---
+
+### 5. **Require linear history**
+
+⚠️ **Optional**
+- Prevents merge commits (enforces rebase)
+- Cleaner history but can be frustrating for contributors
+
+**Recommendation:** Keep **disabled** initially, enable later if needed
+
+---
+
+### 6. **Require deployment to succeed before merging**
+
+❌ **Disable** (unless you have automated deployments)
+- Only needed if you deploy automatically on merge
+
+---
+
+### 7. **Do not allow bypassing the above settings**
+
+✅ **Enable this** (important!)
+- Prevents admins from accidentally merging without reviews
+- Applies rules to everyone including admins
+
+**BUT:** You'll need to allow yourself as admin to bypass for emergency fixes
+- Check: **"Restrict who can push to matching branches"**
+- Add yourself as exception if needed
+
+---
+
+### 8. **Restrict who can push to matching branches**
+
+⚠️ **Optional**
+
+**If enabled:**
+- Only listed people can push directly to main
+- Others must use PRs (recommended for open source)
+
+**Recommendation:** Enable this, but add yourself as exception for emergencies
+
+---
+
+### 9. **Allow force pushes**
+
+❌ **Disable**
+- Never allow force pushes to main
+- Can rewrite history and break things
+
+**Exception:** Only allow for branches matching patterns like `release/*` if needed
+
+---
+
+### 10. **Allow deletions**
+
+❌ **Disable**
+- Prevents accidental deletion of main branch
+
+---
+
+## Summary: Recommended Configuration
+
+✅ **Enable:**
+1. Require pull request before merging (1 approval minimum)
+2. Dismiss stale approvals
+3. Require status checks to pass
+4. Require branches to be up to date
+5. Require conversation resolution
+6. Do not allow bypassing settings (with admin exception)
+7. Restrict who can push (with admin exception)
+
+⚠️ **Optional:**
+- Require signed commits (for security)
+- Require review from Code Owners (if CODEOWNERS exists)
+
+❌ **Disable:**
+- Require linear history (too strict for contributors)
+- Allow force pushes
+- Allow deletions
+
+---
+
+## Step-by-Step Setup in GitHub
+
+1. Go to: `https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/settings/branches`
+
+2. Click **"Add rule"** or **"Add branch protection rule"**
+
+3. **Branch name pattern:** `main`
+
+4. **Configure:**
+
+   - ✅ Check: "Require a pull request before merging"
+     - Number of approvals: `1`
+     - ✅ Check: "Dismiss stale pull request approvals when new commits are pushed"
+
+   - ✅ Check: "Require status checks to pass before merging"
+     - (Add status checks if you have CI/CD)
+     - ✅ Check: "Require branches to be up to date before merging"
+
+   - ✅ Check: "Require conversation resolution before merging"
+
+   - ✅ Check: "Do not allow bypassing the above settings"
+     - Add yourself as exception if needed
+
+   - ✅ Check: "Restrict who can push to matching branches"
+     - Add yourself as exception for emergency fixes
+
+   - ❌ Uncheck: "Allow force pushes"
+
+   - ❌ Uncheck: "Allow deletions"
+
+5. Click **"Create"** or **"Save changes"**
+
+---
+
+## Additional Recommendations
+
+### Create CODEOWNERS File
+
+Create `.github/CODEOWNERS` to automatically request reviews from maintainers:
+
+```
+# Default owner
+* @your-github-username
+
+# Specific areas
+/docs/ @your-github-username
+/bin/ @your-github-username
+/infrastructure/ @your-github-username
+```
+
+### Enable GitHub Actions (if using)
+
+1. Go to: `Settings > Actions > General`
+2. Enable Actions
+3. Create workflows in `.github/workflows/`
+
+Example workflow to add:
+- `test.yml` - Run tests on PRs
+- `lint.yml` - Run linting on PRs
+- `typecheck.yml` - Run type checking on PRs
+
+---
+
+## For Contributors
+
+With these settings, contributors will:
+
+1. Fork the repository
+2. Create a branch from `main`
+3. Make changes
+4. Push to their fork
+5. Create a PR to `main`
+6. Wait for at least 1 approval
+7. Address any review comments
+8. Maintainer merges the PR
+
+---
+
+## Emergency Access
+
+If you need to bypass rules for emergencies:
+
+1. Use GitHub's "Bypass branch protection" option (if enabled)
+2. Or temporarily disable the rule, make the change, re-enable
+3. Or use admin override (if "Do not allow bypassing" is disabled for admins)
+
+---
+
+**Last updated**: 2025-01-13
+

package/docs/CODE_STANDARDS.md

@@ -0,0 +1,440 @@
+# Code Standards - ast-intelligence-hooks
+
+## Table of Contents
+
+1. [Code Style](#code-style)
+2. [ESLint Configuration](#eslint-configuration)
+3. [TypeScript](#typescript)
+4. [Code Conventions](#code-conventions)
+5. [Pre-commit Hooks](#pre-commit-hooks)
+
+---
+
+## Code Style
+
+### JavaScript/TypeScript
+
+The project follows these conventions:
+
+- **Indentation**: 2 spaces
+- **Quotes**: Single quotes (`'`) for strings
+- **Semicolons**: Always use semicolons
+- **Trailing commas**: Use in multi-line objects and arrays
+- **Max line length**: 100 characters (soft, preferably 80)
+
+### Example
+
+```javascript
+const example = {
+  name: 'test',
+  value: 42,
+  items: ['a', 'b', 'c'],
+};
+
+function doSomething(param1, param2) {
+  if (param1 > param2) {
+    return param1;
+  }
+  return param2;
+}
+```
+
+---
+
+## ESLint Configuration
+
+### Current Configuration
+
+The project uses ESLint 9+ with flat configuration.
+
+**File**: `eslint.config.js`
+
+### Main Rules
+
+- **Error**: Problems that break functionality
+- **Warn**: Style issues and best practices
+- **Off**: Disabled rules (with justification)
+
+### Run ESLint
+
+```bash
+# Full linter
+npm run lint
+
+# Hooks only
+npm run lint:hooks
+
+# Auto fix
+npm run lint -- --fix
+```
+
+### Add New Rules
+
+Edit `eslint.config.js`:
+
+```javascript
+rules: {
+  'new-rule-name': 'error',
+  'another-rule': 'warn',
+}
+```
+
+---
+
+## TypeScript
+
+### Configuration
+
+**File**: `tsconfig.json`
+
+### Enabled Features
+
+- **Strict mode**: Enabled
+- **No implicit any**: Enabled
+- **Strict null checks**: Enabled
+- **No unused locals**: Enabled
+- **No unused parameters**: Enabled
+
+### Type Checking
+
+```bash
+# Verify types
+npm run typecheck
+
+# Or using tsc directly
+npx tsc --noEmit
+```
+
+### TypeScript Conventions
+
+- **Interfaces**: For objects and data structures
+- **Types**: For unions, intersections, and complex types
+- **Enums**: Only when absolutely necessary
+
+```typescript
+// ✅ Good: Interface for object
+interface User {
+  id: string;
+  name: string;
+}
+
+// ✅ Good: Type for union
+type Status = 'active' | 'inactive' | 'pending';
+
+// ❌ Avoid: Enum (prefer union types)
+enum Status {
+  Active,
+  Inactive,
+}
+```
+
+---
+
+## Code Conventions
+
+### Naming
+
+#### Variables and Functions
+
+- **camelCase** for variables and functions
+- Descriptive and self-documenting names
+- Avoid abbreviations (except common conventions like `id`, `url`)
+
+```javascript
+// ✅ Good
+const userName = 'John';
+function calculateTotalPrice(items) {}
+
+// ❌ Bad
+const un = 'John';
+function calc(items) {}
+```
+
+#### Classes
+
+- **PascalCase** for classes
+- Noun names that describe what it is
+
+```javascript
+// ✅ Good
+class UserRepository {}
+class AuditResult {}
+
+// ❌ Bad
+class userRepository {}
+class audit {}
+```
+
+#### Constants
+
+- **UPPER_SNAKE_CASE** for global constants
+- **camelCase** for local constants
+
+```javascript
+// ✅ Good
+const MAX_RETRIES = 3;
+const DEFAULT_TIMEOUT = 5000;
+
+// For local constants
+const defaultConfig = { timeout: 5000 };
+```
+
+### Files
+
+- **kebab-case** for file names
+- Extensions: `.js` for JavaScript, `.ts` for TypeScript
+
+```javascript
+// ✅ Good
+user-repository.js
+audit-result.ts
+feature-first-analyzer.js
+
+// ❌ Bad
+UserRepository.js
+auditResult.ts
+FeatureFirstAnalyzer.js
+```
+
+### File Structure
+
+```javascript
+// 1. External imports
+const fs = require('fs');
+const path = require('path');
+
+// 2. Internal imports
+const { Finding } = require('../domain/entities/Finding');
+const { analyzeBackend } = require('../infrastructure/ast/backend');
+
+// 3. Constants
+const MAX_SIZE = 1024;
+
+// 4. Helper functions
+function helperFunction() {}
+
+// 5. Main class/export
+class MainClass {
+  constructor() {}
+  
+  publicMethod() {}
+  
+  privateMethod() {}
+}
+
+// 6. Exports
+module.exports = { MainClass };
+```
+
+---
+
+## Clean Code Principles
+
+### 1. Single Responsibility
+
+```javascript
+// ❌ Bad: Multiple responsibilities
+class UserService {
+  getUser(id) {}
+  saveUser(user) {}
+  sendEmail(user) {}
+  generateReport() {}
+}
+
+// ✅ Good: Single responsibility
+class UserRepository {
+  getUser(id) {}
+  saveUser(user) {}
+}
+
+class EmailService {
+  sendEmail(user) {}
+}
+
+class ReportGenerator {
+  generateReport() {}
+}
+```
+
+### 2. Small Functions
+
+```javascript
+// ❌ Bad: Very long function
+function processOrder(order) {
+  // 50+ lines of code...
+}
+
+// ✅ Good: Small focused functions
+function processOrder(order) {
+  validateOrder(order);
+  calculateTotal(order);
+  applyDiscount(order);
+  saveOrder(order);
+  notifyUser(order);
+}
+```
+
+### 3. Early Returns
+
+```javascript
+// ❌ Bad: Nested ifs
+function process(data) {
+  if (data) {
+    if (data.valid) {
+      if (data.value) {
+        return processValue(data.value);
+      }
+    }
+  }
+  return null;
+}
+
+// ✅ Good: Early returns
+function process(data) {
+  if (!data) return null;
+  if (!data.valid) return null;
+  if (!data.value) return null;
+  
+  return processValue(data.value);
+}
+```
+
+### 4. Avoid Magic Numbers
+
+```javascript
+// ❌ Bad: Magic numbers
+if (user.age > 65) {
+  applySeniorDiscount(user);
+}
+
+// ✅ Good: Named constants
+const SENIOR_AGE_THRESHOLD = 65;
+if (user.age > SENIOR_AGE_THRESHOLD) {
+  applySeniorDiscount(user);
+}
+```
+
+### 5. Self-descriptive Names
+
+```javascript
+// ❌ Bad: Vague names
+function calc(a, b) {
+  return a * b * 1.19;
+}
+
+// ✅ Good: Descriptive names
+function calculateTotalWithTax(price, quantity) {
+  const TAX_RATE = 1.19;
+  return price * quantity * TAX_RATE;
+}
+```
+
+---
+
+## Pre-commit Hooks
+
+### Configuration
+
+Pre-commit hooks automatically run:
+
+1. **ESLint**: Code validation
+2. **Type checking**: TypeScript type verification
+3. **Tests**: Quick execution of relevant tests
+
+### Bypass (Emergencies Only)
+
+```bash
+GIT_BYPASS_HOOK=1 git commit -m "emergency fix"
+```
+
+⚠️ **Warning**: Only use in real emergencies.
+
+---
+
+## Comments
+
+### When to Comment
+
+- **DON'T comment obvious code**: Code should be self-descriptive
+- **DO comment**: Complex logic, design decisions, temporary hacks
+
+```javascript
+// ❌ Bad: Unnecessary comment
+// Increment the counter
+counter++;
+
+// ✅ Good: Self-descriptive code
+counter++;
+
+// ✅ Good: Useful comment for complex logic
+// We use Floyd-Warshall algorithm to find shortest path
+// because we need to consider multiple possible routes
+const shortestPath = floydWarshall(graph);
+```
+
+### Comment Format
+
+```javascript
+// Single line comment
+
+/**
+ * JSDoc comment for public functions/classes
+ * @param {string} name - User name
+ * @returns {boolean} Whether the user is valid
+ */
+function validateUser(name) {
+  // Implementation
+}
+```
+
+---
+
+## Git Commits
+
+### Commit Format
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `style`: Formatting, semicolons, etc.
+- `refactor`: Refactoring
+- `test`: Tests
+- `chore`: Maintenance tasks
+
+### Examples
+
+```bash
+feat(ast): add iOS SourceKitten integration
+
+fix(backend): resolve circular dependency detection
+
+docs(readme): update installation instructions
+
+refactor(domain): simplify AuditResult entity
+```
+
+---
+
+## References
+
+- [Clean Code by Robert C. Martin](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)
+- [ESLint Rules](https://eslint.org/docs/rules/)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+
+---
+
+**Last updated**: 2025-01-13  
+**Version**: 5.3.0