Implement unified serialization layer and enhance type safety

- Created a unified serialization layer with PluginSerializer to centralize JSON operations and improve code organization.
- Added cache versioning and metadata support to enhance plugin data management.
- Improved type safety with TypedDict definitions for better data validation.
- Updated CHANGELOG.md to reflect these new features and enhancements.
- Marked tasks as complete in TODO.md related to serialization and type safety improvements.

Author: twardoch

CHANGELOG.md

@@ -43,6 +43,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added Protocol definitions for scanner interfaces
 - Implemented type safety improvements with types.py
 - Refactored scanners to use common base class functionality
+- Created unified serialization layer with PluginSerializer
+- Added cache versioning and metadata support
+- Improved type safety with TypedDict definitions
+- Centralized all JSON operations in serialization module
 
 ## [1.1.0] - Previous Release
 

TODO.md

@@ -17,11 +17,11 @@
 - [x] Implement type guards for runtime validation
 
 ### Unified Serialization
-- [ ] Create serialization.py module
-- [ ] Implement PluginSerializer class
-- [ ] Replace duplicate serialization code in scanner.py
-- [ ] Add proper error handling to serialization
-- [ ] Add validation for loaded data
+- [x] Create serialization.py module
+- [x] Implement PluginSerializer class
+- [x] Replace duplicate serialization code in scanner.py
+- [x] Add proper error handling to serialization
+- [x] Add validation for loaded data
 
 ## Phase 2: Performance and Architecture
 
@@ -143,12 +143,18 @@
 ✅ Implemented basic plugin parameter extraction
 ✅ Added progress bars for scanning
 ✅ Created initial planning documents
+✅ Created protocols.py with Protocol definitions
+✅ Implemented BaseScanner abstraction
+✅ Refactored scanners to use inheritance
+✅ Created unified serialization layer
+✅ Added type safety with types.py and TypedDict
 
 🚧 In Progress:
-- Type safety improvements
-- Scanner abstraction
+- Removing remaining type: ignore comments
+- Implementing proper error handling
 
 📋 Next Priority:
-- Create protocols.py
-- Implement BaseScanner
-- Fix serialization duplication
+- Create exceptions.py with custom exception hierarchy
+- Add type stubs for pedalboard
+- Implement async scanner support
+- Add comprehensive test coverage

src/pedalboard_pluginary/constants.py

@@ -0,0 +1,49 @@
+"""
+Constants and configuration values for pedalboard_pluginary.
+"""
+
+from typing import Final
+
+# Application metadata
+APP_NAME: Final[str] = "com.twardoch.pedalboard-pluginary"
+APP_VERSION: Final[str] = "0.1.0"  # TODO: Get from package metadata
+
+# Cache configuration
+CACHE_VERSION: Final[str] = "2.0.0"
+PLUGINS_CACHE_FILENAME: Final[str] = "plugins"
+IGNORES_CACHE_FILENAME: Final[str] = "ignores"
+
+# Scanner configuration
+DEFAULT_SCAN_TIMEOUT: Final[int] = 10  # seconds
+MAX_SCAN_RETRIES: Final[int] = 3
+SCAN_RETRY_DELAY: Final[float] = 1.0  # seconds
+
+# Plugin types
+PLUGIN_TYPE_VST3: Final[str] = "vst3"
+PLUGIN_TYPE_AU: Final[str] = "aufx"
+SUPPORTED_PLUGIN_TYPES: Final[list[str]] = [PLUGIN_TYPE_VST3, PLUGIN_TYPE_AU]
+
+# File extensions
+VST3_EXTENSION: Final[str] = ".vst3"
+AU_EXTENSION: Final[str] = ".component"
+
+# Platform names
+PLATFORM_WINDOWS: Final[str] = "Windows"
+PLATFORM_MACOS: Final[str] = "Darwin"
+PLATFORM_LINUX: Final[str] = "Linux"
+
+# Progress reporting
+DEFAULT_PROGRESS_BAR_WIDTH: Final[int] = 80
+PROGRESS_UPDATE_INTERVAL: Final[float] = 0.1  # seconds
+
+# Logging configuration
+LOG_FORMAT: Final[str] = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+LOG_DATE_FORMAT: Final[str] = "%Y-%m-%d %H:%M:%S"
+
+# CLI configuration
+DEFAULT_OUTPUT_FORMAT: Final[str] = "json"
+SUPPORTED_OUTPUT_FORMATS: Final[list[str]] = ["json", "yaml", "table", "csv"]
+
+# Resource paths
+RESOURCES_PACKAGE: Final[str] = "pedalboard_pluginary.resources"
+DEFAULT_IGNORES_FILENAME: Final[str] = "default_ignores.json"

src/pedalboard_pluginary/core.py

@@ -1,34 +1,39 @@
 import json
 from pathlib import Path
-from typing import Any, Dict
+from typing import Dict
 
-from .data import get_cache_path, load_json_file
+from .data import get_cache_path
+from .models import PluginInfo
 from .scanner import PedalboardScanner
+from .serialization import PluginSerializer
 
 
 class PedalboardPluginary:
+    """Main class for the Pedalboard Pluginary application."""
+    
     plugins_path: Path
-    plugins: Dict[str, Any]  # Assuming plugin names (keys) are strings
+    plugins: Dict[str, PluginInfo]
 
     def __init__(self) -> None:
+        """Initialize the Pedalboard Pluginary instance."""
         self.plugins_path = get_cache_path("plugins")
-        self.plugins = {}  # Initialize to empty dict
+        self.plugins = {}
         self.load_data()
 
     def load_data(self) -> None:
+        """Load plugin data from cache or perform a scan if cache doesn't exist."""
         if not self.plugins_path.exists():
             scanner = PedalboardScanner()
