@teevee98/synapse-hub 4.1.4 → 4.2.1

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 (133) 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 +52 -3
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
  5. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
  6. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
  7. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
  8. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
  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 +54 -91
  13. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
  14. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
  15. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
  16. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
  17. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
  18. package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
  19. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
  20. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
  21. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
  22. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
  23. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
  24. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
  25. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
  26. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
  27. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
  28. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
  29. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
  30. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
  31. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
  32. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
  33. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
  34. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
  35. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
  36. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
  37. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
  38. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
  39. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
  40. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
  41. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
  42. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
  43. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  44. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
  45. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
  46. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
  47. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
  48. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
  49. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
  50. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  51. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
  52. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
  53. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
  54. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
  55. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
  56. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
  57. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
  58. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
  59. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
  60. package/.cursor/rules/synapse-qa.mdc +20 -7
  61. package/.cursorrules +19 -5
  62. package/.windsurfrules +18 -3
  63. package/AGENTS.md +51 -59
  64. package/CLAUDE.md +38 -24
  65. package/LICENSE +5 -5
  66. package/NOTICE +1 -1
  67. package/README.en.md +4 -4
  68. package/README.md +4 -4
  69. package/agentskills.json +1 -1
  70. package/docs/ARCHITECTURE.en.md +2 -2
  71. package/docs/ARCHITECTURE.md +11 -2
  72. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  73. package/docs/CLI_REFERENCE.en.md +6 -4
  74. package/docs/CLI_REFERENCE.md +1 -1
  75. package/docs/CONTRIBUTING.en.md +1 -1
  76. package/docs/CONTRIBUTING.md +2 -2
  77. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  78. package/docs/TOOL_CATALOG.md +6 -2
  79. package/docs/research/agent_skill_training_analysis.md +1 -1
  80. package/package.json +1 -1
  81. package/plugin.json +1 -1
  82. package/skills_manifest.json +320 -55
  83. package/synapse.config.json +1 -1
  84. package/templates/ai_bridges/CLAUDE.md +29 -26
  85. package/templates/ai_bridges/copilot-instructions.md +14 -5
  86. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  87. package/templates/ai_bridges/windsurfrules +14 -3
  88. package/templates/ui/index.html +2 -2
  89. package/tools/TOOLS_RUNBOOK.md +1 -1
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +1 -1
  92. package/tools/api_fuzzer.py +447 -132
  93. package/tools/author_integrity.py +121 -11
  94. package/tools/benchmark_swarm_context.py +130 -22
  95. package/tools/break_ui_generator.py +233 -0
  96. package/tools/browser_helpers.js +2 -2
  97. package/tools/check_version_sync.py +18 -50
  98. package/tools/cli.py +110 -19
  99. package/tools/core/bm25_retriever.py +218 -0
  100. package/tools/core/i18n.py +5 -5
  101. package/tools/core/provider_usage_adapter.py +383 -0
  102. package/tools/core/token_estimator.py +81 -15
  103. package/tools/count_tokens.py +7 -2
  104. package/tools/coverage_reporter.py +245 -0
  105. package/tools/dashboard_generator.py +8 -8
  106. package/tools/db_sandbox.py +290 -9
  107. package/tools/distill_log.py +1 -1
  108. package/tools/distill_skill.py +206 -0
  109. package/tools/git_pre_commit_guard.py +202 -1
  110. package/tools/humanize_linter.py +3 -0
  111. package/tools/mcp_docx_server.py +1 -1
  112. package/tools/mcp_excel_server.py +1 -1
  113. package/tools/mcp_server.py +104 -16
  114. package/tools/micro_mutator.py +114 -15
  115. package/tools/pentest_scope_guard.py +674 -58
  116. package/tools/perf/benchmark_perf_runner.py +42 -0
  117. package/tools/project_state.py +29 -5
  118. package/tools/reversible_sandbox.py +58 -13
  119. package/tools/rules_router.py +473 -60
  120. package/tools/security_scanner.py +80 -0
  121. package/tools/senior_code_review.py +14 -0
  122. package/tools/skill_canonical_digest.py +302 -0
  123. package/tools/skill_profiles.py +77 -7
  124. package/tools/slide_deck_exporter.py +477 -0
  125. package/tools/sync_agent_rules.py +187 -61
  126. package/tools/sync_skills_manifest.py +166 -0
  127. package/tools/task_memory_manager.py +275 -0
  128. package/tools/ui_server.py +3 -1
  129. package/tools/update_sentinel.py +3 -3
  130. package/tools/validate_host_interop.py +485 -0
  131. package/tools/validate_skills_schema.py +575 -0
  132. package/tools/verify_all.py +668 -44
  133. package/tools/welcome_page.py +2 -2
