utils/.cursorrules at main · Devlander-Software/utils · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
# Cursor Rules for Devlander Utils

## Git Commit Guidelines

### ALWAYS make conventional commits as you work:
- Use `yarn commit` instead of `git commit` for interactive conventional commits
- Make commits after completing each logical feature or fix
- Follow the conventional commit format: `<type>[optional scope]: <description>`

### Commit Types to Use:
- `feat:` - New features or utilities
- `fix:` - Bug fixes
- `docs:` - Documentation updates
- `refactor:` - Code refactoring
- `test:` - Test additions or updates
- `chore:` - Maintenance tasks, build updates
- `ci:` - CI/CD changes
- `perf:` - Performance improvements

### Examples:
```bash
# After adding a new utility function
yarn commit
# Type: feat
# Scope: validation
# Description: add email validation utility

# After fixing a bug
yarn commit
# Type: fix
# Scope: array-operations
# Description: resolve issue with deduplicate function

# After updating documentation
yarn commit
# Type: docs
# Description: update README with new examples
```

### Commit Frequency:
- Commit after each completed feature
- Commit after each bug fix
- Commit after significant refactoring
- Don't let multiple changes accumulate in one commit

## Code Quality Standards

### TypeScript:
- Use strict TypeScript configuration
- Add proper type annotations
- Use interfaces for complex objects
- Export types when they might be used externally

### Testing:
- Write tests for all new utilities
- Ensure existing tests pass
- Use descriptive test names
- Test edge cases and error conditions

### Documentation:
- Add JSDoc comments for all exported functions
- Include parameter types and return types
- Provide usage examples in comments
- Update README.md for new features

### Code Style:
- Follow existing code patterns
- Use consistent naming conventions
- Keep functions focused and single-purpose
- Add proper error handling

## File Organization

### Source Files:
- Place new utilities in appropriate category folders under `src/`
- Follow existing naming conventions
- Export from category index files
- Update main index.ts for new exports

### Tests:
- Create test files in `src/__tests__/`
- Name test files to match source files
- Group related tests in describe blocks
- Use descriptive test names

### Documentation:
- Update README.md for new features
- Add examples to relevant sections
- Keep documentation in sync with code changes

## Release Process

### Before Committing:
- Run `yarn lint` to check code style
- Run `yarn test` to ensure tests pass
- Run `yarn typecheck` to verify TypeScript
- Run `yarn test:examples` to test cross-platform compatibility

### When Ready to Release:
- Use `yarn release:patch:check` for patch releases
- Use `yarn release:minor:check` for minor releases
- Use `yarn release:major:check` for major releases
- The release process will automatically:
  - Check if version exists on npm
  - Generate changelog from conventional commits
  - Publish to npm
  - Create GitHub release

## Project Structure

### Key Directories:
- `src/` - Source code organized by category
- `src/__tests__/` - Test files
- `examples/` - Example applications for testing
- `docs/` - Generated documentation
- `.github/workflows/` - GitHub Actions

### Important Files:
- `package.json` - Package configuration and scripts
- `README.md` - Project documentation
- `CHANGELOG.md` - Auto-generated from conventional commits
- `COMMIT_GUIDELINES.md` - Detailed commit guidelines

## Workflow Summary

1. **Start Feature**: Create new utility or fix bug
2. **Write Code**: Follow TypeScript and style guidelines
3. **Write Tests**: Ensure comprehensive test coverage
4. **Update Docs**: Add JSDoc comments and README updates
5. **Test Locally**: Run lint, tests, and type checking
6. **Commit**: Use `yarn commit` for conventional commit
7. **Repeat**: Continue with next feature/fix
8. **Release**: Use appropriate release command when ready

## Remember:
- Always use conventional commits
- Test thoroughly before committing
- Keep commits focused and logical
- Update documentation as you go
- Follow the established patterns in the codebase