334 lines
6.5 KiB
Markdown
334 lines
6.5 KiB
Markdown
# assertion-analysis
|
|
|
|
Analyze code for missing assertions and defensive programming opportunities.
|
|
|
|
## Context
|
|
|
|
This task systematically identifies locations where assertions, preconditions, postconditions, and invariants should be added to catch bugs early and make code self-documenting. Assertions act as executable documentation and early warning systems for violations of expected behavior.
|
|
|
|
## Task Execution
|
|
|
|
### Phase 1: Code Analysis
|
|
|
|
#### Identify Assertion Candidates
|
|
|
|
**Function Boundaries:**
|
|
|
|
1. **Preconditions** (Entry assertions):
|
|
- Parameter validation (null, range, type)
|
|
- Required state before execution
|
|
- Resource availability
|
|
- Permission/authorization checks
|
|
|
|
2. **Postconditions** (Exit assertions):
|
|
- Return value constraints
|
|
- State changes completed
|
|
- Side effects occurred
|
|
- Resources properly managed
|
|
|
|
3. **Invariants** (Always true):
|
|
- Class/object state consistency
|
|
- Data structure integrity
|
|
- Relationship maintenance
|
|
- Business rule enforcement
|
|
|
|
**Critical Code Sections:**
|
|
|
|
- Before/after state mutations
|
|
- Around external system calls
|
|
- At algorithm checkpoints
|
|
- After complex calculations
|
|
- Before resource usage
|
|
|
|
### Phase 2: Assertion Category Analysis
|
|
|
|
#### Type 1: Safety Assertions
|
|
|
|
Prevent dangerous operations:
|
|
|
|
```
|
|
- Null/undefined checks before dereference
|
|
- Array bounds before access
|
|
- Division by zero prevention
|
|
- Type safety before operations
|
|
- Resource availability before use
|
|
```
|
|
|
|
#### Type 2: Correctness Assertions
|
|
|
|
Verify algorithmic correctness:
|
|
|
|
```
|
|
- Loop invariants maintained
|
|
- Sorted order preserved
|
|
- Tree balance maintained
|
|
- Graph properties held
|
|
- Mathematical properties true
|
|
```
|
|
|
|
#### Type 3: Contract Assertions
|
|
|
|
Enforce API contracts:
|
|
|
|
```
|
|
- Method preconditions met
|
|
- Return values valid
|
|
- State transitions legal
|
|
- Callbacks invoked correctly
|
|
- Events fired appropriately
|
|
```
|
|
|
|
#### Type 4: Security Assertions
|
|
|
|
Validate security constraints:
|
|
|
|
```
|
|
- Input sanitization complete
|
|
- Authorization verified
|
|
- Rate limits enforced
|
|
- Encryption applied
|
|
- Audit trail updated
|
|
```
|
|
|
|
### Phase 3: Automated Detection
|
|
|
|
#### Static Analysis Patterns
|
|
|
|
**Missing Null Checks:**
|
|
|
|
1. Identify all dereferences (obj.prop, obj->member)
|
|
2. Trace back to find validation
|
|
3. Flag unvalidated accesses
|
|
|
|
**Missing Range Checks:**
|
|
|
|
1. Find array/collection accesses
|
|
2. Identify index sources
|
|
3. Verify bounds checking exists
|
|
|
|
**Missing State Validation:**
|
|
|
|
1. Identify state-dependent operations
|
|
2. Check for state verification
|
|
3. Flag unverified state usage
|
|
|
|
**Missing Return Validation:**
|
|
|
|
1. Find function calls that can fail
|
|
2. Check if return values are validated
|
|
3. Flag unchecked returns
|
|
|
|
### Phase 4: Assertion Generation
|
|
|
|
#### Generate Appropriate Assertions
|
|
|
|
**For Different Languages:**
|
|
|
|
**JavaScript/TypeScript:**
|
|
|
|
```javascript
|
|
console.assert(condition, 'message');
|
|
if (!condition) throw new Error('message');
|
|
```
|
|
|
|
**Python:**
|
|
|
|
```python
|
|
assert condition, "message"
|
|
if not condition: raise AssertionError("message")
|
|
```
|
|
|
|
**Java:**
|
|
|
|
```java
|
|
assert condition : "message";
|
|
if (!condition) throw new AssertionError("message");
|
|
```
|
|
|
|
**C/C++:**
|
|
|
|
```c
|
|
assert(condition);
|
|
if (!condition) { /* handle error */ }
|
|
```
|
|
|
|
#### Assertion Templates
|
|
|
|
**Null/Undefined Check:**
|
|
|
|
```
|
|
assert(param != null, "Parameter 'param' cannot be null");
|
|
```
|
|
|
|
**Range Check:**
|
|
|
|
```
|
|
assert(index >= 0 && index < array.length,
|
|
`Index ${index} out of bounds [0, ${array.length})`);
|
|
```
|
|
|
|
**State Check:**
|
|
|
|
```
|
|
assert(this.isInitialized, "Object must be initialized before use");
|
|
```
|
|
|
|
**Type Check:**
|
|
|
|
```
|
|
assert(typeof value === 'number', `Expected number, got ${typeof value}`);
|
|
```
|
|
|
|
**Invariant Check:**
|
|
|
|
```
|
|
assert(this.checkInvariant(), "Class invariant violated");
|
|
```
|
|
|
|
## Output Format
|
|
|
|
````markdown
|
|
# Assertion Analysis Report
|
|
|
|
## Summary
|
|
|
|
**Files Analyzed:** [count]
|
|
**Current Assertions:** [count]
|
|
**Recommended Additions:** [count]
|
|
**Critical Missing:** [count]
|
|
**Coverage Improvement:** [before]% → [after]%
|
|
|
|
## Critical Assertions Needed
|
|
|
|
### Priority 1: Safety Critical
|
|
|
|
Location: [file:line]
|
|
|
|
```[language]
|
|
// Current code
|
|
[code without assertion]
|
|
|
|
// Recommended addition
|
|
[assertion to add]
|
|
[protected code]
|
|
```
|
|
````
|
|
|
|
**Reason:** [Why this assertion is critical]
|
|
**Risk Without:** [What could go wrong]
|
|
|
|
### Priority 2: Correctness Verification
|
|
|
|
[Similar format for each recommendation]
|
|
|
|
### Priority 3: Contract Enforcement
|
|
|
|
[Similar format for each recommendation]
|
|
|
|
## Assertion Coverage by Component
|
|
|
|
| Component | Current | Recommended | Priority |
|
|
| ---------- | ------- | ----------- | -------------- |
|
|
| [Module A] | [count] | [count] | [High/Med/Low] |
|
|
| [Module B] | [count] | [count] | [High/Med/Low] |
|
|
|
|
## Detailed Recommendations
|
|
|
|
### File: [path/to/file]
|
|
|
|
#### Function: [functionName]
|
|
|
|
**Missing Preconditions:**
|
|
|
|
```[language]
|
|
// Add at function entry:
|
|
assert(param1 != null, "param1 required");
|
|
assert(param2 > 0, "param2 must be positive");
|
|
```
|
|
|
|
**Missing Postconditions:**
|
|
|
|
```[language]
|
|
// Add before return:
|
|
assert(result.isValid(), "Result must be valid");
|
|
```
|
|
|
|
**Missing Invariants:**
|
|
|
|
```[language]
|
|
// Add after state changes:
|
|
assert(this.items.length <= this.maxSize, "Size limit exceeded");
|
|
```
|
|
|
|
## Implementation Strategy
|
|
|
|
### Phase 1: Critical Safety (Immediate)
|
|
|
|
1. Add null checks for all pointer dereferences
|
|
2. Add bounds checks for array accesses
|
|
3. Add division by zero prevention
|
|
|
|
### Phase 2: Correctness (This Sprint)
|
|
|
|
1. Add algorithm invariants
|
|
2. Add state validation
|
|
3. Add return value checks
|
|
|
|
### Phase 3: Comprehensive (Next Sprint)
|
|
|
|
1. Add contract assertions
|
|
2. Add security validations
|
|
3. Add performance assertions
|
|
|
|
## Configuration Recommendations
|
|
|
|
### Development Mode
|
|
|
|
```[language]
|
|
// Enable all assertions
|
|
ASSERT_LEVEL = "all"
|
|
ASSERT_THROW = true
|
|
ASSERT_LOG = true
|
|
```
|
|
|
|
### Production Mode
|
|
|
|
```[language]
|
|
// Keep only critical assertions
|
|
ASSERT_LEVEL = "critical"
|
|
ASSERT_THROW = false
|
|
ASSERT_LOG = true
|
|
```
|
|
|
|
## Benefits Analysis
|
|
|
|
### Bug Prevention
|
|
|
|
- Catch [X]% more bugs in development
|
|
- Reduce production incidents by [Y]%
|
|
- Decrease debugging time by [Z]%
|
|
|
|
### Documentation Value
|
|
|
|
- Self-documenting code contracts
|
|
- Clear API expectations
|
|
- Explicit invariants
|
|
|
|
### Testing Support
|
|
|
|
- Faster test failure identification
|
|
- Better test coverage visibility
|
|
- Clearer failure messages
|
|
|
|
```
|
|
|
|
## Completion Criteria
|
|
- [ ] Code analysis completed
|
|
- [ ] Assertion candidates identified
|
|
- [ ] Priority levels assigned
|
|
- [ ] Assertions generated with proper messages
|
|
- [ ] Implementation plan created
|
|
- [ ] Configuration strategy defined
|
|
- [ ] Benefits quantified
|
|
```
|