synapse-hub 2.7.0 → 3.0.0

package/tools/synapse_qa_bench.py

@@ -19,7 +19,7 @@ import os
 import sys
 import json
 import argparse
-from typing import List, Dict, Any, Tuple
+from typing import List, Dict, Any, Optional
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -96,7 +96,7 @@ BENCHMARK_CASES = [
 class SynapseQABench:
     """Evaluates agent tool-calling capabilities against standardized QA benchmark cases."""
 
-    def __init__(self, cases: List[Dict[str, Any]] = None):
+    def __init__(self, cases: Optional[List[Dict[str, Any]]] = None):
         self.cases = cases or BENCHMARK_CASES
 
     def run_benchmark(self, tool_resolver_fn=None) -> Dict[str, Any]:
@@ -112,7 +112,7 @@ class SynapseQABench:
         details = []
 
         for case in self.cases:
-            expected_tool = case["expected_tool"]
+            expected_tool = str(case["expected_tool"])
             # Baseline keyword resolver simulation
             selected_tool = expected_tool if tool_resolver_fn is None else tool_resolver_fn(case["intent"])
 

package/tools/sync_agent_rules.py

@@ -47,9 +47,10 @@ HEADER_HASH_TEMPLATE = """# ====================================================
 
 
 def generate_claude_md():
+    """Generates the unified CLAUDE.md file compiling agent rules and standards."""
     return f"""# CLAUDE.md — Synapse-Hub Guidelines for Claude Code
 
-> **Author & Creator:** Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>  
+> **Author & Creator:** Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>
 > **License:** MIT License (Mandatory Attribution Preservation)
 
 {HEADER_TEMPLATE}
@@ -100,6 +101,7 @@ In accordance with the MIT License, the original copyright notice crediting **Th
 
 
 def generate_cursorrules():
+    """Generates the .cursorrules file compiling agent rules for Cursor AI."""
     return f"""# .cursorrules — Synapse-Hub Guidelines for Cursor AI
 # Author & Creator: Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>
 # License: MIT License (Mandatory Attribution Preservation)
@@ -127,6 +129,7 @@ def generate_cursorrules():
 
 
 def generate_windsurfrules():
+    """Generates the .windsurfrules configuration for Windsurf AI."""
     return f"""# .windsurfrules — Synapse-Hub Guidelines for Windsurf AI
 # Author & Creator: Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>
 # License: MIT License (Mandatory Attribution Preservation)
@@ -153,6 +156,7 @@ def generate_windsurfrules():
 
 
 def generate_cursor_mdc():
+    """Generates the .cursor/rules/synapse-qa.mdc file for Cursor IDE."""
     return f"""---
 description: Synapse-Hub Enterprise QA Automation & Testing Rules
 globs: **/*
@@ -177,12 +181,13 @@ Attribution notices must be preserved.
 
 
 def generate_copilot_instructions():
+    """Generates the .github/copilot-instructions.md file for GitHub Copilot."""
     return f"""# GitHub Copilot Custom Instructions for Synapse-Hub
 
 {HEADER_TEMPLATE}
 
-> **Project:** Synapse-Hub Enterprise QA Automation  
-> **Author:** Thế Vị (@TeeVee998) — MIT License  
+> **Project:** Synapse-Hub Enterprise QA Automation
+> **Author:** Thế Vị (@TeeVee998) — MIT License
 
 ## Coding Invariants
 - Enforce Clean Page Object Model (POM) with Flat Architecture.
@@ -210,6 +215,14 @@ TARGET_GENERATORS = [
 
 
 def sync_all(check_only=False):
+    """Synchronizes AGENTS.md rules across all IDE and assistant bridge files.
+
+    Args:
+        check_only: If True, only checks for rule drift without modifying files.
+
+    Returns:
+        0 if clean or synchronized, 1 if drift was detected in check_only mode.
+    """
     drift_detected = False
     for rel_path, gen_fn in TARGET_GENERATORS:
         full_path = os.path.join(REPO_ROOT, rel_path)
@@ -249,6 +262,7 @@ def sync_all(check_only=False):
 
 
 def main():
+    """CLI entrypoint for synchronizing AI agent rules."""
     parser = argparse.ArgumentParser(description="Synchronize AGENTS.md to all AI IDE bridges")
     parser.add_argument("--check", action="store_true", help="Check for drift without modifying files")
     args = parser.parse_args()

package/tools/telemetry_correlator.py

@@ -36,7 +36,7 @@ import csv
 import json
 import math
 import argparse
-from typing import Dict, List, Any, Optional, Tuple
+from typing import Dict, List, Any
 
 # Enforce UTF-8 stdout encoding for Windows/macOS/Linux console compatibility
 if hasattr(sys.stdout, "reconfigure"):
@@ -286,7 +286,8 @@ def main():
     args = parser.parse_args()
 
     if args.sample or not args.jtl or not args.server_metrics:
-        import tempfile, time
+        import tempfile
+        import time
         temp_dir = tempfile.gettempdir()
         temp_jtl = os.path.join(temp_dir, "sample_corr_jmeter.jtl")
         temp_srv = os.path.join(temp_dir, "sample_corr_server.csv")

package/tools/test_memory_os.py

@@ -27,6 +27,7 @@ import re
 import json
 import sqlite3
 import time
+import uuid
 import difflib
 import argparse
 from datetime import datetime, timezone, timedelta
@@ -48,6 +49,15 @@ SECRET_PATTERNS = [
 ]
 
 
+class ManagedConnection(sqlite3.Connection):
+    """SQLite connection that automatically commits/rollbacks and closes on context exit."""
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        try:
+            super().__exit__(exc_type, exc_val, exc_tb)
+        finally:
+            self.close()
+
+
 class TestMemoryOS:
     """3-Tier Hierarchical QA Memory OS."""
     __test__ = False
@@ -62,8 +72,8 @@ class TestMemoryOS:
         os.makedirs(os.path.dirname(os.path.abspath(self.db_path)), exist_ok=True)
         self._init_db()
 
-    def _get_connection(self) -> sqlite3.Connection:
-        conn = sqlite3.connect(self.db_path)
+    def _get_connection(self) -> ManagedConnection:
+        conn = sqlite3.connect(self.db_path, factory=ManagedConnection)
         conn.row_factory = sqlite3.Row
         return conn
 
@@ -165,7 +175,7 @@ class TestMemoryOS:
                 INSERT INTO recall_memory (session_id, event_type, actor, payload_json, timestamp)
                 VALUES (?, ?, ?, ?, ?)
             """, (session_id, event_type, actor, payload_str, now))
-            return cursor.lastrowid
+            return cursor.lastrowid or 0
 
     def recall_log(self, session_id: str, limit: int = 50) -> List[Dict[str, Any]]:
         """Retrieves recent sequential steps for a session."""
@@ -199,7 +209,7 @@ class TestMemoryOS:
         """Inserts long-term searchable knowledge into archival memory."""
         payload_str = json.dumps(payload) if not isinstance(payload, str) else payload
         now = datetime.now(timezone.utc).isoformat()
-        mem_id = f"mem_arch_{int(time.time() * 1000) % 10000000}"
+        mem_id = f"mem_arch_{int(time.time() * 1000) % 10000000}_{uuid.uuid4().hex[:6]}"
 
         # Flatten text content for semantic/fuzzy search
         text_content = f"{key} {aut_version} {tags} {payload_str}".lower()
@@ -336,7 +346,7 @@ def main():
     subparsers = parser.add_subparsers(dest="subcommand", help="Subcommand to execute")
 
     # init
-    init_parser = subparsers.add_parser("init", help="Initialize memory OS database")
+    subparsers.add_parser("init", help="Initialize memory OS database")
 
     # update-core
     uc_parser = subparsers.add_parser("update-core", help="Update core memory block")

package/tools/textgrad_mutation_optimizer.py

@@ -20,7 +20,7 @@ import sys
 import re
 import json
 import argparse
-from typing import List, Dict, Any, Tuple, Optional
+from typing import List, Dict, Any, Tuple
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -33,10 +33,10 @@ if hasattr(sys.stdout, 'reconfigure'):
 SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
 sys.path.insert(0, SCRIPT_DIR)
 
-import micro_mutator
+import micro_mutator  # noqa: E402
 
 try:
-    import textgrad
+    import textgrad  # noqa: F401, E402
     TEXTGRAD_AVAILABLE = True
 except ImportError:
     TEXTGRAD_AVAILABLE = False

package/tools/tms_sync_bridge.py

@@ -78,7 +78,7 @@ class TMSBridge:
                 "issue_type": "Story",
                 "status": "Ready for QA",
                 "assignee": self.user_email,
-                "description": f"As an Enterprise Accountant, I want to reconcile invoices matching ERP records to ensure financial accuracy.",
+                "description": "As an Enterprise Accountant, I want to reconcile invoices matching ERP records to ensure financial accuracy.",
                 "acceptance_criteria": [
                     "Given the accountant is logged in with FINANCE_ROLE",
                     "When navigating to '/billing/invoices' and filtering by date '2026-10-01'",
@@ -161,8 +161,8 @@ class TMSBridge:
         bug_key = f"{proj_clean}-BUG-{int(datetime.now().timestamp()) % 10000}"
 
         repro = reproduction_steps or [
-            f"1. Launch headless browser session via Playwright Live.",
-            f"2. Navigate to target application flow under test.",
+            "1. Launch headless browser session via Playwright Live.",
+            "2. Navigate to target application flow under test.",
             f"3. Execute test action sequence for '{test_case_id}'.",
             f"4. Observe failure: {error_message}"
         ]
@@ -299,9 +299,9 @@ def main():
         if args.json:
             print(json.dumps(story, indent=2))
         else:
-            print(f"\n======================================================================")
+            print("\n======================================================================")
             print(f"      ENTERPRISE ALM STORY PULL: [{story.get('issue_key')}]")
-            print(f"======================================================================")
+            print("======================================================================")
             print(f"  Summary   : {story.get('summary')}")
             print(f"  Status    : {story.get('status')} | Assignee: {story.get('assignee')}")
             print(f"  Source    : {story.get('source')}\n")

package/tools/tot_exploratory_tester.py

@@ -21,9 +21,8 @@ import os
 import sys
 import re
 import json
-import time
 import argparse
-from typing import Dict, Any, List, Optional, Tuple
+from typing import Dict, Any, List, Optional, cast
 
 # Enforce UTF-8 stdout encoding
 if hasattr(sys.stdout, 'reconfigure'):
@@ -43,7 +42,7 @@ class TotExploratoryTester:
     def expand_story(self, story_content: str, max_depth: int = 3, beam_width: int = 3) -> Dict[str, Any]:
         """Decomposes story into a 3-branch Tree of Thoughts with risk scores."""
         # Extract title and criteria
-        lines = [l.strip() for l in story_content.splitlines() if l.strip()]
+        lines = [line.strip() for line in story_content.splitlines() if line.strip()]
         title = lines[0] if lines else "Untitled User Story"
         if title.startswith("#"):
             title = title.lstrip("#").strip()
@@ -93,7 +92,7 @@ class TotExploratoryTester:
         ]
 
         # Beam search selection: sort by risk score descending and take beam_width
-        sorted_branches = sorted(branches, key=lambda b: b["risk_score"], reverse=True)
+        sorted_branches = sorted(branches, key=lambda b: cast(float, b["risk_score"]), reverse=True)
         selected_branches = sorted_branches[:beam_width]
 
         return {
@@ -169,7 +168,7 @@ class TotExploratoryTester:
                 "evidence": evidence
             })
 
-        scored_hypotheses.sort(key=lambda h: h["confidence_score"], reverse=True)
+        scored_hypotheses.sort(key=lambda h: cast(float, h["confidence_score"]), reverse=True)
         winner = scored_hypotheses[0]
 
         recommendations = {
@@ -184,7 +183,7 @@ class TotExploratoryTester:
             "status": "PASS",
             "primary_root_cause": winner["hypothesis"],
             "confidence": winner["confidence_score"],
-            "recommended_fix": recommendations.get(winner["hypothesis"], "Review stacktrace with team"),
+            "recommended_fix": recommendations.get(str(winner["hypothesis"]), "Review stacktrace with team"),
             "ranked_hypotheses": scored_hypotheses
         }
 

package/tools/traffic_session_converter.py

@@ -23,7 +23,7 @@ import re
 import sys
 import json
 import argparse
-from typing import Dict, Any, List, Optional
+from typing import Dict, Any, List
 from urllib.parse import urlparse
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
@@ -153,14 +153,14 @@ class TrafficConverter:
         lines = [
             "import { test, expect } from '@playwright/test';",
             "",
-            f"/**",
-            f" * Automated Replay of Production Traffic Session",
-            f" * Generated by traffic_session_converter.py (agent-skills Shift-Right Engine)",
+            "/**",
+            " * Automated Replay of Production Traffic Session",
+            " * Generated by traffic_session_converter.py (agent-skills Shift-Right Engine)",
             f" * Total Actions: {len(requests)} verified network interactions",
-            f" */",
+            " */",
             f"test.describe('{test_name}', () => {{",
-            f"  test('replays production user journey with PII masking', async ({{ page, request }}) => {{",
-            f"    // 1. Base navigation",
+            "  test('replays production user journey with PII masking', async ({ page, request }) => {",
+            "    // 1. Base navigation",
             f"    await page.goto('{base_url}');",
             ""
         ]
@@ -185,9 +185,9 @@ class TrafficConverter:
                     formatted_body = json.dumps(body_str)
 
                 lines.append(f"    const resp{step_num} = await request.{method.lower()}('{url}', {{")
-                lines.append(f"      headers: {{ 'Content-Type': 'application/json' }},")
+                lines.append("      headers: { 'Content-Type': 'application/json' },")
                 lines.append(f"      data: {formatted_body}")
-                lines.append(f"    }});")
+                lines.append("    });")
                 lines.append(f"    expect(resp{step_num}.status()).toBe({status});")
             else:
                 lines.append(f"    const resp{step_num} = await request.get('{url}');")

package/tools/universal_ir.py

@@ -9,8 +9,9 @@ whether the target is Playwright, Selenium, Cypress, Katalon, or Appium.
 
 from enum import Enum
 from typing import Dict, List, Optional, Any
-from dataclasses import dataclass, field, asdict
+from dataclasses import dataclass, field
 import json
+import re
 
 
 class ActionType(str, Enum):
@@ -345,8 +346,6 @@ class ProjectIR:
         return cls.from_dict(data)
 
 
-import re
-
 SHARED_VAR_PATTERNS = [
     (r"\b(?:created_id|order_id|user_id|item_id|customer_id|invoice_id)\b", DataDependencyType.ID),
     (r"\b(?:auth_token|bearer_token|access_token|jwt_token|token)\b", DataDependencyType.AUTH_TOKEN),

package/tools/update_sentinel.py

@@ -65,7 +65,7 @@ def get_local_version():
         try:
             with open(pkg_file, "r", encoding="utf-8") as f:
                 data = json.load(f)
-                return data.get("version", "2.7.0")
+                return data.get("version", "3.0.0")
         except (OSError, json.JSONDecodeError):
             data = {}
 
@@ -74,11 +74,11 @@ def get_local_version():
         try:
             with open(manifest_file, "r", encoding="utf-8") as f:
                 data = json.load(f)
-                return data.get("version", "2.7.0")
+                return data.get("version", "3.0.0")
         except (OSError, json.JSONDecodeError):
             data = {}
 
-    return "2.7.0"
+    return "3.0.0"
 
 
 def fetch_remote_version():
@@ -259,7 +259,6 @@ def perform_update():
     git_dir = os.path.join(HUB_ROOT, ".git")
     is_git_repo = os.path.exists(git_dir)
 
-    updated = False
 
     if is_git_repo:
         print(f"\n{BOLD}[1/3] Pulling latest updates via Git...{RESET}")
@@ -281,7 +280,6 @@ def perform_update():
                     print(f"  {RED}⚠️ Provenance Warning: {msg}{RESET}")
                 else:
                     print(f"  {GREEN}[OK] {msg}{RESET}")
-                updated = True
                 # If this is the first pull, show the welcome landing page
                 try:
                     import welcome_page
@@ -306,9 +304,8 @@ def perform_update():
             )
             if res.returncode == 0:
                 print(f"  {GREEN}[OK] Global NPM package updated to latest!{RESET}")
-                updated = True
         except (subprocess.SubprocessError, OSError):
-            updated = False
+            _ = False
 
     # 2. Check Global Plugin
     if os.path.exists(GLOBAL_PLUGIN_DIR) and GLOBAL_PLUGIN_DIR.lower() != HUB_ROOT.lower():
@@ -319,7 +316,7 @@ def perform_update():
                 subprocess.run(["git", "pull", "--ff-only"], cwd=GLOBAL_PLUGIN_DIR, stdout=subprocess.DEVNULL, timeout=30.0)
                 print(f"  {GREEN}[OK] Updated Global Plugin repository: {GLOBAL_PLUGIN_DIR}{RESET}")
             except (subprocess.SubprocessError, OSError):
-                plugin_synced = False
+                _ = False
         else:
             # Refresh metadata files in global plugin
             try:
@@ -331,7 +328,7 @@ def perform_update():
                         shutil.copy2(src_f, dst_f)
                 print(f"  {GREEN}[OK] Refreshed metadata & LICENSE in: {GLOBAL_PLUGIN_DIR}{RESET}")
             except OSError:
-                copy_done = False
+                _ = False
 
     # 3. Re-initialize SQLite Memory Cache
     print(f"\n{BOLD}[3/3] Synchronizing Central Agent Memory Cache...{RESET}")

package/tools/verify_all.py

@@ -136,6 +136,7 @@ def resolve_target_repo(cli_target=None, cli_repo=None):
 
 
 def gate_0_author_integrity(repo_root, mode="AUTO"):
+    """Gate 0: Verifies author attribution and MIT license provenance across source manifests."""
     print("\n[GATE 0] Verifying Author Attribution & MIT License Integrity...")
     try:
         from author_integrity import (
@@ -194,6 +195,7 @@ MOJIBAKE_INDICATORS = (
 
 
 def gate_1_bom_check(repo_root, mode="AUTO"):
+    """Gate 1: Verifies 100% UTF-8 encoding with zero Byte Order Mark (BOM) bytes."""
     print("\n[GATE 1] Scanning UTF-8 No BOM and Encoding Integrity across repository...")
     ignored_dirs = {".git", ".gradle", "node_modules", "allure-results", "graphify-out", "__pycache__", "build", "dist", "claude-ecosystem-repos", "external_repos", "teamwork"}
     ignored_files = {"verify_all.py", "test_tools.py"}
@@ -241,6 +243,7 @@ def gate_1_bom_check(repo_root, mode="AUTO"):
 
 
 def gate_2_path_portability(repo_root, mode="AUTO"):
+    """Gate 2: Scans for and rejects machine-specific absolute filepaths in code."""
     print("\n[GATE 2] Checking Path Portability (Zero absolute machine paths in repo sources)...")
     ignored_dirs = {
         ".git", ".gradle", "node_modules", "allure-results", "Screenshots",
@@ -286,6 +289,7 @@ def gate_2_path_portability(repo_root, mode="AUTO"):
 
 
 def gate_3_clean_pom(repo_root, mode="AUTO"):
+    """Gate 3: Enforces Clean Page Object Model by rejecting raw selectors in test scripts."""
     print("\n[GATE 3] Checking Clean POM & Flat Architecture in Test Scripts...")
     effective_mode = detect_repo_mode(repo_root) if mode == "AUTO" else mode
     if effective_mode == "HUB":
@@ -346,6 +350,7 @@ def gate_3_clean_pom(repo_root, mode="AUTO"):
 
 
 def gate_4_ai_docs_lint(repo_root, mode="AUTO"):
+    """Gate 4: Reconciles PROJECT_AI_GUIDE.md against physical AST to prevent hallucinated classes."""
     print("\n[GATE 4] Running AI Documentation & Artifact Linter...")
     linter_script = os.path.join(SCRIPT_DIR, "lint_ai_docs.py")
     if not os.path.exists(linter_script):
@@ -368,6 +373,7 @@ def gate_4_ai_docs_lint(repo_root, mode="AUTO"):
 
 
 def gate_5_cleanup_blacklist(repo_root, mode="AUTO"):
+    """Gate 5: Scans for prohibited temporary files, heap dumps, and local cache artifacts."""
     print("\n[GATE 5] Checking Temporary File Blacklist...")
     blacklist_patterns = [
         os.path.join(repo_root, "Reports", "batch*.properties"),
@@ -392,6 +398,7 @@ def gate_5_cleanup_blacklist(repo_root, mode="AUTO"):
 
 
 def gate_6_credential_security(repo_root, mode="AUTO"):
+    """Gate 6: Scans for plaintext passwords, API tokens, and private keys across codebase."""
     print("\n[GATE 6] Checking Credential Security across repository...")
     violations = []
 
@@ -658,6 +665,7 @@ def check_python_ast_integrity(repo_root):
 
 
 def gate_7_infer_linter(repo_root, mode="AUTO"):
+    """Gate 7: Runs Meta Infer-style static defect sentinel catching fake passes, 0 assert, and sleeps."""
     print("\n[GATE 7] Running Meta Infer-Style Static Defect & Fake-Pass Sentinel...")
     effective_mode = detect_repo_mode(repo_root) if mode == "AUTO" else mode
 
@@ -737,6 +745,7 @@ def gate_7_infer_linter(repo_root, mode="AUTO"):
 
 
 def gate_8_micro_mutator(repo_root, mode="AUTO", test_cmd=""):
+    """Gate 8: Runs syntactic mutation testing and verifies assertion sensitivity score >= 80%."""
     eval_mode_desc = f"DYNAMIC EXECUTION MODE ({test_cmd})" if test_cmd else "HEURISTIC STATIC MODE"
     print(f"\n[GATE 8] Running Assertion Sensitivity & Syntactic Mutation Sentinel [{eval_mode_desc}] (Min Score >= 80%)...")
     scripts_dir = os.path.join(repo_root, "Scripts")
@@ -797,6 +806,7 @@ def gate_8_micro_mutator(repo_root, mode="AUTO", test_cmd=""):
 
 
 def gate_9_skill_collision(repo_root, mode="AUTO"):
+    """Gate 9: Scans skill descriptions to ensure semantic trigger overlap remains < 0.75."""
     print("\n[GATE 9] Running Tier-2 Skill Routing & Collision Guard (Addy Osmani Pattern)...")
     guard_script = os.path.join(SCRIPT_DIR, "skill_collision_guard.py")
     if not os.path.exists(guard_script):

package/tools/visual_diff_canvas.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-from __future__ import annotations
 """
 Enterprise Canvas Visual Diff & Regression Checker
 ===================================================
@@ -17,11 +16,11 @@ Usage:
   python3 tools/visual_diff_canvas.py compare baseline.png current.png --diff diff.png --threshold 0.02
   python3 tools/visual_diff_canvas.py check-blank current.png
 """
+from __future__ import annotations
 
 import os
 import sys
 import argparse
-from pathlib import Path
 
 try:
     from PIL import Image, ImageChops, ImageStat

package/tools/visual_som_helper.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-from __future__ import annotations
 """
 Enterprise Vision-Grounded Fallback & Set-of-Marks (SoM) Engine
 --------------------------------------------------------------
@@ -20,27 +19,25 @@ Features:
   4. Compact Vision Prompt Formatter:
      - Formats token-efficient briefs for Multimodal Vision Models (Gemini / Claude / GPT-4o).
 """
+from __future__ import annotations
 
 import os
 import sys
 import json
 import sqlite3
 import argparse
-from typing import Dict, Any, List, Optional, Tuple, Union
+from typing import Dict, Any, List, Optional, Tuple
 try:
     from PIL import Image, ImageDraw, ImageFont, ImageFilter
     HAS_PIL = True
 except ImportError:
-    Image = None
-    ImageDraw = None
-    ImageFont = None
-    ImageFilter = None
+    Image = None  # type: ignore[assignment]
+    ImageDraw = None  # type: ignore[assignment]
+    ImageFont = None  # type: ignore[assignment]
+    ImageFilter = None  # type: ignore[assignment]
     HAS_PIL = False
 
-if HAS_PIL and Image is not None:
-    ImageSourceType = Union[Image.Image, str]
-else:
-    ImageSourceType = Any
+ImageSourceType = Any
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -74,12 +71,12 @@ def compute_visual_hash(image_source: ImageSourceType, bbox: Optional[List[int]]
     if isinstance(image_source, str):
         if not os.path.exists(image_source):
             raise FileNotFoundError(f"Image not found: {image_source}")
-        img = Image.open(image_source)
+        img: Any = Image.open(image_source)
     else:
         img = image_source
 
     if bbox and len(bbox) == 4:
-        img = img.crop(bbox)
+        img = img.crop(tuple(bbox))
 
     # Resize to (hash_size + 1, hash_size) in grayscale
     resized = img.convert("L").resize((hash_size + 1, hash_size), Image.Resampling.LANCZOS)
@@ -266,6 +263,8 @@ class VisualSoMHelper:
         edges = img.filter(ImageFilter.FIND_EDGES)
         edges = edges.point(lambda p: 255 if p > edge_threshold else 0)
         pixels = edges.load()
+        if pixels is None:
+            return []
 
         # Identify active cells with high edge density
         active_cells = set()
@@ -274,7 +273,10 @@ class VisualSoMHelper:
                 count = 0
                 for cy in range(y, min(h, y + stride)):
                     for cx in range(x, min(w, x + stride)):
-                        if pixels[cx, cy] > 0:
+                        px_val = pixels[cx, cy]
+                        if isinstance(px_val, (int, float)) and px_val > 0:
+                            count += 1
+                        elif isinstance(px_val, tuple) and px_val and px_val[0] > 0:
                             count += 1
                 if count >= min_pixels_per_cell:
                     active_cells.add((x // stride, y // stride))

package/tools/watch_mode.py

@@ -156,7 +156,7 @@ def run_incremental_audit(file_path: str, target_dir: str) -> Dict[str, Any]:
     """Performs fast sub-100ms audit on a single changed file."""
     start_t = time.perf_counter()
     rel_path = os.path.relpath(file_path, target_dir)
-    results = {
+    results: Dict[str, Any] = {
         "file": rel_path,
         "bom_pass": True,
         "path_pass": True,

package/tools/wcag_audit.py

@@ -126,6 +126,18 @@ class WCAGAuditor(HTMLParser):
 
 
 def run_audit(target, is_url=False):
+    """Executes a WCAG 2.2 accessibility audit against an HTML file or live web URL.
+
+    Args:
+        target: Filepath or URL pointing to HTML content.
+        is_url: True if target should be fetched over HTTP/HTTPS.
+
+    Returns:
+        The populated WCAGAuditor instance containing violations and stats.
+
+    Raises:
+        ValueError: If an insecure or invalid URL scheme is passed.
+    """
     auditor = WCAGAuditor()
     if is_url:
         parsed = urllib.parse.urlparse(target)
@@ -143,6 +155,15 @@ def run_audit(target, is_url=False):
 
 
 def format_markdown_report(target, auditor):
+    """Generates an executive WCAG 2.2 audit markdown report.
+
+    Args:
+        target: Target URL or file audited.
+        auditor: Populated WCAGAuditor instance.
+
+    Returns:
+        Markdown string containing compliance score, grade, and violation details.
+    """
     violations = auditor.violations
     stats = {
         "elements_scanned": auditor.elements_scanned,
@@ -158,7 +179,7 @@ def format_markdown_report(target, auditor):
     grade = "PASS" if score >= 80 else "NEEDS REMEDIATION"
 
     out = [
-        f"# WCAG 2.2 Accessibility Audit Report",
+        "# WCAG 2.2 Accessibility Audit Report",
         f"**Target:** `{target}`",
         f"**Elements Scanned:** {stats['elements_scanned']}",
         f"**Violations Found:** {stats['violations_found']}",