feat(#71): implement graph data API
Implemented three new API endpoints for knowledge graph visualization: 1. GET /api/knowledge/graph - Full knowledge graph - Returns all entries and links with optional filtering - Supports filtering by tags, status, and node count limit - Includes orphan detection (entries with no links) 2. GET /api/knowledge/graph/stats - Graph statistics - Total entries and links counts - Orphan entries detection - Average links per entry - Top 10 most connected entries - Tag distribution across entries 3. GET /api/knowledge/graph/:slug - Entry-centered subgraph - Returns graph centered on specific entry - Supports depth parameter (1-5) for traversal distance - Includes all connected nodes up to specified depth New Files: - apps/api/src/knowledge/graph.controller.ts - apps/api/src/knowledge/graph.controller.spec.ts Modified Files: - apps/api/src/knowledge/dto/graph-query.dto.ts (added GraphFilterDto) - apps/api/src/knowledge/entities/graph.entity.ts (extended with new types) - apps/api/src/knowledge/services/graph.service.ts (added new methods) - apps/api/src/knowledge/services/graph.service.spec.ts (added tests) - apps/api/src/knowledge/knowledge.module.ts (registered controller) - apps/api/src/knowledge/dto/index.ts (exported new DTOs) - docs/scratchpads/71-graph-data-api.md (implementation notes) Test Coverage: 21 tests (all passing) - 14 service tests including orphan detection, filtering, statistics - 7 controller tests for all three endpoints Follows TDD principles with tests written before implementation. All code quality gates passed (lint, typecheck, tests). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
186
docs/scratchpads/orch-112-conflicts.md
Normal file
186
docs/scratchpads/orch-112-conflicts.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# ORCH-112: Conflict Detection
|
||||
|
||||
## Objective
|
||||
Implement conflict detection service that detects merge conflicts before pushing to remote. This is the final git integration feature for Phase 3.
|
||||
|
||||
## Approach
|
||||
|
||||
### Architecture
|
||||
1. **ConflictDetectionService**: NestJS service that:
|
||||
- Fetches latest changes from remote before push
|
||||
- Detects merge conflicts using simple-git
|
||||
- Returns detailed conflict information
|
||||
- Supports both merge and rebase strategies
|
||||
|
||||
### Conflict Detection Strategy
|
||||
1. Fetch remote branch
|
||||
2. Try merge/rebase in dry-run mode (or check status after fetch)
|
||||
3. Detect conflicts by:
|
||||
- Checking git status for conflicted files
|
||||
- Parsing merge output for conflict markers
|
||||
- Checking for unmerged paths
|
||||
4. Return structured conflict information with file paths and details
|
||||
|
||||
### Integration Points
|
||||
- Uses GitOperationsService for basic git operations
|
||||
- Will be called by orchestrator before push operations
|
||||
- Provides retry capability with different strategies
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Review requirements from ORCH-112
|
||||
- [x] Examine existing git services (GitOperationsService, WorktreeManagerService)
|
||||
- [x] Identify types structure and patterns
|
||||
- [x] Create scratchpad
|
||||
- [x] Write tests for ConflictDetectionService (TDD - RED)
|
||||
- [x] Implement ConflictDetectionService (TDD - GREEN)
|
||||
- [x] Refactor implementation (TDD - REFACTOR)
|
||||
- [x] Add types to types/conflict-detection.types.ts
|
||||
- [x] Export from types/index.ts
|
||||
- [x] Update git.module.ts to include ConflictDetectionService
|
||||
- [x] Update git/index.ts exports
|
||||
- [x] Verify tests pass with ≥85% coverage (95.77% achieved)
|
||||
- [x] Create Gitea issue
|
||||
- [x] Close Gitea issue with completion notes
|
||||
|
||||
## Completion Summary
|
||||
|
||||
Implementation completed successfully with all acceptance criteria met:
|
||||
- ConflictDetectionService implemented with full TDD approach
|
||||
- Supports both merge and rebase strategies
|
||||
- Comprehensive error handling with ConflictDetectionError
|
||||
- 18 unit tests covering all scenarios
|
||||
- Coverage: 95.77% (exceeds 85% requirement)
|
||||
- Proper cleanup after conflict detection
|
||||
- Integrated into GitModule and exported
|
||||
|
||||
Files created/modified:
|
||||
- apps/orchestrator/src/git/conflict-detection.service.ts
|
||||
- apps/orchestrator/src/git/conflict-detection.service.spec.ts
|
||||
- apps/orchestrator/src/git/types/conflict-detection.types.ts
|
||||
- apps/orchestrator/src/git/types/index.ts (updated)
|
||||
- apps/orchestrator/src/git/git.module.ts (updated)
|
||||
- apps/orchestrator/src/git/index.ts (updated)
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests (TDD)
|
||||
1. **No conflicts scenario**:
|
||||
- Fetch succeeds
|
||||
- No conflicts detected
|
||||
- Returns clean status
|
||||
|
||||
2. **Merge conflicts detected**:
|
||||
- Fetch succeeds
|
||||
- Merge shows conflicts
|
||||
- Returns conflict details with file paths
|
||||
|
||||
3. **Rebase conflicts detected**:
|
||||
- Fetch succeeds
|
||||
- Rebase shows conflicts
|
||||
- Returns conflict details
|
||||
|
||||
4. **Fetch failure**:
|
||||
- Remote unavailable
|
||||
- Throws appropriate error
|
||||
|
||||
5. **Check before push**:
|
||||
- Integration with conflict detection
|
||||
- Prevents push if conflicts exist
|
||||
|
||||
### Mock Strategy
|
||||
- Mock simple-git for all git operations
|
||||
- Mock GitOperationsService where needed
|
||||
- Test both merge and rebase strategies
|
||||
|
||||
## Technical Notes
|
||||
|
||||
### Key Methods
|
||||
```typescript
|
||||
// Check for conflicts before push
|
||||
async checkForConflicts(
|
||||
localPath: string,
|
||||
remote: string = 'origin',
|
||||
branch: string = 'develop',
|
||||
strategy: 'merge' | 'rebase' = 'merge'
|
||||
): Promise<ConflictCheckResult>
|
||||
|
||||
// Fetch latest from remote
|
||||
async fetchRemote(
|
||||
localPath: string,
|
||||
remote: string = 'origin'
|
||||
): Promise<void>
|
||||
|
||||
// Detect conflicts in current state
|
||||
async detectConflicts(
|
||||
localPath: string
|
||||
): Promise<ConflictInfo[]>
|
||||
```
|
||||
|
||||
### Types
|
||||
```typescript
|
||||
interface ConflictCheckResult {
|
||||
hasConflicts: boolean;
|
||||
conflicts: ConflictInfo[];
|
||||
strategy: 'merge' | 'rebase';
|
||||
canRetry: boolean;
|
||||
}
|
||||
|
||||
interface ConflictInfo {
|
||||
file: string;
|
||||
type: 'content' | 'delete' | 'add';
|
||||
ours?: string;
|
||||
theirs?: string;
|
||||
}
|
||||
|
||||
class ConflictDetectionError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
operation: string,
|
||||
cause?: Error
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Git Commands
|
||||
- `git fetch origin branch` - Fetch latest
|
||||
- `git merge --no-commit --no-ff origin/branch` - Test merge
|
||||
- `git merge --abort` - Abort test merge
|
||||
- `git status --porcelain` - Check for conflicts
|
||||
- `git diff --name-only --diff-filter=U` - List conflicted files
|
||||
|
||||
### Conflict Detection Logic
|
||||
1. Save current state
|
||||
2. Fetch remote
|
||||
3. Attempt merge/rebase (no commit)
|
||||
4. Check status for "UU" markers (unmerged)
|
||||
5. Parse conflict information
|
||||
6. Abort merge/rebase
|
||||
7. Return conflict details
|
||||
|
||||
## Notes
|
||||
|
||||
### Design Decisions
|
||||
- Use `--no-commit` flag to test merge without committing
|
||||
- Support both merge and rebase strategies
|
||||
- Provide detailed conflict information for agent retry
|
||||
- Clean up after detection (abort merge/rebase)
|
||||
|
||||
### Error Handling
|
||||
- GitOperationError for git command failures
|
||||
- ConflictDetectionError for detection-specific issues
|
||||
- Return structured errors for agent consumption
|
||||
|
||||
### Dependencies
|
||||
- simple-git library (already used in GitOperationsService)
|
||||
- NestJS @Injectable decorator
|
||||
- Logger for debugging
|
||||
|
||||
## Next Steps
|
||||
1. Start with TDD: Write failing tests first
|
||||
2. Implement minimal code to pass tests
|
||||
3. Refactor for clarity
|
||||
4. Ensure coverage ≥85%
|
||||
5. Create and close Gitea issue
|
||||
Reference in New Issue
Block a user