devflow-kit 0.9.0 → 1.1.0

package/shared/skills/regression-patterns/references/detection.md

@@ -0,0 +1,237 @@
+# Regression Detection Reference
+
+Bash commands and techniques for detecting regressions during code review.
+
+---
+
+## Export Comparison
+
+### Compare Module Exports
+
+```bash
+# List exports in main branch
+git show main:src/index.ts | grep -E "^export" > /tmp/exports_before.txt
+
+# List exports in current branch
+grep -E "^export" src/index.ts > /tmp/exports_after.txt
+
+# Find removed exports
+diff /tmp/exports_before.txt /tmp/exports_after.txt | grep "^<"
+```
+
+### Find All Removed Exports Across Files
+
+```bash
+# Get list of changed .ts files
+git diff main...HEAD --name-only --diff-filter=M "*.ts" | while read file; do
+  echo "=== $file ==="
+  diff <(git show main:"$file" 2>/dev/null | grep "^export") \
+       <(cat "$file" | grep "^export") | grep "^<" || echo "(no removals)"
+done
+```
+
+---
+
+## Function Usage Analysis
+
+### Find Removed Function Calls
+
+```bash
+# Check if function is still called
+git show main:src/*.ts | grep "oldFunction" | wc -l  # Before: 15
+grep -r "oldFunction" src/*.ts | wc -l                # After: 3 (12 removed!)
+```
+
+### Verify All Consumers Updated
+
+```bash
+# Find all imports of changed module
+grep -rn "from './changed-module'" --include="*.ts"
+
+# Check each importer for usage of changed exports
+for file in $(grep -l "from './changed-module'" src/**/*.ts); do
+  echo "=== $file ==="
+  grep -n "changedExport\|renamedFunction" "$file"
+done
+```
+
+### Find Incomplete Migrations
+
+```bash
+# Count usages of old vs new API
+echo "Old API usages:"
+grep -r "oldFunction" src/ --include="*.ts" | wc -l
+
+echo "New API usages:"
+grep -r "newFunction" src/ --include="*.ts" | wc -l
+
+# List files still using old API
+grep -rl "oldFunction" src/ --include="*.ts"
+```
+
+---
+
+## File Structure Comparison
+
+### Compare File Trees
+
+```bash
+# Compare file structure
+diff <(git ls-tree -r --name-only main src/) \
+     <(git ls-tree -r --name-only HEAD src/)
+```
+
+### Find Deleted Files
+
+```bash
+# Find removed files
+git diff main...HEAD --name-status | grep "^D"
+
+# Find removed test files specifically
+git diff main...HEAD --name-status | grep "^D.*test"
+
+# Find removed type definition files
+git diff main...HEAD --name-status | grep "^D.*\.d\.ts"
+```
+
+---
+
+## Change Analysis
+
+### Find Large Deletions
+
+```bash
+# Find files with significant deletions
+git diff main...HEAD --stat | grep -E "^\s+-" | head -20
+
+# Show deletion-heavy changes
+git diff main...HEAD --numstat | awk '$2 > 50 {print $3 ": +" $1 " -" $2}'
+```
+
+### Find TODO/FIXME Additions
+
+```bash
+# Find incomplete work markers
+git diff main...HEAD | grep "^\+.*TODO\|^\+.*FIXME"
+
+# Count new vs resolved TODOs
+echo "New TODOs:"
+git diff main...HEAD | grep "^\+.*TODO" | wc -l
+
+echo "Resolved TODOs:"
+git diff main...HEAD | grep "^-.*TODO" | wc -l
+```
+
+---
+
+## API Endpoint Analysis
+
+### Find Removed Routes
+
+```bash
+# Compare route definitions
+diff <(git show main:src/routes/*.ts | grep -E "app\.(get|post|put|delete|patch)") \
+     <(cat src/routes/*.ts | grep -E "app\.(get|post|put|delete|patch)")
+
+# Find removed Express routes
+git diff main...HEAD src/routes/ | grep "^-.*app\.\(get\|post\|put\|delete\)"
+```
+
+### Find Removed Event Handlers
+
+```bash
+# Compare event handlers
+diff <(git show main:src/**/*.ts | grep -E "\.on\(|\.addEventListener\(") \
+     <(cat src/**/*.ts | grep -E "\.on\(|\.addEventListener\(") | grep "^<"
+```
+
+---
+
+## CLI Option Analysis
+
+### Compare CLI Options
+
+```bash
+# Find commander/yargs options before
+git show main:src/cli.ts | grep -E "\.option\(|\.command\(" > /tmp/cli_before.txt
+
+# Find options after
+grep -E "\.option\(|\.command\(" src/cli.ts > /tmp/cli_after.txt
+
+# Compare
+diff /tmp/cli_before.txt /tmp/cli_after.txt | grep "^<"
+```
+
+---
+
+## Return Type Analysis
+
+### Find Changed Return Types
+
+```bash
+# Extract function signatures
+git show main:src/services/*.ts | grep -E "function.*\):" > /tmp/sigs_before.txt
+grep -E "function.*\):" src/services/*.ts > /tmp/sigs_after.txt
+
+# Compare (look for added | null, | undefined)
+diff /tmp/sigs_before.txt /tmp/sigs_after.txt
+```
+
+---
+
+## Side Effect Analysis
+
+### Find Removed Logging
+
+```bash
+# Count logger calls before vs after
+echo "Logging before:"
+git show main:src/**/*.ts | grep -c "logger\.\|console\."
+
+echo "Logging after:"
+grep -rc "logger\.\|console\." src/**/*.ts | awk -F: '{sum += $2} END {print sum}'
+```
+
+### Find Removed Event Emissions
+
+```bash
+# Count event emissions before vs after
+echo "Events before:"
+git show main:src/**/*.ts | grep -c "\.emit\("
+
+echo "Events after:"
+grep -rc "\.emit\(" src/**/*.ts | awk -F: '{sum += $2} END {print sum}'
+```
+
+---
+
+## Quick Regression Checks
+
+### All-in-One Regression Scan
+
+```bash
+#!/bin/bash
+# regression-check.sh
+
+echo "=== REGRESSION CHECK ==="
+
+echo -e "\n1. Removed exports:"
+git diff main...HEAD | grep "^-export" | head -10
+
+echo -e "\n2. Removed files:"
+git diff main...HEAD --name-status | grep "^D" | head -10
+
+echo -e "\n3. Removed routes:"
+git diff main...HEAD | grep "^-.*app\.\(get\|post\|put\|delete\)" | head -10
+
+echo -e "\n4. Removed event handlers:"
+git diff main...HEAD | grep "^-.*\.on\(" | head -10
+
+echo -e "\n5. New TODOs (incomplete work):"
+git diff main...HEAD | grep "^\+.*TODO" | head -10
+
+echo -e "\n6. Type changes (potential breaks):"
+git diff main...HEAD | grep "^\+.*| null\|^\+.*| undefined" | head -10
+
+echo -e "\n=== END CHECK ==="
+```

