@teevee98/synapse-hub 4.1.4 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (116) hide show
  1. package/.agents/rules/git-push-protocol.md +2 -2
  2. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +6 -1
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +6 -1
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +8 -3
  5. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +6 -1
  6. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +6 -1
  7. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +6 -1
  8. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +6 -1
  9. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  10. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  11. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  12. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +7 -2
  13. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +6 -1
  14. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +6 -1
  15. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +6 -1
  16. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +6 -1
  17. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +6 -1
  18. package/.agents/skills/02-test-design/review-spec/SKILL.md +4 -1
  19. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +6 -1
  20. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +6 -1
  21. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +6 -1
  22. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +7 -2
  23. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +7 -2
  24. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +4 -1
  25. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +6 -1
  26. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +6 -1
  27. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +6 -1
  28. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +6 -1
  29. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +6 -1
  30. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +6 -1
  31. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +7 -2
  32. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +6 -1
  33. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +6 -1
  34. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +6 -1
  35. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +6 -1
  36. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +6 -1
  37. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +6 -1
  38. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +6 -1
  39. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +6 -1
  40. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +6 -1
  41. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +6 -1
  42. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +6 -1
  43. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +6 -1
  44. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +4 -1
  45. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +4 -1
  46. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +6 -1
  47. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +4 -1
  48. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +6 -1
  49. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +6 -1
  50. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +6 -1
  51. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +6 -1
  52. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +6 -1
  53. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +6 -1
  54. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +6 -1
  55. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +6 -1
  56. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +6 -1
  57. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +6 -1
  58. package/AGENTS.md +7 -1
  59. package/LICENSE +5 -5
  60. package/NOTICE +1 -1
  61. package/README.en.md +4 -4
  62. package/README.md +4 -4
  63. package/agentskills.json +1 -1
  64. package/docs/ARCHITECTURE.en.md +2 -2
  65. package/docs/ARCHITECTURE.md +11 -2
  66. package/docs/CLI_REFERENCE.en.md +6 -4
  67. package/docs/CLI_REFERENCE.md +1 -1
  68. package/docs/CONTRIBUTING.en.md +1 -1
  69. package/docs/CONTRIBUTING.md +2 -2
  70. package/docs/TOOL_CATALOG.md +6 -2
  71. package/docs/research/agent_skill_training_analysis.md +1 -1
  72. package/package.json +1 -1
  73. package/plugin.json +1 -1
  74. package/skills_manifest.json +320 -55
  75. package/synapse.config.json +1 -1
  76. package/templates/ui/index.html +2 -2
  77. package/tools/TOOL_CATALOG.json +63 -3
  78. package/tools/__init__.py +1 -1
  79. package/tools/api_fuzzer.py +179 -118
  80. package/tools/author_integrity.py +121 -11
  81. package/tools/benchmark_swarm_context.py +119 -18
  82. package/tools/break_ui_generator.py +233 -0
  83. package/tools/browser_helpers.js +2 -2
  84. package/tools/check_version_sync.py +18 -50
  85. package/tools/cli.py +109 -18
  86. package/tools/core/bm25_retriever.py +218 -0
  87. package/tools/core/i18n.py +4 -4
  88. package/tools/core/provider_usage_adapter.py +317 -0
  89. package/tools/core/token_estimator.py +42 -14
  90. package/tools/count_tokens.py +5 -0
  91. package/tools/coverage_reporter.py +245 -0
  92. package/tools/dashboard_generator.py +6 -6
  93. package/tools/db_sandbox.py +146 -4
  94. package/tools/distill_skill.py +191 -0
  95. package/tools/git_pre_commit_guard.py +12 -0
  96. package/tools/humanize_linter.py +3 -0
  97. package/tools/mcp_docx_server.py +1 -1
  98. package/tools/mcp_excel_server.py +1 -1
  99. package/tools/mcp_server.py +75 -15
  100. package/tools/micro_mutator.py +84 -14
  101. package/tools/pentest_scope_guard.py +399 -56
  102. package/tools/perf/benchmark_perf_runner.py +42 -0
  103. package/tools/rules_router.py +401 -41
  104. package/tools/security_scanner.py +80 -0
  105. package/tools/senior_code_review.py +14 -0
  106. package/tools/skill_canonical_digest.py +244 -0
  107. package/tools/skill_profiles.py +77 -7
  108. package/tools/slide_deck_exporter.py +477 -0
  109. package/tools/sync_skills_manifest.py +166 -0
  110. package/tools/task_memory_manager.py +260 -0
  111. package/tools/ui_server.py +1 -1
  112. package/tools/update_sentinel.py +3 -3
  113. package/tools/validate_host_interop.py +485 -0
  114. package/tools/validate_skills_schema.py +282 -0
  115. package/tools/verify_all.py +572 -42
  116. package/tools/welcome_page.py +2 -2
