commit remaining modified project files
This commit is contained in:
windyboy
@@ -0,0 +1,127 @@
|
||||
# Refactor and Refinement Execution Plan
|
||||
|
||||
## Objective
|
||||
|
||||
Refactor the current `vlm` codebase to reduce structural technical debt while preserving the existing safety-first pipeline behavior. The plan focuses on improving CLI maintainability, strengthening stage boundaries, clarifying state semantics, enabling provider and strategy extensibility, and increasing testability and observability without changing the user-visible safety guarantees.
|
||||
|
||||
## Context and Scope
|
||||
|
||||
This plan is based on the verified review findings in the code analysis report, especially the structural issues around CLI size and repetitive error handling, weak dict/JSON contracts between stages, analyze-phase ordering coupling, duplicated sample-path rules, filesystem-dependent plan generation, configuration semantic overlap, review-state ambiguity, provider hard-coding, and the lack of unified state and strategy abstractions. Key source areas include `src/vlm/cli.py:158-603`, `src/vlm/commands/parse.py:66-155`, `src/vlm/io.py:85-249`, `src/vlm/commands/analyze.py:41-55`, `src/vlm/planner.py:34-40`, `src/vlm/planner.py:43-76`, `src/vlm/planner.py:354-358`, `src/vlm/enrichment.py:203-225`, `src/vlm/state.py:22-205`, `src/vlm/models.py:46-53`, and `src/vlm/models.py:79-85`.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- Preserve the current pipeline order and safety behavior unless a change explicitly improves safety or determinism.
|
||||
- Avoid introducing breaking changes to the CLI surface in the first refactor wave.
|
||||
- Prefer incremental, reviewable changes that can ship independently.
|
||||
- Keep the artifact-driven workflow as the default, while making room for future hybrid or streaming modes.
|
||||
- Treat documentation, tests, and observability updates as first-class deliverables rather than afterthoughts.
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 0: Baseline, guardrails, and dependency mapping
|
||||
|
||||
- [ ] Capture the current behavior baseline for the full workflow, including `scan`, `parse`, `enrich`, `analyze`, `plan`, and `execute`, so every later refactor can be compared against the existing safety model. This is necessary because the codebase relies on many cross-stage assumptions and the review identified several fragile boundaries.
|
||||
- [ ] Map the exact data flow between artifact files and in-memory models for `inventory`, `identities`, `analysis`, and `plan` outputs. This reduces the chance of accidental schema drift while refactoring the stage contracts.
|
||||
- [ ] Identify the minimum set of high-value integration paths to protect first: CLI startup, parse/enrich transition, analyze pairing, plan generation, execute rollback, and quarantine handling. These paths correspond to the highest-risk areas in the review.
|
||||
|
||||
### Phase 1: CLI decomposition and unified error handling
|
||||
|
||||
- [ ] Extract a shared command execution/error-wrapping layer from `src/vlm/cli.py:158-603` so repeated `try/except + echo + logger + exit` logic is centralized. This is needed to stop the CLI file from continuing to grow and to keep error behavior consistent.
|
||||
- [ ] Split non-core commands and support workflows into smaller command modules and keep the CLI module focused on registration and dispatch. This reduces the blast radius of future command additions and improves discoverability.
|
||||
- [ ] Standardize CLI-level error presentation so file, JSON, validation, and OS errors all follow one predictable response shape. This improves user experience and avoids duplicated branching.
|
||||
- [x] Update the CLI workflow description to match the actual supported flow, including `enrich`, so the user-facing guidance reflects the true pipeline. This is a low-cost refinement that removes user confusion.
|
||||
|
||||
### Phase 2: Stronger stage contracts and typed intermediate models
|
||||
|
||||
- [ ] Replace the most fragile dict-based stage boundaries with typed records or `TypedDict` models, starting with parse output and the io conversion layer in `src/vlm/commands/parse.py:66-155` and `src/vlm/io.py:85-249`. This directly addresses schema drift and makes refactors safer.
|
||||
- [x] Define explicit schemas for `identities.json`, `analysis.json`, and `plan.json`, and validate them on load/save. This adds a durable guardrail against silent data-shape changes.
|
||||
- [ ] Align enrichment output mutation with typed contracts so fields like `display_title`, `needs_review`, and review metadata have a single authoritative shape. This prevents inconsistent stage assumptions.
|
||||
- [x] Refactor `identities_to_analysis_input()` so it returns explicit identity-file pairs instead of relying on positional slicing and zipping in `src/vlm/commands/analyze.py:41-55`. This removes the fragile ordering dependency identified in the review.
|
||||
|
||||
### Phase 3: Shared rule extraction and deterministic planning
|
||||
|
||||
- [x] Extract the duplicated sample-path rule from `src/vlm/planner.py:34-40`, `src/vlm/duplicate_resolve.py:11-16`, and `src/vlm/plan_review.py:12-16` into a single shared helper. This reduces duplication and guarantees consistent classification behavior.
|
||||
- [x] Separate logical plan generation from live environment validation so plan output becomes reproducible and execute-time validation becomes an explicit pass. This addresses the filesystem-state coupling in `src/vlm/planner.py:43-76` and `src/vlm/planner.py:354-358`.
|
||||
- [x] Tag any environment-derived metadata in plan artifacts as snapshots rather than intrinsic plan facts. This makes the distinction between logical intent and runtime validation clear.
|
||||
- [ ] Review plan-related metadata and operation structures so they can support deterministic comparisons across runs. This is important for review tooling and regression analysis.
|
||||
|
||||
### Phase 4: Unified state model and review semantics
|
||||
|
||||
- [ ] Introduce a centralized state model that clearly separates processing, review, execution, and quarantine semantics. This directly addresses the spread of state concepts across `src/vlm/state.py:22-205`, `src/vlm/models.py:46-53`, and `src/vlm/models.py:79-85`.
|
||||
- [ ] Make `needs_review` a derived or secondary field rather than the main source of truth, and ensure `review_status` and `review_reason` are the primary review semantics. This removes the current overlap and reduces future workflow ambiguity.
|
||||
- [ ] Align execution and rollback state transitions with the centralized model so success, failure, rollback, and restore paths are all represented consistently.
|
||||
- [ ] Review persisted state files and transition logic for atomicity and consistency after the model changes are introduced.
|
||||
|
||||
### Phase 5: Provider extensibility and strategy abstractions
|
||||
|
||||
- [ ] Replace hard-coded provider assembly in `src/vlm/enrichment.py:203-225` with a registry or plugin-style registration mechanism. This enables new metadata sources without requiring direct edits to the core enrichment orchestration.
|
||||
- [ ] Introduce a strategy layer for naming, conflict handling, and keep/delete decisions so `Config` is no longer the only mechanism for behavior variation. This addresses the current static-config limitation in `src/vlm/config.py:13-148`.
|
||||
- [ ] Refactor media-type and operation-type dispatch toward registered handlers rather than expanding `if/elif` chains in the parser and executor. This makes future media types and operation kinds easier to add.
|
||||
- [ ] Keep the default built-in behavior intact while allowing new strategies to be added incrementally. This limits regression risk while improving extensibility.
|
||||
|
||||
### Phase 6: Error taxonomy and observability
|
||||
|
||||
- [ ] Define a small domain exception hierarchy for enrichment, planning, and execution safety failures, and update command-layer handling to use those typed errors. This makes failure handling more precise than broad exception catching.
|
||||
- [ ] Add structured logging or event fields for high-value workflow events such as cache hits, quarantine operations, rollback actions, and plan conflicts. This improves supportability and analysis quality.
|
||||
- [ ] Add stage-level timing and outcome metrics so long-running operations can be measured consistently. This is especially useful once the pipeline grows beyond small libraries.
|
||||
|
||||
### Phase 7: Testing expansion and validation coverage
|
||||
|
||||
- [ ] Add integration tests for cross-stage transitions, especially parse→enrich, analyze→plan, and plan→execute. These paths need stronger guarantees than isolated unit tests.
|
||||
- [ ] Add end-to-end tests that run a complete safe workflow against a controlled fixture library, including rollback and quarantine behavior. This validates the pipeline as a whole rather than one module at a time.
|
||||
- [ ] Add performance-oriented checks or benchmark fixtures for larger datasets so future changes can be evaluated against scaling regressions.
|
||||
- [ ] Extend property-based coverage where the new typed contracts or state transitions create meaningful invariants.
|
||||
|
||||
### Phase 8: UX refinement and future-mode readiness
|
||||
|
||||
- [ ] Refresh help text and workflow guidance after the CLI and pipeline changes are stable, so the documented flow stays aligned with actual behavior.
|
||||
- [ ] Evaluate whether a hybrid execution mode or a guided interactive mode should be introduced once the state model and contracts are stable. This is a future-facing refinement to improve usability without sacrificing safety.
|
||||
- [ ] Keep the artifact-first mode as the default until the alternative execution modes have matching safety guarantees and test coverage.
|
||||
|
||||
## Verification Criteria
|
||||
|
||||
- [ ] CLI startup and command registration still work, and repeated command-level error handling is no longer duplicated across the main CLI file.
|
||||
- [x] Stage artifact schemas are explicitly validated, and malformed inputs fail early with clear errors.
|
||||
- [x] Analyze no longer depends on positional assumptions between identities and video files.
|
||||
- [x] Sample-path classification produces one consistent result across planner, duplicate resolution, and review flows.
|
||||
- [x] Plan generation is reproducible for the same logical inputs, with live filesystem checks clearly separated as validation snapshots.
|
||||
- [ ] Review state semantics are no longer ambiguous, and `review_status` is the primary review source of truth.
|
||||
- [ ] Provider registration can be extended without editing the core orchestration logic.
|
||||
- [ ] Integration and E2E coverage exists for the main safe workflow and rollback/quarantine scenarios.
|
||||
- [ ] Structured logs or metrics expose workflow health and failure patterns.
|
||||
- [ ] The default user-visible pipeline still preserves the safety-first execution model.
|
||||
|
||||
## Potential Risks and Mitigations
|
||||
|
||||
1. **Risk: Refactor scope expands faster than the code can be stabilized**
|
||||
Mitigation: Keep the work split into independently shippable phases and require the baseline behavior to remain intact after each phase.
|
||||
|
||||
2. **Risk: Typed contracts introduce temporary friction in serialization/deserialization code**
|
||||
Mitigation: Introduce schema validation and typed records incrementally, starting with the highest-risk artifacts.
|
||||
|
||||
3. **Risk: State model changes cascade through planner, executor, and review flows**
|
||||
Mitigation: Centralize the new model first, then migrate consumers one by one while keeping compatibility adapters where needed.
|
||||
|
||||
4. **Risk: Provider and strategy abstraction can become too generic too early**
|
||||
Mitigation: Start with the current built-in cases as default registrations before allowing external extensibility.
|
||||
|
||||
5. **Risk: New tests may be slow or hard to maintain if they overuse large fixtures**
|
||||
Mitigation: Prefer focused fixtures for unit/integration coverage and reserve large datasets for targeted performance checks.
|
||||
|
||||
## Alternative Approaches
|
||||
|
||||
1. **Incremental refactor first**: Keep the current artifact-first architecture and only extract the most painful seams now. Trade-off: lowest regression risk, but slower progress on deeper extensibility issues.
|
||||
2. **Boundary-first refactor**: Prioritize typed contracts, state model, and deterministic planning before provider and strategy work. Trade-off: better long-term clarity, but requires more cross-module updates early.
|
||||
3. **Platform-style refactor**: Introduce registries, strategies, and structured observability as a broader platform layer. Trade-off: highest flexibility, but the largest immediate complexity increase.
|
||||
|
||||
## Status Tracking
|
||||
|
||||
- **Not Started**: Phase 0 baseline capture and dependency mapping
|
||||
- **Partially Completed**: Phase 1 CLI decomposition and unified error handling
|
||||
- **Partially Completed**: Phase 2 stronger stage contracts and typed intermediate models
|
||||
- **Partially Completed**: Phase 3 shared rule extraction and deterministic planning
|
||||
- **Not Started**: Phase 4 unified state model and review semantics
|
||||
- **Not Started**: Phase 5 provider extensibility and strategy abstractions
|
||||
- **Not Started**: Phase 6 error taxonomy and observability
|
||||
- **Not Started**: Phase 7 testing expansion and validation coverage
|
||||
- **Not Started**: Phase 8 UX refinement and future-mode readiness
|
||||
Reference in New Issue
Block a user