```
**🔧 Prevention:**
1. **Target specific files** instead of entire directories
2. **Use `--dry` run first** to verify only expected files change
3. **Review all diffs carefully** before committing
4. **Create cleanup commits** if formatting issues slip through
**🔧 Cleanup Pattern:**
```typescript
// Find files with formatting artifacts
git diff HEAD~1 HEAD --name-only | grep -v "target-component"
// Manual cleanup needed for unintended changes
```
### Documentation Reversion Issues
**⚠️ Problem:** Linters, formatters, or branch switches can revert documentation changes.
**🔧 Prevention:**
- **Commit documentation separately** from code changes
- **Verify documentation persists** after all code changes
- **Check git status** before final PR creation
- **Re-add documentation** if reverted by automation
### Component Package Dependencies
**⚠️ Problem:** Components in different packages need different import handling.
```typescript
// Icon is in @vibe/icon but also re-exported from @vibe/core
// Both need to be handled correctly
```
**🔧 Solution:**
- Check component package structure first
- Handle both direct imports and re-exports
- Test codemod on actual usage patterns
### Build System Validation
**⚠️ Problem:** Not all components build even before changes, causing false positives.
**🔧 Approach:**
- **Test individual packages** first (`yarn workspace @vibe/icon build`)
- **Focus on changed packages** rather than full monorepo build
- **Separate build issues** from breaking change issues
### Cross-Package Component Updates
**⚠️ Problem:** Breaking changes often affect components across multiple packages, not just the main @vibe/core package.
**Real Example - Icon Migration:**
Icon component is in `@vibe/icon` but used throughout:
- `packages/components/tooltip/` - standalone package using Icon
- `packages/core/src/components/` - 25+ core components using Icon
- `packages/components/icon-button/` - IconButton using Icon internally
- `packages/mcp/` - documentation and examples
**🔧 Comprehensive Search Strategy:**
```bash
# 1. Find ALL files with old prop usage across entire monorepo
grep -r "iconType\|iconSize\|iconLabel" packages/ --include="*.tsx" --include="*.ts" --include="*.jsx" --include="*.js"
# 2. Identify usage by package type
find packages/components -name "*.tsx" -o -name "*.ts" | xargs grep -l "iconType="
find packages/core/src -name "*.tsx" -o -name "*.ts" | xargs grep -l "iconSize="
# 3. Check supporting files (docs, examples, tests)
grep -r "iconLabel=" packages/mcp packages/docs
```
**🔧 Update Strategy:**
1. **Component Package First** - Update the source component and its internal hooks
2. **Core Package Components** - Systematically update all core components (20-30 files typical)
3. **Standalone Packages** - Update components that depend on the changed component
4. **Supporting Files** - Update documentation, examples, and MCP tools
5. **Build Verification** - Test each package individually before full build
### TypeScript Build Errors in Related Components
**⚠️ Problem:** Breaking changes can reveal existing TypeScript errors in related components.
**Real Example - IconButton Props:**
```typescript
// DatePickerHeader was using deprecated Button static properties
// Fixed to use string literals
```
**🔧 Resolution Approach:**
1. **Isolate the error** - determine if it's related to your breaking change or pre-existing
2. **Check component API** - verify correct prop values for the component
3. **Use string literals** instead of deprecated static enum properties
4. **Test build** after each fix to catch additional issues
### Documentation and Example Updates
**⚠️ Problem:** Code examples in documentation and MCP tools need updating with new API.
**🔧 Required Updates:**
- **MCP Documentation** - Update usage examples with new props
- **Component Stories** - Storybook examples using the component
- **README files** - Any inline code examples
- **Test files** - Update snapshot tests and component tests
## Quality Gates
**⚠️ These are hard gates, not suggestions. Do NOT proceed past a gate until every item passes.**
**Before committing (all must pass with exit code 0):**
- [ ] `yarn lint` — zero errors
- [ ] `yarn build` — zero errors
- [ ] `yarn test` — zero failures
- [ ] Migration guide entry complete
**Before creating PR:**
- [ ] All of the above still pass after final commit
- [ ] Codemod tested (if applicable)
- [ ] Documentation updated
## Integration Points
- **Package Dependencies:** Update `package.json` files as needed
- **TypeScript:** Ensure type consistency across packages
- **Build System:** Verify Rollup configurations handle changes
- **Storybook:** Update stories to reflect new API
- **Documentation:** Sync with component documentation site
================================================
FILE: .claude/skills/vibe-breaking-change/references/codemod-best-practices.md
================================================
# Codemod Best Practices for Vibe Breaking Changes
## Lessons Learned from Real Implementation
This guide covers critical lessons learned from implementing the Icon component prop renames codemod, including major pitfalls to avoid.
## ❌ Common Mistakes to Avoid
### 1. Using Non-Existent Functions
**WRONG:**
```typescript
import { renameProp } from "../../../src/utils"; // ❌ Doesn't exist
elements.forEach(elementPath => {
if (isPropExists(j, elementPath, "oldProp")) {
renameProp(j, elementPath, "oldProp", "newProp"); // ❌ Function doesn't exist
}
});
```
**CORRECT:**
```typescript
import { migratePropsNames } from "../../../src/utils"; // ✅ Real function
elements.forEach(elementPath => {
migratePropsNames(j, elementPath, filePath, componentName, {
oldProp: "newProp",
anotherOld: "anotherNew"
}); // ✅ Handles all props in one efficient call
});
```
### 2. Wrong Import Path Detection
**WRONG:**
```typescript
// This only finds "monday-ui-react-core" imports, not "@vibe/core"
const imports = getCoreImportsForFile(root);
```
**CORRECT:**
```typescript
import { NEW_CORE_IMPORT_PATH } from "../../../src/consts";
// This finds "@vibe/core" imports correctly
const imports = getImports(root, NEW_CORE_IMPORT_PATH);
```
### 3. Inefficient Multiple Loops
**WRONG:**
```typescript
elements.forEach(elementPath => {
// Separate check for each prop - inefficient!
if (isPropExists(j, elementPath, "iconLabel")) {
renameProp(j, elementPath, "iconLabel", "label");
}
if (isPropExists(j, elementPath, "iconType")) {
renameProp(j, elementPath, "iconType", "type");
}
if (isPropExists(j, elementPath, "iconSize")) {
renameProp(j, elementPath, "iconSize", "size");
}
});
```
**CORRECT:**
```typescript
elements.forEach(elementPath => {
// Single call handles all prop renames efficiently
migratePropsNames(j, elementPath, filePath, componentName, {
iconLabel: "label",
iconType: "type",
iconSize: "size"
});
});
```
## 🔧 Proven Codemod Pattern
Based on successful v2-v3 codemods, use this proven pattern:
```typescript
import {
wrap,
getImports,
getComponentNameOrAliasFromImports,
findComponentElements,
migratePropsNames
} from "../../../src/utils";
import { NEW_CORE_IMPORT_PATH } from "../../../src/consts";
import { TransformationContext } from "../../../types";
function transform({ j, root, filePath }: TransformationContext) {
// 1. Find imports from correct package
const imports = getImports(root, NEW_CORE_IMPORT_PATH);
// 2. Check if component is imported
const componentName = getComponentNameOrAliasFromImports(j, imports, "ComponentName");
if (!componentName) return;
// 3. Find all component elements
const elements = findComponentElements(root, componentName);
if (!elements.length) return;
// 4. Migrate props efficiently
elements.forEach(elementPath => {
migratePropsNames(j, elementPath, filePath, componentName, {
oldProp1: "newProp1",
oldProp2: "newProp2",
oldProp3: "newProp3"
});
});
}
export default wrap(transform);
```
## ⚠️ JSCodeshift Formatting Artifacts
### The Problem
JSCodeshift can add unnecessary parentheses around JSX elements, even in files that **don't use the target component**.
**Example:**
```jsx
// Original code
Content
// After codemod (WRONG!)
(
Content
)
```
### Root Cause
JSCodeshift parses and rebuilds the AST, which can introduce formatting changes even when no transforms are applied.
### Prevention Strategies
#### 1. Target Specific Files
```bash
# WRONG - transforms entire directory
npx jscodeshift -t transform.js packages/core/src/components/
# BETTER - target specific files known to use the component
npx jscodeshift -t transform.js packages/core/src/components/Button/Button.tsx packages/core/src/components/IconButton/IconButton.tsx
```
#### 2. Use Dry Run First
```bash
# Always run dry first to see what changes
npx jscodeshift -t transform.js packages/ --dry
# Review the output carefully
# Only proceed if changes look correct
npx jscodeshift -t transform.js packages/
```
#### 3. Filter by Import Detection
```typescript
function transform({ j, root, filePath }: TransformationContext) {
// Only proceed if file actually imports the component
const imports = getImports(root, NEW_CORE_IMPORT_PATH);
const componentName = getComponentNameOrAliasFromImports(j, imports, "ComponentName");
if (!componentName) return; // ✅ Exit early, no changes
// ... rest of transform
}
```
### Cleanup Process
If formatting artifacts slip through:
```bash
# 1. Identify files with unintended changes
git diff HEAD~1 HEAD --name-only | grep -E "(Checkbox|AvatarGroup|Dropdown)"
# 2. Review each file
git diff HEAD~1 HEAD -- path/to/file.tsx
# 3. Manual cleanup
# Remove extra parentheses: (
→
# Fix indentation as needed
# 4. Commit cleanup
git add .
git commit -m "fix: remove codemod formatting artifacts"
```
## 🧪 Testing Best Practices
### Test Development
```typescript
// Cover edge cases in tests
defineInlineTest(
transform,
{},
prependImport('const element = ;'),
prependImport('const element = ;'),
"should rename all three props"
);
// Test aliased imports
defineInlineTest(
transform,
{},
`import { Icon as VibeIcon } from "@vibe/core";
const element = ;`,
`import { Icon as VibeIcon } from "@vibe/core";
const element = ;`,
"should work with aliased imports"
);
```
### Expected Results
- **7-8 out of 8 tests pass** - indicates working codemod
- **1 formatting test failure** - expected jscodeshift artifact (acceptable)
- **0 tests pass** - indicates broken codemod logic
## 📝 Documentation Integration
### Migration Guide Entry
```markdown
## ComponentName API Changes
### Breaking Changes
**Props Renamed:**
- `oldProp` → `newProp`
- `anotherOld` → `anotherNew`
### Automated Migration
```bash
npx @vibe/codemod component-name-props-update src/
```
### Manual Migration
[Include before/after examples]
```
### Changelog Entry
```markdown
#### ComponentName v2.0.0
- **BREAKING**: Renamed props for better consistency
- **Migration**: Use `npx @vibe/codemod component-name-props-update`
- **Task**: Monday.com #[task-id]
```
## 🚀 Success Criteria
A successful codemod implementation should:
1. **✅ Follow established patterns** from v2-v3 codemods
2. **✅ Use correct utility functions** (migratePropsNames, getImports)
3. **✅ Handle import paths correctly** (NEW_CORE_IMPORT_PATH)
4. **✅ Be efficient** (single loop, batch prop updates)
5. **✅ Have comprehensive tests** (7+ passing test cases)
6. **✅ Minimize formatting artifacts** (targeted file updates)
7. **✅ Include cleanup process** (for any artifacts that slip through)
## 🔄 Iteration Process
1. **RED**: Write failing tests first
2. **GREEN**: Implement minimal working codemod
3. **REFACTOR**: Fix issues, improve efficiency
4. **CLEANUP**: Remove formatting artifacts
5. **DOCUMENT**: Update migration guide and changelog
6. **VALIDATE**: Test on real codebase examples
================================================
FILE: .claude/skills/vibe-breaking-change/references/codemod-examples.md
================================================
# Codemod Examples for Vibe Breaking Changes
## Simple Prop Rename
```typescript
// Transform: oldProp → newProp
import type { Transform } from 'jscodeshift';
const transform: Transform = (file, api) => {
const j = api.jscodeshift;
const root = j(file.source);
// Transform JSX prop usage
root
.find(j.JSXElement)
.filter(path => {
const name = path.value.openingElement?.name;
return name && name.type === 'JSXIdentifier' && name.name === 'ComponentName';
})
.forEach(path => {
const attributes = path.value.openingElement?.attributes || [];
attributes.forEach(attr => {
if (
attr.type === 'JSXAttribute' &&
attr.name?.type === 'JSXIdentifier' &&
attr.name.name === 'oldProp'
) {
attr.name.name = 'newProp';
}
});
});
return root.toSource();
};
export default transform;
```
## Enum to String Union Migration
```typescript
// Transform: ComponentName.SIZE.LARGE → "large"
import type { Transform } from 'jscodeshift';
const transform: Transform = (file, api) => {
const j = api.jscodeshift;
const root = j(file.source);
// Replace enum member access with string literal
root
.find(j.MemberExpression, {
object: {
type: 'MemberExpression',
object: { name: 'ComponentName' },
property: { name: 'SIZE' }
}
})
.forEach(path => {
const property = path.value.property;
if (property.type === 'Identifier') {
const stringValue = property.name.toLowerCase();
j(path).replaceWith(j.literal(stringValue));
}
});
return root.toSource();
};
export default transform;
```
## Complex Import Path Update
```typescript
// Transform: from old package to new package structure
import type { Transform } from 'jscodeshift';
const transform: Transform = (file, api) => {
const j = api.jscodeshift;
const root = j(file.source);
// Update import declarations
root
.find(j.ImportDeclaration)
.filter(path => {
return path.value.source.value?.includes('@vibe/core/components/ComponentName');
})
.forEach(path => {
if (path.value.source.type === 'Literal') {
path.value.source.value = '@vibe/component-name';
}
});
return root.toSource();
};
export default transform;
```
## Testing Codemod Changes
```bash
# Test codemod on specific file
npx jscodeshift -t packages/codemod/src/transforms/component-prop-rename.ts packages/core/src/components/Button/__tests__/Button.test.tsx --dry
# Test on directory
npx jscodeshift -t packages/codemod/src/transforms/component-prop-rename.ts packages/core/src/components/ --dry
# Apply transformation
npx jscodeshift -t packages/codemod/src/transforms/component-prop-rename.ts packages/core/src/components/
# Add to codemod CLI
# Edit packages/codemod/src/index.ts to include new transform
```
## Codemod Integration Checklist
- [ ] Transform handles JSX usage
- [ ] Transform handles TypeScript interfaces
- [ ] Transform handles prop destructuring
- [ ] Transform handles spread props appropriately
- [ ] Test cases cover edge cases
- [ ] Dry run shows expected changes
- [ ] Added to codemod CLI interface
- [ ] Documentation includes usage example
================================================
FILE: .claude/skills/vibe-breaking-change/references/dependency-analysis.md
================================================
# Dependency Analysis for Breaking Changes
## Component Dependency Mapping
### Finding Direct Dependencies
```bash
# Find components importing the target component
grep -r "import.*ComponentName" packages/core/src/components/
grep -r "import.*ComponentName" packages/components/
# Find usage in TypeScript files
grep -r "ComponentName" packages/*/src/**/*.tsx
grep -r "ComponentName" packages/*/src/**/*.ts
# Find usage in test files
grep -r "ComponentName" packages/*/src/**/__tests__/*.tsx
grep -r "ComponentName" packages/*/src/**/__stories__/*.tsx
```
### Finding Indirect Dependencies
```bash
# Check for components that extend or compose target component
grep -r "extends.*ComponentNameProps" packages/
grep -r "ComponentName.*Props" packages/
# Find re-exports
grep -r "export.*ComponentName" packages/*/src/index.ts
grep -r "export.*from.*ComponentName" packages/
```
### Analyzing Package Dependencies
```bash
# Check package.json dependencies
find packages/ -name "package.json" -exec grep -l "@vibe/component-name\|ComponentName" {} \;
# Check workspace dependencies
yarn workspace @vibe/core info
yarn workspaces info
```
## Impact Assessment Matrix
| Component | Import Type | Usage Pattern | Breaking Impact | Update Required |
|-----------|-------------|---------------|-----------------|-----------------|
| ButtonGroup | Direct | Props passed through | High | Yes - API change |
| Dialog | Indirect | Used in composition | Medium | Yes - prop update |
| Form | Test only | Test utilities | Low | Maybe - test update |
## Component Relationship Types
### Direct Usage
- Component imports and uses target component
- Props passed directly to target component
- **Impact:** High - requires immediate update
### Composed Usage
- Component wraps or extends target component
- May add additional props or behavior
- **Impact:** Medium - requires careful testing
### Re-export Usage
- Package re-exports target component
- May not use component directly
- **Impact:** Low - update exports only
### Test/Story Usage
- Only used in test files or Storybook
- No runtime impact on users
- **Impact:** Minimal - update tests/stories
## Dependency Update Strategy
### Phase 1: Core Component Update
1. Update target component with breaking change
2. Update component types and interfaces
3. Ensure component builds and basic tests pass
### Phase 2: Direct Dependencies
1. Update components with direct imports
2. Update prop passing and usage patterns
3. Fix compilation errors
### Phase 3: Indirect Dependencies
1. Update composed components
2. Update complex usage patterns
3. Verify behavioral consistency
### Phase 4: Package Dependencies
1. Update package.json versions if needed
2. Update workspace dependencies
3. Verify cross-package compatibility
## Validation Commands
```bash
# Check TypeScript compilation across all packages
lerna run type-check
# Check for remaining references to old API
grep -r "oldProp" packages/ --include="*.ts" --include="*.tsx"
# Verify no broken imports
yarn workspace @vibe/core build
lerna run build
# Check for usage in Storybook
grep -r "oldProp" packages/**/__stories__/
```
## Common Dependency Patterns
### Button Dependencies
- ButtonGroup, IconButton, SplitButton
- Form components (FieldButton, FormButton)
- Dialog components (DialogButton)
### Icon Dependencies
- All components using icons
- IconButton, Button with icons
- Menu items, navigation components
### Layout Dependencies
- Grid system components
- Container components
- Responsive utilities
### Hook Dependencies
- Components using shared hooks
- Custom hook implementations
- Test utilities using hooks
## Risk Mitigation
### High-Risk Changes
- Core utility changes (hooks, constants)
- Base component changes (Button, Icon)
- Type system changes (VibeComponentProps)
### Medium-Risk Changes
- Layout component changes
- Form component changes
- Complex composite components
### Low-Risk Changes
- Leaf components (no dependencies)
- Style-only changes
- Test utility changes
================================================
FILE: .claude/skills/vibe-breaking-change/references/pr-templates.md
================================================
# PR and Documentation Templates
## PR Template for Breaking Changes
### PR Title Format
Follow [Conventional Commits](https://www.conventionalcommits.org/). Use the appropriate type (`feat`, `fix`, `refactor`, etc.):
```
(): brief description
Examples:
feat(Button): remove deprecated size prop
refactor(Dialog): update API for better accessibility
fix(Form): replace onSubmit with onFormSubmit
```
### PR Description Template
```markdown
## Summary
• Brief description of the breaking change
• Why this change was necessary
• Impact on existing users
## Breaking Changes
**[ComponentName] API Changes:**
- ❌ Removed: `oldProp` prop
- ✅ Added: `newProp` prop with enhanced functionality
- 🔄 Changed: `existingProp` now requires different value format
## Migration Path
### Automated Migration (Codemod Available)
```bash
npx @vibe/codemod component-name-api-update
```
### Manual Migration
**Before:**
```jsx
```
**After:**
```jsx
```
## Task Link
[Monday.com Task](https://monday.monday.com/boards//pulses/)
## Testing
- [ ] All component tests pass
- [ ] Integration tests updated and passing
- [ ] Dependent components tested
- [ ] Storybook stories render correctly
- [ ] Codemod tested on real codebase examples
- [ ] Performance impact assessed
## Documentation
- [ ] Migration guide updated
- [ ] API documentation updated
- [ ] Changelog entry added
- [ ] Codemod documentation added
## Validation
- [ ] Full monorepo build passes
- [ ] All linting checks pass
- [ ] TypeScript compilation successful
- [ ] No broken imports or exports
- [ ] Manual testing completed
## Reviewer Notes
- Focus on [specific areas of concern]
- Pay attention to [migration complexity/edge cases]
- Verify [specific functionality still works]
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
```
## Commit Message Template
Follow [Conventional Commits](https://www.conventionalcommits.org/). Use the appropriate type (`feat`, `fix`, `refactor`, etc.):
```
(): brief description
Detailed explanation of what changed and why.
Include context about the problem being solved.
BREAKING CHANGE: Specific description of what breaks.
Explain the old behavior vs new behavior.
Migration:
- Old usage: ComponentName.oldProp
- New usage: ComponentName.newProp
- Codemod: npx @vibe/codemod component-migration
Affects:
- ComponentName API
- Dependent components: ButtonGroup, Dialog
- Documentation: Migration guide updated
Co-Authored-By: Claude Opus 4.6
```
## Migration Guide Entry Template
```markdown
## [ComponentName] API Changes
### Overview
Brief explanation of what changed and why the breaking change was necessary.
### Breaking Changes
#### Removed `oldProp` prop
- **Impact**: High - affects all usage
- **Reason**: Simplifies API and improves performance
- **Migration**: Replace with `newProp`
#### Changed `existingProp` format
- **Impact**: Medium - affects complex usage
- **Reason**: Better type safety and validation
- **Migration**: Convert values using utility function
### Before and After
#### Basic Usage
```jsx
// Before
// After
```
#### Advanced Usage
```jsx
// Before
handleOldWay(data)}
/>
// After
handleNewWay(data)}
/>
```
### Migration Strategies
#### Automated Migration
Use the provided codemod for straightforward cases:
```bash
npx @vibe/codemod componentname-api-update src/
```
The codemod handles:
- Simple prop renames
- Basic value transformations
- Import statement updates
#### Manual Migration
For complex cases requiring human judgment:
1. **Dynamic prop values**: Review logic and update calculations
2. **Event handlers**: Update to match new event signature
3. **Conditional usage**: Verify new API handles all conditions
4. **Tests**: Update test assertions and mocks
#### Gradual Migration
For large codebases, consider a phased approach:
1. **Phase 1**: Update critical components first
2. **Phase 2**: Update high-traffic components
3. **Phase 3**: Update remaining components
4. **Phase 4**: Remove any compatibility shims
### Common Issues
#### TypeScript Errors
```typescript
// Error: Property 'oldProp' does not exist
// Solution: Use new prop name
```
#### Runtime Errors
```javascript
// Error: onOldEvent is not a function
props.onOldEvent?.(data);
// Solution: Use new event name
props.onNewEvent?.(data);
```
### Validation
After migration, verify:
- [ ] No TypeScript compilation errors
- [ ] Component renders as expected
- [ ] Event handlers work correctly
- [ ] Tests pass
- [ ] No console warnings
```
## Changelog Entry Template
```markdown
### BREAKING CHANGES
#### ComponentName v2.0.0
- **BREAKING**: Removed `oldProp` in favor of `newProp` for better API consistency
- **BREAKING**: Changed `existingProp` format from object to string for improved performance
- **Migration**: Use `npx @vibe/codemod componentname-api-update` for automated migration
- **Affects**: All ComponentName usage, ButtonGroup, Dialog components
##### Migration Example
```jsx
// Before
// After
```
See [Migration Guide](./VIBE4_MIGRATION_GUIDE.md#componentname-api-changes) for detailed instructions.
```
## Code Review Checklist Template
```markdown
## Breaking Change Review Checklist
### API Design
- [ ] Breaking change is necessary and well-justified
- [ ] New API is more intuitive than old API
- [ ] API follows Vibe design system conventions
- [ ] TypeScript types are accurate and helpful
### Implementation
- [ ] Target component updated correctly
- [ ] All dependent components updated
- [ ] No lingering references to old API
- [ ] Error handling updated appropriately
### Testing
- [ ] Component tests updated and comprehensive
- [ ] Integration tests cover dependent components
- [ ] Edge cases tested
- [ ] Performance impact assessed
### Documentation
- [ ] Migration guide entry is clear and complete
- [ ] Code examples work correctly
- [ ] Codemod documented and tested
- [ ] Breaking change clearly flagged
### Developer Experience
- [ ] TypeScript errors are helpful
- [ ] Runtime errors (if any) are clear
- [ ] Migration path is straightforward
- [ ] Documentation is discoverable
### Build System
- [ ] All packages build successfully
- [ ] No circular dependencies introduced
- [ ] Import/export structure clean
- [ ] Version bumps appropriate
```
================================================
FILE: .claude/skills/vibe-breaking-change/references/testing-validation.md
================================================
# Testing and Validation for Breaking Changes
## Testing Strategy
### 1. Unit Tests
Test individual component behavior with new API
```typescript
// Before: Test with old API
it('should handle oldProp correctly', () => {
render();
expect(screen.getByRole('button')).toHaveAttribute('data-old', 'value');
});
// After: Test with new API
it('should handle newProp correctly', () => {
render();
expect(screen.getByRole('button')).toHaveAttribute('data-new', 'value');
});
// Migration test: Ensure old API no longer works
it('should not accept oldProp', () => {
// TypeScript should prevent this at compile time
// @ts-expect-error - oldProp no longer exists
render();
});
```
### 2. Integration Tests
Test dependent components work with changes
```typescript
// Test component that uses the changed component
it('should work with updated ComponentName API', () => {
render(
);
// Verify integration works
expect(screen.getByTestId('parent-wrapper')).toBeInTheDocument();
expect(screen.getByRole('button')).toHaveAttribute('data-new', 'value');
});
```
### 3. Snapshot Testing
Update snapshots for visual regression testing
```bash
# Update component snapshots
yarn workspace @vibe/core test -- ComponentName --updateSnapshot
# Update all affected snapshots
yarn workspace @vibe/core test -- --updateSnapshot
# Check snapshot diffs are intentional
git diff packages/core/src/components/ComponentName/__tests__/__snapshots__/
```
## Validation Checklist
### Pre-Implementation Validation
- [ ] Impact analysis complete
- [ ] Dependent components identified
- [ ] Migration strategy defined
- [ ] Breaking change justified and approved
### Implementation Validation
- [ ] Target component updated correctly
- [ ] TypeScript compilation passes
- [ ] Component tests updated and passing
- [ ] No console errors in development
### Dependency Validation
- [ ] All dependent components updated
- [ ] Integration tests passing
- [ ] No broken imports or exports
- [ ] Cross-package dependencies resolved
### Build Validation
```bash
# Full monorepo build
lerna run build
# Individual package builds
yarn workspace @vibe/core build
yarn workspace @vibe/components build
# TypeScript validation
lerna run type-check
# Lint validation
lerna run lint
```
### Runtime Validation
```bash
# Storybook validation
yarn storybook
# Manually verify affected stories render correctly
# Test app validation (if available)
yarn start
# Test breaking changes in demo application
```
### Documentation Validation
- [ ] Migration guide updated with clear examples
- [ ] Breaking change documented with before/after
- [ ] Codemod usage documented (if applicable)
- [ ] API documentation updated
## Test Update Patterns
### Props Interface Changes
```typescript
// Old interface
interface OldComponentProps {
oldProp?: string;
size?: 'small' | 'medium' | 'large';
}
// New interface
interface NewComponentProps {
newProp?: string;
size?: ComponentSize; // enum to string union
}
// Test updates needed:
// 1. Update prop names in test cases
// 2. Update enum values to string literals
// 3. Add tests for new API behavior
// 4. Remove tests for deprecated functionality
```
### Behavior Changes
```typescript
// Test behavioral changes
describe('ComponentName behavior changes', () => {
it('should trigger callback on new event', () => {
const mockCallback = jest.fn();
render();
// Trigger new behavior
fireEvent.click(screen.getByRole('button'));
expect(mockCallback).toHaveBeenCalledWith(/* new signature */);
});
it('should not trigger old callback', () => {
// Ensure old behavior is removed
const mockOldCallback = jest.fn();
// @ts-expect-error - old callback should not exist
render();
});
});
```
## Common Testing Pitfalls
### 1. Incomplete Test Updates
- **Problem:** Tests still use old API but pass due to lenient typing
- **Solution:** Enable strict TypeScript checking in tests
- **Validation:** `yarn workspace @vibe/core test --typecheck`
### 2. Missing Integration Tests
- **Problem:** Individual components work but integration breaks
- **Solution:** Test component composition scenarios
- **Validation:** Create test cases for typical usage patterns
### 3. Snapshot Pollution
- **Problem:** Snapshots updated but changes not reviewed
- **Solution:** Review snapshot diffs before committing
- **Validation:** `git diff --no-index old-snapshot new-snapshot`
### 4. Performance Regressions
- **Problem:** New API performs worse than old API
- **Solution:** Add performance benchmarks for critical components
- **Validation:** Use React DevTools Profiler
## Automated Validation Scripts
### Pre-commit Validation
```bash
#!/bin/bash
# scripts/validate-breaking-change.sh
echo "🔍 Validating breaking change implementation..."
# 1. Check TypeScript compilation
echo "Checking TypeScript..."
lerna run type-check || exit 1
# 2. Run tests
echo "Running tests..."
lerna run test || exit 1
# 3. Check for old API usage
echo "Checking for old API usage..."
if grep -r "oldProp" packages/ --include="*.ts" --include="*.tsx"; then
echo "❌ Found old API usage"
exit 1
fi
# 4. Build validation
echo "Validating build..."
lerna run build || exit 1
echo "✅ Breaking change validation passed"
```
================================================
FILE: .claude/skills/vibe-breaking-change/references/workflow-checklist.md
================================================
# Complete Breaking Change Workflow Checklist
## Pre-Implementation Phase
### Planning and Analysis
- [ ] Breaking change request approved by team
- [ ] Impact analysis completed
- [ ] Alternative solutions considered and ruled out
- [ ] Migration strategy defined
- [ ] Timeline established
### Dependency Mapping
- [ ] Direct dependencies identified
- [ ] Indirect dependencies mapped
- [ ] Cross-package impacts assessed
- [ ] Test dependencies catalogued
- [ ] Documentation dependencies noted
## Implementation Phase
### Code Changes
- [ ] Target component updated with breaking change
- [ ] TypeScript interfaces updated
- [ ] Component logic implements new API
- [ ] Old API removed or deprecated appropriately
- [ ] Component constants updated
### Dependent Components
- [ ] Direct dependents updated
- [ ] Prop passing updated
- [ ] Event handling updated
- [ ] Composition patterns maintained
- [ ] Integration points verified
### Type System
- [ ] Component props interfaces updated
- [ ] Export types updated
- [ ] Enum to string union conversions (if applicable)
- [ ] Generic constraints updated
- [ ] Utility type helpers updated
## Testing Phase
### Unit Testing
- [ ] Component tests updated for new API
- [ ] Old API tests removed
- [ ] Edge cases covered
- [ ] Error conditions tested
- [ ] Accessibility tests updated
### Integration Testing
- [ ] Dependent component tests updated
- [ ] Cross-package integration tested
- [ ] Composition scenarios tested
- [ ] Event flow tested
- [ ] State management tested
### Build and Compilation
- [ ] TypeScript compilation passes
- [ ] All packages build successfully
- [ ] No circular dependencies
- [ ] Import/export consistency verified
- [ ] Bundle size impact assessed
### Quality Assurance
- [ ] Linting passes
- [ ] Style linting passes
- [ ] Prettier formatting applied
- [ ] No console errors/warnings
- [ ] Performance benchmarks within acceptable range
## Documentation Phase
### Migration Guide
- [ ] Clear before/after examples
- [ ] Migration strategies documented
- [ ] Common issues addressed
- [ ] Validation steps provided
- [ ] Timeline for migration suggested
### API Documentation
- [ ] Component API docs updated
- [ ] Props documentation current
- [ ] Examples reflect new API
- [ ] TypeScript signatures accurate
- [ ] Deprecation notices removed
### Changelog
- [ ] Breaking change clearly flagged
- [ ] Version bump appropriate
- [ ] Impact description clear
- [ ] Migration instructions included
- [ ] Related issues referenced
## Codemod Phase (If Applicable)
### Codemod Development
- [ ] Transform logic implements correctly
- [ ] Edge cases handled
- [ ] TypeScript compatibility maintained
- [ ] JSX patterns covered
- [ ] Test cases comprehensive
### Codemod Testing
- [ ] Dry run on real examples
- [ ] Before/after comparison reviewed
- [ ] Complex scenarios tested
- [ ] Error handling validated
- [ ] Performance acceptable
### Codemod Integration
- [ ] Added to codemod CLI
- [ ] Documentation written
- [ ] Usage examples provided
- [ ] Integration tests added
- [ ] Release notes updated
## Validation Phase
### Comprehensive Testing
- [ ] Full test suite passes
- [ ] Storybook stories render correctly
- [ ] Example applications work
- [ ] Performance tests pass
- [ ] Accessibility tests pass
### Build Verification
- [ ] All packages build
- [ ] Linting checks pass
- [ ] Type checking passes
- [ ] Bundle analysis clean
- [ ] No build warnings
### Manual Testing
- [ ] Component behavior verified in browser
- [ ] Responsive behavior tested
- [ ] Keyboard navigation tested
- [ ] Screen reader compatibility verified
- [ ] Cross-browser testing completed
## Release Phase
### Branch and Commit
- [ ] Feature branch created from vibe4
- [ ] Meaningful commit messages
- [ ] Breaking change flagged in commit
- [ ] Co-authored appropriately
- [ ] Commit history clean
### Pull Request
- [ ] PR title follows convention
- [ ] Description comprehensive and clear
- [ ] Breaking changes highlighted
- [ ] Migration instructions included
- [ ] Task/issue linked
- [ ] Reviewers assigned
### Code Review
- [ ] API design reviewed
- [ ] Implementation reviewed
- [ ] Test coverage reviewed
- [ ] Documentation reviewed
- [ ] Migration path validated
### CI/CD Pipeline
- [ ] All automated tests pass
- [ ] Build artifacts generated
- [ ] Quality gates passed
- [ ] Security scans clean
- [ ] Performance benchmarks acceptable
## Post-Implementation Phase
### Merge and Deploy
- [ ] PR approved and merged
- [ ] Branch cleaned up
- [ ] Version tagged appropriately
- [ ] Release notes published
- [ ] Team notified of changes
### Monitoring
- [ ] Error rates monitored
- [ ] Performance impact tracked
- [ ] User feedback collected
- [ ] Migration adoption tracked
- [ ] Support requests handled
### Follow-up Actions
- [ ] Migration deadline set and communicated
- [ ] Deprecated API removal scheduled
- [ ] Backward compatibility plan finalized
- [ ] Success metrics defined
- [ ] Lessons learned documented
================================================
FILE: .cursor/rules/accessibility-guidelines.mdc
================================================
---
description: Provides general web accessibility guidelines for developing components in the `@vibe/core` library (under `packages/core/`). This rule covers adherence to WCAG, use of semantic HTML, correct ARIA attribute application, ensuring keyboard navigability, proper focus management, and context-appropriate labeling for form inputs within components.
globs:
alwaysApply: false
---
# Web Accessibility Guidelines
This document outlines general web accessibility guidelines to ensure our components are usable by everyone, including people with disabilities. Adherence to these guidelines is crucial for creating inclusive digital experiences. This document is only relevant for the "@vibe/core" library, which is at "packages/core" directory.
## 1. WCAG Compliance
- **Follow WCAG:** Always strive to meet the Web Content Accessibility Guidelines (WCAG) at the AA level. Refer to the latest official WCAG documentation known to you for specific success criteria and techniques.
## 2. Semantic HTML
- **Use HTML Semantically:** Utilize HTML elements according to their intended purpose. For example, use `