-            scanner.full_scan()  # Updated to use full_scan instead of scan
+            scanner.full_scan()
 
-        # Ensure plugins are loaded even if scan wasn't needed or if it just ran
-        # load_json_file returns Dict[Any, Any], but we expect Dict[str, Any] for plugins
-        loaded_plugins = load_json_file(self.plugins_path)
-        if isinstance(loaded_plugins, dict):
-            self.plugins = loaded_plugins
-        else:
-            # This case should ideally not happen if save_json_file and load_json_file are robust
-            self.plugins = {}
+        # Load plugins using the serializer
+        self.plugins = PluginSerializer.load_plugins(self.plugins_path)
 
     def list_plugins(self) -> str:
         """Returns a JSON string representation of the plugins."""
-        return json.dumps(self.plugins, indent=4)
+        # Convert PluginInfo objects to dictionaries for JSON serialization
+        plugins_dict = {}
+        for plugin_id, plugin in self.plugins.items():
+            plugins_dict[plugin_id] = PluginSerializer.plugin_to_dict(plugin)
+        
+        return json.dumps(plugins_dict, indent=4)

src/pedalboard_pluginary/data.py

@@ -1,16 +1,11 @@
 import json
 import os
-import platform  # Added
+import platform
 import shutil
 from importlib import resources
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Set, Union
+from typing import Any, Dict, List, Set, Union
 
-from .models import PluginInfo, PluginParameter  # Added
-
-# pkg_resources import removed, will rely on importlib.resources primarily.
-# Fallback block for pkg_resources in copy_default_ignores will try to use it
-# and handle NameError if it's not available.
 from .utils import ensure_folder
 
 APP_NAME: str = "com.twardoch.pedalboard-pluginary"
@@ -41,8 +36,8 @@ def get_cache_path(cache_name: str) -> Path:
     return app_data_dir / f"{cache_name}.json"
 
 
-def load_json_file(file_path: Path) -> Dict[str, Any]:
-    """Load JSON data from a file. If it's the plugins cache, reconstruct PluginInfo objects."""
+def load_json_file(file_path: Path) -> Any:
+    """Load JSON data from a file."""
     if not file_path.exists():
         return {}
 
@@ -52,63 +47,12 @@ def load_json_file(file_path: Path) -> Dict[str, Any]:
         except json.JSONDecodeError:
             return {}  # Return empty dict if JSON is corrupted
 
-    # Check if this is the plugins cache file by its name
-    if file_path.name == f"{PLUGINS_CACHE_FILENAME_BASE}.json":
-        if not isinstance(raw_data, dict):
-            return {}  # Corrupted plugin cache
-
-        reconstructed_plugins: Dict[str, PluginInfo] = {}
-        for plugin_id, plugin_data_dict in raw_data.items():
-            if not isinstance(plugin_data_dict, dict):
-                continue  # Skip malformed entries
-
-            param_dicts = plugin_data_dict.get("parameters", {})
-            reconstructed_params: Dict[str, PluginParameter] = {}
-            if isinstance(param_dicts, dict):
-                for param_name, param_data_dict in param_dicts.items():
-                    if isinstance(param_data_dict, dict):
-                        try:
-                            reconstructed_params[param_name] = PluginParameter(
-                                name=str(param_data_dict.get("name", param_name)),
-                                value=param_data_dict.get("value", 0.0),
-                            )
-                        except TypeError as e:
-                            print(
-                                f"Warning: Could not reconstruct parameter {param_name} for {plugin_id}: {e}"
-                            )
-                            continue
-
-            try:
-                reconstructed_plugins[plugin_id] = PluginInfo(
-                    id=plugin_data_dict.get("id", plugin_id),
-                    name=plugin_data_dict.get("name", "Unknown Plugin Name"),
-                    path=plugin_data_dict.get("path", ""),
-                    filename=plugin_data_dict.get("filename", ""),
-                    plugin_type=plugin_data_dict.get("plugin_type", "unknown"),
-                    parameters=reconstructed_params,
-                    manufacturer=plugin_data_dict.get("manufacturer"),
-                    name_in_file=plugin_data_dict.get("name_in_file"),
-                )
-            except TypeError as e:
-                print(
-                    f"Warning: Could not reconstruct plugin info for {plugin_id}: {e}"
-                )
-                continue
-
-        return reconstructed_plugins
-
-    # Handle non-plugin cache files
-    result: Dict[str, Any] = {}
-    if isinstance(raw_data, dict):
-        result = {str(k): v for k, v in raw_data.items()}
-    elif isinstance(raw_data, list):
-        result = {str(i): item for i, item in enumerate(raw_data)}
-    return result
+    return raw_data
 
 
 def save_json_file(data: Union[Dict[Any, Any], List[Any]], file_path: Path) -> None:
     """Save JSON data to a file."""
-    ensure_folder(file_path)
+    ensure_folder(file_path.parent)
     with open(file_path, "w", encoding="utf-8") as file:
         json.dump(data, file, indent=4)
 
@@ -136,7 +80,7 @@ def copy_default_ignores(destination_path: Path) -> None:
         ).joinpath("default_ignores.json")
 
         if not destination_path.exists():
-            ensure_folder(destination_path)
+            ensure_folder(destination_path.parent)
             with importlib.resources.as_file(
                 default_ignores_src_path
             ) as src_file_on_fs:
@@ -149,5 +93,5 @@ def copy_default_ignores(destination_path: Path) -> None:
             f"Warning: Could not copy default ignores using importlib.resources: {e}. Creating empty ignores file."
         )
         if not destination_path.exists():
-            ensure_folder(destination_path)
-            save_json_file([], destination_path)
+            ensure_folder(destination_path.parent)
+            save_json_file([], destination_path)