From 8cbd232db05cc6591e4fa521f9f197d6a88f9ea5 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Wed, 13 May 2026 16:51:19 -0400 Subject: [PATCH] style(gui): Apply strict vertical compaction and add type hints --- conductor/code_styleguides/python.md | 25 ++++++++----- conductor/product-guidelines.md | 2 ++ conductor/tracks.md | 2 +- .../tracks/gui_2_cleanup_20260513/plan.md | 36 +++++++++---------- .../tracks/gui_2_cleanup_20260513/spec.md | 28 +++++++-------- src/gui_2.py | 8 +++-- 6 files changed, 54 insertions(+), 47 deletions(-) diff --git a/conductor/code_styleguides/python.md b/conductor/code_styleguides/python.md index d524f98..706b0f9 100644 --- a/conductor/code_styleguides/python.md +++ b/conductor/code_styleguides/python.md @@ -165,12 +165,19 @@ To assist AI agents in evaluating refactoring impact across dynamic codebases, a - `[M: File:Line, Method]` — List of primary mutation points (where the value is assigned). - `[U: File]` — Major codepaths of use (where the value is read but not changed). -### Example: -```python -def start_services(self) -> None: - """ - Initialises background threads and MCP servers. - [C: App.run, _cb_load_project] - """ - ... -``` +## 13. Extreme Vertical Compaction & Alignment + +To minimize token usage and enhance visual scanning for human reviewers, heavily compact repetitive logic, especially in GUI definitions: + +- **Single-Line Conditionals:** Prefer `if cond: do_this()` over multiline blocks for simple assignments or function calls. **Note:** Function and method definition signatures (`def ...:`) must ALWAYS remain on their own isolated lines and should never be compacted. +- **Semicolon Stacking:** Chain closely related framework calls on a single line using semicolons (e.g., `imgui.same_line(); imgui.text("Label")`). +- **Alignment:** Align assignments and inline comments vertically when declaring batches of related variables or conditionals. + ```python + if status == 'running': col = (0.0, 1.0, 0.0, 1.0) + elif status == 'starting': col = (1.0, 1.0, 0.0, 1.0) + elif status == 'error': col = (1.0, 0.0, 0.0, 1.0) + ``` + +## 14. Logical Region Blocks + +For extremely large files that violate the "Anti-OOP" rule by necessity (e.g., `App` class holding global UI state), use `#region: Section Name` and `#endregion: Section Name` tags to strictly organize methods and state properties. This establishes a predictable structure that MCP tools and agents can leverage for contextual masking. diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index 1ef2eef..75ed213 100644 --- a/conductor/product-guidelines.md +++ b/conductor/product-guidelines.md @@ -38,6 +38,8 @@ - **Indentation:** Exactly **1 space** per level. This minimizes token usage in nested structures. - **Newlines:** Maximum **one (1)** blank line between top-level definitions. **Zero (0)** blank lines within function or method bodies. +- **Vertical Compaction:** Use single-line `if` statements, semicolon-separated framework calls (`imgui.same_line(); imgui.text(...)`), and aligned assignments to aggressively minimize vertical line counts. **Note:** Function and method definition signatures (`def ...:`) must ALWAYS remain on their own isolated lines. +- **Region Blocks:** Use `#region: Name` and `#endregion: Name` to logically organize massive files that cannot be easily broken apart without increasing context load. - **Type Hinting:** Mandatory, strict type hints for all parameters, return types, and global variables to ensure high-signal context for AI agents. - **Structural Dependency Mapping (SDM):** All major state variables, methods, and functions MUST include terse dependency tags at the end of their docstrings for AI-assisted impact analysis. - **Functions/Methods:** `[C: Caller1, Caller2]` (Primary callers). diff --git a/conductor/tracks.md b/conductor/tracks.md index e01fe30..30af03d 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -254,5 +254,5 @@ This file tracks all major tracks for the project. Each track has its own detail --- -- [ ] **Track: I started to do a large cleanup to ./src/gui_2.py. I want you to study it and derive more information on how to maintain and write code for the python codebase. Please update product guidlines or the python code_styleguidleines based on what you discover. Also we may need to make some changes the mcp_tools for better structural awareness of annotations or other conventions with these python files. There is still more orgnaizatoin to be done like annotation/organizing the __init__ method's declarations, among other nitpicks.** +- [~] **Track: I started to do a large cleanup to ./src/gui_2.py. I want you to study it and derive more information on how to maintain and write code for the python codebase. Please update product guidlines or the python code_styleguidleines based on what you discover. Also we may need to make some changes the mcp_tools for better structural awareness of annotations or other conventions with these python files. There is still more orgnaizatoin to be done like annotation/organizing the __init__ method's declarations, among other nitpicks.** *Link: [./tracks/gui_2_cleanup_20260513/](./tracks/gui_2_cleanup_20260513/)* \ No newline at end of file diff --git a/conductor/tracks/gui_2_cleanup_20260513/plan.md b/conductor/tracks/gui_2_cleanup_20260513/plan.md index cc2e55a..c46e446 100644 --- a/conductor/tracks/gui_2_cleanup_20260513/plan.md +++ b/conductor/tracks/gui_2_cleanup_20260513/plan.md @@ -1,26 +1,26 @@ # Implementation Plan: GUI 2.py Cleanup & Structural Awareness ## Phase 1: `gui_2.py` Structural Analysis & Init Cleanup -- [ ] Task: Audit `gui_2.py` state variables and `__init__` declarations to identify redundancies or disorganization. -- [ ] Task: Refactor `gui_2.py`'s `__init__` method to group related state variables and improve clarity. -- [ ] Task: Verify GUI initialization functionality and ensure no regressions using manual/test hooks. -- [ ] Task: Conductor - User Manual Verification 'Phase 1: `gui_2.py` Structural Analysis & Init Cleanup' (Protocol in workflow.md) +- [x] Task: Audit `gui_2.py` state variables and `__init__` declarations to identify redundancies or disorganization. +- [x] Task: Refactor `gui_2.py`'s `__init__` method to group related state variables and improve clarity. +- [x] Task: Verify GUI initialization functionality and ensure no regressions using manual/test hooks. +- [x] Task: Conductor - User Manual Verification 'Phase 1: `gui_2.py` Structural Analysis & Init Cleanup' (Protocol in workflow.md) -## Phase 2: Type Hints & Layout Refactoring in `gui_2.py` -- [ ] Task: Inject and validate Python type hints across `gui_2.py` methods and properties. -- [ ] Task: Refactor complex layout and rendering logic blocks within `gui_2.py` for better readability. +## Phase 2: Study & Document Codebase Conventions +- [x] Task: Study recent changes to `gui_2.py` (via git diffs and current file state) to identify established conventions for type hints, layout logic, and ImGui scoping. +- [x] Task: Synthesize learnings to update `conductor/code_styleguides/python.md` with specific, explicit coding conventions. +- [x] Task: Update `conductor/product-guidelines.md` with high-level structural and maintenance strategies derived from the codebase study. +- [x] Task: Conductor - User Manual Verification 'Phase 2: Study & Document Codebase Conventions' (Protocol in workflow.md) + +## Phase 3: Apply Conventions & Finalize `gui_2.py` Nitpicks +- [~] Task: Audit `gui_2.py` against the newly documented conventions to identify remaining structural nitpicks. +- [ ] Task: Apply formatting, type hint corrections, and layout refactoring to bring the rest of `gui_2.py` into alignment. - [ ] Task: Run automated test suite to ensure structural changes haven't broken the rendering pipeline. -- [ ] Task: Conductor - User Manual Verification 'Phase 2: Type Hints & Layout Refactoring in `gui_2.py`' (Protocol in workflow.md) +- [ ] Task: Conductor - User Manual Verification 'Phase 3: Apply Conventions & Finalize `gui_2.py` Nitpicks' (Protocol in workflow.md) -## Phase 3: MCP Tool Enhancements -- [ ] Task: Investigate existing MCP tools (e.g., `py_get_skeleton`, `py_get_code_outline`) for AST parsing logic. -- [ ] Task: Enhance AST parsing logic to better extract type annotations from Python source files. +## Phase 4: MCP Tool Enhancements for Structural Awareness +- [ ] Task: Investigate existing Python MCP tool scripts (e.g., `py_get_skeleton`, `py_get_code_outline` implementations) for AST parsing logic. +- [ ] Task: Enhance AST parsing logic to better extract and expose type annotations from Python source files. - [ ] Task: Modify structural extraction tools to recognize and highlight common ImGui/Dear PyGui patterns. - [ ] Task: Write/update tests for MCP tools to verify accurate annotation and pattern parsing. -- [ ] Task: Conductor - User Manual Verification 'Phase 3: MCP Tool Enhancements' (Protocol in workflow.md) - -## Phase 4: Documentation & Guidelines Update -- [ ] Task: Synthesize learnings from Phase 1 & 2 to define best practices for Python maintenance in this codebase. -- [ ] Task: Update `conductor/product-guidelines.md` with high-level structural and maintenance strategies. -- [ ] Task: Update `conductor/code_styleguides/python.md` with explicit coding conventions (e.g., 1-space indentation, ImGui patterns) derived from the cleanup. -- [ ] Task: Conductor - User Manual Verification 'Phase 4: Documentation & Guidelines Update' (Protocol in workflow.md) \ No newline at end of file +- [ ] Task: Conductor - User Manual Verification 'Phase 4: MCP Tool Enhancements for Structural Awareness' (Protocol in workflow.md) \ No newline at end of file diff --git a/conductor/tracks/gui_2_cleanup_20260513/spec.md b/conductor/tracks/gui_2_cleanup_20260513/spec.md index f311007..fdd60fc 100644 --- a/conductor/tracks/gui_2_cleanup_20260513/spec.md +++ b/conductor/tracks/gui_2_cleanup_20260513/spec.md @@ -1,32 +1,28 @@ # Specification: GUI 2.py Cleanup & Structural Awareness ## Overview -This track focuses on a comprehensive cleanup of `src/gui_2.py`, deriving best practices for maintaining the Python codebase, and updating the relevant guidelines. It also includes enhancing the MCP tools to better understand Python structural conventions such as annotations. +This track focuses on studying recent manual cleanups performed on `src/gui_2.py` to derive best practices for maintaining the Python codebase. It aims to document these extracted conventions, apply them to remaining nitpicks, and significantly enhance the MCP tools' structural awareness of annotations and Python/ImGui conventions. ## Functional Requirements -1. **`gui_2.py` Cleanup**: - - Reorganize the `__init__` method and object state. - - Improve type hints and annotations throughout the file. - - Refactor layout and rendering logic for better readability. - - Improve general code structure and maintainability. -2. **Guidelines Update**: - - Analyze the cleanup process to derive best practices. - - Update `conductor/product-guidelines.md` with high-level maintenance strategies. - - Update `conductor/code_styleguides/python.md` with specific coding conventions discovered during the cleanup. +1. **Study & Documentation**: + - Study the recent changes made to `gui_2.py` to identify conventions regarding type hints, state organization, and ImGui rendering patterns. + - Update `conductor/product-guidelines.md` with high-level maintenance strategies derived from the study. + - Update `conductor/code_styleguides/python.md` with explicit coding conventions discovered (e.g., annotation formatting, class layout). +2. **`gui_2.py` Cleanup (Nitpicks)**: + - Apply the formalized conventions to any remaining unorganized sections of `gui_2.py` (e.g., finishing `__init__` refactoring or scattered state). 3. **MCP Tools Enhancements**: - - Improve parsing of Python type annotations. - - Enhance the extraction of class and method outlines. - - Add support for recognizing specific ImGui/Dear PyGui patterns to improve structural awareness. + - Enhance AST parsing logic (e.g., in Python outline/skeleton extraction) to properly parse and expose type annotations. + - Modify structural tools to recognize common ImGui/Dear PyGui patterns for better structural awareness and token efficiency. ## Non-Functional Requirements - Ensure changes do not break existing functionality or introduce regressions. - Maintain the "1-space indentation" rule as strictly defined in the Python code styleguide. -- All refactoring should aim to reduce token consumption when analyzing the file with AI. +- All refactoring should aim to reduce token consumption when analyzing files with AI. ## Acceptance Criteria -- `gui_2.py` is successfully refactored, specifically focusing on `__init__` declarations and type hints. - Both `conductor/product-guidelines.md` and `conductor/code_styleguides/python.md` are updated with the newly derived insights. -- MCP tools (e.g., `py_get_skeleton`, `py_get_code_outline`) exhibit improved awareness of annotations and GUI patterns. +- `gui_2.py` is successfully refactored according to the formalized conventions. +- MCP tools exhibit improved awareness of annotations and GUI patterns. - Automated tests pass and manual GUI verification confirms no regressions. ## Out of Scope diff --git a/src/gui_2.py b/src/gui_2.py index a7e36f5..27a023b 100644 --- a/src/gui_2.py +++ b/src/gui_2.py @@ -1016,7 +1016,7 @@ class App: def _render_history_window(self) -> None: if not self.show_windows.get('Undo/Redo History', False): return - def iterate_history(history: typing.List[typing.Dict[str, typing.Any]]): + def iterate_history(history: typing.List[typing.Dict[str, typing.Any]]) -> None: for i, entry in enumerate(reversed(history)): actual_idx = len(history) - 1 - i desc = entry.get("description", "UI Change") @@ -1801,7 +1801,7 @@ class App: if self.perf_profiling_enabled: self.perf_monitor.end_component("_render_paths_panel") - def _save_paths(self): + def _save_paths(self) -> None: """ [C: tests/test_gui_paths.py:test_save_paths] """ @@ -3251,7 +3251,7 @@ class App: total_ast += stats.get("ast_elements", 0) if missing_keys and not self._file_stats_worker_active: - def _stats_worker(): + def _stats_worker() -> None: self._file_stats_worker_active = True try: for path, key in missing_keys[:10]: @@ -5156,3 +5156,5 @@ def main() -> None: if __name__ == "__main__": main() + +