@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
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env python3
2
- # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
3
3
  # SPDX-License-Identifier: MIT
4
- # Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
5
 
6
6
  """
7
7
  tools/author_integrity.py — Author Attribution & Repository Provenance Guard
@@ -17,7 +17,7 @@ Note on Legal Scope:
17
17
  for external legal SBOM scans or formal trademark/copyright enforcement.
18
18
 
19
19
  Checks:
20
- 1. LICENSE file exists with original copyright notice (Thế Vị @TeeVee998).
20
+ 1. LICENSE file exists with original copyright notice (Thế Vị @TeeVee98).
21
21
  2. package.json maintains the original author attribution.
22
22
  3. README.md retains the original creator and repository provenance.
23
23
  4. pyproject.toml preserves the author declaration.
@@ -65,6 +65,106 @@ def verify_author_fingerprint() -> bool:
65
65
  return computed == CANONICAL_AUTHOR_SIG or computed in CANONICAL_AUTHOR_SIGS
66
66
 
67
67
 
68
+ def _resolve_license_content(root: str, allow_global_metadata: bool = False) -> Tuple[Optional[str], Optional[str]]:
69
+ """
70
+ Locates LICENSE content and its origin path across repository root, tools/,
71
+ dist-info directories, or distribution metadata (importlib.metadata).
72
+ Returns (license_text, origin_description).
73
+ """
74
+ # 1. Direct LICENSE in root
75
+ license_path = os.path.join(root, "LICENSE")
76
+ if os.path.isfile(license_path):
77
+ try:
78
+ with open(license_path, "r", encoding="utf-8", errors="ignore") as f:
79
+ return f.read(), license_path
80
+ except Exception as e:
81
+ return None, f"Could not read LICENSE file: {e}"
82
+
83
+ # 2. Check dist-info directories specifically inside the given root
84
+ if os.path.isdir(root):
85
+ try:
86
+ for entry in os.listdir(root):
87
+ if entry.endswith(".dist-info") and ("synapse" in entry.lower()):
88
+ dist_info_dir = os.path.join(root, entry)
89
+ for sub in (
90
+ os.path.join("licenses", "LICENSE"),
91
+ "LICENSE",
92
+ "LICENSE.txt",
93
+ ):
94
+ lic_candidate = os.path.join(dist_info_dir, sub)
95
+ if os.path.isfile(lic_candidate):
96
+ try:
97
+ with open(lic_candidate, "r", encoding="utf-8", errors="ignore") as f:
98
+ return f.read(), lic_candidate
99
+ except (OSError, UnicodeDecodeError) as read_err:
100
+ lic_read_err = str(read_err)
101
+ continue
102
+ except OSError as list_err:
103
+ lic_list_err = str(list_err)
104
+
105
+ # 3. Check tools/LICENSE inside root
106
+ root_tools_lic = os.path.join(root, "tools", "LICENSE")
107
+ if os.path.isfile(root_tools_lic):
108
+ try:
109
+ with open(root_tools_lic, "r", encoding="utf-8", errors="ignore") as f:
110
+ return f.read(), root_tools_lic
111
+ except (OSError, UnicodeDecodeError) as tools_err:
112
+ lic_tools_err = str(tools_err)
113
+
114
+ # 4. Only if allowed (running in installed runtime / default root), check global metadata and SCRIPT_DIR
115
+ if allow_global_metadata:
116
+ tools_lic = os.path.join(SCRIPT_DIR, "LICENSE")
117
+ if os.path.isfile(tools_lic):
118
+ try:
119
+ with open(tools_lic, "r", encoding="utf-8", errors="ignore") as f:
120
+ return f.read(), tools_lic
121
+ except (OSError, UnicodeDecodeError) as s_err:
122
+ lic_s_err = str(s_err)
123
+
124
+ try:
125
+ import importlib.metadata as meta
126
+ for pkg in ("synapse-hub", "synapse_hub"):
127
+ try:
128
+ pkg_files = meta.files(pkg)
129
+ if pkg_files:
130
+ for pf in pkg_files:
131
+ p_str = str(pf).replace("\\", "/")
132
+ if p_str.endswith("LICENSE") or "licenses/LICENSE" in p_str:
133
+ try:
134
+ return pf.read_text(encoding="utf-8"), f"metadata:{p_str}"
135
+ except (OSError, UnicodeDecodeError) as meta_read_err:
136
+ lic_meta_err = str(meta_read_err)
137
+ continue
138
+ except meta.PackageNotFoundError:
139
+ continue
140
+ except Exception as meta_err:
141
+ lic_import_err = str(meta_err)
142
+
143
+ parent_script = os.path.dirname(SCRIPT_DIR)
144
+ if os.path.isdir(parent_script) and parent_script != root:
145
+ try:
146
+ for entry in os.listdir(parent_script):
147
+ if entry.endswith(".dist-info") and ("synapse" in entry.lower()):
148
+ dist_info_dir = os.path.join(parent_script, entry)
149
+ for sub in (
150
+ os.path.join("licenses", "LICENSE"),
151
+ "LICENSE",
152
+ "LICENSE.txt",
153
+ ):
154
+ lic_candidate = os.path.join(dist_info_dir, sub)
155
+ if os.path.isfile(lic_candidate):
156
+ try:
157
+ with open(lic_candidate, "r", encoding="utf-8", errors="ignore") as f:
158
+ return f.read(), lic_candidate
159
+ except (OSError, UnicodeDecodeError) as p_err:
160
+ lic_p_err = str(p_err)
161
+ continue
162
+ except OSError as p_list_err:
163
+ lic_p_list_err = str(p_list_err)
164
+
165
+ return None, None
166
+
167
+
68
168
  def assert_integrity_or_raise(repo_root: Optional[str] = None) -> bool:
69
169
  """
