breaking-change-detector

Detection:

Change type: API endpoint removal
File: routes/stats.ts
Line: router.get('/api/v1/stats', ...)
Action: DELETE

Impact analysis:

# Search for endpoint usage
grep -r "/api/v1/stats" --include="*.ts" --include="*.js"

Found:
- Frontend: src/services/api.ts (1 call)
- Mobile app: Documented in integration guide
- API logs: 450 requests/day

Clients:
- Web dashboard (internal, can update)
- Mobile app v2.3 (external, 10K users)
- Unknown clients (logged as "curl/7.0", "Python requests")

Severity determination:

Traffic: 450 requests/day → Moderate usage
Clients: External mobile app → Cannot force update
Unknown clients: Present → Unpredictable impact

Severity: CRITICAL
Reason: External clients depend on endpoint

Migration suggestion:

🚨 BREAKING CHANGE BLOCKED

Cannot remove /api/v1/stats - active external usage detected.

Impact:
- Mobile app v2.3 (10K users)
- Unknown clients (curl, Python scripts)
- 450 requests/day

Safe migration path (RECOMMENDED):

Phase 1: Deprecation (Days 0-90)
1. Add response header: X-Deprecated: "true; sunset=2025-03-01; replacement=/api/v2/analytics"
2. Add deprecation notice to API docs
3. Email known clients (mobile team)
4. Log warnings when endpoint called

Phase 2: Monitoring (Days 0-90)
1. Track usage metrics
2. Identify remaining clients (log User-Agent)
3. Reach out to high-volume clients

Phase 3: Removal (Day 90+)
1. Wait until usage < 10 requests/day
2. Return 410 Gone with migration instructions
3. Monitor for spikes (indicates missed client)
4. Remove code after 30 days at 410

Estimated timeline: 4 months

Would you like me to implement Phase 1 (deprecation)?

Implementation (if approved):

// routes/stats.ts (DEPRECATE, don't remove)
router.get('/api/v1/stats',
  deprecationMiddleware({
    sunset: '2025-03-01',
    replacement: '/api/v2/analytics',
    message: 'This endpoint is deprecated and will be removed on 2025-03-01'
  }),
  statsController.getStats  // Keep working
);

// middleware/deprecation.ts (NEW)
export function deprecationMiddleware(options: DeprecationOptions) {
  return (req, res, next) => {
    res.header('X-Deprecated', 'true');
    res.header('Sunset', options.sunset);
    res.header('Link', `<${options.replacement}>; rel="successor-version"`);

    logger.warn('Deprecated endpoint called', {
      endpoint: req.path,
      client: req.get('User-Agent'),
      ip: req.ip,
      sunset: options.sunset
    });

    next();
  };
}

See examples/api-endpoint-removal-full.md for complete example.

Change type: Database column removal
Table: users
Column: phone
Action: DROP COLUMN

# Search for column usage
grep -r "\.phone\|phone:" --include="*.ts"

Found:
- models/User.ts: phone: string
- services/UserService.ts: user.phone (3 references)
- controllers/UserController.ts: req.body.phone (1 reference)
- Database: 15,000 users have phone numbers (non-null)

Data at risk: 15,000 phone numbers
Code impact: 5 files, 10 references

Data loss: 15,000 records → CRITICAL
Code breakage: 5 files → HIGH
Rollback difficulty: Cannot recover deleted data → CRITICAL

Severity: CRITICAL
Reason: Irreversible data loss

🚨 BREAKING CHANGE BLOCKED

Cannot drop users.phone column - data loss risk.

Impact:
- 15,000 users have phone numbers (data loss)
- 5 files reference phone column (code breaks)
- No backup of phone data

Safe migration path (RECOMMENDED):

Option A: Soft delete (SAFEST)
1. Rename column: phone → phone_deprecated
2. Make column nullable
3. Update code to not use phone
4. Keep data for 6 months
5. Drop column after verification period

Option B: Archive before delete
1. Export phone data to archive table
2. Create users_phone_archive(user_id, phone, archived_at)
3. Copy data: INSERT INTO users_phone_archive SELECT id, phone FROM users
4. Verify archive: Check row counts match
5. Drop column from users table
6. Keep archive table indefinitely