@@ -13,7 +13,7 @@
13
13
  (function () {
14
14
  'use strict';
15
15
 
16
- if (window.__qa && window.__qa.__version === '4.1.4') {
16
+ if (window.__qa && window.__qa.__version === '4.2.0') {
17
17
  return window.__qa;
18
18
  }
19
19
 
@@ -47,7 +47,7 @@
47
47
  }
48
48
 
49
49
  const qa = {
50
- __version: '4.1.4',
50
+ __version: '4.2.0',
51
51
 
52
52
  /**
53
53
  * 1. Smart Action Batching
@@ -192,9 +192,15 @@ def extract_versions(repo_root: str) -> Dict[str, str]:
192
192
  return versions
193
193
 
194
194
 
195
+ from skill_canonical_digest import (
196
+ validate_lockfile_integrity,
197
+ update_skills_lockfile,
198
+ )
199
+
200
+
195
201
  def check_sync(repo_root: str, expected_version: Optional[str] = None) -> Tuple[bool, Dict[str, str], str]:
196
202
  """
197
- Checks if all version definitions match.
203
+ Checks if all version definitions match across manifests and verifies canonical skill lockfile integrity.
198
204
  Returns (is_synced, versions_dict, canonical_version_or_error_msg).
199
205
  """
200
206
  versions = extract_versions(repo_root)
@@ -216,65 +222,27 @@ def check_sync(repo_root: str, expected_version: Optional[str] = None) -> Tuple[
216
222
 
217
223
  if mismatches:
218
224
  return False, versions, target_ver
219
- return True, versions, target_ver
220
225
 
226
+ # Enforce canonical skills lockfile integrity (live content hash validation)
227
+ lock_ok, lock_msg = validate_lockfile_integrity(repo_root, enforce_content_hash=True)
228
+ if not lock_ok:
229
+ return False, versions, f"Lockfile integrity verification failed: {lock_msg}"
221
230
 
222
- def validate_lockfile_integrity(repo_root: str) -> Tuple[bool, str]:
223
- """
224
- Validates canonical lockfile (skills-lock.json), synchronizes .skill-lock.json,
225
- and verifies SHA-256 integrity hash for all registered skills.
226
- """
227
- canonical_lock = os.path.join(repo_root, "skills-lock.json")
228
- secondary_lock = os.path.join(repo_root, ".skill-lock.json")
229
-
230
- if not os.path.exists(canonical_lock):
231
- return False, "Canonical lockfile skills-lock.json is missing!"
232
-
233
- try:
234
- with open(canonical_lock, "r", encoding="utf-8") as f:
235
- lock_data = json.load(f)
236
- except Exception as e:
237
- return False, f"skills-lock.json malformed JSON: {e}"
238
-
239
- skills = lock_data.get("skills", {})
240
- if len(skills) != 53:
241
- return False, f"Expected 53 skills in skills-lock.json, found {len(skills)}"
242
-
243
- for s_name, s_meta in skills.items():
244
- s_path = s_meta.get("skillPath")
245
- if not s_path:
246
- return False, f"Skill '{s_name}' missing skillPath"
247
- full_path = os.path.join(repo_root, s_path)
248
- if not os.path.exists(full_path):
249
- return False, f"Skill '{s_name}' path not found: {s_path}"
250
- s_hash = s_meta.get("skillFolderHash")
251
- if not s_hash or len(s_hash) != 64 or not all(c in "0123456789abcdefABCDEF" for c in s_hash):
252
- return False, f"Skill '{s_name}' has invalid SHA-256 hash: {s_hash}"
253
-
254
- # Auto-sync secondary lockfile .skill-lock.json to maintain atomic parity
255
- try:
256
- with open(canonical_lock, "rb") as cf:
257
- content_bytes = cf.read()
258
- needs_write = True
259
- if os.path.exists(secondary_lock):
260
- with open(secondary_lock, "rb") as sf:
261
- if sf.read() == content_bytes:
262
- needs_write = False
263
- if needs_write:
264
- with open(secondary_lock, "wb") as sf:
265
- sf.write(content_bytes)
266
- except Exception as e:
267
- return False, f"Failed to sync .skill-lock.json: {e}"
268
-
269
- return True, "53/53 skills verified with valid paths & SHA-256 hashes (auto-synced .skill-lock.json)"
231
+ return True, versions, target_ver
270
232
 
271
233
 
272
234
  def main() -> int:
273
235
  parser = argparse.ArgumentParser(description="Verify universal version sync across Synapse Hub files")
274
236
  parser.add_argument("--expected-version", "-e", help="Expected version string (e.g. from git tag)", default=None)
275
237
  parser.add_argument("--repo-root", default=REPO_ROOT, help="Root directory of the repository")
238
+ parser.add_argument("--update-hashes", action="store_true", help="Recalculate and update canonical skill folder hashes in lockfiles")
276
239
  args = parser.parse_args()
277
240
 
241
+ if args.update_hashes:
242
+ ok, msg = update_skills_lockfile(args.repo_root)
243
+ print(f"[{'SUCCESS' if ok else 'FAIL'}] {msg}")
244
+ return 0 if ok else 1
245
+
278
246
  expected = args.expected_version
279
247
  if expected and expected.startswith("v"):
280
248
  expected = expected[1:]
package/tools/cli.py CHANGED
@@ -16,7 +16,7 @@ import json
16
16
  import re
17
17
  import difflib
18
18
  import argparse
19
- from typing import Optional
19
+ from typing import Any, Optional
20
20
 
21
21
  # Enforce UTF-8 stdout encoding for Windows console compatibility
22
22
  if hasattr(sys.stdout, 'reconfigure'):
@@ -96,27 +96,55 @@ def cmd_set_lang(args):
96
96
  sys.exit(0)
97
97
 
98
98
 
99
+ def _resolve_manifest_path(repo_root: Optional[str] = None) -> Optional[str]:
100
+ """
101
+ Fallback manifest resolution:
102
+ 1. REPO_ROOT/skills_manifest.json
103
+ 2. tools/skills_manifest.json
104
+ 3. importlib.resources.files("tools").joinpath("skills_manifest.json")
105
+ """
106
+ root = repo_root or REPO_ROOT
107
+ candidate1 = os.path.join(root, "skills_manifest.json")
108
+ if os.path.isfile(candidate1):
109
+ return candidate1
110
+ candidate2 = os.path.join(SCRIPT_DIR, "skills_manifest.json")
111
+ if os.path.isfile(candidate2):
112
+ return candidate2
113
+ candidate2_alt = os.path.join(root, "tools", "skills_manifest.json")
114
+ if os.path.isfile(candidate2_alt):
115
+ return candidate2_alt
116
+ try:
117
+ import importlib.resources as pkg_resources
118
+ resource = pkg_resources.files("tools").joinpath("skills_manifest.json")
119
+ if resource.is_file():
120
+ try:
121
+ r_str = str(resource)
122
+ if os.path.isfile(r_str):
123
+ return r_str
124
+ except (TypeError, ValueError) as str_err:
125
+ res_str_err = str(str_err)
126
+ with pkg_resources.as_file(resource) as p:
127
+ return str(p)
128
+ except (ImportError, AttributeError, TypeError) as res_err:
129
+ res_load_err = str(res_err)
130
+ return None
131
+
132
+
99
133
  def cmd_version(args):
100
134
  """Displays the current hub version, skill catalog count, and license information."""
101
- manifest_path = os.path.join(REPO_ROOT, "skills_manifest.json")
102
- version = "4.1.4"
103
- if os.path.exists(manifest_path):
135
+ manifest_path = _resolve_manifest_path()
136
+ version = "4.2.0"
137
+ manifest_skills = 53
138
+ if manifest_path and os.path.exists(manifest_path):
104
139
  try:
105
140
  import json
106
141
  with open(manifest_path, "r", encoding="utf-8") as f:
107
142
  data = json.load(f)
108
143
  version = data.get("version", version)
109
- except (OSError, json.JSONDecodeError):
110
- data = {}
144
+ manifest_skills = data.get("totalSkills", manifest_skills)
145
+ except (OSError, json.JSONDecodeError) as json_err:
146
+ manifest_err = str(json_err)
111
147
  print(f"Agent-QA Hub CLI v{version}")
112
- manifest_skills = 42
113
- if os.path.exists(manifest_path):
114
- try:
115
- import json
116
- with open(manifest_path, "r", encoding="utf-8") as f:
117
- manifest_skills = json.load(f).get("totalSkills", 42)
118
- except (OSError, json.JSONDecodeError):
119
- manifest_skills = 42
120
148
  print(f"Catalog: {manifest_skills} Standardized Skills | 9 Subagent Swarm Profiles")
121
149
  print("Created by: Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>")
122
150
  print("License : MIT (Attribution Required)")
@@ -485,9 +513,70 @@ def cmd_init_config(args):
485
513
  sys.exit(init_cfg_main())
486
514
 
487
515
 
516
+ def get_registered_commands(parser: Optional[argparse.ArgumentParser] = None, lang: str = "en") -> list[dict[str, Any]]:
517
+ """
518
+ Dynamically introspects the CLI parser subparsers action and extracts
519
+ all registered commands, aliases, and localized descriptions directly from the registry.
520
+ """
521
+ if parser is None:
522
+ parser = build_parser(lang)
523
+
524
+ subparsers_action = None
525
+ for action in parser._actions:
526
+ if isinstance(action, argparse._SubParsersAction):
527
+ subparsers_action = action
528
+ break
529
+
530
+ if not subparsers_action:
531
+ return []
532
+
533
+ help_map = {a.dest: a.help for a in getattr(subparsers_action, "_choices_actions", [])}
534
+
535
+ commands = []
536
+ seen_parsers = set()
537
+ for name, subp in subparsers_action.choices.items():
538
+ if id(subp) in seen_parsers:
539
+ continue
540
+ seen_parsers.add(id(subp))
541
+ aliases = [n for n, s in subparsers_action.choices.items() if s is subp and n != name]
542
+ help_text = help_map.get(name) or getattr(subp, "description", None) or getattr(subp, "help", "") or ""
543
+ commands.append({
544
+ "name": name,
545
+ "aliases": aliases,
546
+ "help": help_text,
547
+ "prog": getattr(subp, "prog", f"agent-qa {name}"),
548
+ })
549
+ commands.sort(key=lambda c: c["name"])
550
+ return commands
551
+
552
+
488
553
  def cmd_help(args):
489
554
  """Displays command-line help and usage documentation."""
490
555
  parser = getattr(args, "_parser", None)
556
+ if not parser:
557
+ lang = getattr(args, "lang", None) or resolve_language(_extract_cli_lang())
558
+ parser = build_parser(lang)
559
+
560
+ lang = getattr(parser, "lang", "en")
561
+
562
+ if getattr(args, "json_output", False):
563
+ commands = get_registered_commands(parser, lang)
564
+ print(json.dumps(commands, indent=2, ensure_ascii=False))
565
+ sys.exit(0)
566
+
567
+ if getattr(args, "md_output", False):
568
+ commands = get_registered_commands(parser, lang)
569
+ lines = [
570
+ "| Command | Aliases | Description |",
571
+ "| :--- | :--- | :--- |",
572
+ ]
573
+ for cmd in commands:
574
+ aliases_str = ", ".join(f"`{a}`" for a in cmd["aliases"]) if cmd["aliases"] else "—"
575
+ desc = cmd["help"].replace("\n", " ").strip()
576
+ lines.append(f"| `{cmd['name']}` | {aliases_str} | {desc} |")
577
+ print("\n".join(lines))
578
+ sys.exit(0)
579
+
491
580
  if parser:
492
581
  parser.print_help()
493
582
  sys.exit(0)
@@ -685,15 +774,15 @@ def cmd_trend(args):
685
774
 
686
775
 
687
776
  def _hub_version():
688
- manifest_path = os.path.join(REPO_ROOT, "skills_manifest.json")
689
- version = "4.1.4"
690
- if os.path.exists(manifest_path):
777
+ manifest_path = _resolve_manifest_path()
778
+ version = "4.2.0"
779
+ if manifest_path and os.path.exists(manifest_path):
691
780
  try:
692
781
  import json
693
782
  with open(manifest_path, "r", encoding="utf-8") as f:
694
783
  version = json.load(f).get("version", version)
695
784
  except (OSError, json.JSONDecodeError):
696
- version = "4.1.4"
785
+ version = "4.2.0"
697
786
  return version
698
787
 
699
788
 
@@ -878,6 +967,8 @@ def _register_core_and_setup_commands(subparsers, lang: Optional[str] = None):
878
967
  # help
879
968
  p_help = subparsers.add_parser("help", help=t("cmd_help", lang=lang))
880
969
  p_help.add_argument("--all", "-a", action="store_true", dest="show_all", help=t("opt_all", lang=lang))
970
+ p_help.add_argument("--json", action="store_true", dest="json_output", help=_lh("Output complete registered command list as JSON", "Xuất toàn bộ danh sách lệnh đã đăng ký dưới dạng JSON", lang))
971
+ p_help.add_argument("--markdown", "--md", action="store_true", dest="md_output", help=_lh("Output complete registered command list as Markdown table", "Xuất toàn bộ danh sách lệnh đã đăng ký dưới dạng bảng Markdown", lang))
881
972
  p_help.set_defaults(func=cmd_help)
882
973
 
883
974
  # set-lang
@@ -0,0 +1,218 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
3
+ # SPDX-License-Identifier: MIT
4
+
5
+ # -*- coding: utf-8 -*-
6
+ """
7
+ tools/core/bm25_retriever.py — Zero-Dependency Pure Python BM25 Knowledge Retriever
8
+ Inspired by nextlevelbuilder/ui-ux-pro-max-skill core.py algorithm.
9
+ Enables instant sub-millisecond retrieval of guidelines, rules, and QA patterns
10
+ with zero external dependencies and guaranteed < 300 character truncation (95% token savings).
11
+ 100% UTF-8 No BOM.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import argparse
17
+ import json
18
+ import math
19
+ import os
20
+ import re
21
+ import sys
22
+ from collections import Counter
23
+ from typing import Any, Dict, List, Tuple
24
+
25
+ # Enforce UTF-8 stdout encoding
26
+ if hasattr(sys.stdout, "reconfigure"):
27
+ try:
28
+ sys.stdout.reconfigure(encoding="utf-8")
29
+ sys.stderr.reconfigure(encoding="utf-8")
30
+ except Exception:
31
+ pass
32
+
33
+ TRUNCATE_AT: int = 300
34
+
35
+ # Common English / QA stopwords
36
+ STOPWORDS: set[str] = {
37
+ "a", "an", "the", "and", "or", "in", "on", "at", "to", "for", "with",
38
+ "by", "of", "from", "is", "are", "was", "were", "be", "been", "being",
39
+ "have", "has", "had", "do", "does", "did", "this", "that", "these",
40
+ "those", "it", "its", "as", "if", "each", "which", "into", "than", "then"
41
+ }
42
+
43
+ # Domain acronyms & synonym expansion mapping
44
+ SYNONYMS: Dict[str, List[str]] = {
45
+ "pom": ["page", "object", "model", "locator"],
46
+ "a11y": ["accessibility", "wcag", "aria", "contrast"],
47
+ "perf": ["performance", "latency", "p95", "throughput", "jmeter", "k6"],
48
+ "sec": ["security", "credential", "sarif", "cwe", "vuln"],
49
+ "fsm": ["finite", "state", "machine", "stage", "lifecycle"],
50
+ "dod": ["definition", "done", "gate", "verify", "quality"],
51
+ "ast": ["abstract", "syntax", "tree", "mutation", "linter"],
52
+ }
53
+
54
+
55
+ def tokenize(text: str) -> List[str]:
56
+ """Tokenizes text into lowercase alphanumeric tokens, filtering stopwords."""
57
+ if not text:
58
+ return []
59
+ words = re.findall(r"[a-zA-Z0-9_]+", text.lower())
60
+ tokens: List[str] = []
61
+ for w in words:
62
+ if len(w) > 1 and w not in STOPWORDS:
63
+ tokens.append(w)
64
+ if w in SYNONYMS:
65
+ tokens.extend(SYNONYMS[w])
66
+ return tokens
67
+
68
+
69
+ class BM25Document:
70
+ """Represents an indexed document with precomputed tokens."""
71
+
72
+ def __init__(self, doc_id: str, title: str, content: str, source: str = ""):
73
+ self.doc_id = doc_id
74
+ self.title = title
75
+ self.content = content
76
+ self.source = source
77
+ self.tokens = tokenize(f"{title} {content}")
78
+ self.length = len(self.tokens)
79
+ self.term_freqs = Counter(self.tokens)
80
+
81
+ def snippet(self, max_len: int = TRUNCATE_AT) -> str:
82
+ """Returns a trimmed snippet bounded by max_len."""
83
+ cleaned = re.sub(r"\s+", " ", self.content).strip()
84
+ if len(cleaned) <= max_len:
85
+ return cleaned
86
+ return cleaned[:max_len].rstrip() + "..."
87
+
88
+
89
+ class BM25Index:
90
+ """
91
+ Rank BM25 search index using the Okapi BM25 formula:
92
+ IDF(q) = ln((N - n(q) + 0.5) / (n(q) + 0.5) + 1)
93
+ Score = sum(IDF(q) * (f(q, D) * (k1 + 1)) / (f(q, D) + k1 * (1 - b + b * (|D| / avgdl))))
94
+ """
95
+
96
+ def __init__(self, k1: float = 1.5, b: float = 0.75):
97
+ self.k1 = k1
98
+ self.b = b
99
+ self.documents: List[BM25Document] = []
100
+ self.doc_count: int = 0
101
+ self.avg_doc_len: float = 0.0
102
+ self.doc_freqs: Counter[str] = Counter()
103
+ self.idf_cache: Dict[str, float] = {}
104
+
105
+ def add_document(self, doc_id: str, title: str, content: str, source: str = "") -> None:
106
+ """Adds a single document to the index."""
107
+ doc = BM25Document(doc_id, title, content, source)
108
+ self.documents.append(doc)
109
+ self.doc_count = len(self.documents)
110
+
111
+ def build(self) -> None:
112
+ """Finalizes the index, computes average document length and IDF scores."""
113
+ self.doc_freqs.clear()
114
+ total_len = 0
115
+ for doc in self.documents:
116
+ total_len += doc.length
117
+ for token in set(doc.tokens):
118
+ self.doc_freqs[token] += 1
119
+
120
+ self.avg_doc_len = (total_len / self.doc_count) if self.doc_count > 0 else 0.0
121
+
122
+ # Precompute IDF
123
+ self.idf_cache.clear()
124
+ for token, df in self.doc_freqs.items():
125
+ # Robertson-Spärck Jones IDF formula with +1 smoothing
126
+ idf = math.log(((self.doc_count - df + 0.5) / (df + 0.5)) + 1.0)
127
+ self.idf_cache[token] = max(idf, 0.0)
128
+
129
+ def search(
130
+ self, query: str, top_k: int = 3, truncate_at: int = TRUNCATE_AT
131
+ ) -> List[Dict[str, Any]]:
132
+ """Searches documents matching the query and returns top_k ranked results."""
133
+ if not self.documents:
134
+ return []
135
+
136
+ query_tokens = tokenize(query)
137
+ if not query_tokens:
138
+ return []
139
+
140
+ scores: List[Tuple[float, BM25Document]] = []
141
+ for doc in self.documents:
142
+ if doc.length == 0:
143
+ continue
144
+ score = 0.0
145
+ doc_len_ratio = doc.length / self.avg_doc_len if self.avg_doc_len > 0 else 1.0
146
+ len_norm = 1.0 - self.b + self.b * doc_len_ratio
147
+
148
+ for q in query_tokens:
149
+ if q in doc.term_freqs:
150
+ freq = doc.term_freqs[q]
151
+ idf = self.idf_cache.get(q, 0.0)
152
+ numerator = freq * (self.k1 + 1.0)
153
+ denominator = freq + self.k1 * len_norm
154
+ score += idf * (numerator / denominator)
155
+
156
+ if score > 0.0:
157
+ scores.append((score, doc))
158
+
159
+ scores.sort(key=lambda x: x[0], reverse=True)
160
+
161
+ results: List[Dict[str, Any]] = []
162
+ for rank, (score, doc) in enumerate(scores[:top_k], start=1):
163
+ results.append({
164
+ "rank": rank,
165
+ "score": round(score, 4),
166
+ "doc_id": doc.doc_id,
167
+ "title": doc.title,
168
+ "snippet": doc.snippet(truncate_at),
169
+ "source": doc.source,
170
+ })
171
+ return results
172
+
173
+
174
+ def index_directory(dir_path: str, extensions: Tuple[str, ...] = (".md", ".txt")) -> BM25Index:
175
+ """Indexes all files with matching extensions under dir_path."""
176
+ index = BM25Index()
177
+ if not os.path.exists(dir_path):
178
+ return index
179
+
180
+ for root, _, files in os.walk(dir_path):
181
+ for f in files:
182
+ if any(f.endswith(ext) for ext in extensions):
183
+ full_path = os.path.join(root, f)
184
+ try:
185
+ with open(full_path, "r", encoding="utf-8", errors="replace") as fp:
186
+ content = fp.read()
187
+ rel_path = os.path.relpath(full_path, dir_path)
188
+ title = f.replace(".md", "").replace("_", " ").title()
189
+ index.add_document(doc_id=rel_path, title=title, content=content, source=full_path)
190
+ except OSError:
191
+ continue
192
+
193
+ index.build()
194
+ return index
195
+
196
+
197
+ def main() -> None:
198
+ parser = argparse.ArgumentParser(description="BM25 Knowledge Retriever for Synapse Hub")
199
+ parser.add_argument("--query", "-q", type=str, required=True, help="Search query string")
200
+ parser.add_argument("--dir", "-d", type=str, default=".agents/rules", help="Directory to search (default: .agents/rules)")
201
+ parser.add_argument("--top-k", "-k", type=int, default=3, help="Number of results to return (default: 3)")
202
+ parser.add_argument("--json", action="store_true", help="Output results in JSON format")
203
+ args = parser.parse_args()
204
+
205
+ index = index_directory(args.dir)
206
+ results = index.search(args.query, top_k=args.top_k)
207
+
208
+ if args.json:
209
+ print(json.dumps(results, indent=2, ensure_ascii=False))
210
+ else:
211
+ print(f"🔍 BM25 Search Results for: '{args.query}' in '{args.dir}' (Found: {len(results)})")
212
+ for res in results:
213
+ print(f"\n[#{res['rank']}] {res['title']} (Score: {res['score']}) -> {res['doc_id']}")
214
+ print(f" {res['snippet']}")
215
+
216
+
217
+ if __name__ == "__main__":
218
+ main()
@@ -26,13 +26,13 @@ MESSAGES: Dict[str, Dict[str, str]] = {
26
26
  "core_commands_title": "🌟 CORE & DAILY WORKFLOWS:",
27
27
  "advanced_highlights_title": "🎯 ADVANCED AI/QA CAPABILITIES:",
28
28
  "general_options_title": "GENERAL OPTIONS:",
29
- "opt_all": "Display all 58+ advanced and infrastructure commands",
29
+ "opt_all": "Display all registered advanced and infrastructure commands",
30
30
  "opt_version": "Show current version and author provenance",
31
31
  "opt_offline": "Force 100% offline air-gapped mode (zero network / LLM calls)",
32
32
  "opt_quiet": "Suppress banner, show only verdict and critical output",
33
33
  "opt_lang": "Set CLI interface language (en: English, vi: Vietnamese)",
34
34
  "tips_header": "💡 Quick Navigation Tips:",
35
- "tip_all": "👉 Run 'agent-qa --help --all' to inspect all 58+ commands.",
35
+ "tip_all": "👉 Run 'agent-qa --help --all' to inspect all registered commands.",
36
36
  "tip_cmd": "👉 Run 'agent-qa <command> --help' for detailed command options.",
37
37
  "tip_welcome": "👉 Run 'agent-qa welcome' to launch the interactive visual landing page.",
38
38
  "tip_lang_switch": "💡 Switch language: agent-qa --lang vi (Vietnamese) | agent-qa --lang en (English)",
@@ -122,13 +122,13 @@ MESSAGES: Dict[str, Dict[str, str]] = {
122
122
  "core_commands_title": "🌟 LỆNH CỐT LÕI & THƯỜNG DÙNG:",
123
123
  "advanced_highlights_title": "🎯 CÁC KHÁI NIỆM AI/QA NÂNG CAO TIÊU BIỂU:",
124
124
  "general_options_title": "TÙY CHỌN CHUNG:",
125
- "opt_all": "Hiển thị toàn bộ 58+ lệnh nâng cao & hạ tầng",
125
+ "opt_all": "Hiển thị toàn bộ các lệnh nâng cao & hạ tầng đã đăng ký",
126
126
  "opt_version": "Hiển thị phiên bản hiện tại và thông tin tác quyền MIT",
127
127
  "opt_offline": "Ép chế độ 100% offline air-gapped (zero network / LLM calls)",
128
128
  "opt_quiet": "Ẩn banner thông tin, chỉ xuất kết quả phán quyết quan trọng",
129
129
  "opt_lang": "Chọn ngôn ngữ hiển thị giao diện CLI (en: Tiếng Anh, vi: Tiếng Việt)",
130
130
  "tips_header": "💡 Mẹo Tra Cứu:",
131
- "tip_all": "👉 Chạy 'agent-qa --help --all' để xem toàn bộ 58+ lệnh.",
131
+ "tip_all": "👉 Chạy 'agent-qa --help --all' để xem toàn bộ các lệnh đã đăng ký.",
132
132
  "tip_cmd": "👉 Chạy 'agent-qa <lệnh> --help' để xem hướng dẫn chi tiết cho từng lệnh cụ thể.",
133
133
  "tip_welcome": "👉 Chạy 'agent-qa welcome' để mở giao diện Landing Page tương tác trực quan.",
134
134
  "tip_lang_switch": "💡 Chuyển đổi ngôn ngữ: agent-qa --lang vi (Tiếng Việt) | agent-qa --lang en (Tiếng Anh)",