package/shared/skills/regression-patterns/references/patterns.md

@@ -0,0 +1,226 @@
+# Regression-Safe Patterns Reference
+
+Correct patterns for avoiding regressions during code changes.
+
+---
+
+## Safe Export Changes
+
+### Deprecation Before Removal
+
+```typescript
+// Step 1: Deprecate (release v1.1)
+/**
+ * @deprecated Use `createUserV2` instead. Will be removed in v2.0.
+ */
+export function createUser(data: UserData): User {
+  console.warn('createUser is deprecated. Use createUserV2.');
+  return createUserV2({ ...data, version: 1 });
+}
+
+// New function
+export function createUserV2(data: UserDataV2): User { }
+
+// Step 2: Remove in next major version (v2.0)
+// export function createUser - REMOVED with changelog entry
+export function createUserV2(data: UserDataV2): User { }
+```
+
+### Additive Changes Only
+
+```typescript
+// SAFE: Adding new exports
+export function existingFunction() { }  // Unchanged
+export function newFunction() { }       // Added - safe
+export const NEW_CONSTANT = 'value';    // Added - safe
+
+// SAFE: Adding optional parameters
+function fetch(url: string, options?: FetchOptions): Promise<Response> { }
+// Adding options parameter with default - safe for existing callers
+```
+
+---
+
+## Safe Return Type Changes
+
+### Widening with Type Guards
+
+```typescript
+// BEFORE
+function getUser(id: string): User { }
+
+// AFTER: Widen return type safely
+function getUser(id: string): User | null { }
+
+// MIGRATION: Provide type guard for existing callers
+function isUserFound(user: User | null): user is User {
+  return user !== null;
+}
+
+// Usage for existing code:
+const user = getUser(id);
+if (isUserFound(user)) {
+  console.log(user.name);  // Safe - type narrowed
+}
+```
+
+### Result Type Migration
+
+```typescript
+// BEFORE: Throws
+function parseConfig(json: string): Config {
+  if (!valid) throw new ConfigError('Invalid');
+  return config;
+}
+
+// AFTER: Returns Result
+function parseConfig(json: string): Result<Config, ConfigError> {
+  if (!valid) return { ok: false, error: new ConfigError('Invalid') };
+  return { ok: true, value: config };
+}
+
+// MIGRATION: Provide wrapper for existing callers
+function parseConfigOrThrow(json: string): Config {
+  const result = parseConfig(json);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+```
+
+---
+
+## Safe Default Value Changes
+
+### Explicit Override
+
+```typescript
+// BEFORE
+function fetch(url: string, timeout = 5000): Promise<Response> { }
+
+// AFTER: New default with explicit legacy option
+const LEGACY_TIMEOUT = 5000;
+const NEW_TIMEOUT = 1000;
+
+function fetch(
+  url: string,
+  timeout = NEW_TIMEOUT,
+  options?: { useLegacyTimeout?: boolean }
+): Promise<Response> {
+  const actualTimeout = options?.useLegacyTimeout ? LEGACY_TIMEOUT : timeout;
+  // ...
+}
+
+// Existing code can opt-in to legacy behavior
+fetch(url, undefined, { useLegacyTimeout: true });
+```
+
+---
+
+## Safe API Changes
+
+### Versioned Endpoints
+
+```typescript
+// Keep old endpoint, add new version
+app.get('/api/v1/users/:id', getUserV1);  // Unchanged
+app.get('/api/v2/users/:id', getUserV2);  // New version
+
+// Document deprecation timeline
+// v1 sunset: 2025-06-01
+```
+
+### Backward Compatible Response
+
+```typescript
+// BEFORE response
+{ id: '123', name: 'John' }
+
+// AFTER: Add fields, don't remove
+{ id: '123', name: 'John', displayName: 'John Doe', avatar: 'url' }
+// name still present for backward compatibility
+```
+
+---
+
+## Complete Migration Pattern
+
+### Track Migration Progress
+
+```typescript
+// migration-tracker.ts
+const MIGRATION_STATUS = {
+  'src/api/users.ts': 'complete',
+  'src/api/orders.ts': 'complete',
+  'src/services/auth.ts': 'pending',    // NOT YET MIGRATED
+  'src/utils/format.ts': 'pending',     // NOT YET MIGRATED
+} as const;
+
+// Verify before merge
+function assertMigrationComplete(): void {
+  const pending = Object.entries(MIGRATION_STATUS)
+    .filter(([_, status]) => status === 'pending');
+
+  if (pending.length > 0) {
+    throw new Error(`Migration incomplete: ${pending.map(([f]) => f).join(', ')}`);
+  }
+}
+```
+
+### Automated Consumer Updates
+
+```typescript
+// codemod for migration
+// jscodeshift transform
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+
+  return j(file.source)
+    .find(j.CallExpression, { callee: { name: 'oldFunction' } })
+    .replaceWith(path => {
+      const [a, b] = path.node.arguments;
+      return j.callExpression(
+        j.identifier('newFunction'),
+        [j.objectExpression([
+          j.property('init', j.identifier('a'), a),
+          j.property('init', j.identifier('b'), b),
+        ])]
+      );
+    })
+    .toSource();
+}
+```
+
+---
+
+## Event Handler Safety
+
+### Preserve Side Effects
+
+```typescript
+// When refactoring, preserve all side effects
+function processOrder(order: Order): ProcessedOrder {
+  // PRESERVED: Logging for debugging
+  logger.info('Processing order', { orderId: order.id });
+
+  const result = doProcessing(order);
+
+  // PRESERVED: Event for downstream systems
+  events.emit('order.processed', result);
+
+  return result;
+}
+```
+
+### Document Intentional Removal
+
+```typescript
+// If side effect removal is intentional, document it
+function processOrder(order: Order): ProcessedOrder {
+  // INTENTIONAL: Removed analytics event (tracked in ANALYTICS-123)
+  // Reason: Moving to dedicated analytics service
+  // Migration: Analytics service polls order database directly
+
+  const result = doProcessing(order);
+  return result;
+}
+```