Option C: Make nullable (don't drop)
1. ALTER TABLE users ALTER COLUMN phone DROP NOT NULL
2. Update code to handle null
3. Set existing phones to null (or keep them)
4. Column exists but unused (no data loss)

Which option do you prefer? I recommend Option B (archive).

Change type: Function signature modification
Function: getUserById
Return type change: Promise<User> → Promise<User | null>

// Search for function calls
grep -r "getUserById" --include="*.ts"

Found 23 call sites:
- controllers/UserController.ts (3 calls)
- services/OrderService.ts (5 calls)
- services/NotificationService.ts (2 calls)
- ... (13 more files)

None handle null return:
const user = await getUserById(id);
user.name  // Will throw if null

Call sites: 23 locations
Null handling: 0/23 handle null
Impact: Runtime errors (Cannot read 'name' of null)

Severity: HIGH
Reason: Breaks existing code with runtime errors

⚠️ BREAKING CHANGE DETECTED

Changing getUserById return type to nullable breaks 23 call sites.

Current: Promise<User> (never null)
Proposed: Promise<User | null> (can be null)

Impact:
- 23 call sites assume non-null
- Will throw "Cannot read property of null" at runtime
- Requires updating all callers

Safe migration path:

Option A: Deprecate + replace (RECOMMENDED)
1. Keep getUserById as-is (throws if not found)
2. Create findUserById that returns User | null
3. Update callers gradually to findUserById
4. Mark getUserById as @deprecated
5. Remove getUserById in v2.0

Option B: Update all callers first
1. Find all 23 call sites
2. Add null checks: if (!user) throw new NotFoundError()
3. Then change return type
4. Runtime-safe, but large changeset

Option C: Overload (TypeScript only)
1. Add overload: getUserById(id, options: { throwIfNotFound: false }): Promise<User | null>
2. Keep default: getUserById(id): Promise<User>
3. Backward compatible

Recommended: Option A (new function)

// services/UserService.ts

/**
 * Get user by ID
 * @deprecated Use findUserById instead. This will be removed in v2.0.
 * @throws NotFoundError if user doesn't exist
 */
async getUserById(id: string): Promise<User> {
  const user = await this.findUserById(id);
  if (!user) {
    throw new NotFoundError(`User ${id} not found`);
  }
  return user;
}

/**
 * Find user by ID
 * @returns User if found, null otherwise
 */
async findUserById(id: string): Promise<User | null> {
  return await prisma.user.findUnique({ where: { id } });
}

Detector: "⚠️ This will break clients"
Developer: "It's fine, I'll fix it later" *proceeds anyway*
Result: Production breaks, emergency rollback

Detector: "⚠️ This will break clients"
Developer: "Let me implement the migration path first"
*Implements deprecation strategy*
*Then makes change safely*

-- Just drop it
DROP TABLE old_users;

-- Deprecate first
ALTER TABLE old_users RENAME TO old_users_deprecated;

-- Add deprecation notice
COMMENT ON TABLE old_users_deprecated IS 'DEPRECATED: Use users table instead. Will be dropped 2025-06-01';

-- Monitor usage (if any queries fail, we know what's still using it)

-- Drop after deprecation period
DROP TABLE old_users_deprecated;  -- 6 months later

// v1 returns array
GET /api/users → [{ id: 1 }, { id: 2 }]

// Changed to pagination (BREAKING)
GET /api/users → { items: [...], total: 2, page: 1 }

// v1 unchanged
GET /api/v1/users → [{ id: 1 }, { id: 2 }]

// v2 with pagination
GET /api/v2/users → { items: [...], total: 2, page: 1 }

ALTER TABLE users DROP COLUMN legacy_id;  -- Data gone forever

-- Archive first
CREATE TABLE users_legacy_data AS
SELECT id, legacy_id FROM users;

-- Then drop
ALTER TABLE users DROP COLUMN legacy_id;

-- Keep archive for 12 months