@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/_shared/rules/conventions/git.md

@@ -0,0 +1,265 @@
+---
+paths:
+  - "**/*"
+---
+
+# Git Rules
+
+## Commit Messages (Conventional Commits)
+
+Format: `type(scope): description`
+
+```bash
+# Types
+feat     # New feature
+fix      # Bug fix
+docs     # Documentation only
+style    # Formatting, no code change
+refactor # Code change, no feature/fix
+perf     # Performance improvement
+test     # Adding/updating tests
+chore    # Build, CI, dependencies
+```
+
+```bash
+# Good examples
+feat(auth): add OAuth2 login with Google
+fix(cart): resolve race condition in checkout
+refactor(api): simplify error handling middleware
+perf(db): add index on users.email column
+test(orders): add integration tests for payment flow
+chore(deps): upgrade typescript to 5.3
+
+# Bad examples
+fix: bug fix                    # Too vague
+updated stuff                   # No type, unclear
+feat: Add new feature for users # Capitalized, vague
+```
+
+## Branch Naming
+
+```bash
+# Pattern: type/description or type/TICKET-description
+feat/user-authentication
+feat/JIRA-123-oauth-login
+fix/cart-total-calculation
+fix/BUG-456-null-pointer
+refactor/api-error-handling
+chore/upgrade-dependencies
+```
+
+## Workflow
+
+```bash
+# Start new feature
+git checkout main
+git pull --rebase
+git checkout -b feat/my-feature
+
+# Regular commits during work
+git add -p                    # Stage interactively
+git commit -m "feat(scope): description"
+
+# Before pushing - rebase on main
+git fetch origin
+git rebase origin/main
+
+# Push (first time)
+git push -u origin feat/my-feature
+
+# Push (subsequent)
+git push
+```
+
+## Rebase vs Merge
+
+```bash
+# ALWAYS rebase local changes on remote
+git pull --rebase origin main
+
+# NEVER merge main into feature branch
+git merge main    # Creates ugly merge commits
+
+# Interactive rebase to clean up commits before PR
+git rebase -i HEAD~3
+```
+
+## Interactive Rebase
+
+```bash
+# Clean up last 3 commits
+git rebase -i HEAD~3
+
+# In editor:
+pick abc1234 feat(auth): add login endpoint
+squash def5678 fix typo              # Squash into previous
+fixup ghi9012 more fixes             # Squash, discard message
+reword jkl3456 wip                   # Edit commit message
+```
+
+## Stashing
+
+```bash
+# Save work in progress
+git stash push -m "WIP: feature description"
+
+# List stashes
+git stash list
+
+# Apply and drop
+git stash pop
+
+# Apply specific stash
+git stash apply stash@{2}
+
+# Drop stash
+git stash drop stash@{0}
+```
+
+## Undoing Changes
+
+```bash
+# Unstage file (keep changes)
+git restore --staged file.ts
+
+# Discard local changes (DESTRUCTIVE)
+git restore file.ts
+
+# Undo last commit (keep changes staged)
+git reset --soft HEAD~1
+
+# Undo last commit (keep changes unstaged)
+git reset HEAD~1
+
+# Completely undo last commit (DESTRUCTIVE)
+git reset --hard HEAD~1
+
+# Create new commit that undoes previous
+git revert abc1234
+```
+
+## Viewing History
+
+```bash
+# Compact log
+git log --oneline -20
+
+# With graph
+git log --oneline --graph --all
+
+# Changes in commit
+git show abc1234
+
+# Who changed this line
+git blame file.ts
+
+# Search commits by message
+git log --grep="fix auth"
+
+# Search commits by code change
+git log -S "functionName" --oneline
+```
+
+## Cherry-Pick
+
+```bash
+# Apply specific commit to current branch
+git cherry-pick abc1234
+
+# Cherry-pick without committing
+git cherry-pick --no-commit abc1234
+
+# Cherry-pick range
+git cherry-pick abc1234..def5678
+```
+
+## Tags
+
+```bash
+# Create annotated tag
+git tag -a v1.2.0 -m "Release 1.2.0"
+
+# Push tags
+git push origin v1.2.0
+git push origin --tags
+
+# List tags
+git tag -l "v1.*"
+
+# Delete tag
+git tag -d v1.2.0
+git push origin :refs/tags/v1.2.0
+```
+
+## Hooks (Husky)
+
+```bash
+# .husky/pre-commit
+npm run lint-staged
+
+# .husky/commit-msg
+npx commitlint --edit $1
+
+# .husky/pre-push
+npm run test
+```
+
+## .gitignore Essentials
+
+```gitignore
+# Dependencies
+node_modules/
+.venv/
+vendor/
+
+# Build
+dist/
+build/
+*.dll
+*.exe
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Environment
+.env
+.env.local
+*.local
+
+# Secrets (NEVER commit)
+*.pem
+*.key
+credentials.json
+secrets.yaml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Test
+coverage/
+.nyc_output/
+```
+
+## PR Best Practices
+
+```bash
+# Keep PRs small and focused
+# - One feature/fix per PR
+# - <400 lines changed ideal
+# - Split large changes into stacked PRs
+
+# Before creating PR
+git rebase -i origin/main    # Clean history
+npm run lint                  # Pass lint
+npm run test                  # Pass tests
+
+# PR title follows commit convention
+feat(auth): add OAuth2 login with Google
+```