package/shared/skills/regression-patterns/references/violations.md

@@ -0,0 +1,225 @@
+# Regression Violations Reference
+
+Extended examples of regression patterns to detect during code review.
+
+---
+
+## Lost Functionality Violations
+
+### Removed Exports
+
+```typescript
+// BEFORE: module exports
+export function createUser(data: UserData): User { }
+export function deleteUser(id: string): void { }
+export function updateUser(id: string, data: Partial<UserData>): User { }
+export const USER_ROLES = ['admin', 'user', 'guest'] as const;
+
+// AFTER: exports removed (REGRESSION!)
+export function createUser(data: UserData): User { }
+// deleteUser - REMOVED
+// updateUser - REMOVED
+// USER_ROLES - REMOVED
+```
+
+### Removed CLI Options
+
+```typescript
+// BEFORE
+program
+  .option('-v, --verbose', 'Verbose output')
+  .option('-q, --quiet', 'Quiet mode')
+  .option('-f, --force', 'Force operation')
+  .option('--dry-run', 'Preview changes');
+
+// AFTER: options removed (REGRESSION!)
+program
+  .option('-v, --verbose', 'Verbose output');
+// --quiet, --force, --dry-run REMOVED
+
+// Users with scripts using these flags will break!
+```
+
+### Removed API Endpoints
+
+```typescript
+// BEFORE
+app.get('/api/users', listUsers);
+app.get('/api/users/:id', getUser);
+app.post('/api/users', createUser);
+app.delete('/api/users/:id', deleteUser);  // REMOVED!
+
+// AFTER
+app.get('/api/users', listUsers);
+app.get('/api/users/:id', getUser);
+app.post('/api/users', createUser);
+// DELETE endpoint removed - clients will get 404!
+```
+
+### Removed Event Handlers
+
+```typescript
+// BEFORE
+eventBus.on('user.created', sendWelcomeEmail);
+eventBus.on('user.created', syncToAnalytics);
+eventBus.on('order.completed', updateInventory);
+
+// AFTER
+eventBus.on('user.created', sendWelcomeEmail);
+// syncToAnalytics handler REMOVED - analytics will be incomplete!
+// updateInventory handler REMOVED - inventory won't update!
+```
+
+---
+
+## Broken Behavior Violations
+
+### Changed Return Types
+
+```typescript
+// BEFORE
+async function getUser(id: string): Promise<User> {
+  return user;
+}
+
+// AFTER: Return type changed (BREAKING!)
+async function getUser(id: string): Promise<User | null> {
+  return user ?? null;
+}
+
+// All callers assuming non-null will break:
+const user = await getUser(id);
+console.log(user.name);  // Potential null dereference!
+```
+
+### Changed Side Effects
+
+```typescript
+// BEFORE: Function logs and emits event
+function processOrder(order: Order): ProcessedOrder {
+  logger.info('Processing order', { orderId: order.id });
+  const result = doProcessing(order);
+  events.emit('order.processed', result);
+  return result;
+}
+
+// AFTER: Side effects removed (REGRESSION!)
+function processOrder(order: Order): ProcessedOrder {
+  const result = doProcessing(order);
+  return result;
+  // No logging - harder to debug production issues!
+  // No event - downstream systems won't be notified!
+}
+```
+
+### Changed Default Values
+
+```typescript
+// BEFORE
+interface Options {
+  timeout?: number;  // default: 5000
+  retries?: number;  // default: 3
+}
+
+function fetch(url: string, options: Options = { timeout: 5000, retries: 3 }) { }
+
+// AFTER: Defaults changed (REGRESSION!)
+function fetch(url: string, options: Options = { timeout: 1000, retries: 1 }) { }
+// Existing code relying on 5s timeout may start failing!
+```
+
+### Changed Error Handling
+
+```typescript
+// BEFORE: Throws specific error
+async function authenticate(credentials: Credentials): Promise<User> {
+  if (!valid) throw new AuthenticationError('Invalid credentials');
+  return user;
+}
+
+// AFTER: Returns null instead (BREAKING!)
+async function authenticate(credentials: Credentials): Promise<User | null> {
+  if (!valid) return null;  // Callers catching AuthenticationError will miss this!
+  return user;
+}
+```
+
+---
+
+## Intent Mismatch Violations
+
+### Commit Says X, Code Does Y
+
+```typescript
+// Commit message: "Add retry logic to API calls"
+
+// ACTUAL CODE: No retry logic!
+async function fetchData(): Promise<Data> {
+  const response = await api.get('/data');
+  return response.data;
+}
+
+// Expected: Retry on failure
+// Reality: No retry implemented
+```
+
+### Partial Implementation
+
+```typescript
+// Commit message: "Implement user preferences"
+
+// ACTUAL CODE: Only partial implementation
+interface UserPreferences {
+  theme: 'light' | 'dark';
+  language: string;
+  notifications: NotificationSettings;  // Not implemented!
+  privacy: PrivacySettings;             // Not implemented!
+}
+
+function updatePreferences(prefs: Partial<UserPreferences>) {
+  if (prefs.theme) user.theme = prefs.theme;
+  if (prefs.language) user.language = prefs.language;
+  // notifications and privacy not handled!
+}
+```
+
+---
+
+## Incomplete Migration Violations
+
+### Partial Call Site Updates
+
+```typescript
+// OLD API
+function oldFunction(a: string, b: number): Result { }
+
+// NEW API
+function newFunction(params: { a: string; b: number }): Result { }
+
+// PARTIALLY MIGRATED:
+// file1.ts - Updated
+const result = newFunction({ a: 'test', b: 42 });
+
+// file2.ts - NOT updated (REGRESSION!)
+const result = oldFunction('test', 42);  // Still using old API!
+
+// file3.ts - NOT updated (REGRESSION!)
+const result = oldFunction('other', 100);  // Still using old API!
+```
+
+### Consumer Model Mismatch
+
+```typescript
+// CHANGED: User model
+interface User {
+  id: string;
+  email: string;
+  // name: string;  // REMOVED
+  displayName: string;  // ADDED (replacement)
+}
+
+// CONSUMER NOT UPDATED (REGRESSION!)
+function formatUserGreeting(user: User): string {
+  return `Hello, ${user.name}!`;  // TypeScript error: 'name' doesn't exist
+}
+```