@@ -21,7 +21,9 @@ Key Capabilities:
21
21
 
22
22
  from __future__ import annotations
23
23
 
24
+ from datetime import datetime, timezone
24
25
  import glob
26
+ import hashlib
25
27
  import json
26
28
  import os
27
29
  import re
@@ -39,6 +41,15 @@ try:
39
41
  except ImportError:
40
42
  _TIKTOKEN_ENCODER = None
41
43
 
44
+ try:
45
+ from tools.core.provider_usage_adapter import get_repo_version_and_commit
46
+ except ImportError:
47
+ try:
48
+ from core.provider_usage_adapter import get_repo_version_and_commit
49
+ except ImportError:
50
+ def get_repo_version_and_commit(repo_root=None):
51
+ return "1.0.0", "unversioned"
52
+
42
53
  # Cache mapping canonical manifest_path -> (mtime, parsed_manifest)
43
54
  _SKILLS_MANIFEST_CACHE: Dict[str, Any] = {}
44
55
 
@@ -119,8 +130,8 @@ def _get_skills_manifest(repo_root: str) -> Dict[str, Dict[str, Any]]:
119
130
  """
120
131
  Loads and caches skills_manifest.json mapping skill_id to metadata.
121
132
  Cache is keyed by the canonical realpath of the manifest file and validated
122
- against file modification time (mtime) to support multi-repo isolation,
123
- runtime manifest mutations, and deletions.
133
+ against file mtime_ns, size, and content SHA-256 digest to guarantee that
134
+ mutations are detected even if file modification time remains identical.
124
135
  """
125
136
  global _SKILLS_MANIFEST_CACHE
126
137
  manifest_path = os.path.realpath(os.path.join(repo_root, "skills_manifest.json"))
@@ -130,26 +141,41 @@ def _get_skills_manifest(repo_root: str) -> Dict[str, Dict[str, Any]]:
130
141
  return {}
131
142
 
132
143
  try:
133
- current_mtime = os.path.getmtime(manifest_path)
144
+ st = os.stat(manifest_path)
145
+ current_mtime_ns = st.st_mtime_ns
146
+ current_size = st.st_size
147
+ except OSError:
148
+ _SKILLS_MANIFEST_CACHE.pop(manifest_path, None)
149
+ return {}
150
+
151
+ try:
152
+ with open(manifest_path, "rb") as f:
153
+ raw_bytes = f.read()
154
+ current_digest = hashlib.sha256(raw_bytes).digest()
134
155
  except OSError:
135
156
  _SKILLS_MANIFEST_CACHE.pop(manifest_path, None)
136
157
  return {}
137
158
 
138
159
  if manifest_path in _SKILLS_MANIFEST_CACHE:
139
- cached_mtime, cached_data = _SKILLS_MANIFEST_CACHE[manifest_path]
140
- if cached_mtime == current_mtime:
141
- return cached_data
160
+ cached_entry = _SKILLS_MANIFEST_CACHE[manifest_path]
161
+ if len(cached_entry) == 4:
162
+ cached_mtime_ns, cached_size, cached_digest, cached_data = cached_entry
163
+ if cached_digest == current_digest:
164
+ return cached_data
165
+ elif len(cached_entry) == 2:
166
+ cached_mtime, cached_data = cached_entry
167
+ if cached_mtime == st.st_mtime:
168
+ return cached_data
142
169
 
143
170
  manifest_data: Dict[str, Dict[str, Any]] = {}
144
171
  try:
145
- with open(manifest_path, "r", encoding="utf-8") as f:
146
- data = json.load(f)
147
- for s in data.get("skills", []):
148
- sid = s.get("id")
149
- if sid:
150
- manifest_data[sid] = s
151
- _SKILLS_MANIFEST_CACHE[manifest_path] = (current_mtime, manifest_data)
152
- except (OSError, json.JSONDecodeError) as err:
172
+ data = json.loads(raw_bytes.decode("utf-8"))
173
+ for s in data.get("skills", []):
174
+ sid = s.get("id")
175
+ if sid:
176
+ manifest_data[sid] = s
177
+ _SKILLS_MANIFEST_CACHE[manifest_path] = (current_mtime_ns, current_size, current_digest, manifest_data)
178
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as err:
153
179
  import sys
154
180
  sys.stderr.write(f"Warning: Failed to load manifest at {manifest_path}: {err}\n")
155
181
  _SKILLS_MANIFEST_CACHE.pop(manifest_path, None)
@@ -215,7 +241,27 @@ def calculate_hydration_payload(
215
241
 
216
242
  catalog_skill_tokens = count_tokens("\n".join(catalog_lines)) if catalog_lines else 0
217
243
 
244
+ info = get_estimator_info()
245
+ version, commit_sha = get_repo_version_and_commit(repo_root)
246
+ input_str = f"rules:{','.join(sorted(rules))};skills:{','.join(sorted(skills))}"
247
+ input_hash = hashlib.sha256(input_str.encode("utf-8")).hexdigest()
248
+ now_iso = datetime.now(timezone.utc).isoformat()
249
+ is_fallback = not info.get("is_exact", False)
250
+ encoding = info.get("encoding", "cl100k_base")
251
+
218
252
  return {
253
+ "measurement_kind": "static_estimate",
254
+ "static_estimated_tokens": rule_tokens + full_skill_tokens,
255
+ "commit_sha": commit_sha,
256
+ "timestamp": now_iso,
257
+ "input_hash": input_hash,
258
+ "is_fallback": is_fallback,
259
+ "encoding": encoding,
260
+ "tokenizer_engine": info.get("engine", "heuristic_polyglot"),
261
+ "provider_reported_input_tokens": None,
262
+ "provider_reported_output_tokens": None,
263
+ "provider_cached_tokens": None,
264
+ "avoided_disk_bytes": 0,
219
265
  "rule_tokens": rule_tokens,
220
266
  "rule_bytes": rule_bytes,
221
267
  "skill_catalog_tokens": catalog_skill_tokens,
@@ -269,7 +315,27 @@ def get_full_unrouted_baseline(repo_root: str) -> Dict[str, Any]:
269
315
 
270
316
  total_cat_tokens = count_tokens("\n".join(catalog_lines)) if catalog_lines else 0
271
317
 
318
+ info = get_estimator_info()
319
+ version, commit_sha = get_repo_version_and_commit(repo_root)
320
+ input_str = f"rules:{','.join(sorted(all_rule_files))};skills:{','.join(sorted(all_skill_ids))}"
321
+ input_hash = hashlib.sha256(input_str.encode("utf-8")).hexdigest()
322
+ now_iso = datetime.now(timezone.utc).isoformat()
323
+ is_fallback = not info.get("is_exact", False)
324
+ encoding = info.get("encoding", "cl100k_base")
325
+
272
326
  return {
327
+ "measurement_kind": "static_estimate",
328
+ "static_estimated_tokens": total_rule_tokens + total_skill_tokens,
329
+ "commit_sha": commit_sha,
330
+ "timestamp": now_iso,
331
+ "input_hash": input_hash,
332
+ "is_fallback": is_fallback,
333
+ "encoding": encoding,
334
+ "tokenizer_engine": info.get("engine", "heuristic_polyglot"),
335
+ "provider_reported_input_tokens": None,
336
+ "provider_reported_output_tokens": None,
337
+ "provider_cached_tokens": None,
338
+ "avoided_disk_bytes": 0,
273
339
  "rule_count": len(all_rule_files),
274
340
  "rule_tokens": total_rule_tokens,
275
341
  "rule_bytes": total_rule_bytes,
@@ -282,7 +348,7 @@ def get_full_unrouted_baseline(repo_root: str) -> Dict[str, Any]:
282
348
  "total_full_bytes": total_rule_bytes + total_skill_bytes,
283
349
  "all_rules": all_rule_files,
284
350
  "all_skills": all_skill_ids,
285
- "estimator_info": get_estimator_info(),
351
+ "estimator_info": info,
286
352
  }
287
353
 
288
354
 
@@ -732,10 +732,10 @@ def calculate_hub_savings(input_tokens: int, cache_tokens: int, output_tokens: i
732
732
  """
733
733
  Empirical Hub Savings Model:
734
734
  Compares actual Synapse-Hub execution against vanilla/non-Hub agent execution:
735
- 1. Log Distillation (Observation Masking): Hub cuts CLI noise by 95% (raw vs distilled).
735
+ 1. Log Distillation (Observation Masking): Hub compresses CLI noise (raw vs distilled logs).
736
736
  2. Sparse Retrieval (Repo Map): 500-token AST map vs reading full 4,000-line classes.
737
737
  3. Compact AOM: <500-token interactive tree vs 15,000-token raw HTML DOM.
738
- 4. KV-Cache Alignment: 95%+ Cache Hit vs <15% without prefix stability.
738
+ 4. KV-Cache Alignment: High Cache Hit rates via prefix stability.
739
739
  5. Lean Telemetry Badge: ~180 tokens/turn saved by omitting verbose footer.
740
740
  """
741
741
  pricing = PRICING_TABLE.get(model_key, PRICING_TABLE[DEFAULT_MODEL])
@@ -775,6 +775,10 @@ def calculate_hub_savings(input_tokens: int, cache_tokens: int, output_tokens: i
775
775
 
776
776
  return {
777
777
  "model_name": pricing["name"],
778
+ "measurement_kind": "counterfactual_model_estimate",
779
+ "provider_reported_input_tokens": input_tokens,
780
+ "provider_reported_output_tokens": output_tokens,
781
+ "provider_cached_tokens": cache_tokens,
778
782
  "non_hub_input": estimated_non_hub_input,
779
783
  "non_hub_cache": estimated_non_hub_cache,
780
784
  "non_hub_total": estimated_non_hub_total,
@@ -788,6 +792,7 @@ def calculate_hub_savings(input_tokens: int, cache_tokens: int, output_tokens: i
788
792
  "savings_pct": round(savings_pct, 1),
789
793
  "cost_saved_usd": round(cost_saved_usd, 4),
790
794
  "cost_savings_pct": round(cost_savings_pct, 1),
795
+ "note": "Actual hub tokens are parsed from session transcripts. Non-hub baseline is an estimated counterfactual.",
791
796
  }
792
797
 
793
798
 
@@ -0,0 +1,245 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
+
6
+ """
7
+ tools/coverage_reporter.py — Standardized Coverage Metrics & Roadmap Evaluator
8
+ -------------------------------------------------------------------------------
9
+ Evaluates and distinguishes:
10
+ 1. Statement / Line Coverage (fail_under: 60.00% calibrated floor, roadmap: 70% -> 80%).
11
+ 2. Branch Coverage (floor: 50.00% baseline floor, roadmap: 60% -> 70%).
12
+ 3. Combined Coverage (statements + branches hit / total).
13
+
14
+ Maintains strict separation between line coverage, branch coverage, static heuristic,
15
+ and dynamic mutation kill scores.
16
+
17
+ Outputs:
18
+ - reports/coverage_summary.json (Standardized multi-metric artifact)
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import argparse
24
+ import json
25
+ import logging
26
+ import os
27
+ import subprocess
28
+ import sys
29
+ from datetime import datetime, timezone
30
+ from typing import Any, Dict
31
+
32
+ _logger = logging.getLogger("coverage_reporter")
33
+ REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
34
+ DEFAULT_COVERAGE_JSON = os.path.join(REPO_ROOT, "reports", "coverage.json")
35
+ DEFAULT_COVERAGE_XML = os.path.join(REPO_ROOT, "reports", "coverage.xml")
36
+ DEFAULT_SUMMARY_JSON = os.path.join(REPO_ROOT, "reports", "coverage_summary.json")
37
+
38
+ # Calibrated floors and roadmap milestones
39
+ LINE_COVERAGE_FLOOR_PCT = 60.00
40
+ BRANCH_COVERAGE_FLOOR_PCT = 50.00
41
+
42
+ ROADMAP_THRESHOLDS = {
43
+ "current_calibrated": {"line_pct": 60.00, "branch_pct": 50.00},
44
+ "phase_2_consolidation": {"line_pct": 70.00, "branch_pct": 60.00},
45
+ "target_enterprise": {"line_pct": 80.00, "branch_pct": 70.00},
46
+ }
47
+
48
+
49
+ def get_git_commit(repo_root: str = REPO_ROOT) -> str:
50
+ try:
51
+ out = subprocess.check_output(
52
+ ["git", "rev-parse", "HEAD"],
53
+ cwd=repo_root,
54
+ stderr=subprocess.DEVNULL,
55
+ )
56
+ return out.decode("utf-8").strip()
57
+ except (OSError, subprocess.SubprocessError) as err:
58
+ _logger.debug("Could not determine git commit: %s", err)
59
+ return "unversioned"
60
+
61
+
62
+ def parse_coverage_metrics(
63
+ json_path: str = DEFAULT_COVERAGE_JSON,
64
+ ) -> Dict[str, Any]:
65
+ """Parses coverage metrics from coverage.py json report."""
66
+ if not os.path.exists(json_path):
67
+ raise FileNotFoundError(f"Coverage JSON report not found: {json_path}")
68
+
69
+ with open(json_path, "r", encoding="utf-8") as f:
70
+ data = json.load(f)
71
+
72
+ totals = data.get("totals", {})
73
+ num_statements = totals.get("num_statements", 0)
74
+ covered_lines = totals.get("covered_lines", 0)
75
+ missing_lines = totals.get("missing_lines", 0)
76
+
77
+ # Line / Statement coverage
78
+ line_cov_pct = float(
79
+ totals.get(
80
+ "percent_statements_covered",
81
+ (covered_lines / num_statements * 100.0) if num_statements > 0 else 0.0,
82
+ )
83
+ )
84
+
85
+ # Branch coverage
86
+ num_branches = totals.get("num_branches", 0)
87
+ covered_branches = totals.get("covered_branches", 0)
88
+ missing_branches = totals.get("missing_branches", 0)
89
+ branch_cov_pct = float(
90
+ totals.get(
91
+ "percent_branches_covered",
92
+ (covered_branches / num_branches * 100.0) if num_branches > 0 else 0.0,
93
+ )
94
+ )
95
+
96
+ # Combined coverage
97
+ combined_cov_pct = float(totals.get("percent_covered", 0.0))
98
+
99
+ return {
100
+ "num_statements": num_statements,
101
+ "covered_lines": covered_lines,
102
+ "missing_lines": missing_lines,
103
+ "line_coverage_pct": round(line_cov_pct, 2),
104
+ "num_branches": num_branches,
105
+ "covered_branches": covered_branches,
106
+ "missing_branches": missing_branches,
107
+ "branch_coverage_pct": round(branch_cov_pct, 2),
108
+ "combined_coverage_pct": round(combined_cov_pct, 2),
109
+ }
110
+
111
+
112
+ def evaluate_coverage(
113
+ coverage_data: Dict[str, Any],
114
+ line_floor: float = LINE_COVERAGE_FLOOR_PCT,
115
+ branch_floor: float = BRANCH_COVERAGE_FLOOR_PCT,
116
+ enforce_branch: bool = True,
117
+ ) -> Dict[str, Any]:
118
+ """Evaluates metrics against calibrated floor and roadmap milestones."""
119
+ line_pct = coverage_data["line_coverage_pct"]
120
+ branch_pct = coverage_data["branch_coverage_pct"]
121
+
122
+ line_pass = line_pct >= line_floor
123
+ branch_pass = branch_pct >= branch_floor if enforce_branch and coverage_data["num_branches"] > 0 else True
124
+ all_pass = line_pass and branch_pass
125
+
126
+ return {
127
+ "line_pass": line_pass,
128
+ "branch_pass": branch_pass,
129
+ "all_pass": all_pass,
130
+ "line_floor": line_floor,
131
+ "branch_floor": branch_floor,
132
+ "enforce_branch": enforce_branch,
133
+ }
134
+
135
+
136
+ def generate_coverage_summary(
137
+ coverage_json: str = DEFAULT_COVERAGE_JSON,
138
+ coverage_xml: str = DEFAULT_COVERAGE_XML,
139
+ output_summary_json: str = DEFAULT_SUMMARY_JSON,
140
+ line_floor: float = LINE_COVERAGE_FLOOR_PCT,
141
+ branch_floor: float = BRANCH_COVERAGE_FLOOR_PCT,
142
+ enforce_branch: bool = True,
143
+ repo_root: str = REPO_ROOT,
144
+ ) -> Dict[str, Any]:
145
+ """Generates standardized coverage summary artifact and writes to disk."""
146
+ metrics = parse_coverage_metrics(coverage_json)
147
+ eval_res = evaluate_coverage(
148
+ metrics,
149
+ line_floor=line_floor,
150
+ branch_floor=branch_floor,
151
+ enforce_branch=enforce_branch,
152
+ )
153
+
154
+ commit_sha = get_git_commit(repo_root)
155
+ now_iso = datetime.now(timezone.utc).isoformat()
156
+
157
+ summary_doc = {
158
+ "generated_at": now_iso,
159
+ "commit": commit_sha,
160
+ "metrics": {
161
+ "line_coverage_pct": metrics["line_coverage_pct"],
162
+ "branch_coverage_pct": metrics["branch_coverage_pct"],
163
+ "combined_coverage_pct": metrics["combined_coverage_pct"],
164
+ "statements_total": metrics["num_statements"],
165
+ "statements_covered": metrics["covered_lines"],
166
+ "statements_missing": metrics["missing_lines"],
167
+ "branches_total": metrics["num_branches"],
168
+ "branches_covered": metrics["covered_branches"],
169
+ "branches_missing": metrics["missing_branches"],
170
+ },
171
+ "thresholds": {
172
+ "line_floor_pct": line_floor,
173
+ "branch_floor_pct": branch_floor,
174
+ "roadmap": ROADMAP_THRESHOLDS,
175
+ },
176
+ "evaluation": {
177
+ "line_passed": eval_res["line_pass"],
178
+ "branch_passed": eval_res["branch_pass"],
179
+ "all_passed": eval_res["all_pass"],
180
+ },
181
+ "artifacts": {
182
+ "coverage_json": os.path.relpath(coverage_json, repo_root) if os.path.exists(coverage_json) else None,
183
+ "coverage_xml": os.path.relpath(coverage_xml, repo_root) if os.path.exists(coverage_xml) else None,
184
+ "summary_json": os.path.relpath(output_summary_json, repo_root),
185
+ },
186
+ }
187
+
188
+ out_dir = os.path.dirname(output_summary_json)
189
+ if out_dir:
190
+ os.makedirs(out_dir, exist_ok=True)
191
+ with open(output_summary_json, "w", encoding="utf-8") as f:
192
+ json.dump(summary_doc, f, indent=2)
193
+
194
+ return summary_doc
195
+
196
+
197
+ def main() -> int:
198
+ parser = argparse.ArgumentParser(description="Synapse Hub Standardized Coverage Reporter")
199
+ parser.add_argument("--json-report", default=DEFAULT_COVERAGE_JSON, help="Path to coverage.json")
200
+ parser.add_argument("--xml-report", default=DEFAULT_COVERAGE_XML, help="Path to coverage.xml")
201
+ parser.add_argument("--summary-out", default=DEFAULT_SUMMARY_JSON, help="Path to write coverage_summary.json")
202
+ parser.add_argument("--line-floor", type=float, default=LINE_COVERAGE_FLOOR_PCT, help="Statement/line coverage floor")
203
+ parser.add_argument("--branch-floor", type=float, default=BRANCH_COVERAGE_FLOOR_PCT, help="Branch coverage floor")
204
+ parser.add_argument("--no-branch", action="store_true", help="Do not enforce branch coverage threshold")
205
+ parser.add_argument("--check", action="store_true", help="Fail with non-zero exit code if coverage is below threshold")
206
+ parser.add_argument("--json", action="store_true", help="Print summary JSON to stdout")
207
+ args = parser.parse_args()
208
+
209
+ if not os.path.exists(args.json_report):
210
+ sys.stderr.write(f"Error: Coverage JSON report not found at {args.json_report}.\n")
211
+ return 1
212
+
213
+ summary = generate_coverage_summary(
214
+ coverage_json=args.json_report,
215
+ coverage_xml=args.xml_report,
216
+ output_summary_json=args.summary_out,
217
+ line_floor=args.line_floor,
218
+ branch_floor=args.branch_floor,
219
+ enforce_branch=not args.no_branch,
220
+ )
221
+
222
+ if args.json:
223
+ print(json.dumps(summary, indent=2))
224
+ else:
225
+ m = summary["metrics"]
226
+ e = summary["evaluation"]
227
+ print("======================================================================")
228
+ print(" SYNAPSE HUB STANDARDIZED TEST COVERAGE REPORT ")
229
+ print("======================================================================")
230
+ print(f" Line Coverage (Statements) : {m['line_coverage_pct']}% (Floor: >= {args.line_floor}%) - {'✅ PASS' if e['line_passed'] else '❌ FAIL'}")
231
+ print(f" Branch Coverage : {m['branch_coverage_pct']}% (Floor: >= {args.branch_floor}%) - {'✅ PASS' if e['branch_passed'] else '❌ FAIL'}")
232
+ print(f" Combined (Stmt + Branch) : {m['combined_coverage_pct']}%")
233
+ print(f" Total Statements : {m['statements_total']:,} (Covered: {m['statements_covered']:,})")
234
+ print(f" Total Branches : {m['branches_total']:,} (Covered: {m['branches_covered']:,})")
235
+ print(f" Coverage Summary Artifact : {summary['artifacts']['summary_json']}")
236
+ print(f" Coverage XML Artifact : {summary['artifacts']['coverage_xml']}")
237
+ print("======================================================================")
238
+
239
+ if args.check and not summary["evaluation"]["all_passed"]:
240
+ return 1
241
+ return 0
242
+
243
+
244
+ if __name__ == "__main__":
245
+ sys.exit(main())
@@ -605,8 +605,8 @@ def build_swarm_timeline_html(default_lang: str = "vi") -> str:
605
605
  "name_vi": "3. Thực Thi Headless, API & Tải",
606
606
  "name_en": "3. Headless Run, API & Load",
607
607
  "agent": "test-runner / perf-engineer / api-engineer",
608
- "desc_vi": "Thực thi test headless qua CLI (E2E Playwright, API Newman & Tải k6/JMeter), tinh lọc log 95%",
609
- "desc_en": "Headless CLI (E2E, API & k6/JMeter Load), distill logs 95%, isolate failures",
608
+ "desc_vi": "Thực thi test headless qua CLI (E2E Playwright, API Newman & Tải k6/JMeter), tinh lọc log",
609
+ "desc_en": "Headless CLI (E2E, API & k6/JMeter Load), distill logs, isolate failures",
610
610
  "icon": "⚡",
611
611
  "badge": "PASS",
612
612
  },
@@ -1350,7 +1350,7 @@ def _build_target_translations(
1350
1350
  "th_step_status": "Trạng Thái",
1351
1351
  "th_step_details": "Chi Tiết Kỹ Thuật (OTel & AST)",
1352
1352
 
1353
- "footer_text": "Báo cáo được khởi tạo tự động bởi Synapse-Hub v4.1.4 &bull; Bản quyền &copy; Thế Vị (@TeeVee98) &bull; Chuẩn Clean POM & Kiểm Thử Tự Chủ",
1353
+ "footer_text": "Báo cáo được khởi tạo tự động bởi Synapse-Hub v4.2.1 &bull; Bản quyền &copy; Thế Vị (@TeeVee98) &bull; Chuẩn Clean POM & Kiểm Thử Tự Chủ",
1354
1354
  }
1355
1355
 
1356
1356
  translations_en = {
@@ -1428,7 +1428,7 @@ def _build_target_translations(
1428
1428
  "th_step_status": "Status",
1429
1429
  "th_step_details": "Technical Details (OTel & AST)",
1430
1430
 
1431
- "footer_text": "Generated automatically by Synapse-Hub v4.1.4 &bull; Copyright &copy; Thế Vị (@TeeVee98) &bull; Clean POM & Autonomous Testing",
1431
+ "footer_text": "Generated automatically by Synapse-Hub v4.2.1 &bull; Copyright &copy; Thế Vị (@TeeVee98) &bull; Clean POM & Autonomous Testing",
1432
1432
  }
1433
1433
 
1434
1434
  _inject_gate_translations(translations_vi, translations_en, gates)
@@ -1917,7 +1917,7 @@ def _build_hub_translations(
1917
1917
  """Builds bilingual dictionaries for Hub Dashboard."""
1918
1918
  translations_vi = {
1919
1919
  "header_title": "Bảng Điều Hành Chất Lượng Doanh Nghiệp",
1920
- "header_subtitle": "Synapse-Hub v4.1.4 &bull; Hệ Sinh Thái Kiểm Thử AI Agent Tự Chủ",
1920
+ "header_subtitle": "Synapse-Hub v4.2.1 &bull; Hệ Sinh Thái Kiểm Thử AI Agent Tự Chủ",
1921
1921
  "nav_welcome": "Giới Thiệu",
1922
1922
  "meta_mode": "🏷️ Chế độ: <strong>HỆ SINH THÁI QA HUB</strong>",
1923
1923
  "meta_gen": f"🕒 Khởi tạo: <strong>{now_str}</strong>",
@@ -1987,12 +1987,12 @@ def _build_hub_translations(
1987
1987
  "th_sk_ver": "Phiên Bản",
1988
1988
  "th_sk_cap": "Khả Năng Nghiệp Vụ Cốt Lõi",
1989
1989
 
1990
- "footer_text": "Bảng Điều Hành Chất Lượng Doanh Nghiệp &bull; Synapse-Hub v4.1.4 &bull; Bản quyền &copy; Thế Vị (@TeeVee98) &bull; Hệ Thống Kiểm Thử AI Agent Tự Chủ",
1990
+ "footer_text": "Bảng Điều Hành Chất Lượng Doanh Nghiệp &bull; Synapse-Hub v4.2.1 &bull; Bản quyền &copy; Thế Vị (@TeeVee98) &bull; Hệ Thống Kiểm Thử AI Agent Tự Chủ",
1991
1991
  }
1992
1992
 
1993
1993
  translations_en = {
1994
1994
  "header_title": "Enterprise QA Executive Dashboard",
1995
- "header_subtitle": "Synapse-Hub v4.1.4 &bull; Autonomous AI Agent Testing Ecosystem",
1995
+ "header_subtitle": "Synapse-Hub v4.2.1 &bull; Autonomous AI Agent Testing Ecosystem",
1996
1996
  "nav_welcome": "Welcome",
1997
1997
  "meta_mode": "🏷️ Mode: <strong>QA HUB ECOSYSTEM</strong>",
1998
1998
  "meta_gen": f"🕒 Generated: <strong>{now_str}</strong>",
@@ -2062,7 +2062,7 @@ def _build_hub_translations(
2062
2062
  "th_sk_ver": "Version",
2063
2063
  "th_sk_cap": "Core Capabilities",
2064
2064
 
2065
- "footer_text": "Enterprise QA Executive Dashboard &bull; Synapse-Hub v4.1.4 &bull; Copyright &copy; Thế Vị (@TeeVee98) &bull; Autonomous AI Agent Testing Ecosystem",
2065
+ "footer_text": "Enterprise QA Executive Dashboard &bull; Synapse-Hub v4.2.1 &bull; Copyright &copy; Thế Vị (@TeeVee98) &bull; Autonomous AI Agent Testing Ecosystem",
2066
2066
  }
2067
2067
 
2068
2068
  _inject_gate_translations(translations_vi, translations_en, gates)