metacoding 1.0.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +79 -42
- package/LICENSE +1 -1
- package/lib/commands/init.d.ts.map +1 -1
- package/lib/commands/init.js +1 -1
- package/lib/commands/init.js.map +1 -1
- package/lib/services/template-manager.d.ts +4 -1
- package/lib/services/template-manager.d.ts.map +1 -1
- package/lib/services/template-manager.js +129 -10
- package/lib/services/template-manager.js.map +1 -1
- package/lib/services/vscode.js +1 -1
- package/lib/services/vscode.js.map +1 -1
- package/package.json +12 -4
- package/templates/general/code-review.instructions.md +265 -0
- package/templates/general/{files/copilot-instructions.md.template → copilot-instructions.md} +97 -140
- package/templates/{python/files → general}/docs-update.instructions.md +45 -32
- package/templates/general/release.instructions.md +242 -0
- package/templates/general/test-runner.instructions.md +188 -0
- package/templates/node/nodejs.coding.instructions.md +249 -0
- package/templates/node/nodejs.docs.instructions.md +234 -0
- package/templates/node/nodejs.testing.instructions.md +373 -0
- package/templates/python/python.coding.instructions.md +339 -0
- package/templates/python/python.docs.instructions.md +1147 -0
- package/templates/python/python.testing.instructions.md +1074 -0
- package/templates/react/react.coding.instructions.md +695 -0
- package/templates/react/react.docs.instructions.md +427 -0
- package/templates/react/react.testing.instructions.md +193 -0
- package/templates/react/test-runner.instructions.md +135 -0
- package/templates/typescript/template.json +16 -0
- package/templates/typescript/typescript.coding.instructions.md +368 -0
- package/templates/typescript/typescript.docs.instructions.md +734 -0
- package/templates/typescript/typescript.testing.instructions.md +740 -0
- package/templates/general/files/code-review.instructions.md +0 -111
- package/templates/general/files/docs-update.instructions.md +0 -203
- package/templates/general/files/release.instructions.md +0 -72
- package/templates/general/files/test-runner.instructions.md +0 -107
- package/templates/node/files/code-review.instructions.md +0 -222
- package/templates/node/files/copilot-instructions.md.template +0 -391
- package/templates/node/files/docs-update.instructions.md +0 -203
- package/templates/node/files/release.instructions.md +0 -72
- package/templates/node/files/test-runner.instructions.md +0 -108
- package/templates/python/files/code-review.instructions.md +0 -215
- package/templates/python/files/copilot-instructions.md.template +0 -418
- package/templates/python/files/release.instructions.md +0 -72
- package/templates/python/files/test-runner.instructions.md +0 -108
- package/templates/react/files/code-review.instructions.md +0 -160
- package/templates/react/files/copilot-instructions.md.template +0 -472
- package/templates/react/files/docs-update.instructions.md +0 -203
- package/templates/react/files/release.instructions.md +0 -72
- package/templates/react/files/test-runner.instructions.md +0 -108
|
@@ -1,203 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: 'Guidelines for maintaining project documentation'
|
|
3
|
-
applyTo: '**/*.md'
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Documentation Maintenance Guidelines
|
|
7
|
-
|
|
8
|
-
## Documentation Architecture Principles
|
|
9
|
-
|
|
10
|
-
This project enforces a strict distinction between different types of documentation to ensure clarity, maintainability, and appropriate use of status indicators.
|
|
11
|
-
|
|
12
|
-
### System Documentation (Evergreen, Factual)
|
|
13
|
-
|
|
14
|
-
**Purpose:** Describes the current state of the system, architecture, and implemented features.
|
|
15
|
-
**Files:** README.md, architecture.md, api-design.md, system-documentation.md, code documentation
|
|
16
|
-
**Language:** Present tense, factual, descriptive
|
|
17
|
-
**Status Indicators:** ❌ **NEVER use status emojis or temporal language**
|
|
18
|
-
**Content Focus:** What exists now, how it works, what it does
|
|
19
|
-
**Examples:**
|
|
20
|
-
|
|
21
|
-
- ✅ Correct: "The authentication system uses JWT tokens"
|
|
22
|
-
- ❌ Incorrect: "🚧 Authentication system (in progress)"
|
|
23
|
-
- ✅ Correct: "The API supports the following endpoints:"
|
|
24
|
-
- ❌ Incorrect: "📋 Planned API endpoints:"
|
|
25
|
-
|
|
26
|
-
### Project Management Documentation (Temporal, Status-Oriented)
|
|
27
|
-
|
|
28
|
-
**Purpose:** Tracks work progress, planning, and execution status.
|
|
29
|
-
**Files:** project-task-list.md, sprint-planning.md, backlog.md
|
|
30
|
-
**Language:** Status-oriented, temporal references allowed
|
|
31
|
-
**Status Indicators:** ✅ **Required - use emojis and progress indicators**
|
|
32
|
-
**Content Focus:** What needs to be done, work progress, planning
|
|
33
|
-
**Examples:**
|
|
34
|
-
|
|
35
|
-
- ✅ Correct: "🚧 In Progress - Authentication system implementation"
|
|
36
|
-
- ✅ Correct: "✅ Completed - JWT token validation"
|
|
37
|
-
- ✅ Correct: "📋 Backlog - Add OAuth integration"
|
|
38
|
-
|
|
39
|
-
### User Documentation (Instructional, Current)
|
|
40
|
-
|
|
41
|
-
**Purpose:** Helps users understand how to use the system.
|
|
42
|
-
**Files:** Installation guides, usage examples, tutorials
|
|
43
|
-
**Language:** Imperative, instructional, present tense
|
|
44
|
-
**Status Indicators:** ⚠️ **Use sparingly** - only for actual user-facing feature status
|
|
45
|
-
**Content Focus:** How to use, what users can do, step-by-step guidance
|
|
46
|
-
|
|
47
|
-
### Enforcement Rules
|
|
48
|
-
|
|
49
|
-
1. **No Status Emojis in System Documentation:** Architecture, API docs, and README feature descriptions must be purely factual
|
|
50
|
-
2. **No Temporal Language in System Documentation:** Avoid "currently", "recently", "planned", "upcoming" in system docs
|
|
51
|
-
3. **Status Indicators Required in Project Management:** All task lists and project planning docs must use clear status indicators
|
|
52
|
-
4. **Regular Documentation Audits:** Review and remove status language that has crept into system documentation
|
|
53
|
-
5. **Template Compliance:** All generated documentation must follow these principles
|
|
54
|
-
|
|
55
|
-
## Documentation Quality Standards
|
|
56
|
-
|
|
57
|
-
- **Clarity:** Write clear, concise explanations
|
|
58
|
-
- **Completeness:** Ensure documentation covers all necessary aspects
|
|
59
|
-
- **Accuracy:** Verify all information is current and correct
|
|
60
|
-
- **Consistency:** Maintain consistent tone and formatting
|
|
61
|
-
- **Accessibility:** Use clear language and proper formatting for accessibility
|
|
62
|
-
- **Architecture Compliance:** Follow the system vs project documentation distinction
|
|
63
|
-
|
|
64
|
-
## Status Indication Guidelines (For Project Management Documentation Only)
|
|
65
|
-
|
|
66
|
-
**⚠️ IMPORTANT: These guidelines apply ONLY to project management documentation (task lists, planning docs). System documentation (README, architecture, API docs) must NEVER use status indicators.**
|
|
67
|
-
|
|
68
|
-
- **Use checkboxes for task status:** `- [ ]` for incomplete, `- [x]` for complete
|
|
69
|
-
- **Use clear status indicators in project management docs:**
|
|
70
|
-
- ✅ Complete/Implemented
|
|
71
|
-
- 🚧 In Progress
|
|
72
|
-
- ❌ Not Started
|
|
73
|
-
- ⚠️ Needs Review
|
|
74
|
-
- 🔄 Under Revision
|
|
75
|
-
- **Examples of correct project management documentation:**
|
|
76
|
-
- ✅ Good: "🚧 In Progress - User authentication implementation"
|
|
77
|
-
- ✅ Good: "Development Status" with current checkboxes
|
|
78
|
-
- ✅ Good: "✅ Completed - API endpoint testing"
|
|
79
|
-
- **Examples of incorrect system documentation:**
|
|
80
|
-
- ❌ Bad: "🚧 Authentication Features" (in README.md)
|
|
81
|
-
- ❌ Bad: "Authentication system (planned)" (in architecture.md)
|
|
82
|
-
- ❌ Bad: "📋 API Endpoints" (in api-design.md)
|
|
83
|
-
|
|
84
|
-
## Task Management Documentation Guidelines
|
|
85
|
-
|
|
86
|
-
- **Focus on current state:** Document what needs to be done, not what was recently done
|
|
87
|
-
- **Use project phases:** Organize by logical project phases or milestones, not completion status
|
|
88
|
-
- **Move completed work to changelog:** Record completed work in CHANGELOG.md, not in task lists
|
|
89
|
-
- **Keep task lists current:** Update completed items with current status instead of maintaining "completed" sections
|
|
90
|
-
- **Use descriptive section names:** Use functional names like "Core Features", "Infrastructure", "Testing" instead of "Completed Tasks"
|
|
91
|
-
- **Avoid temporal references:** Don't use "Recent", "Latest", "Upcoming" in section headers - they become outdated quickly
|
|
92
|
-
|
|
93
|
-
## README.md Standards (System Documentation)
|
|
94
|
-
|
|
95
|
-
**⚠️ README.md is system documentation - NO status indicators or temporal language allowed**
|
|
96
|
-
|
|
97
|
-
- **Project Overview:** Keep description current with latest capabilities using factual, present-tense language
|
|
98
|
-
- **Installation Instructions:** Verify and update installation steps with clear, current procedures
|
|
99
|
-
- **Usage Examples:** Ensure all code examples are tested and working, describe what they do
|
|
100
|
-
- **Feature Documentation:** Document all major features with examples using factual descriptions
|
|
101
|
-
- **Version Badges:** Keep version badges synchronized with package.json
|
|
102
|
-
- **Links Verification:** Regularly check that all links work correctly
|
|
103
|
-
- **Screenshots/GIFs:** Update visual documentation when UI changes
|
|
104
|
-
- **Avoid Status Language:** Never use "planned", "upcoming", "in progress", or status emojis
|
|
105
|
-
- **Examples:**
|
|
106
|
-
- ✅ Correct: "The CLI provides three commands for project setup"
|
|
107
|
-
- ❌ Incorrect: "🚧 CLI commands (in development)"
|
|
108
|
-
- ✅ Correct: "Authentication uses JWT tokens with refresh capability"
|
|
109
|
-
- ❌ Incorrect: "Authentication system (planned for v2.0)"
|
|
110
|
-
|
|
111
|
-
## CHANGELOG.md Maintenance
|
|
112
|
-
|
|
113
|
-
- **User-Facing Changes:** Document all changes that affect users
|
|
114
|
-
- **Consistent Format:** Follow established changelog format
|
|
115
|
-
- **Categorization:** Group changes appropriately (Added, Changed, Fixed, etc.)
|
|
116
|
-
- **Breaking Changes:** Clearly mark breaking changes
|
|
117
|
-
- **Migration Guides:** Provide migration guidance for breaking changes
|
|
118
|
-
|
|
119
|
-
## Code Documentation
|
|
120
|
-
|
|
121
|
-
- **JSDoc Comments:** Update JSDoc comments when changing public APIs
|
|
122
|
-
- **Inline Comments:** Add comments for complex logic, not obvious code
|
|
123
|
-
- **Function Documentation:** Document parameters, return values, and side effects
|
|
124
|
-
- **Class Documentation:** Explain class purpose, responsibilities, and usage patterns
|
|
125
|
-
- **Type Documentation:** Document complex TypeScript types and interfaces
|
|
126
|
-
|
|
127
|
-
## API Documentation
|
|
128
|
-
|
|
129
|
-
- **Endpoint Documentation:** Keep API endpoint documentation current
|
|
130
|
-
- **Parameter Changes:** Update parameter descriptions for any modifications
|
|
131
|
-
- **Response Examples:** Provide realistic response examples
|
|
132
|
-
- **Error Handling:** Document error responses and status codes
|
|
133
|
-
- **Authentication:** Keep authentication documentation accurate
|
|
134
|
-
|
|
135
|
-
## Architectural Documentation (System Documentation)
|
|
136
|
-
|
|
137
|
-
**⚠️ Architecture docs are system documentation - NO status indicators or temporal language allowed**
|
|
138
|
-
|
|
139
|
-
- **Decision Records:** Record significant architectural decisions in `/meta` folder using factual language
|
|
140
|
-
- **System Overview:** Maintain high-level system architecture documentation describing current implementation
|
|
141
|
-
- **Data Flow:** Document data flow and process workflows as they currently exist
|
|
142
|
-
- **Integration Points:** Document external system integrations that are implemented
|
|
143
|
-
- **Performance Considerations:** Document performance implications of current design decisions
|
|
144
|
-
- **Examples:**
|
|
145
|
-
- ✅ Correct: "The system uses a microservices architecture with three main services"
|
|
146
|
-
- ❌ Incorrect: "🏗️ Microservices architecture (under development)"
|
|
147
|
-
- ✅ Correct: "Data flows through the validation layer before storage"
|
|
148
|
-
- ❌ Incorrect: "Data validation layer (planned implementation)"
|
|
149
|
-
|
|
150
|
-
## Code Examples and Tutorials
|
|
151
|
-
|
|
152
|
-
- **Working Examples:** Ensure all code examples compile and run
|
|
153
|
-
- **Complete Examples:** Provide complete, runnable examples when possible
|
|
154
|
-
- **Progressive Complexity:** Start with simple examples, build to complex ones
|
|
155
|
-
- **Error Handling:** Show proper error handling in examples
|
|
156
|
-
- **Best Practices:** Demonstrate best practices in example code
|
|
157
|
-
|
|
158
|
-
## Test Documentation Standards
|
|
159
|
-
|
|
160
|
-
Follow the standardized table format for all test case documentation:
|
|
161
|
-
|
|
162
|
-
### Required Table Format
|
|
163
|
-
|
|
164
|
-
```markdown
|
|
165
|
-
| Test Case ID | Description | Type | Status |
|
|
166
|
-
| :------------ | :------------------------------------------ | :--- | :-------- |
|
|
167
|
-
| AREA-TYPE-001 | Brief but descriptive test case description | Unit | Completed |
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
### Test Case ID Conventions
|
|
171
|
-
|
|
172
|
-
- **Format:** `[AREA]-[TYPE]-[NUMBER]`
|
|
173
|
-
- **Area Prefixes (Node.js/Backend):** API, SRV, DB, MW, AUTH, ROUTE, UTIL, CONFIG, DOC, E2E, INT
|
|
174
|
-
- **Type Suffixes:** UNIT, INT, E2E
|
|
175
|
-
- **Sequential Numbering:** 001, 002, 003, etc.
|
|
176
|
-
|
|
177
|
-
### Table Organization Requirements
|
|
178
|
-
|
|
179
|
-
- **Functional Grouping:** Group test cases by system area/component
|
|
180
|
-
- **Consistent Formatting:** Maintain proper column alignment using pipes
|
|
181
|
-
- **Clear Headers:** Use descriptive section headers (e.g., "Template System", "CLI Commands")
|
|
182
|
-
- **Status Tracking:** Use simple status values: "Completed", "In Progress", "Not Started"
|
|
183
|
-
|
|
184
|
-
### Documentation Testing
|
|
185
|
-
|
|
186
|
-
- **Link Checking:** Regularly verify all links work
|
|
187
|
-
- **Code Testing:** Test all code examples in documentation
|
|
188
|
-
- **Installation Testing:** Verify installation instructions work in clean environment
|
|
189
|
-
- **User Testing:** Occasionally have someone unfamiliar try following docs
|
|
190
|
-
|
|
191
|
-
## Maintenance Schedule
|
|
192
|
-
|
|
193
|
-
- **Regular Review:** Schedule regular documentation review cycles
|
|
194
|
-
- **Release Updates:** Update documentation as part of release process
|
|
195
|
-
- **Issue Tracking:** Track documentation issues and improvements
|
|
196
|
-
- **Community Feedback:** Incorporate user feedback on documentation clarity
|
|
197
|
-
|
|
198
|
-
## Localization Considerations
|
|
199
|
-
|
|
200
|
-
- **Clear English:** Use clear, simple English for international audiences
|
|
201
|
-
- **Cultural Sensitivity:** Avoid culture-specific references
|
|
202
|
-
- **Technical Terms:** Define technical terms when first introduced
|
|
203
|
-
- **Consistent Terminology:** Use consistent terminology throughout
|
|
@@ -1,72 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: "Step-by-step release process automation"
|
|
3
|
-
applyTo: "package.json"
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Release Process Checklist
|
|
7
|
-
|
|
8
|
-
## Pre-Release Validation
|
|
9
|
-
1. **Test Suite:** Verify all tests pass: `npm test`
|
|
10
|
-
2. **Build Verification:** Ensure clean build without errors: `npm run build`
|
|
11
|
-
3. **Linting:** Check code quality standards: `npm run lint`
|
|
12
|
-
4. **Dependencies:** Review and update dependencies if needed
|
|
13
|
-
5. **Security Audit:** Run security audit: `npm audit`
|
|
14
|
-
|
|
15
|
-
## Version Management
|
|
16
|
-
1. **Semantic Versioning:** Update version in package.json following SemVer:
|
|
17
|
-
- **MAJOR:** Breaking changes (X.0.0)
|
|
18
|
-
- **MINOR:** New features, backward compatible (0.X.0)
|
|
19
|
-
- **PATCH:** Bug fixes, backward compatible (0.0.X)
|
|
20
|
-
2. **Version Consistency:** Ensure version matches across all relevant files
|
|
21
|
-
3. **Breaking Changes:** Document breaking changes prominently in changelog
|
|
22
|
-
|
|
23
|
-
## Documentation Updates
|
|
24
|
-
1. **README.md Updates:**
|
|
25
|
-
- Update version badges to match package.json version
|
|
26
|
-
- Refresh installation instructions if needed
|
|
27
|
-
- Update feature descriptions for new capabilities
|
|
28
|
-
- Verify all links and examples work correctly
|
|
29
|
-
2. **API Documentation:** Update API docs for any interface changes
|
|
30
|
-
|
|
31
|
-
## Changelog Management
|
|
32
|
-
1. **Add New Entry:** Create new section in CHANGELOG.md with:
|
|
33
|
-
- Release version number (matching package.json)
|
|
34
|
-
- Release date in YYYY-MM-DD format
|
|
35
|
-
- Grouped changes by category:
|
|
36
|
-
- **Added:** New features
|
|
37
|
-
- **Changed:** Changes in existing functionality
|
|
38
|
-
- **Deprecated:** Soon-to-be removed features
|
|
39
|
-
- **Removed:** Now removed features
|
|
40
|
-
- **Fixed:** Bug fixes
|
|
41
|
-
- **Security:** Security vulnerability fixes
|
|
42
|
-
2. **Entry Guidelines:**
|
|
43
|
-
- Keep entries brief but descriptive (1-2 lines per change)
|
|
44
|
-
- Focus on user impact rather than technical implementation
|
|
45
|
-
- Reference issue/PR numbers when applicable: `(#123)`
|
|
46
|
-
- Highlight breaking changes with ⚠️ or **BREAKING:**
|
|
47
|
-
|
|
48
|
-
## Git Operations
|
|
49
|
-
1. **Commit Changes:** Stage all release-related changes
|
|
50
|
-
2. **Commit Message:** Use format: `chore: bump version to vX.Y.Z`
|
|
51
|
-
3. **Create Tag:** Tag the commit with version number: `git tag vX.Y.Z`
|
|
52
|
-
4. **Push Changes:** Push commits and tags: `git push && git push --tags`
|
|
53
|
-
|
|
54
|
-
## GitHub Release
|
|
55
|
-
1. **Create Release:** Create GitHub release with tag matching package.json version
|
|
56
|
-
2. **Release Title:** Use format: `vX.Y.Z - [Brief description]`
|
|
57
|
-
3. **Release Notes:**
|
|
58
|
-
- Copy relevant sections from CHANGELOG.md
|
|
59
|
-
- Include installation instructions
|
|
60
|
-
- Highlight major changes and breaking changes
|
|
61
|
-
- Thank contributors if applicable
|
|
62
|
-
|
|
63
|
-
## Post-Release Verification
|
|
64
|
-
1. **Package Registry:** Verify package published correctly (if applicable)
|
|
65
|
-
2. **Installation Test:** Test installation from registry in clean environment
|
|
66
|
-
3. **Documentation Links:** Ensure all documentation links work correctly
|
|
67
|
-
4. **Monitor Issues:** Watch for any immediate issues reported by users
|
|
68
|
-
|
|
69
|
-
## Rollback Plan
|
|
70
|
-
- **Git Revert:** Know how to revert problematic releases
|
|
71
|
-
- **Package Unpublish:** Understand package registry policies for unpublishing
|
|
72
|
-
- **Communication:** Prepare communication strategy for critical issues
|
|
@@ -1,108 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: 'Instructions for running and maintaining tests'
|
|
3
|
-
applyTo: 'test/**/*.ts'
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Test Execution Guidelines
|
|
7
|
-
|
|
8
|
-
## Pre-Commit Testing
|
|
9
|
-
|
|
10
|
-
- Run all tests before committing changes: `npm test`
|
|
11
|
-
- Ensure tests pass in both development and CI environments
|
|
12
|
-
- Fix failing tests before proceeding with commits
|
|
13
|
-
- Run specific test suites for targeted changes when appropriate
|
|
14
|
-
|
|
15
|
-
## Test Development Standards
|
|
16
|
-
|
|
17
|
-
- **New Features:** Ensure all new features have corresponding unit tests
|
|
18
|
-
- **Test Coverage:** Aim for high coverage of critical functionality paths
|
|
19
|
-
- **Test Documentation:** Follow table format in `test/test-documentation.md` for all test cases
|
|
20
|
-
- **Test Organization:** Group related tests in describe blocks with clear hierarchy
|
|
21
|
-
|
|
22
|
-
## Test Case Documentation Format
|
|
23
|
-
|
|
24
|
-
All test cases must be documented using the standardized table format:
|
|
25
|
-
|
|
26
|
-
```markdown
|
|
27
|
-
| Test Case ID | Description | Type | Status |
|
|
28
|
-
| :------------ | :------------------------------------------ | :--- | :-------- |
|
|
29
|
-
| AREA-TYPE-001 | Brief but descriptive test case description | Unit | Completed |
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
## Test Case Naming Conventions
|
|
33
|
-
|
|
34
|
-
### Test Case ID Format: `[AREA]-[TYPE]-[NUMBER]`
|
|
35
|
-
|
|
36
|
-
**Area Prefixes (Node.js/Backend specific):**
|
|
37
|
-
|
|
38
|
-
- `API` - REST API endpoint tests
|
|
39
|
-
- `SRV` - Service layer tests
|
|
40
|
-
- `DB` - Database/ORM tests
|
|
41
|
-
- `MW` - Middleware tests
|
|
42
|
-
- `AUTH` - Authentication/Authorization tests
|
|
43
|
-
- `ROUTE` - Route handler tests
|
|
44
|
-
- `UTIL` - Utility function tests
|
|
45
|
-
- `CONFIG` - Configuration management tests
|
|
46
|
-
- `DOC` - Documentation Quality tests
|
|
47
|
-
- `E2E` - End-to-End workflow tests
|
|
48
|
-
- `INT` - Integration tests
|
|
49
|
-
|
|
50
|
-
**Type Suffixes:**
|
|
51
|
-
|
|
52
|
-
- `UNIT` - Unit tests
|
|
53
|
-
- `INT` - Integration tests
|
|
54
|
-
- `E2E` - End-to-end tests
|
|
55
|
-
|
|
56
|
-
**Examples:**
|
|
57
|
-
|
|
58
|
-
- `API-UNIT-001` - First unit test for API Endpoints
|
|
59
|
-
- `SRV-UNIT-001` - First unit test for Service Layer
|
|
60
|
-
- `DB-INT-001` - First integration test for Database Layer
|
|
61
|
-
- `E2E-WF-001` - First end-to-end workflow test
|
|
62
|
-
|
|
63
|
-
### Test Method Naming
|
|
64
|
-
|
|
65
|
-
- Format: `methodName_scenario_expectedOutcome`
|
|
66
|
-
- Example: `getUserById_userExists_returnsUserObject`
|
|
67
|
-
- Use camelCase for all test method names
|
|
68
|
-
|
|
69
|
-
## Test Data Management
|
|
70
|
-
|
|
71
|
-
- **Fixtures:** Update test fixtures when data structures change
|
|
72
|
-
- **Realistic Data:** Use realistic data in integration tests to catch real-world issues
|
|
73
|
-
- **Mock Strategy:** Mock external dependencies in unit tests for isolation
|
|
74
|
-
- **Test Database:** Use separate test database/environment for integration tests
|
|
75
|
-
- **Temporary File Cleanup:** Clean up all temporary test files, debug outputs, and mock data after test execution
|
|
76
|
-
- **Fixture Organization:** Move reusable test data to `/test/fixtures/` directory for proper organization
|
|
77
|
-
|
|
78
|
-
## Test File Hygiene
|
|
79
|
-
|
|
80
|
-
- **No Orphaned Files:** Remove temporary test files created during debugging or development
|
|
81
|
-
- **Debug Output Cleanup:** Remove console.log statements and debug files before committing
|
|
82
|
-
- **Test Artifact Management:** Ensure test screenshots, logs, and reports are properly managed or cleaned up
|
|
83
|
-
- **Resource Management:** Properly dispose of file handles, database connections, and other test resources
|
|
84
|
-
|
|
85
|
-
## Test Types and Patterns
|
|
86
|
-
|
|
87
|
-
- **Unit Tests:** Test individual functions, methods, and components in isolation
|
|
88
|
-
- **Integration Tests:** Test feature workflows and component interactions
|
|
89
|
-
- **End-to-End Tests:** Test complete user scenarios and workflows
|
|
90
|
-
- **Regression Tests:** Add tests for previously fixed bugs to prevent recurrence
|
|
91
|
-
|
|
92
|
-
## Performance Testing
|
|
93
|
-
|
|
94
|
-
- **Test Execution Speed:** Keep unit tests fast (under 100ms each when possible)
|
|
95
|
-
- **Parallel Execution:** Structure tests to run safely in parallel
|
|
96
|
-
- **Resource Cleanup:** Ensure proper cleanup of test resources and temporary data
|
|
97
|
-
- **Memory Management:** Monitor and prevent memory leaks in long-running test suites
|
|
98
|
-
|
|
99
|
-
## Test Maintenance
|
|
100
|
-
|
|
101
|
-
- **Regular Review:** Periodically review and refactor outdated tests
|
|
102
|
-
- **Documentation:** Document complex test scenarios and their purposes
|
|
103
|
-
- **Continuous Updates:** Update tests when requirements or APIs change
|
|
104
|
-
- **Test Quality:** Apply the same code quality standards to test code as production code
|
|
105
|
-
- **Update test-documentation.md:** Add new test cases to the appropriate table section
|
|
106
|
-
- **Status Tracking:** Update test status as development progresses
|
|
107
|
-
- **Table Format:** Maintain consistent table formatting and column alignment
|
|
108
|
-
- **ID Assignment:** Assign sequential IDs within each area (AREA-TYPE-001, AREA-TYPE-002, etc.)
|
|
@@ -1,215 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: 'Python backend code review checklist with Django/Flask/FastAPI focus'
|
|
3
|
-
applyTo: '**/*.py'
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Python Backend Code Review Focus Areas
|
|
7
|
-
|
|
8
|
-
## Python Language and Framework Assessment
|
|
9
|
-
|
|
10
|
-
### Code Quality and Pythonic Patterns
|
|
11
|
-
|
|
12
|
-
- **PEP 8 Compliance:** Does the code follow Python style guidelines?
|
|
13
|
-
- **Type Hints:** Are type hints used appropriately for function parameters and returns?
|
|
14
|
-
- **Docstrings:** Are docstrings present for classes, functions, and modules?
|
|
15
|
-
- **Python Idioms:** Does the code use Pythonic patterns (list comprehensions, context managers, etc.)?
|
|
16
|
-
- **Import Organization:** Are imports organized properly (standard library, third-party, local)?
|
|
17
|
-
- **Virtual Environment:** Is the project using virtual environments correctly?
|
|
18
|
-
|
|
19
|
-
### Django-Specific Review Points
|
|
20
|
-
|
|
21
|
-
- **Model Design:** Are models properly structured with appropriate fields and relationships?
|
|
22
|
-
- **Migration Safety:** Are database migrations safe and reversible?
|
|
23
|
-
- **View Logic:** Are views handling only HTTP logic, delegating business logic to services?
|
|
24
|
-
- **Template Security:** Are templates using proper escaping and CSRF protection?
|
|
25
|
-
- **Admin Configuration:** Is Django admin configured securely and efficiently?
|
|
26
|
-
- **Settings Management:** Are settings properly organized by environment?
|
|
27
|
-
|
|
28
|
-
### Flask/FastAPI-Specific Review Points
|
|
29
|
-
|
|
30
|
-
- **Application Factory:** Is the application using the factory pattern correctly?
|
|
31
|
-
- **Blueprint Organization:** Are blueprints used for modular code organization?
|
|
32
|
-
- **Request Handling:** Are request validation and serialization handled properly?
|
|
33
|
-
- **Error Handling:** Are custom error handlers implemented for different HTTP errors?
|
|
34
|
-
- **Configuration Management:** Is configuration handled securely across environments?
|
|
35
|
-
- **Extension Integration:** Are Flask extensions or FastAPI dependencies configured correctly?
|
|
36
|
-
|
|
37
|
-
## Security Review for Python Applications
|
|
38
|
-
|
|
39
|
-
### Authentication and Authorization
|
|
40
|
-
|
|
41
|
-
- **Password Security:** Are passwords hashed using secure algorithms (bcrypt, scrypt)?
|
|
42
|
-
- **Session Management:** Are sessions handled securely with proper timeouts?
|
|
43
|
-
- **JWT Implementation:** Are JWT tokens implemented with proper signing and validation?
|
|
44
|
-
- **Permission Classes:** Are Django permission classes or Flask decorators used correctly?
|
|
45
|
-
- **CSRF Protection:** Is CSRF protection enabled for state-changing operations?
|
|
46
|
-
- **CORS Configuration:** Are CORS settings configured appropriately for the application?
|
|
47
|
-
|
|
48
|
-
### Input Validation and Data Security
|
|
49
|
-
|
|
50
|
-
- **Form Validation:** Are Django forms or serializers validating all inputs?
|
|
51
|
-
- **SQL Injection Prevention:** Is the ORM used properly to prevent SQL injection?
|
|
52
|
-
- **XSS Prevention:** Are user inputs properly escaped in templates?
|
|
53
|
-
- **File Upload Security:** Are file uploads validated and stored securely?
|
|
54
|
-
- **Environment Variables:** Are secrets stored in environment variables, not code?
|
|
55
|
-
- **Database Security:** Are database connections and queries secure?
|
|
56
|
-
|
|
57
|
-
## Performance and Scalability Review
|
|
58
|
-
|
|
59
|
-
### Database Optimization
|
|
60
|
-
|
|
61
|
-
- **Query Efficiency:** Are database queries optimized (select_related, prefetch_related)?
|
|
62
|
-
- **N+1 Query Prevention:** Are N+1 queries identified and resolved?
|
|
63
|
-
- **Database Indexing:** Are appropriate database indexes defined?
|
|
64
|
-
- **Migration Performance:** Do migrations handle large datasets efficiently?
|
|
65
|
-
- **Connection Pooling:** Is database connection pooling configured properly?
|
|
66
|
-
- **Raw SQL Usage:** Is raw SQL avoided where ORM can be used safely?
|
|
67
|
-
|
|
68
|
-
### Caching and Performance
|
|
69
|
-
|
|
70
|
-
- **Caching Strategy:** Are appropriate caching mechanisms implemented (Redis, Memcached)?
|
|
71
|
-
- **View Caching:** Are expensive views cached appropriately?
|
|
72
|
-
- **Static Files:** Are static files served efficiently?
|
|
73
|
-
- **Async Implementation:** Are async views used where I/O operations are performed?
|
|
74
|
-
- **Background Tasks:** Are long-running operations moved to background tasks (Celery)?
|
|
75
|
-
- **Pagination:** Is pagination implemented for large datasets?
|
|
76
|
-
|
|
77
|
-
## Testing and Quality Assurance
|
|
78
|
-
|
|
79
|
-
### Test Coverage and Quality
|
|
80
|
-
|
|
81
|
-
- **Test Types:** Are unit, integration, and functional tests present?
|
|
82
|
-
- **Test Organization:** Are tests organized by functionality and easy to understand?
|
|
83
|
-
- **Factory Usage:** Are test factories (factory_boy) used for test data creation?
|
|
84
|
-
- **Mock Usage:** Are external dependencies properly mocked in tests?
|
|
85
|
-
- **Database Testing:** Are database operations tested with test databases?
|
|
86
|
-
- **API Testing:** Are API endpoints tested with proper assertions?
|
|
87
|
-
|
|
88
|
-
### Testing Frameworks and Tools
|
|
89
|
-
|
|
90
|
-
- **pytest Configuration:** Is pytest configured correctly with appropriate plugins?
|
|
91
|
-
- **Coverage Reporting:** Is test coverage measured and reported?
|
|
92
|
-
- **Test Fixtures:** Are test fixtures used appropriately for setup and teardown?
|
|
93
|
-
- **Parameterized Tests:** Are parameterized tests used for multiple test scenarios?
|
|
94
|
-
- **Integration Testing:** Are third-party integrations tested appropriately?
|
|
95
|
-
- **Performance Testing:** Are performance-critical paths tested for scalability?
|
|
96
|
-
|
|
97
|
-
## Error Handling and Logging
|
|
98
|
-
|
|
99
|
-
### Exception Handling
|
|
100
|
-
|
|
101
|
-
- **Specific Exceptions:** Are specific exception types caught rather than bare except clauses?
|
|
102
|
-
- **Error Response Format:** Are API error responses consistent and informative?
|
|
103
|
-
- **Graceful Degradation:** Does the application handle failures gracefully?
|
|
104
|
-
- **Custom Exceptions:** Are custom exception classes defined for domain-specific errors?
|
|
105
|
-
- **Error Recovery:** Are there appropriate recovery mechanisms for transient errors?
|
|
106
|
-
- **User-Friendly Messages:** Are error messages helpful for both developers and users?
|
|
107
|
-
|
|
108
|
-
### Logging and Monitoring
|
|
109
|
-
|
|
110
|
-
- **Logging Configuration:** Is logging configured appropriately for different environments?
|
|
111
|
-
- **Log Levels:** Are appropriate log levels used (DEBUG, INFO, WARNING, ERROR)?
|
|
112
|
-
- **Structured Logging:** Is structured logging used for easier parsing and analysis?
|
|
113
|
-
- **Sensitive Data:** Are sensitive data excluded from logs?
|
|
114
|
-
- **Performance Logging:** Are performance metrics logged for monitoring?
|
|
115
|
-
- **Error Tracking:** Is error tracking configured (Sentry, Rollbar)?
|
|
116
|
-
|
|
117
|
-
## Deployment and Environment Configuration
|
|
118
|
-
|
|
119
|
-
### Environment Management
|
|
120
|
-
|
|
121
|
-
- **Environment Variables:** Are all configuration values externalized to environment variables?
|
|
122
|
-
- **Settings Organization:** Are settings organized by environment (dev, staging, production)?
|
|
123
|
-
- **Secret Management:** Are secrets managed securely and not committed to version control?
|
|
124
|
-
- **Docker Configuration:** Are Docker configurations optimized for Python applications?
|
|
125
|
-
- **Dependency Management:** Are dependencies pinned to specific versions in requirements.txt?
|
|
126
|
-
- **Environment Isolation:** Are different environments properly isolated?
|
|
127
|
-
|
|
128
|
-
### Production Readiness
|
|
129
|
-
|
|
130
|
-
- **WSGI/ASGI Configuration:** Is the WSGI/ASGI server configured correctly for production?
|
|
131
|
-
- **Static File Serving:** Are static files configured for production serving?
|
|
132
|
-
- **Database Configuration:** Is the database configured for production workloads?
|
|
133
|
-
- **Monitoring Setup:** Are monitoring and alerting configured for production?
|
|
134
|
-
- **Backup Strategy:** Is a backup strategy implemented for data protection?
|
|
135
|
-
- **Health Checks:** Are health check endpoints implemented for load balancers?
|
|
136
|
-
|
|
137
|
-
## Temporary File Management and Cleanup
|
|
138
|
-
|
|
139
|
-
### Python Artifact cleanup
|
|
140
|
-
|
|
141
|
-
- **Bytecode Files:** Are `__pycache__` directories and `.pyc` files cleaned up?
|
|
142
|
-
- **Build Artifacts:** Are `build/`, `dist/`, and `*.egg-info/` directories managed?
|
|
143
|
-
- **Test Artifacts:** Are test coverage files and pytest cache cleaned up?
|
|
144
|
-
- **Log File Rotation:** Are application logs rotated and old logs cleaned up?
|
|
145
|
-
- **Media File cleanup:** Are temporary uploaded files cleaned up appropriately?
|
|
146
|
-
- **Virtual Environment cleanup:** Are old virtual environments removed when not needed?
|
|
147
|
-
|
|
148
|
-
### Cleanup Automation
|
|
149
|
-
|
|
150
|
-
- **Scheduled cleanup:** Are cleanup tasks scheduled appropriately?
|
|
151
|
-
- **Disk Space Monitoring:** Is disk space monitored to prevent storage issues?
|
|
152
|
-
- **Temporary File Management:** Are temporary files created and cleaned up properly?
|
|
153
|
-
- **Session cleanup:** Are expired sessions cleaned up from the database?
|
|
154
|
-
- **Cache Expiration:** Are cache entries expired and cleaned up appropriately?
|
|
155
|
-
- **Log Retention:** Are log retention policies implemented and enforced?
|
|
156
|
-
|
|
157
|
-
## Workflow and Process Review
|
|
158
|
-
|
|
159
|
-
### Development Workflow Compliance
|
|
160
|
-
|
|
161
|
-
- **7-Step Workflow:** Does the implementation follow the mandatory 7-step development workflow?
|
|
162
|
-
- **Test-Driven Development:** Were tests written before implementation (TDD approach)?
|
|
163
|
-
- **Documentation Updates:** Is all documentation current and accurate?
|
|
164
|
-
- **Task Management:** Are tasks properly tracked and status updated?
|
|
165
|
-
- **Code Review Process:** Has the code been properly reviewed before merging?
|
|
166
|
-
- **Version Control:** Are commits atomic and well-documented?
|
|
167
|
-
|
|
168
|
-
### Quality Gates and Standards
|
|
169
|
-
|
|
170
|
-
- **Coding Standards:** Does the code follow established Python and framework-specific standards?
|
|
171
|
-
- **Security Standards:** Are security best practices followed throughout?
|
|
172
|
-
- **Performance Standards:** Does the code meet performance requirements?
|
|
173
|
-
- **Testing Standards:** Is test coverage adequate and tests meaningful?
|
|
174
|
-
- **Documentation Standards:** Is documentation comprehensive and up-to-date?
|
|
175
|
-
- **Deployment Standards:** Is the code ready for production deployment?
|
|
176
|
-
|
|
177
|
-
## Framework-Specific Anti-Patterns
|
|
178
|
-
|
|
179
|
-
### Django Anti-Patterns to Flag
|
|
180
|
-
|
|
181
|
-
- **Fat Models:** Models with too much business logic
|
|
182
|
-
- **Fat Views:** Views handling business logic instead of delegating
|
|
183
|
-
- **Circular Imports:** Apps importing from each other inappropriately
|
|
184
|
-
- **Direct DB Access:** Bypassing Django ORM without good reason
|
|
185
|
-
- **Missing Migrations:** Schema changes without corresponding migrations
|
|
186
|
-
- **Hardcoded URLs:** Using hardcoded URLs instead of reverse() or url names
|
|
187
|
-
|
|
188
|
-
### Flask/FastAPI Anti-Patterns to Flag
|
|
189
|
-
|
|
190
|
-
- **Global State:** Using global variables for application state
|
|
191
|
-
- **No Application Factory:** Not using factory pattern for app creation
|
|
192
|
-
- **Missing Error Handling:** No custom error handlers for different scenarios
|
|
193
|
-
- **Blocking Operations:** Synchronous operations in async contexts
|
|
194
|
-
- **No Request Validation:** Missing input validation and serialization
|
|
195
|
-
- **Poor Configuration:** Configuration mixed with application code
|
|
196
|
-
|
|
197
|
-
## Review Process Guidelines
|
|
198
|
-
|
|
199
|
-
### Constructive Python-Specific Feedback
|
|
200
|
-
|
|
201
|
-
- **Framework Best Practices:** Suggest framework-specific improvements
|
|
202
|
-
- **Python Idioms:** Recommend more Pythonic approaches
|
|
203
|
-
- **Security Improvements:** Flag security vulnerabilities specific to Python/Django/Flask
|
|
204
|
-
- **Performance Optimizations:** Suggest Python-specific performance improvements
|
|
205
|
-
- **Testing Improvements:** Recommend better testing strategies for Python applications
|
|
206
|
-
- **Documentation:** Ensure Python docstring conventions are followed
|
|
207
|
-
|
|
208
|
-
### Review Checklist
|
|
209
|
-
|
|
210
|
-
- **Code Quality:** Pythonic, PEP 8 compliant, well-documented
|
|
211
|
-
- **Security:** Input validation, authentication, authorization, SQL injection prevention
|
|
212
|
-
- **Performance:** Database optimization, caching, async where appropriate
|
|
213
|
-
- **Testing:** Comprehensive test coverage with appropriate testing strategies
|
|
214
|
-
- **Deployment:** Production-ready configuration and environment management
|
|
215
|
-
- **cleanup:** Proper temporary file and resource management
|