70
170
  Enforces author attribution and MIT License provenance in accordance with open-source licensing.
@@ -74,15 +174,23 @@ def assert_integrity_or_raise(repo_root: Optional[str] = None) -> bool:
74
174
  if not verify_author_fingerprint():
75
175
  raise RuntimeError(
76
176
  "🛑 CRITICAL INTEGRITY CORRUPTED: Canonical author fingerprint mismatch. "
77
- "Synapse Hub requires original author attribution ('Thế Vị @TeeVee998') to execute."
177
+ "Synapse Hub requires original author attribution ('Thế Vị @TeeVee98') to execute."
78
178
  )
79
179
  valid, violations = verify_author_attribution(repo_root)
80
180
  license_violations = [v for v in violations if "LICENSE" in v]
181
+ if license_violations:
182
+ # Fallback inspection of distribution metadata before declaring critical violation
183
+ root = repo_root or DEFAULT_REPO_ROOT
184
+ lic_content, _ = _resolve_license_content(root, allow_global_metadata=True)
185
+ if lic_content and ORIGINAL_AUTHOR_NAME in lic_content and ("@TeeVee98" in lic_content or "@TeeVee998" in lic_content) and "Synapse-Hub" in lic_content:
186
+ license_violations = []
187
+ violations = [v for v in violations if "LICENSE" not in v]
188
+
81
189
  if license_violations:
82
190
  err_msg = "🛑 CRITICAL INTEGRITY VIOLATION: Mandatory MIT copyright notice missing or altered.\n"
83
191
  for v in license_violations:
84
192
  err_msg += f" • {v}\n"
85
- err_msg += "Under the MIT License, original author attribution to 'Thế Vị (@TeeVee998)' must be preserved in LICENSE."
193
+ err_msg += "Under the MIT License, original author attribution to 'Thế Vị (@TeeVee98)' must be preserved in LICENSE."
86
194
  raise RuntimeError(err_msg)
87
195
  elif not valid:
88
196
  # Non-fatal warning for peripheral files (README/package.json) to allow flexible downstream fork usage
