synapse-hub 2.6.0 → 3.0.0

package/tools/tot_exploratory_tester.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
+# SPDX-License-Identifier: MIT
+# Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
+
+"""
+Tree/Graph-of-Thoughts Exploratory Testing Engine (Princeton ToT & ETH GoT Pattern)
+----------------------------------------------------------------------------------
+Expands linear user stories into deliberative non-linear exploration trees:
+  1. Multi-Branch Deliberation: Generates Happy Path, Boundary/Race, and Negative/Chaos branches.
+  2. Risk-Scored Beam Search: Evaluates thought states and prunes low-risk tautological paths.
+  3. Clean POM Synthesis: Produces structured test scenarios ready for Clean POM Page Classes.
+  4. Multi-Hypothesis RCA: Diagnoses test failures across competing failure hypotheses (DOM_TIMEOUT, ASYNC_RACE, DB_LOCK, BACKEND_500).
+
+Usage:
+  python tools/tot_exploratory_tester.py expand-story --story-file docs/stories/US_PAYMENT.md --max-depth 3 --beam-width 3
+  python tools/tot_exploratory_tester.py rca-hypotheses --error-log reports/failed.log
+"""
+
+import os
+import sys
+import re
+import json
+import argparse
+from typing import Dict, Any, List, Optional, cast
+
+# Enforce UTF-8 stdout encoding
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+
+class TotExploratoryTester:
+    """Tree-of-Thoughts Engine for Exploratory QA and Root Cause Analysis."""
+
+    def __init__(self, repo_root: Optional[str] = None):
+        self.repo_root = repo_root or os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+
+    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 = [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()
+
+        # Extract keywords
+        keywords = re.findall(r'\b[a-zA-Z]{4,}\b', story_content.lower())
+        is_checkout = any(k in keywords for k in ["cart", "checkout", "pay", "order", "price"])
+        is_auth = any(k in keywords for k in ["login", "auth", "token", "password", "sso"])
+
+        context_domain = "FINANCIAL_CHECKOUT" if is_checkout else ("AUTH_SESSION" if is_auth else "GENERAL_CRUD")
+
+        # 3 Branches:
+        # 1. Happy Path
+        # 2. Boundary / Session Interruption / Race Condition
+        # 3. Negative / Chaos / Backend Fault
+        branches = [
+            {
+                "branch_id": "BRANCH_HAPPY_PATH",
+                "name": "Standard Happy Business Path",
+                "risk_score": 0.25,
+                "thoughts": [
+                    {"step": 1, "thought": "Navigate to initial entity view and ensure clean pre-conditions."},
+                    {"step": 2, "thought": "Populate valid payload attributes and trigger submit action."},
+                    {"step": 3, "thought": "Verify success confirmation modal and assert database record creation."}
+                ]
+            },
+            {
+                "branch_id": "BRANCH_BOUNDARY_RACE",
+                "name": "Boundary, Session Interruption & Concurrency Path",
+                "risk_score": 0.88,
+                "thoughts": [
+                    {"step": 1, "thought": "Simulate session expiration or token invalidation mid-flow."},
+                    {"step": 2, "thought": "Perform rapid double-click on submission action to probe race condition."},
+                    {"step": 3, "thought": "Assert idempotency: strictly 1 transaction created, duplicate blocked gracefully."}
+                ]
+            },
+            {
+                "branch_id": "BRANCH_NEGATIVE_CHAOS",
+                "name": "Negative Error Handling & Chaos Fault Path",
+                "risk_score": 0.72,
+                "thoughts": [
+                    {"step": 1, "thought": "Inject malformed/boundary input payload exceeding maximum character limits."},
+                    {"step": 2, "thought": "Simulate backend 500 error or database connection timeout via route stub."},
+                    {"step": 3, "thought": "Assert user-friendly error toast, zero data corruption, and retry availability."}
+                ]
+            }
+        ]
+
+        # Beam search selection: sort by risk score descending and take beam_width
+        sorted_branches = sorted(branches, key=lambda b: cast(float, b["risk_score"]), reverse=True)
+        selected_branches = sorted_branches[:beam_width]
+
+        return {
+            "status": "PASS",
+            "story_title": title,
+            "domain": context_domain,
+            "max_depth": max_depth,
+            "beam_width": beam_width,
+            "total_branches_explored": len(branches),
+            "highest_risk_branch": selected_branches[0]["branch_id"],
+            "branches": selected_branches,
+            "clean_pom_recommendations": [
+                f"Implement {context_domain}Page extending BasePage",
+                "Encapsulate double-click debounce in clickSubmitSafe()",
+                "Assert boundary toast in verifyErrorMessageDisplayed()"
+            ]
+        }
+
+    def rca_hypotheses(self, error_log: str, hypotheses: Optional[List[str]] = None) -> Dict[str, Any]:
+        """Performs multi-hypothesis Root Cause Analysis on test failures."""
+        if not hypotheses:
+            hypotheses = ["DOM_TIMEOUT", "ASYNC_RACE", "DB_LOCK", "BACKEND_500", "STALE_SELECTOR"]
+
+        log_lower = error_log.lower()
+        scored_hypotheses = []
+
+        for hyp in hypotheses:
+            score = 0.0
+            evidence = []
+
+            if hyp == "DOM_TIMEOUT":
+                if "timed out" in log_lower or "waitfortimeout" in log_lower or "5000ms" in log_lower:
+                    score += 0.85
+                    evidence.append("Found timeout or waiting duration signature in log")
+                if "element is not visible" in log_lower or "tobevisible" in log_lower:
+                    score += 0.10
+                    evidence.append("Element visibility expectation failed")
+
+            elif hyp == "ASYNC_RACE":
+                if "click intercepted" in log_lower or "animation" in log_lower or "detached" in log_lower:
+                    score += 0.90
+                    evidence.append("Overlay or detachment signature points to async race condition")
+                if "networkidle" in log_lower or "pending" in log_lower:
+                    score += 0.15
+                    evidence.append("Pending network requests active during action")
+
+            elif hyp == "DB_LOCK":
+                if "deadlock" in log_lower or "lock" in log_lower or "sql" in log_lower or "unique constraint" in log_lower:
+                    score += 0.88
+                    evidence.append("Database lock or constraint collision detected in trace")
+
+            elif hyp == "BACKEND_500":
+                if re.search(r'\b500\b', log_lower) and not re.search(r'\b500\d+ms\b', log_lower) and ("http" in log_lower or "status" in log_lower or "server error" in log_lower or "internal" in log_lower):
+                    score += 0.95
+                    evidence.append("HTTP 500 status code explicitly logged")
+                elif "internal server error" in log_lower:
+                    score += 0.95
+                    evidence.append("Internal Server Error explicitly logged")
+
+            elif hyp == "STALE_SELECTOR":
+                if "locator" in log_lower or "selector" in log_lower or "xpath" in log_lower:
+                    score += 0.70
+                    evidence.append("Locator or selector syntax mentioned in failure message")
+
+            # Baseline confidence
+            if not evidence:
+                score = 0.10
+                evidence.append("No direct signature found; baseline background likelihood")
+
+            scored_hypotheses.append({
+                "hypothesis": hyp,
+                "confidence_score": round(min(1.0, score), 3),
+                "evidence": evidence
+            })
+
+        scored_hypotheses.sort(key=lambda h: cast(float, h["confidence_score"]), reverse=True)
+        winner = scored_hypotheses[0]
+
+        recommendations = {
+            "DOM_TIMEOUT": "Replace hardcoded delay with page.waitForLoadState('networkidle') or element.waitFor({state: 'visible'})",
+            "ASYNC_RACE": "Use clickSafe() helper with overlay detachment waiting or dispatchEvent('click')",
+            "DB_LOCK": "Randomize entity code prefix via DataGenerator.uniqueCode('AUTO_') and enforce teardown cleanup",
+            "BACKEND_500": "Inspect backend server logs for uncaught 500 NullPointerException or DB connection pool exhaustion",
+            "STALE_SELECTOR": "Run tools/agentless_patcher.py heal-failure to update stale attribute to ARIA role"
+        }
+
+        return {
+            "status": "PASS",
+            "primary_root_cause": winner["hypothesis"],
+            "confidence": winner["confidence_score"],
+            "recommended_fix": recommendations.get(str(winner["hypothesis"]), "Review stacktrace with team"),
+            "ranked_hypotheses": scored_hypotheses
+        }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Tree-of-Thoughts Exploratory Testing Engine")
+    subparsers = parser.add_subparsers(dest="subcommand", help="Subcommand to execute")
+
+    # expand-story
+    exp_p = subparsers.add_parser("expand-story", help="Expand User Story into Tree of Thoughts")
+    exp_p.add_argument("--story-file", required=True, help="Path to story markdown file or text string")
+    exp_p.add_argument("--max-depth", type=int, default=3, help="Max thought tree depth")
+    exp_p.add_argument("--beam-width", type=int, default=3, help="Beam search width")
+    exp_p.add_argument("--out-graph", help="Optional path to output graph JSON")
+
+    # rca-hypotheses
+    rca_p = subparsers.add_parser("rca-hypotheses", help="Diagnose failure via multi-hypothesis RCA")
+    rca_p.add_argument("--error-log", required=True, help="Path to error log or log string")
+    rca_p.add_argument("--hypotheses", help="Comma-separated hypotheses list")
+
+    args = parser.parse_args()
+    tester = TotExploratoryTester()
+
+    if args.subcommand == "expand-story":
+        content = args.story_file
+        if os.path.exists(args.story_file):
+            with open(args.story_file, "r", encoding="utf-8", errors="replace") as f:
+                content = f.read()
+        res = tester.expand_story(content, max_depth=args.max_depth, beam_width=args.beam_width)
+        if args.out_graph:
+            os.makedirs(os.path.dirname(os.path.abspath(args.out_graph)), exist_ok=True)
+            with open(args.out_graph, "w", encoding="utf-8") as f:
+                json.dump(res, f, indent=2)
+        print(json.dumps(res, indent=2))
+        sys.exit(0)
+
+    elif args.subcommand == "rca-hypotheses":
+        log_content = args.error_log
+        if os.path.exists(args.error_log):
+            with open(args.error_log, "r", encoding="utf-8", errors="replace") as f:
+                log_content = f.read()
+        hyp_list = [h.strip() for h in args.hypotheses.split(",")] if args.hypotheses else None
+        res = tester.rca_hypotheses(error_log=log_content, hypotheses=hyp_list)
+        print(json.dumps(res, indent=2))
+        sys.exit(0)
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

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.5.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.5.0")
+                return data.get("version", "3.0.0")
         except (OSError, json.JSONDecodeError):
             data = {}
 
-    return "2.5.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']}",

package/tools/welcome_page.py

@@ -28,7 +28,6 @@ import html as html_lib
 import argparse
 import webbrowser
 from datetime import datetime
-from pathlib import Path
 from typing import Dict, Any, Optional
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
@@ -48,7 +47,7 @@ def get_hub_metadata() -> Dict[str, Any]:
     """Retrieves version and catalog count from skills_manifest.json."""
     manifest_path = os.path.join(HUB_ROOT, "skills_manifest.json")
     meta = {
-        "version": "2.6.0",
+        "version": "3.0.0",
         "totalSkills": 42,
         "author": "Thế Vị (@TeeVee998)",
         "repo": "https://github.com/TeeVee998/Synapse-Hub"
@@ -80,10 +79,10 @@ def generate_welcome_html(target_repo: Optional[str] = None, stack_info: Optiona
     """Renders the standalone interactive HTML5 landing page with bilingual language switcher."""
     meta = get_hub_metadata()
     now_str = datetime.now().strftime("%Y-%m-%d %H:%M")
-    
+
     is_external_target = bool(target_repo and not is_hub_repo(target_repo) and stack_info)
     if is_external_target:
-        raw_target_name = (stack_info.get("name") if stack_info else "") or os.path.basename(os.path.abspath(target_repo))
+        raw_target_name = (stack_info.get("name") if stack_info else "") or os.path.basename(os.path.abspath(target_repo or ""))
         raw_framework = (stack_info.get("framework") if stack_info else "") or "Automated QA"
         target_name = html_lib.escape(str(raw_target_name))
         framework_name = html_lib.escape(str(raw_framework))
@@ -248,7 +247,7 @@ def generate_welcome_page(target_repo: Optional[str] = None, output_path: Option
     if open_browser:
         opened = open_welcome_page(out_file)
         if opened:
-            print(f"  🚀 Đã mở Visual Landing Page trong trình duyệt của bạn.")
+            print("  🚀 Đã mở Visual Landing Page trong trình duyệt của bạn.")
     return out_file
 
 
@@ -284,7 +283,7 @@ def main():
         mark_first_run_completed(target_dir)
 
     print(f"✅ Landing page generated successfully at:\n   file://{out_path}")
-    print(f"👉 You can re-open it anytime with: npx synapse-hub welcome")
+    print("👉 You can re-open it anytime with: npx synapse-hub welcome")
 
 
 if __name__ == "__main__":