package/configs/_shared/rules/conventions/npm.md

@@ -0,0 +1,80 @@
+---
+paths:
+  - "**/package.json"
+---
+
+# npm Conventions
+
+## Version Pinning
+
+**Always use exact versions** - no `^` or `~` prefixes.
+
+```json
+// GOOD
+{
+  "dependencies": {
+    "express": "4.18.2",
+    "lodash": "4.17.21"
+  }
+}
+
+// BAD
+{
+  "dependencies": {
+    "express": "^4.18.2",
+    "lodash": "~4.17.21"
+  }
+}
+```
+
+### Why?
+
+- **Reproducible builds** across environments
+- **No surprise breaking changes** from minor/patch updates
+- **Lock file is source of truth** but pinning adds defense in depth
+- **Explicit upgrades** via `npm update` or renovate/dependabot
+
+### Commands
+
+```bash
+# Install with exact version
+npm install express --save-exact
+
+# Configure npm to always save exact
+npm config set save-exact true
+
+# Or in .npmrc
+save-exact=true
+```
+
+## Scripts
+
+Use consistent script names:
+
+```json
+{
+  "scripts": {
+    "dev": "...",
+    "build": "...",
+    "start": "...",
+    "test": "...",
+    "test:watch": "...",
+    "test:cov": "...",
+    "lint": "...",
+    "lint:fix": "...",
+    "format": "..."
+  }
+}
+```
+
+## Engine Requirements
+
+Specify Node.js version:
+
+```json
+{
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}
+```

package/configs/_shared/{.claude/rules → rules/conventions}/performance.md