@@ -97,16 +205,18 @@ def verify_author_attribution(repo_root: Optional[str] = None) -> Tuple[bool, Li
97
205
  Returns (is_valid, list_of_violations).
98
206
  """
99
207
  root = repo_root or DEFAULT_REPO_ROOT
208
+ allow_global = (repo_root is None or repo_root == DEFAULT_REPO_ROOT)
100
209
  violations: List[str] = []
101
210
 
102
- # 1. Check LICENSE file
103
- license_path = os.path.join(root, "LICENSE")
104
- if not os.path.exists(license_path):
105
- violations.append("Missing LICENSE file. MIT License with author copyright notice is mandatory.")
211
+ # 1. Check LICENSE file or distribution metadata
212
+ lic_content, lic_source = _resolve_license_content(root, allow_global_metadata=allow_global)
213
+ if lic_content is None:
214
+ if lic_source and lic_source.startswith("Could not read"):
215
+ violations.append(lic_source)
216
+ else:
217
+ violations.append("Missing LICENSE file. MIT License with author copyright notice is mandatory.")
106
218
  else:
107
219
  try:
108
- with open(license_path, "r", encoding="utf-8", errors="ignore") as f:
109
- lic_content = f.read()
110
220
  if ORIGINAL_AUTHOR_NAME not in lic_content or ("@TeeVee98" not in lic_content and "@TeeVee998" not in lic_content):
111
221
  violations.append("LICENSE file modified: original copyright notice for 'Thế Vị (@TeeVee98)' was removed or altered.")
112
222
  if "Synapse-Hub" not in lic_content:
@@ -18,6 +18,7 @@ from __future__ import annotations
18
18
 
19
19
  import argparse
20
20
  from datetime import datetime, timezone
21
+ import hashlib
21
22
  import json
22
23
  import os
23
24
  import re
@@ -36,7 +37,7 @@ REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
36
37
  if REPO_ROOT not in sys.path:
37
38
  sys.path.insert(0, REPO_ROOT)
38
39
 
39
- # Import core token estimator
40
+ # Import core token estimator and provider usage adapter
40
41
  try:
41
42
  from tools.core.token_estimator import count_tokens, get_estimator_info
42
43
  except ImportError:
@@ -53,6 +54,15 @@ except ImportError:
53
54
  def get_estimator_info() -> Dict[str, Any]:
54
55
  return {"engine": "fallback_words", "is_exact": False, "encoding": "cl100k_base"}
55
56
 
57
+ try:
58
+ from tools.core.provider_usage_adapter import get_repo_version_and_commit
59
+ except ImportError:
60
+ try:
61
+ from core.provider_usage_adapter import get_repo_version_and_commit
62
+ except ImportError:
63
+ def get_repo_version_and_commit(repo_root=None):
64
+ return "1.0.0", "unversioned"
65
+
56
66
 
57
67
  def estimate_tokens(text: str) -> int:
58
68
  """Wrapper for backward compatibility."""
@@ -287,6 +297,9 @@ def run_synthetic_benchmark(dataset_dir: Optional[str] = None) -> Dict[str, Any]
287
297
  results = []
288
298
  total_baseline_tokens = 0
289
299
  total_synapse_tokens = 0
300
+ info = get_estimator_info() if callable(globals().get("get_estimator_info")) else {"engine": "heuristic_polyglot", "is_exact": False, "encoding": "cl100k_base"}
301
+ version, commit = get_repo_version_and_commit(REPO_ROOT)
302
+ now_iso = datetime.now(timezone.utc).isoformat()
290
303
 
291
304
  for scn in scenarios:
292
305
  baseline_tokens = count_tokens(scn["baseline_payload"])
@@ -294,10 +307,26 @@ def run_synthetic_benchmark(dataset_dir: Optional[str] = None) -> Dict[str, Any]
294
307
  saved_tokens = baseline_tokens - synapse_tokens
295
308
  savings_pct = round((saved_tokens / max(1, baseline_tokens)) * 100.0, 2)
296
309
 
310
+ # Fixture hash for reproducibility
311
+ fixture_bytes = (scn.get("baseline_payload", "") + "::" + scn.get("synapse_payload", "")).encode("utf-8")
312
+ fixture_hash = hashlib.sha256(fixture_bytes).hexdigest()[:16]
313
+
297
314
  results.append({
298
315
  "id": scn["id"],
299
316
  "name": scn["name"],
300
317
  "description": scn["description"],
318
+ "measurement_kind": "synthetic",
319
+ "measurement_source": "deterministic_micro_workload",
320
+ "fixture_hash": fixture_hash,
321
+ "synthetic_tokens": synapse_tokens,
322
+ "baseline_synthetic_tokens": baseline_tokens,
323
+ "saved_synthetic_tokens": saved_tokens,
324
+ "reduction_pct": savings_pct,
325
+ "provider_reported_input_tokens": None,
326
+ "provider_reported_output_tokens": None,
327
+ "provider_cached_tokens": None,
328
+ "avoided_disk_bytes": 0,
329
+ # Backward compatibility fields
301
330
  "baseline_tokens": baseline_tokens,
302
331
  "synapse_tokens": synapse_tokens,
303
332
  "saved_tokens": saved_tokens,
@@ -311,12 +340,29 @@ def run_synthetic_benchmark(dataset_dir: Optional[str] = None) -> Dict[str, Any]
311
340
  net_savings_pct = round((net_savings_tokens / max(1, total_baseline_tokens)) * 100.0, 2)
312
341
 
313
342
  return {
314
- "timestamp": datetime.now(timezone.utc).isoformat(),
343
+ "timestamp": now_iso,
344
+ "measurement_kind": "synthetic",
345
+ "measurement_source": "synthetic_micro_workloads_suite",
346
+ "tokenizer_engine": info.get("engine", "heuristic_polyglot"),
347
+ "encoding": info.get("encoding", "cl100k_base"),
348
+ "is_exact": info.get("is_exact", False),
349
+ "version": version,
350
+ "commit": commit,
351
+ "total_baseline_synthetic_tokens": total_baseline_tokens,
352
+ "total_synapse_synthetic_tokens": total_synapse_tokens,
353
+ "net_saved_synthetic_tokens": net_savings_tokens,
354
+ "net_savings_pct": net_savings_pct,
355
+ "provider_reported_input_tokens": None,
356
+ "provider_reported_output_tokens": None,
357
+ "provider_cached_tokens": None,
358
+ "provider_observed": False,
359
+ "avoided_disk_bytes": 0,
360
+ "verified_claim_ge_40_pct": (net_savings_pct >= 40.0),
361
+ "note": "Synthetic micro-workload measurements evaluated via offline tokenizer; does not represent live LLM provider billing usage.",
362
+ # Backward compatibility fields
315
363
  "total_baseline_tokens": total_baseline_tokens,
316
364
  "total_synapse_tokens": total_synapse_tokens,
317
365
  "net_saved_tokens": net_savings_tokens,
318
- "net_savings_pct": net_savings_pct,
319
- "verified_claim_ge_40_pct": (net_savings_pct >= 40.0),
320
366
  "scenarios": results,
321
367
  }
322
368
 
@@ -335,6 +381,10 @@ def run_empirical_projects_benchmark() -> Dict[str, Any]:
335
381
  ("Selenium Suite", os.path.join(REPO_ROOT, "examples", "selenium-suite")),
336
382
  ]
337
383
 
384
+ info = get_estimator_info() if callable(globals().get("get_estimator_info")) else {"engine": "heuristic_polyglot", "is_exact": False, "encoding": "cl100k_base"}
385
+ version, commit = get_repo_version_and_commit(REPO_ROOT)
386
+ now_iso = datetime.now(timezone.utc).isoformat()
387
+
338
388
  project_results = []
339
389
  for name, p_path in project_folders:
340
390
  if not os.path.isdir(p_path):
@@ -346,21 +396,45 @@ def run_empirical_projects_benchmark() -> Dict[str, Any]:
346
396
 
347
397
  project_results.append({
348
398
  "project_name": name,
399
+ "measurement_kind": "static_estimate",
400
+ "measurement_source": "repository_reference_suites",
349
401
  "detected_stacks": routed["detected_stacks"],
350
402
  "confidence_score": routed["confidence_score"],
351
- "catalog_baseline": cat["baseline_tokens"],
352
- "catalog_routed": cat["routed_tokens"],
403
+ "static_estimated_tokens": hyd["routed_tokens"],
404
+ "catalog_summary_tokens": cat["routed_tokens"],
405
+ "catalog_baseline_tokens": cat["baseline_tokens"],
353
406
  "catalog_saved_tokens": cat["tokens_saved"],
354
407
  "catalog_reduction_pct": cat["reduction_pct"],
355
- "hydrated_baseline": hyd["baseline_tokens"],
356
- "hydrated_routed": hyd["routed_tokens"],
408
+ "hydrated_baseline_tokens": hyd["baseline_tokens"],
409
+ "hydrated_routed_tokens": hyd["routed_tokens"],
357
410
  "hydrated_saved_tokens": hyd["tokens_saved"],
358
411
  "hydrated_reduction_pct": hyd["reduction_pct"],
359
412
  "avoided_disk_bytes": rf.get("avoided_bytes", 0),
413
+ "provider_reported_input_tokens": None,
414
+ "provider_reported_output_tokens": None,
415
+ "provider_cached_tokens": None,
416
+ "provider_observed": False,
417
+ # Backward compatibility fields
418
+ "catalog_baseline": cat["baseline_tokens"],
419
+ "catalog_routed": cat["routed_tokens"],
420
+ "hydrated_baseline": hyd["baseline_tokens"],
421
+ "hydrated_routed": hyd["routed_tokens"],
360
422
  })
361
423
 
362
424
  return {
363
- "timestamp": datetime.now(timezone.utc).isoformat(),
425
+ "timestamp": now_iso,
426
+ "measurement_kind": "static_estimate",
427
+ "measurement_source": "disk_workspace_inspection",
428
+ "tokenizer_engine": info.get("engine", "heuristic_polyglot"),
429
+ "encoding": info.get("encoding", "cl100k_base"),
430
+ "is_exact": info.get("is_exact", False),
431
+ "version": version,
432
+ "commit": commit,
433
+ "provider_observed": False,
434
+ "provider_reported_input_tokens": None,
435
+ "provider_reported_output_tokens": None,
436
+ "provider_cached_tokens": None,
437
+ "note": "Real project filesystem workspace inspections evaluated via static rules_router hydration; avoided bytes represent disk I/O not context tokens.",
364
438
  "projects_count": len(project_results),
365
439
  "results": project_results,
366
440
  }
@@ -370,8 +444,22 @@ def run_benchmark(dataset_dir: Optional[str] = None) -> Dict[str, Any]:
370
444
  """Runs combined dual-track benchmark."""
371
445
  synthetic = run_synthetic_benchmark(dataset_dir)
372
446
  empirical = run_empirical_projects_benchmark()
447
+ info = get_estimator_info() if callable(globals().get("get_estimator_info")) else {"engine": "heuristic_polyglot", "is_exact": False, "encoding": "cl100k_base"}
448
+ version, commit = get_repo_version_and_commit(REPO_ROOT)
449
+ now_iso = datetime.now(timezone.utc).isoformat()
450
+
373
451
  return {
374
- "timestamp": datetime.now(timezone.utc).isoformat(),
452
+ "timestamp": now_iso,
453
+ "measurement_kind": "dual_track_benchmark",
454
+ "tokenizer_engine": info.get("engine", "heuristic_polyglot"),
455
+ "encoding": info.get("encoding", "cl100k_base"),
456
+ "is_exact": info.get("is_exact", False),
457
+ "version": version,
458
+ "commit": commit,
459
+ "provider_observed": False,
460
+ "provider_reported_input_tokens": None,
461
+ "provider_reported_output_tokens": None,
462
+ "provider_cached_tokens": None,
375
463
  "synthetic_track": synthetic,
376
464
  "empirical_track": empirical,
377
465
  # Backward compatibility fields
@@ -388,16 +476,17 @@ def format_markdown_report(bench: Dict[str, Any]) -> str:
388
476
  """Formats benchmark results in a clean, scientifically honest markdown report."""
389
477
  syn = bench.get("synthetic_track", bench)
390
478
  emp = bench.get("empirical_track", {})
391
- info = get_estimator_info() if "get_estimator_info" in globals() else {"engine": "cl100k_base", "is_exact": True, "encoding": "cl100k_base"}
479
+ info = get_estimator_info() if callable(globals().get("get_estimator_info")) else {"engine": "heuristic_polyglot", "is_exact": False, "encoding": "cl100k_base"}
392
480
 
393
481
  md = [
394
482
  "# Empirical Context & Token Reduction Benchmark (Dual-Track)",
395
483
  "",
396
484
  "> **Scientific Disclosure:** This benchmark distinguishes between:",
397
485
  "> 1. **Track 1 (Synthetic Micro-Workloads):** Deterministic micro-workloads evaluating isolated context patterns.",
398
- "> 2. **Track 2 (Empirical Reference Suites):** Live measurements on real example workspaces within the repository.",
399
- f"> - **Tokenizer Engine:** `{info.get('engine', 'cl100k_base')}` (Exact: `{info.get('is_exact', True)}`)",
400
- f"> - **Encoding Scope:** `{info.get('encoding', 'cl100k_base')}` (Standard OpenAI BPE encoding for LLMs; benchmark artifact specifies exact tokenizer scope).",
486
+ "> 2. **Track 2 (Empirical Reference Suites):** Live static file inspections on real example workspaces within the repository.",
487
+ f"> - **Tokenizer Engine:** `{info.get('engine', 'heuristic_polyglot')}` (Exact: `{info.get('is_exact', False)}`)",
488
+ f"> - **Encoding Scope:** `{info.get('encoding', 'cl100k_base')}` (Standard OpenAI BPE encoding for LLMs).",
489
+ "> - **Billing Notice:** Offline estimates do not represent live LLM provider billing usage. Live provider usage reduction is only verified when real provider response metrics are paired.",
401
490
  "",
402
491
  "## Track 1: Deterministic Micro-Workload Benchmark (Synthetic)",
403
492
  "",
@@ -420,10 +509,10 @@ def format_markdown_report(bench: Dict[str, Any]) -> str:
420
509
  if emp and emp.get("results"):
421
510
  md.extend([
422
511
  "",
423
- "## Track 2: Empirical Reference Suites Benchmark (Real Projects)",
512
+ "## Track 2: Empirical Reference Suites Benchmark (Static Workspace Inspection)",
424
513
  "",
425
514
  "> *Methodology: Dynamically enumerates all 13 rules and 53 skills in repository without static per-skill multiplier assumptions.*",
426
- "> *Disclosure: 'Avoided Disk Read' measures disk file bytes not read from storage, distinguished from prompt context tokens.*",
515
+ "> *Disclosure: 'Avoided Disk Read (I/O)' measures filesystem file size bytes not read from storage; it is strictly distinguished from context tokens and is not billed token savings.*",
427
516
  "",
428
517
  "| Reference Project | Detected Stack | Confidence | Catalog Summary Saved | Full Hydration Saved | Avoided Disk Read (I/O) |",
429
518
  "|---|---|:---:|:---:|:---:|:---:|",
@@ -480,9 +569,21 @@ def main() -> int:
480
569
  json.dump(bench, f, indent=2)
481
570
 
482
571
  if args.json:
572
+ # Guarantee single parseable JSON object on stdout
483
573
  print(json.dumps(bench, indent=2))
484
- else:
485
- print(format_markdown_report(bench))
574
+ if bench["net_savings_pct"] < args.verify_min_savings:
575
+ print(
576
+ f"\n[FAIL] Token savings {bench['net_savings_pct']}% is below required threshold of {args.verify_min_savings}%.",
577
+ file=sys.stderr,
578
+ )
579
+ return 1
580
+ print(
581
+ f"\n[PASS] Empirical token reduction verified: {bench['net_savings_pct']}% >= {args.verify_min_savings}% threshold.",
582
+ file=sys.stderr,
583
+ )
584
+ return 0
585
+
586
+ print(format_markdown_report(bench))
486
587
 
487
588
  if bench["net_savings_pct"] < args.verify_min_savings:
488
589
  print(f"\n[FAIL] Token savings {bench['net_savings_pct']}% is below required threshold of {args.verify_min_savings}%.")
@@ -0,0 +1,233 @@
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/break_ui_generator.py — Edge-Case UI Stress Testing Data Generator
8
+ Inspired by Emil Kowalski's break-ui skill (emilkowalski/skills).
9
+ Generates extreme data boundaries, unspaced strings, Zalgo, RTL, boundary floats,
10
+ and odd viewports to proactively discover layout breakages, text truncation bugs,
11
+ and visual regressions before production deployment.
12
+ 100% UTF-8 No BOM. Zero external dependencies.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import argparse
18
+ import json
19
+ import sys
20
+ from typing import Any, Dict, List
21
+
22
+ # Enforce UTF-8 stdout encoding
23
+ if hasattr(sys.stdout, "reconfigure"):
24
+ try:
25
+ sys.stdout.reconfigure(encoding="utf-8")
26
+ sys.stderr.reconfigure(encoding="utf-8")
27
+ except Exception:
28
+ pass
29
+
30
+ # 1. Extreme Strings (Zalgo, unspaced overflow, zero-width, markup injection)
31
+ BREAK_STRINGS: List[Dict[str, str]] = [
32
+ {
33
+ "name": "unspaced_500_chars",
34
+ "description": "500-char continuous string to test CSS word-break / overflow-wrap",
35
+ "value": "Supercalifragilisticexpialidocious" * 15,
36
+ },
37
+ {
38
+ "name": "unspaced_2000_chars",
39
+ "description": "2,000-char continuous string to force container overflow",
40
+ "value": "A" * 2000,
41
+ },
42
+ {
43
+ "name": "zero_width_spaces",
44
+ "description": "Invisible zero-width joiners and spaces to test renderer length calculation",
45
+ "value": "Zero\u200BWidth\u200CSpace\u200DTest\uFEFFInvisible",
46
+ },
47
+ {
48
+ "name": "zalgo_corrupted_text",
49
+ "description": "Heavily combining diacritic marks to test vertical line-height clipping",
50
+ "value": "T̶͕͂é̷̯s̴̱͘t̸͙͒ ̸͚̈́Z̷̯̆a̴͖̓l̸͔̐g̶̭͒ỏ̷̱ ̶̦̋C̴̠̃o̶̧͝r̶̠̾r̵͇̈́ǘ̸͎p̸̀ͅẗ̴͚́ì̷̳o̸̭͝n̶̡̈́",
51
+ },
52
+ {
53
+ "name": "html_markup_injection",
54
+ "description": "Unescaped HTML tags to ensure UI framework escapes entities safely",
55
+ "value": "<script>alert('XSS')</script><b>Bold</b>&amp;\"'<svg onload=alert(1)>",
56
+ },
57
+ {
58
+ "name": "sql_syntax_injection",
59
+ "description": "SQL special characters in UI input to verify backend sanitization",
60
+ "value": "' OR '1'='1' -- /* drop table users; */ \";",
61
+ },
62
+ {
63
+ "name": "emoji_complex_graphemes",
64
+ "description": "Multi-codepoint composite emojis testing font glyph rendering",
65
+ "value": "👨‍👩‍👧‍👦 🏳️‍⚧️ 🧑🏾‍🚀 🦾 👁️‍🗨️",
66
+ },
67
+ ]
68
+
69
+ # 2. Localization & Directional Boundaries (RTL, German compounds, CJK, Vietnamese tones)
70
+ BREAK_LOCALIZATION: List[Dict[str, str]] = [
71
+ {
72
+ "name": "rtl_arabic",
73
+ "description": "Right-to-Left Arabic text to test bidirectional layout mirroring",
74
+ "value": "مرحبا بالعالم! هذا اختبار لتخطيط الواجهة من اليمين إلى اليسار.",
75
+ },
76
+ {
77
+ "name": "rtl_hebrew",
78
+ "description": "Right-to-Left Hebrew text with mixed LTR numbers",
79
+ "value": "בדיקת ממשק משתמש בעברית עם מספרים: 12345 וטקست באנגלית ABC.",
80
+ },
81
+ {
82
+ "name": "german_compound_noun",
83
+ "description": "Extremely long German word to test column wrapping",
84
+ "value": "Rindfleischetikettierungsüberwachungsaufgabenübertragungsgesetz",
85
+ },
86
+ {
87
+ "name": "vietnamese_complex_tones",
88
+ "description": "Stacked diacritics testing font vertical metrics and accent collisions",
89
+ "value": "Khảo sát tự động hóa kiểm thử: Độc lập - Tự do - Hạnh phúc (Thuở, Nghĩa, Triệu)",
90
+ },
91
+ {
92
+ "name": "cjk_wide_characters",
93
+ "description": "Full-width East Asian glyphs testing monospace alignment and line breaks",
94
+ "value": "日本語のテスト文字列。全角文字と半角文字の混在チェック:12345ABCDE。",
95
+ },
96
+ ]
97
+
98
+ # 3. Numeric Boundaries & Floating Point Edge Cases
99
+ BREAK_NUMBERS: List[Dict[str, Any]] = [
100
+ {
101
+ "name": "max_safe_integer_js",
102
+ "description": "JavaScript Number.MAX_SAFE_INTEGER (2^53 - 1)",
103
+ "value": 9007199254740991,
104
+ },
105
+ {
106
+ "name": "min_safe_integer_js",
107
+ "description": "JavaScript Number.MIN_SAFE_INTEGER -(2^53 - 1)",
108
+ "value": -9007199254740991,
109
+ },
110
+ {
111
+ "name": "int64_max",
112
+ "description": "Signed 64-bit maximum integer (2^63 - 1)",
113
+ "value": 9223372036854775807,
114
+ },
115
+ {
116
+ "name": "extreme_decimal_precision",
117
+ "description": "20-decimal float testing rounding and currency formatting truncation",
118
+ "value": 1234567.12345678901234567890,
119
+ },
120
+ {
121
+ "name": "near_zero_subnormal",
122
+ "description": "Subnormal scientific notation close to zero",
123
+ "value": 1e-15,
124
+ },
125
+ {
126
+ "name": "extreme_large_scientific",
127
+ "description": "Large exponent testing scientific notation formatting",
128
+ "value": 1.7976931348623157e308,
129
+ },
130
+ {
131
+ "name": "zero_and_negative_zero",
132
+ "description": "Zero and boundary float 0.0",
133
+ "value": 0.0,
134
+ },
135
+ ]
136
+
137
+ # 4. Viewport Dimensions for Layout Stress Testing
138
+ BREAK_VIEWPORTS: List[Dict[str, Any]] = [
139
+ {"name": "mobile_compact_se", "width": 320, "height": 568, "device_scale": 2.0},
140
+ {"name": "mobile_modern_tall", "width": 390, "height": 844, "device_scale": 3.0},
141
+ {"name": "tablet_portrait", "width": 768, "height": 1024, "device_scale": 2.0},
142
+ {"name": "tablet_landscape", "width": 1024, "height": 768, "device_scale": 2.0},
143
+ {"name": "desktop_standard_hd", "width": 1366, "height": 768, "device_scale": 1.0},
144
+ {"name": "desktop_full_hd_standard", "width": 1920, "height": 1080, "device_scale": 1.0},
145
+ {"name": "desktop_ultrawide", "width": 3440, "height": 1440, "device_scale": 1.0},
146
+ {"name": "desktop_4k_extreme", "width": 3840, "height": 2160, "device_scale": 2.0},
147
+ ]
148
+
149
+
150
+ def get_break_strings() -> List[Dict[str, str]]:
151
+ """Returns extreme string boundaries for text input and layout testing."""
152
+ return list(BREAK_STRINGS)
153
+
154
+
155
+ def get_break_localization() -> List[Dict[str, str]]:
156
+ """Returns bidirectional, CJK, and complex diacritic strings."""
157
+ return list(BREAK_LOCALIZATION)
158
+
159
+
160
+ def get_break_numbers() -> List[Dict[str, Any]]:
161
+ """Returns numerical edge cases and boundary floats."""
162
+ return list(BREAK_NUMBERS)
163
+
164
+
165
+ def get_break_viewports() -> List[Dict[str, Any]]:
166
+ """Returns standard and extreme responsive viewport configurations."""
167
+ return list(BREAK_VIEWPORTS)
168
+
169
+
170
+ def generate_all_break_payloads() -> Dict[str, Any]:
171
+ """Generates the unified break-ui testing catalog."""
172
+ return {
173
+ "version": "1.0.0",
174
+ "source": "Synapse Hub break-ui generator (Emil Kowalski pattern)",
175
+ "categories": {
176
+ "strings": get_break_strings(),
177
+ "localization": get_break_localization(),
178
+ "numbers": get_break_numbers(),
179
+ "viewports": get_break_viewports(),
180
+ },
181
+ "total_cases": (
182
+ len(BREAK_STRINGS)
183
+ + len(BREAK_LOCALIZATION)
184
+ + len(BREAK_NUMBERS)
185
+ + len(BREAK_VIEWPORTS)
186
+ ),
187
+ }
188
+
189
+
190
+ def main() -> None:
191
+ parser = argparse.ArgumentParser(description="Break-UI Edge-Case Test Data Generator for Synapse Hub")
192
+ parser.add_argument(
193
+ "--category",
194
+ "-c",
195
+ choices=["strings", "localization", "numbers", "viewports", "all"],
196
+ default="all",
197
+ help="Category of edge-case test data to generate (default: all)",
198
+ )
199
+ parser.add_argument("--limit", "-l", type=int, default=0, help="Limit number of items output (0 = all)")
200
+ parser.add_argument("--json", action="store_true", help="Output in machine-readable JSON format")
201
+ args = parser.parse_args()
202
+
203
+ catalog = generate_all_break_payloads()
204
+
205
+ if args.category == "all":
206
+ data: Any = catalog["categories"]
207
+ else:
208
+ data = catalog["categories"][args.category]
209
+ if args.limit > 0:
210
+ data = data[:args.limit]
211
+
212
+ if args.json:
213
+ print(json.dumps(data, indent=2, ensure_ascii=False))
214
+ else:
215
+ print(f"💥 Break-UI Generator (Category: {args.category})")
216
+ if isinstance(data, dict):
217
+ for cat, items in data.items():
218
+ print(f"\n[{cat.upper()}] ({len(items)} items)")
219
+ for item in items[: (args.limit if args.limit > 0 else len(items))]:
220
+ val = str(item.get("value", f"{item.get('width')}x{item.get('height')}"))
221
+ if len(val) > 60:
222
+ val = val[:57] + "..."
223
+ print(f" • {item['name']:<28} : {val}")
224
+ else:
225
+ for item in data:
226
+ val = str(item.get("value", f"{item.get('width')}x{item.get('height')}"))
227
+ if len(val) > 60:
228
+ val = val[:57] + "..."
229
+ print(f" • {item['name']:<28} : {val}")
230
+
231
+
232
+ if __name__ == "__main__":
233
+ main()