Medios-Macina/PIPELINE_REFACTOR_SUMMARY.md

Pipeline Refactoring Summary

Overview

Refactored pipeline.py to remove all backwards compatibility and legacy code, consolidating on a single modern context-based approach using PipelineStageContext.

Changes Made

1. Removed Legacy Global Variables

• ❌ _PIPE_EMITS - Replaced with PipelineStageContext.emits
• ❌ _PIPE_ACTIVE - Replaced with checking _CURRENT_CONTEXT is not None
• ❌ _PIPE_IS_LAST - Replaced with PipelineStageContext.is_last_stage
• ❌ _LAST_PIPELINE_CAPTURE - Removed (unused ephemeral handoff)

2. Removed Legacy Functions

• ❌ set_active(bool) - No longer needed, context tracks this
• ❌ set_last_stage(bool) - No longer needed, context tracks this
• ❌ set_last_capture(obj) - Removed
• ❌ get_last_capture() - Removed

3. Updated Core Functions

emit(obj)

Before: Dual-path with fallback to legacy _PIPE_EMITS

if _CURRENT_CONTEXT is not None:
    _CURRENT_CONTEXT.emit(obj)
    return
_PIPE_EMITS.append(obj)  # Legacy fallback

After: Single context-based path

if _CURRENT_CONTEXT is not None:
    _CURRENT_CONTEXT.emit(obj)

emit_list(objects)

Before: Dual-path with legacy fallback After: Single context-based path, removed duplicate definition

print_if_visible()

Before: Checked _PIPE_ACTIVE and _PIPE_IS_LAST

should_print = (not _PIPE_ACTIVE) or _PIPE_IS_LAST

After: Uses context state

should_print = (_CURRENT_CONTEXT is None) or (_CURRENT_CONTEXT.is_last_stage)

get_emitted_items()

Before: Returned _PIPE_EMITS After: Returns _CURRENT_CONTEXT.emits if context exists

clear_emits()

Before: Cleared global _PIPE_EMITS After: Clears _CURRENT_CONTEXT.emits if context exists

reset()

Before: Reset 10+ legacy variables After: Only resets active state variables, sets _CURRENT_CONTEXT = None

4. Updated Call Sites

TUI/pipeline_runner.py

Before:

ctx.set_stage_context(pipeline_ctx)
ctx.set_active(True)
ctx.set_last_stage(index == total - 1)
# ...
ctx.set_stage_context(None)
ctx.set_active(False)

After:

ctx.set_stage_context(pipeline_ctx)
# ...
ctx.set_stage_context(None)

CLI.py (2 locations)

Before:

ctx.set_stage_context(pipeline_ctx)
ctx.set_active(True)

After:

ctx.set_stage_context(pipeline_ctx)

Result

Code Reduction

• Removed ~15 lines of legacy global variable declarations
• Removed ~30 lines of legacy function definitions
• Removed ~10 lines of dual-path logic in core functions
• Removed ~8 lines of redundant function calls at call sites

Benefits

1. Single Source of Truth: All pipeline state is now in PipelineStageContext
2. Cleaner API: No redundant set_active() / set_last_stage() calls needed
3. Type Safety: Context object provides better type hints and IDE support
4. Maintainability: One code path to maintain, no backwards compatibility burden
5. Clarity: Intent is clear - context manages all stage-related state

Preserved Functionality

All user-facing functionality remains unchanged:

• ✅ @N selection syntax
• ✅ Result table history (@.. and @,,)
• ✅ Display overlays
• ✅ Pipeline value storage/retrieval
• ✅ Worker attribution
• ✅ UI refresh callbacks
• ✅ Pending pipeline tail preservation

Type Checking Notes

Some type checker warnings remain about accessing attributes on Optional types (e.g., _LAST_RESULT_TABLE.source_command). These are safe because:

1. Code uses _is_selectable_table() runtime checks before access
2. Functions check is not None before attribute access
3. These warnings are false positives from static analysis

These do not represent actual runtime bugs.