synapse-hub 0.0.0-stage → 2.0.0

package/tools/lint_ai_docs.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""
+Enterprise AI Documentation & Artifact Linter (Anti-Drift Guard v2.0)
+---------------------------------------------------------------
+Automatically cross-references AI skills, agent instructions, and markdown
+documents against the actual repository files, classes, methods, and test cases.
+
+Checks:
+  1. Page Class references: Matches against Keywords/pages/*.groovy.
+  2. Test Suite references: Matches against Test Suites/*.ts.
+  3. Tool script references: Matches against tools/*.
+  4. Test Case references: Matches against Test Cases/*.tc (and validates TC-1..259 range).
+  5. Method call references: Matches EnterpriseHelper.xxx() and BasePage.xxx() against real AST/regex methods.
+
+Prevents AI agents from hallucinating nonexistent PageClasses, suites, tools, methods, or test cases.
+Supports both Target Test Project mode and Hub Repository mode.
+"""
+
+import os
+import sys
+import glob
+import re
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+GENERIC_PAGES = {
+    "WebPage", "CurrentPage", "LandingPage", "GitHubPage", "SamplePage",
+    "BasePage", "Page", "SinglePage", "MultiPage"
+}
+
+def extract_groovy_methods(file_path):
+    """Extracts standard public/static methods from a Groovy class file."""
+    methods = set()
+    if not os.path.exists(file_path):
+        return methods
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="ignore") as fp:
+            lines = fp.readlines()
+        method_pattern = re.compile(
+            r'^\s*(?:@\w+\s+)*(?:public|protected|private)?\s*(?:static\s+)?(?:final\s+)?'
+            r'(?:void|def|String|int|boolean|List[^\s]*|TestObject|WebDriver|[A-Za-z0-9_<>\[\]]+)\s+([a-z][a-zA-Z0-9_]*)\s*\('
+        )
+        for line in lines:
+            stripped = line.strip()
+            if stripped.startswith("//") or stripped.startswith("*"):
+                continue
+            m = method_pattern.search(line)
+            if m:
+                mname = m.group(1)
+                if mname not in {"if", "for", "while", "switch", "catch"}:
+                    methods.add(mname)
+    except Exception:
+        pass
+    return methods
+
+def get_actual_entities(repo_root):
+    pages_dir = os.path.join(repo_root, "Keywords", "pages")
+    helpers_dir = os.path.join(repo_root, "Keywords", "helpers")
+    suites_dir = os.path.join(repo_root, "Test Suites")
+    cases_dir = os.path.join(repo_root, "Test Cases")
+    tools_dir = os.path.join(repo_root, "tools")
+
+    actual_pages = set()
+    class_methods = {}
+
+    if os.path.isdir(pages_dir):
+        for f in os.listdir(pages_dir):
+            if f.endswith(".groovy"):
+                pname = f[:-7]
+                actual_pages.add(pname)
+                class_methods[pname] = extract_groovy_methods(os.path.join(pages_dir, f))
+
+    if os.path.isdir(helpers_dir):
+        for f in os.listdir(helpers_dir):
+            if f.endswith(".groovy"):
+                hname = f[:-7]
+                class_methods[hname] = extract_groovy_methods(os.path.join(helpers_dir, f))
+
+    actual_suites = set()
+    if os.path.isdir(suites_dir):
+        for f in os.listdir(suites_dir):
+            if f.endswith(".ts"):
+                actual_suites.add(f[:-3])
+
+    actual_cases = set()
+    actual_tc_ids = set()
+    if os.path.isdir(cases_dir):
+        for f in os.listdir(cases_dir):
+            if f.endswith(".tc"):
+                base_name = f[:-3]
+                actual_cases.add(base_name)
+                m = re.match(r'(TC-\d+)', base_name)
+                if m:
+                    actual_tc_ids.add(m.group(1))
+
+    actual_tools = set()
+    if os.path.isdir(tools_dir):
+        actual_tools.update(os.listdir(tools_dir))
+    # Always include Hub tools directory in decoupled architecture
+    hub_tools = os.path.abspath(os.path.dirname(__file__))
+    if os.path.isdir(hub_tools):
+        actual_tools.update(os.listdir(hub_tools))
+
+    return actual_pages, actual_suites, actual_cases, actual_tc_ids, actual_tools, class_methods
+
+def find_doc_files(repo_root):
+    md_patterns = [
+        os.path.join(repo_root, ".agents", "**", "*.md"),
+        os.path.join(repo_root, "*.md"),
+    ]
+    doc_files = []
+    for pattern in md_patterns:
+        for f in glob.glob(pattern, recursive=True):
+            rel = os.path.relpath(f, repo_root)
+            if "node_modules" in rel or ".git" in rel or "allure-results" in rel:
+                continue
+            doc_files.append(rel)
+    return sorted(doc_files)
+
+def lint_docs(repo_root):
+    actual_pages, actual_suites, actual_cases, actual_tc_ids, actual_tools, class_methods = get_actual_entities(repo_root)
+    doc_files = find_doc_files(repo_root)
+
+    page_pattern = re.compile(r'\b([A-Z][A-Za-z0-9]+Page)\b')
+    suite_pattern = re.compile(r'(?:Test Suites/|-Suite\s+["\'](?:Test Suites/)?|--testSuitePath=["\'](?:Test Suites/)?)([A-Za-z0-9_]+)')
+    tool_pattern = re.compile(r'\btools/([a-zA-Z0-9_\-\.]+\.(?:py|sh|ps1|bat|js))\b')
+    tc_id_pattern = re.compile(r'\b(TC-\d+)\b')
+    tc_path_pattern = re.compile(r'Test Cases/([A-Za-z0-9_ \-\.\(\)]+?)(?:\.tc)?["\s\)]')
+    method_pattern = re.compile(r'\b(EnterpriseHelper|BasePage|[A-Z][a-zA-Z0-9]+Page)\.([a-z][a-zA-Z0-9_]+)\s*\(')
+
+    errors = []
+    warnings = []
+
+    # Ignored tool references (examples, output targets, artifacts)
+    ignored_tool_refs = {"api_matrix.json", "output.json", "report.json", "output.txt", "summary.json"}
+
+    for doc in doc_files:
+        full_path = os.path.join(repo_root, doc)
+        try:
+            with open(full_path, "r", encoding="utf-8", errors="ignore") as fp:
+                lines = fp.readlines()
+        except Exception as e:
+            errors.append(f"Cannot read {doc}: {e}")
+            continue
+
+        is_historical = "FINAL_REPORT.md" in doc or "POM_REFACTORING_PLAN.md" in doc
+
+        for line_no, line in enumerate(lines, 1):
+            # 1. Page Class Lint (Only strictly enforced if repository defines Page Classes in Keywords/pages)
+            if actual_pages:
+                for m in page_pattern.finditer(line):
+                    pname = m.group(1)
+                    if pname not in actual_pages and pname not in GENERIC_PAGES:
+                        if is_historical:
+                            continue
+                        errors.append(f"[{doc}:{line_no}] Non-existent Page Class referenced: '{pname}' (Must be one of {sorted(actual_pages)})")
+
+            # 2. Test Suite Lint (Only strictly enforced if repository defines Test Suites)
+            if actual_suites:
+                for m in suite_pattern.finditer(line):
+                    sname = m.group(1)
+                    if "xxx" in sname.lower() or "example" in sname.lower():
+                        continue
+                    if is_historical:
+                        continue
+                    if sname not in actual_suites:
+                        errors.append(f"[{doc}:{line_no}] Non-existent Test Suite referenced: '{sname}'")
+
+            # 3. Tool Script Lint (Enforced in both Hub and Target modes)
+            for m in tool_pattern.finditer(line):
+                tname = m.group(1)
+                if tname in ignored_tool_refs:
+                    continue
+                if tname not in actual_tools:
+                    errors.append(f"[{doc}:{line_no}] Non-existent tool script referenced: 'tools/{tname}'")
+
+            # 4. Test Case Validation (Only strictly enforced if repository defines Test Cases)
+            if actual_cases and not is_historical:
+                # 4a. Validate TC-xxx numeric range
+                for m in tc_id_pattern.finditer(line):
+                    tcid = m.group(1)
+                    num = int(tcid[3:])
+                    if num < 1 or num > 259:
+                        errors.append(f"[{doc}:{line_no}] Out-of-range Test Case ID referenced: '{tcid}' (Valid range: TC-1 to TC-259)")
+
+                # 4b. Validate full Test Cases/... paths
+                for m in tc_path_pattern.finditer(line):
+                    tcname = m.group(1).strip()
+                    if "xxx" in tcname.lower() or "*" in tcname or "example" in tcname.lower():
+                        continue
+                    if tcname.endswith(".tc"):
+                        tcname = tcname[:-3]
+                    if tcname not in actual_cases:
+                        # Check prefix match
+                        matching = [c for c in actual_cases if c.startswith(tcname)]
+                        if not matching:
+                            errors.append(f"[{doc}:{line_no}] Non-existent Test Case path referenced: 'Test Cases/{tcname}'")
+
+            # 5. Method Call Lint (Cross-checks Class.method() against Groovy AST/regex)
+            for m in method_pattern.finditer(line):
+                cname = m.group(1)
+                mname = m.group(2)
+                if "xxx" in mname.lower() or "example" in mname.lower():
+                    continue
+                if cname in class_methods:
+                    valid_methods = class_methods[cname]
+                    # Also include inherited BasePage methods if it's a Page class
+                    if cname != "BasePage" and "BasePage" in class_methods:
+                        valid_methods = valid_methods.union(class_methods["BasePage"])
+
+                    if mname not in valid_methods:
+                        errors.append(f"[{doc}:{line_no}] Non-existent method referenced: '{cname}.{mname}()' (Class '{cname}' does not define this method)")
+
+    return errors, warnings
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="Enterprise AI Documentation & Artifact Linter")
+    parser.add_argument("target", nargs="?", default=None, help="Path to repository root to lint")
+    parser.add_argument("--repo", default=None, help="Path to repository root to lint")
+    args = parser.parse_args()
+
+    target_path = args.repo or args.target
+    if target_path:
+        repo_root = os.path.abspath(target_path)
+    else:
+        repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+
+    print(f"[AI-DOCS-LINT] Running Documentation & Artifact Linter on: {os.path.basename(repo_root)}")
+    errors, warnings = lint_docs(repo_root)
+
+    if warnings:
+        print(f"\n[WARN] {len(warnings)} Warnings:")
+        for w in warnings:
+            print(f"   - {w}")
+
+    if errors:
+        print(f"\n[FAIL] {len(errors)} Lint Errors Found (Documentation Drift / Hallucination):")
+        for e in errors:
+            print(f"   - {e}")
+        print("\n[BLOCKED] Verification failed: Please align documentation with real disk entities.")
+        return 1
+    else:
+        print("[PASS] All documented tools, PageClasses, Suites, and Method calls verified on disk.")
+        return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/lookup_tc.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""
+Enterprise QA: Fast Test Case Metadata Lookup (lookup_tc.py)
+-------------------------------------------------------------
+Fast lookup tool for Test Cases from project JSON testcase specifications.
+Enables AI Agents to load a single targeted test case (<100 tokens)
+instead of reading entire massive test suites (~45,000 tokens).
+
+Multi-tier Resolution:
+  1. CLI Flag: python tools/lookup_tc.py <query> --file <path_to_json> (-f)
+  2. Environment variable: TC_DATA_FILE or TESTCASES_JSON
+  3. Automatic discovery: testcases.json, tc_index.json, test_cases.json...
+  4. Internal Hub archive fallback: archive/legacy_references/Enterprise_testcases.json
+"""
+
+import sys
+import json
+import os
+import argparse
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+
+def resolve_json_path(cli_file=None):
+    """Resolves Test Case JSON file path via precedence order."""
+    # 1. CLI flag
+    if cli_file:
+        if os.path.exists(cli_file):
+            return os.path.abspath(cli_file)
+        else:
+            print(f"⚠️  Warning: File specified via --file '{cli_file}' does not exist.")
+
+    # 2. Environment variable
+    env_file = os.environ.get("TC_DATA_FILE") or os.environ.get("TESTCASES_JSON")
+    if env_file and os.path.exists(env_file):
+        return os.path.abspath(env_file)
+
+    # 3. Automatic discovery in CWD and common directories
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    hub_root = os.path.abspath(os.path.join(script_dir, ".."))
+    cwd = os.getcwd()
+
+    search_dirs = [
+        cwd,
+        os.path.join(cwd, "references"),
+        os.path.join(cwd, "data"),
+        os.path.join(cwd, "tools"),
+        os.path.join(cwd, "docs"),
+        script_dir
+    ]
+
+    candidate_names = [
+        "testcases.json",
+        "tc_index.json",
+        "Enterprise_testcases.json",
+        "test_cases.json",
+        "tc_matrix.json"
+    ]
+
+    for d in search_dirs:
+        for name in candidate_names:
+            candidate = os.path.join(d, name)
+            if os.path.isfile(candidate):
+                return os.path.abspath(candidate)
+
+    # 4. Hub Archive fallback
+    for legacy_name in ["Enterprise_testcases.json", "dmit_testcases.json", "odp_testcases.json"]:
+        legacy_file = os.path.join(hub_root, "archive", "legacy_references", legacy_name)
+        if os.path.isfile(legacy_file):
+            return os.path.abspath(legacy_file)
+
+    return None
+
+
+def normalize_testcase_data(raw_data):
+    """Normalizes Test Case data across diverse JSON structures (list, dict, dict of dicts)."""
+    if isinstance(raw_data, list):
+        return raw_data
+    elif isinstance(raw_data, dict):
+        if "testcases" in raw_data and isinstance(raw_data["testcases"], list):
+            return raw_data["testcases"]
+        if "items" in raw_data and isinstance(raw_data["items"], list):
+            return raw_data["items"]
+        
+        flat = []
+        for k, v in raw_data.items():
+            if isinstance(v, dict):
+                item = dict(v)
+                if "ID" not in item:
+                    item["ID"] = k
+                flat.append(item)
+            else:
+                flat.append({"ID": k, "Name": str(v)})
+        return flat
+    return []
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Fast Test Case lookup from project JSON specifications")
+    parser.add_argument("query", help="Test Case ID (e.g., TC-132, 132) or search keyword")
+    parser.add_argument("-f", "--file", dest="file", help="Path to JSON file containing test cases")
+    args = parser.parse_args()
+
+    json_path = resolve_json_path(args.file)
+
+    if not json_path:
+        print("❌ Error: Test Case JSON data file not found.")
+        print("\n👉 Guidance to configure test case data for target project:")
+        print("  1. Use CLI flag: python tools/lookup_tc.py <query> --file <path_to_testcases.json>")
+        print("  2. Set environment variable: export TC_DATA_FILE='path/to/testcases.json' (or set TC_DATA_FILE=...)")
+        print("  3. Place 'testcases.json' in project root or declare path in PROJECT_AI_GUIDE.md")
+        sys.exit(1)
+
+    try:
+        with open(json_path, "r", encoding="utf-8") as f:
+            raw_data = json.load(f)
+    except Exception as e:
+        print(f"❌ Error reading file '{json_path}': {e}")
+        sys.exit(1)
+
+    data = normalize_testcase_data(raw_data)
+    query = args.query.strip().lower()
+
+    exact_matches = []
+    fuzzy_matches = []
+
+    for tc in data:
+        tc_id = str(tc.get("ID") or tc.get("id") or tc.get("tc_id") or "").strip().lower()
+        tc_name = str(tc.get("Name") or tc.get("name") or tc.get("title") or "").strip().lower()
+
+        if query == tc_id or f"tc-{query}" == tc_id or f"tc_{query}" == tc_id:
+            exact_matches.append(tc)
+        elif query in tc_id or query in tc_name:
+            fuzzy_matches.append(tc)
+
+    matches = exact_matches if exact_matches else fuzzy_matches
+
+    if not matches:
+        print(f"No Test Cases found matching: '{args.query}' in file '{os.path.basename(json_path)}'")
+        sys.exit(0)
+
+    rel_source = os.path.relpath(json_path, os.getcwd()) if os.path.exists(json_path) else json_path
+    print(f"=== Found {len(matches)} Test Case(s) (Source: {rel_source}) ===")
+    for tc in matches[:5]:
+        tc_id = tc.get("ID") or tc.get("id") or "N/A"
+        tc_mod = tc.get("Module") or tc.get("module") or "GLOBAL"
+        tc_name = tc.get("Name") or tc.get("name") or tc.get("title") or "N/A"
+        tc_expected = tc.get("Expected") or tc.get("expected") or tc.get("expected_result") or "N/A"
+        tc_steps = tc.get("Steps") or tc.get("steps") or tc.get("description") or "N/A"
+
+        print(f"ID: {tc_id} | Module: {tc_mod}")
+        print(f"Name: {tc_name}")
+        print(f"Expected: {tc_expected}")
+        print(f"Steps:\n{tc_steps}")
+        print("-" * 50)
+
+
+if __name__ == "__main__":
+    main()

package/tools/lookup_xpath.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""
+Enterprise QA: Fast XPath / Selector Lookup (lookup_xpath.py)
+-------------------------------------------------------------
+Fast lookup tool for XPaths and selectors from Page Class JSON specifications.
+Enables AI Agents to retrieve only the relevant selectors (<300 tokens)
+instead of reading entire selector repositories or rescanning live DOM.
+
+Multi-tier Resolution:
+  1. CLI Flag: python tools/lookup_xpath.py <query> --file <path_to_json> (-f)
+  2. Environment variable: XPATH_DATA_FILE, SELECTORS_JSON, or LOCATORS_JSON
+  3. Automatic discovery: selectors.json, locators.json, scraped_xpaths.json...
+  4. Internal Hub archive fallback: archive/legacy_references/Enterprise_scraped_xpaths.json
+"""
+
+import sys
+import json
+import os
+import argparse
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+
+def resolve_json_path(cli_file=None):
+    """Resolves Selector/XPath JSON file path via precedence order."""
+    # 1. CLI flag
+    if cli_file:
+        if os.path.exists(cli_file):
+            return os.path.abspath(cli_file)
+        else:
+            print(f"⚠️  Warning: File specified via --file '{cli_file}' does not exist.")
+
+    # 2. Environment variable
+    env_file = os.environ.get("XPATH_DATA_FILE") or os.environ.get("SELECTORS_JSON") or os.environ.get("LOCATORS_JSON")
+    if env_file and os.path.exists(env_file):
+        return os.path.abspath(env_file)
+
+    # 3. Automatic discovery in CWD and common directories
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    hub_root = os.path.abspath(os.path.join(script_dir, ".."))
+    cwd = os.getcwd()
+
+    search_dirs = [
+        cwd,
+        os.path.join(cwd, "references"),
+        os.path.join(cwd, "data"),
+        os.path.join(cwd, "tools"),
+        os.path.join(cwd, "docs"),
+        script_dir
+    ]
+
+    candidate_names = [
+        "selectors.json",
+        "scraped_xpaths.json",
+        "locators.json",
+        "Enterprise_scraped_xpaths.json",
+        "page_selectors.json",
+        "elements.json"
+    ]
+
+    for d in search_dirs:
+        for name in candidate_names:
+            candidate = os.path.join(d, name)
+            if os.path.isfile(candidate):
+                return os.path.abspath(candidate)
+
+    # 4. Hub Archive fallback
+    for legacy_name in ["Enterprise_scraped_xpaths.json", "dmit_scraped_xpaths.json", "batch01_scraped_xpaths.json"]:
+        legacy_file = os.path.join(hub_root, "archive", "legacy_references", legacy_name)
+        if os.path.isfile(legacy_file):
+            return os.path.abspath(legacy_file)
+
+    return None
+
+
+def normalize_selector_data(raw_data):
+    """Normalizes Selector data across PageClass dictionary or flat list schemas."""
+    if isinstance(raw_data, dict):
+        return raw_data
+    elif isinstance(raw_data, list):
+        grouped = {}
+        for item in raw_data:
+            page = item.get("page") or item.get("page_class") or "GLOBAL"
+            if page not in grouped:
+                grouped[page] = []
+            grouped[page].append(item)
+        return grouped
+    return {}
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Fast Selector / XPath lookup from project JSON specifications")
+    parser.add_argument("query", help="PageClass name or selector identifier keyword (e.g., TargetPlanPage, TXT_CODE)")
+    parser.add_argument("-f", "--file", dest="file", help="Path to JSON file containing selector/xpaths")
+    args = parser.parse_args()
+
+    json_path = resolve_json_path(args.file)
+
+    if not json_path:
+        print("❌ Error: Selector / XPath JSON data file not found.")
+        print("\n👉 Guidance to configure selector data for target project:")
+        print("  1. Use CLI flag: python tools/lookup_xpath.py <query> --file <path_to_selectors.json>")
+        print("  2. Set environment variable: export XPATH_DATA_FILE='path/to/selectors.json' (or set XPATH_DATA_FILE=...)")
+        print("  3. Place 'selectors.json' in project root or declare path in PROJECT_AI_GUIDE.md")
+        sys.exit(1)
+
+    try:
+        with open(json_path, "r", encoding="utf-8") as f:
+            raw_data = json.load(f)
+    except Exception as e:
+        print(f"❌ Error reading file '{json_path}': {e}")
+        sys.exit(1)
+
+    data = normalize_selector_data(raw_data)
+    query = args.query.strip()
+
+    # 1. Match by Page Class name
+    matched_page = None
+    for page_name in data.keys():
+        if query.lower() == page_name.lower():
+            matched_page = page_name
+            break
+
+    if matched_page:
+        selectors = data[matched_page]
+        source_label = os.path.relpath(json_path, os.getcwd()) if os.path.exists(json_path) else json_path
+        print(f"=== {matched_page} ({len(selectors)} selectors) [Source: {source_label}] ===")
+        for item in selectors:
+            c = item.get("constant") or item.get("name") or "SELECTOR"
+            tag = item.get("tag") or "element"
+            xp = item.get("xpath") or item.get("selector") or item.get("css") or ""
+            print(f"- {c} ({tag}): {xp}")
+        return
+
+    # 2. Match keyword across constant or xpath
+    found = []
+    for page_name, selectors in data.items():
+        if isinstance(selectors, list):
+            for item in selectors:
+                c = item.get("constant") or item.get("name") or ""
+                xp = item.get("xpath") or item.get("selector") or item.get("css") or ""
+                tag = item.get("tag") or "element"
+                if query.lower() in c.lower() or query.lower() in xp.lower():
+                    found.append((page_name, c, tag, xp))
+        elif isinstance(selectors, dict):
+            for c, xp in selectors.items():
+                if query.lower() in c.lower() or query.lower() in str(xp).lower():
+                    found.append((page_name, c, "element", str(xp)))
+
+    if not found:
+        print(f"No selectors found matching: '{query}' in file '{os.path.basename(json_path)}'")
+        return
+
+    source_label = os.path.relpath(json_path, os.getcwd()) if os.path.exists(json_path) else json_path
+    print(f"=== Found {len(found)} selector(s) for query '{query}' [Source: {source_label}] ===")
+    for page, c, tag, xp in found[:15]:
+        print(f"[{page}] {c} ({tag}): {xp}")
+
+
+if __name__ == "__main__":
+    main()