Final refinements: improve docstrings, use pipe separator, fix variable shadowing

Co-authored-by: Mte90 <403283+Mte90@users.noreply.github.com>

Author: Copilot

main.py

@@ -64,10 +64,10 @@ async def lifespan(app: FastAPI):
     yield
 
     # Stop FileWatcher on shutdown
-    watcher = app_state.get_file_watcher()
-    if watcher:
+    shutdown_watcher = app_state.get_file_watcher()
+    if shutdown_watcher:
         try:
-            watcher.stop()
+            shutdown_watcher.stop()
             logger.info("FileWatcher stopped successfully")
         except Exception as e:
             logger.error(f"Error stopping FileWatcher: {e}")

utils/file_watcher.py

@@ -201,7 +201,8 @@ def set_on_change_callback(self, callback: Callable[[str, List[str]], None]) ->
         Set a callback to be called when changes are detected.
         
         Args:
-            callback: Function(project_id, changed_files) to call on changes
+            callback: Function(project_id: str, changed_files: List[str]) to call on changes.
+                     changed_files is a list of relative file paths that changed.
         """
         self._on_change_callback = callback
 
@@ -316,11 +317,12 @@ def _scan_directory(self, directory: str) -> Dict[str, str]:
 
                     try:
                         # Use both modification time and file size as signature
+                        # Format: "mtime|size" (using pipe as separator to avoid conflicts)
                         stat = os.stat(filepath)
                         mtime = stat.st_mtime
                         size = stat.st_size
                         relative_path = os.path.relpath(filepath, directory)
-                        file_hashes[relative_path] = f"{mtime}:{size}"
+                        file_hashes[relative_path] = f"{mtime}|{size}"
                     except (OSError, ValueError):
                         # Skip files we can't access
                         continue