@@ -79,7 +79,7 @@ await cache.delete(`user:${userId}`);
 ### Memoization
 ```typescript
 // Memoize pure functions
-const memoize = <T>(fn: (...args: any[]) => T): ((...args: any[]) => T) => {
+const memoize = <T, Args extends unknown[]>(fn: (...args: Args) => T): ((...args: Args) => T) => {
   const cache = new Map();
   return (...args) => {
     const key = JSON.stringify(args);

package/configs/_shared/rules/conventions/principles.md

@@ -0,0 +1,334 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.py"
+  - "**/*.cs"
+---
+
+# Software Engineering Principles
+
+## YAGNI - You Aren't Gonna Need It
+
+Don't implement features until they're actually needed.
+
+```typescript
+// BAD - Building for hypothetical future
+interface UserService {
+  getUser(id: string): User;
+  getUserWithCache(id: string, ttl?: number): User;
+  getUserAsync(id: string): Promise<User>;
+  getUserBatch(ids: string[]): User[];
+  getUserByEmail(email: string): User;
+  getUserByPhone(phone: string): User;  // No one asked for this
+  getUserBySSN(ssn: string): User;      // No one asked for this
+}
+
+// GOOD - Only what's needed now
+interface UserService {
+  getUser(id: string): Promise<User>;
+  getUserByEmail(email: string): Promise<User>;
+}
+```
+
+```typescript
+// BAD - Premature abstraction
+class AbstractDataProcessor<T, R, C extends Config> {
+  // 200 lines of "flexible" code no one uses
+}
+
+// GOOD - Concrete implementation
+function processUserData(users: User[]): ProcessedUser[] {
+  return users.map(u => ({ ...u, fullName: `${u.first} ${u.last}` }));
+}
+```
+
+## KISS - Keep It Simple, Stupid
+
+Choose the simplest solution that works.
+
+```typescript
+// BAD - Over-engineered
+class StringUtils {
+  private static instance: StringUtils;
+  private constructor() {}
+
+  static getInstance(): StringUtils {
+    if (!this.instance) this.instance = new StringUtils();
+    return this.instance;
+  }
+
+  capitalize(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+}
+// Usage: StringUtils.getInstance().capitalize('hello')
+
+// GOOD - Simple function
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+// Usage: capitalize('hello')
+```
+
+```typescript
+// BAD - Unnecessary complexity
+const isAdult = (age: number) =>
+  new AgeValidator(new AgePolicy(18)).validate(age).isValid();
+
+// GOOD - Direct and clear
+const isAdult = (age: number) => age >= 18;
+```
+
+## SOLID Principles
+
+### S - Single Responsibility
+
+A class/function should have only one reason to change.
+
+```typescript
+// BAD - Multiple responsibilities
+class UserService {
+  createUser(data: UserData) { /* ... */ }
+  sendWelcomeEmail(user: User) { /* ... */ }
+  generatePDF(user: User) { /* ... */ }
+  validateCreditCard(card: Card) { /* ... */ }
+}
+
+// GOOD - Single responsibility each
+class UserService {
+  createUser(data: UserData) { /* ... */ }
+}
+
+class EmailService {
+  sendWelcomeEmail(user: User) { /* ... */ }
+}
+
+class PDFService {
+  generateUserReport(user: User) { /* ... */ }
+}
+```
+
+### O - Open/Closed
+
+Open for extension, closed for modification.
+
+```typescript
+// BAD - Must modify to add new types
+function calculateArea(shape: Shape) {
+  if (shape.type === 'circle') {
+    return Math.PI * shape.radius ** 2;
+  } else if (shape.type === 'rectangle') {
+    return shape.width * shape.height;
+  }
+  // Must add new else-if for each shape
+}
+
+// GOOD - Extend without modifying
+interface Shape {
+  area(): number;
+}
+
+class Circle implements Shape {
+  constructor(private radius: number) {}
+  area() { return Math.PI * this.radius ** 2; }
+}
+
+class Rectangle implements Shape {
+  constructor(private width: number, private height: number) {}
+  area() { return this.width * this.height; }
+}
+
+// Add new shapes without changing existing code
+class Triangle implements Shape {
+  constructor(private base: number, private height: number) {}
+  area() { return 0.5 * this.base * this.height; }
+}
+```
+
+### L - Liskov Substitution
+
+Subtypes must be substitutable for their base types.
+
+```typescript
+// BAD - Violates LSP
+class Bird {
+  fly() { /* ... */ }
+}
+
+class Penguin extends Bird {
+  fly() { throw new Error("Can't fly!"); } // Breaks substitutability
+}
+
+// GOOD - Proper hierarchy
+interface Bird {
+  move(): void;
+}
+
+class FlyingBird implements Bird {
+  move() { this.fly(); }
+  private fly() { /* ... */ }
+}
+
+class Penguin implements Bird {
+  move() { this.swim(); }
+  private swim() { /* ... */ }
+}
+```
+
+### I - Interface Segregation
+
+Clients shouldn't depend on interfaces they don't use.
+
+```typescript
+// BAD - Fat interface
+interface Worker {
+  work(): void;
+  eat(): void;
+  sleep(): void;
+  attendMeeting(): void;
+  writeReport(): void;
+}
+
+// GOOD - Segregated interfaces
+interface Workable {
+  work(): void;
+}
+
+interface Meetable {
+  attendMeeting(): void;
+}
+
+interface Reportable {
+  writeReport(): void;
+}
+
+class Developer implements Workable, Meetable {
+  work() { /* ... */ }
+  attendMeeting() { /* ... */ }
+}
+
+class Robot implements Workable {
+  work() { /* ... */ }
+  // Doesn't need eat, sleep, or meetings
+}
+```
+
+### D - Dependency Inversion
+
+Depend on abstractions, not concretions.
+
+```typescript
+// BAD - Depends on concrete implementation
+class OrderService {
+  private db = new MySQLDatabase();
+  private mailer = new SendGridMailer();
+
+  createOrder(order: Order) {
+    this.db.save(order);
+    this.mailer.send(order.userEmail, 'Order confirmed');
+  }
+}
+
+// GOOD - Depends on abstractions
+class OrderService {
+  constructor(
+    private repository: OrderRepository,
+    private notifier: Notifier,
+  ) {}
+
+  createOrder(order: Order) {
+    this.repository.save(order);
+    this.notifier.notify(order.userEmail, 'Order confirmed');
+  }
+}
+
+// Can inject any implementation
+new OrderService(new PostgresOrderRepo(), new EmailNotifier());
+new OrderService(new MongoOrderRepo(), new SMSNotifier());
+```
+
+## SoC - Separation of Concerns
+
+Separate code into distinct sections, each handling a specific concern.
+
+```typescript
+// BAD - Mixed concerns
+async function handleUserRegistration(req: Request, res: Response) {
+  // Validation
+  if (!req.body.email.includes('@')) {
+    return res.status(400).json({ error: 'Invalid email' });
+  }
+
+  // Business logic
+  const hashedPassword = await bcrypt.hash(req.body.password, 10);
+
+  // Data access
+  const user = await db.query(
+    'INSERT INTO users (email, password) VALUES ($1, $2)',
+    [req.body.email, hashedPassword]
+  );
+
+  // Presentation
+  return res.json({ id: user.id, email: user.email });
+}
+
+// GOOD - Separated concerns
+// validation.ts
+const userSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+// user.service.ts
+class UserService {
+  async register(data: CreateUserDto): Promise<User> {
+    const hashedPassword = await this.hashPassword(data.password);
+    return this.userRepository.create({ ...data, password: hashedPassword });
+  }
+}
+
+// user.controller.ts
+async function register(req: Request, res: Response) {
+  const data = userSchema.parse(req.body);
+  const user = await userService.register(data);
+  return res.json(toUserResponse(user));
+}
+```
+
+## DRY - Don't Repeat Yourself
+
+But don't over-apply it. Duplication is better than the wrong abstraction.
+
+```typescript
+// BAD - Premature DRY (wrong abstraction)
+function processEntity(entity: User | Product | Order, action: string) {
+  // 100 lines of if/else handling all cases
+}
+
+// GOOD - Some duplication is OK when contexts differ
+function processUser(user: User) { /* user-specific logic */ }
+function processProduct(product: Product) { /* product-specific logic */ }
+function processOrder(order: Order) { /* order-specific logic */ }
+
+// GOOD - DRY when truly duplicated
+function formatCurrency(amount: number): string {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount);
+}
+// Use everywhere instead of repeating the formatting logic
+```
+
+## Summary
+
+| Principle | Remember |
+|-----------|----------|
+| YAGNI | Build what you need now, not what you might need |
+| KISS | Simple > Clever. If it's hard to explain, simplify it |
+| SRP | One reason to change per class/function |
+| OCP | Add new code, don't modify existing code |
+| LSP | Subtypes must honor parent contracts |
+| ISP | Small, focused interfaces > large, general ones |
+| DIP | Inject dependencies, don't instantiate them |
+| SoC | Validation, business logic, data access = separate |
+| DRY | Avoid duplication, but not at the cost of clarity |