{
    "sourceFile": "detailed_documentation_plan.md",
    "activeCommit": 0,
    "commits": [
        {
            "activePatchIndex": 0,
            "patches": [
                {
                    "date": 1745328667729,
                    "content": "Index: \n===================================================================\n--- \n+++ \n"
                }
            ],
            "date": 1745328667729,
            "name": "Commit-0",
            "content": "# Final Plan for Updating documentation.txt with Debugging Details\r\n\r\nThis document outlines the final plan for enhancing `documentation.txt` with detailed internal information crucial for debugging the Asset Processor Tool. This plan incorporates analysis of `asset_processor.py`, `configuration.py`, `main.py`, and `gui/processing_handler.py`.\r\n\r\n## Task Objective\r\n\r\nAnalyze relevant source code (`asset_processor.py`, `configuration.py`, `main.py`, `gui/processing_handler.py`) to gather specific details about internal logic, state management, error handling, data structures, concurrency, resource management, and limitations. Integrate this information into the existing `documentation.txt` to aid developers in debugging.\r\n\r\n## Analysis Steps Completed\r\n\r\n1.  Read and analyzed `readme.md`.\r\n2.  Listed code definitions in the root directory (`.`).\r\n3.  Listed code definitions in the `gui/` directory.\r\n4.  Read and analyzed `asset_processor.py`.\r\n5.  Read and analyzed `configuration.py`.\r\n6.  Read and analyzed `main.py`.\r\n7.  Read and analyzed `gui/processing_handler.py`.\r\n\r\n## Final Integration Plan (Merged Structure)\r\n\r\n1.  **Add New Top-Level Section:**\r\n    *   Append the following section header to the end of `documentation.txt`:\r\n        ```\r\n        ================================\r\n        Internal Details for Debugging\r\n        ================================\r\n        ```\r\n\r\n2.  **Create Subsections:**\r\n    *   Under the new \"Internal Details\" section, create the following subsections (renumbering from 7 onwards):\r\n        *   `7. Internal Logic & Algorithms`\r\n        *   `8. State Management`\r\n        *   `9. Error Handling & Propagation`\r\n        *   `10. Key Data Structures`\r\n        *   `11. Concurrency Models (CLI & GUI)`\r\n        *   `12. Resource Management`\r\n        *   `13. Known Limitations & Edge Cases`\r\n\r\n3.  **Populate Subsections with Specific Details:**\r\n\r\n    *   **7. Internal Logic & Algorithms:**\r\n        *   **Configuration Preparation (`Configuration` class):** Detail the `__init__` process: loading `config.py` and preset JSON, validating structure (`_validate_configs`), compiling regex (`_compile_regex_patterns` using `_fnmatch_to_regex`). Mention compiled patterns storage.\r\n        *   **CLI Argument Parsing (`main.py:setup_arg_parser`):** Briefly describe `argparse` usage and key flags influencing execution.\r\n        *   **Output Directory Resolution (`main.py:main`):** Explain how the final output path is determined and resolved.\r\n        *   **Asset Processing (`AssetProcessor` class):**\r\n            *   *Classification (`_inventory_and_classify_files`):* Describe multi-pass approach using compiled regex from `Configuration`. Detail variant sorting criteria.\r\n            *   *Map Processing (`_process_maps`):* Detail image loading, Gloss->Rough inversion, resizing, format determination (using `Configuration` rules), bit depth conversion, stats calculation, aspect ratio logic, save fallback.\r\n            *   *Merging (`_merge_maps`):* Detail common resolution finding, input loading, channel merging (using `Configuration` rules), output determination, save fallback.\r\n            *   *Metadata (`_determine_base_metadata`, etc.):* Summarize base name extraction, category/archetype determination (using `Configuration` rules), `metadata.json` population.\r\n        *   **Blender Integration (`main.py:run_blender_script`, `gui/processing_handler.py:_run_blender_script_subprocess`):** Explain subprocess execution, command construction (`-b`, `--python`, `--`), argument passing (`asset_root_dir`).\r\n\r\n    *   **8. State Management:**\r\n        *   `Configuration` object: Holds loaded config state and compiled regex. Instantiated per worker.\r\n        *   `AssetProcessor`: Primarily stateless between `process()` calls. Internal state within `process()` managed by local variables (e.g., `current_asset_metadata`). `self.classified_files` populated once and filtered per asset.\r\n        *   `main.py`: Tracks overall CLI run counts (processed, skipped, failed).\r\n        *   `gui/processing_handler.py`: Manages GUI processing run state via flags (`_is_running`, `_cancel_requested`) and stores `Future` objects (`_futures`).\r\n\r\n    *   **9. Error Handling & Propagation:**\r\n        *   Custom Exceptions: `AssetProcessingError`, `ConfigurationError`.\r\n        *   `Configuration`: Raises `ConfigurationError` on load/validation failure. Logs regex compilation warnings.\r\n        *   `AssetProcessor`: Catches exceptions within per-asset loop, logs error, marks asset \"failed\", continues loop. Handles specific save fallbacks (EXR->PNG). Raises `AssetProcessingError` for critical setup failures.\r\n        *   Worker Wrapper (`main.py:process_single_asset_wrapper`): Catches exceptions from `Configuration`/`AssetProcessor`, logs, returns \"failed\" status tuple.\r\n        *   Process Pool (`main.py`, `gui/processing_handler.py`): `try...except` around executor block catches pool-level errors.\r\n        *   GUI Communication (`ProcessingHandler`): Catches errors during future result retrieval, emits failure status via signals.\r\n        *   Blender Scripts: Checks subprocess return code, logs stderr. Catches `FileNotFoundError`.\r\n\r\n    *   **10. Key Data Structures:**\r\n        *   `Configuration` attributes: `compiled_map_keyword_regex`, `compiled_extra_regex`, etc. (compiled `re.Pattern` objects).\r\n        *   `AssetProcessor` structures: `self.classified_files` (dict[str, list[dict]]), `processed_maps_details_asset` (dict[str, dict[str, dict]]), `file_to_base_name_map` (dict[Path, Optional[str]]).\r\n        *   Return values: Status dictionary from `AssetProcessor.process()`, status tuple from `process_single_asset_wrapper`.\r\n        *   `ProcessingHandler._futures`: dict[Future, str].\r\n\r\n    *   **11. Concurrency Models (CLI & GUI):**\r\n        *   **Common Core:** Both use `concurrent.futures.ProcessPoolExecutor` running `main.process_single_asset_wrapper`. `Configuration` and `AssetProcessor` instantiated within each worker process for isolation.\r\n        *   **CLI Orchestration (`main.py:run_processing`):** Direct executor usage, `as_completed` gathers results synchronously.\r\n        *   **GUI Orchestration (`gui/processing_handler.py`):** `ProcessingHandler` (QObject) runs executor logic in a `QThread`. Results processed in handler thread, communicated asynchronously to UI thread via Qt signals (`progress_updated`, `file_status_updated`, `processing_finished`).\r\n        *   **Cancellation (`gui/processing_handler.py:request_cancel`):** Sets flag, attempts `executor.shutdown(wait=False)`, tries cancelling pending futures. Limitation: Does not stop already running workers.\r\n\r\n    *   **12. Resource Management:**\r\n        *   `Configuration`: Uses `with open` for preset files.\r\n        *   `AssetProcessor`: Manages temporary workspace (`tempfile.mkdtemp`, `shutil.rmtree` in `finally`). Uses `with open` for metadata JSON.\r\n        *   `ProcessPoolExecutor`: Lifecycle managed via `with` statement in `main.py` and `gui/processing_handler.py`.\r\n\r\n    *   **13. Known Limitations & Edge Cases:**\r\n        *   Configuration: Basic structural validation only; regex compilation errors are warnings; `_fnmatch_to_regex` helper is basic.\r\n        *   AssetProcessor: Relies heavily on filename patterns; high memory potential for large images; limited intra-asset error recovery; simplified prediction logic.\r\n        *   CLI: Basic preset file existence check only before starting workers; Blender executable finding logic order (config > PATH).\r\n        *   GUI Concurrency: Cancellation doesn't stop currently executing worker processes.\r\n\r\n4.  **Switch Mode:** Request switching to Code mode to apply these changes by appending to `documentation.txt`."
        }
    ]
}