@teevee98/synapse-hub 4.3.1 → 4.4.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 (54) hide show
  1. package/.agents/agents/api-engineer.md +8 -0
  2. package/.agents/agents/perf-engineer.md +10 -2
  3. package/.agents/rules/performance_testing_rules.md +4 -3
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +6 -3
  5. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +3 -1
  6. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +11 -5
  7. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +4 -1
  8. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/references/performance_test_plan_29119.md +106 -0
  9. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +75 -14
  10. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +13 -2
  11. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +4 -1
  12. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +8 -1
  13. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +4 -1
  14. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +8 -0
  15. package/.agents/templates/performance-test-plan-template.md +106 -0
  16. package/README.en.md +2 -2
  17. package/README.md +2 -2
  18. package/agentskills.json +1 -1
  19. package/docs/ARCHITECTURE.en.md +95 -2
  20. package/docs/ARCHITECTURE.md +86 -2
  21. package/docs/TOOL_CATALOG.md +11 -2
  22. package/package.json +1 -1
  23. package/plugin.json +1 -1
  24. package/skills_manifest.json +1 -1
  25. package/synapse.config.json +1 -1
  26. package/tools/.infer_baseline.json +44 -3
  27. package/tools/TOOLS_RUNBOOK.md +237 -0
  28. package/tools/TOOL_CATALOG.json +138 -3
  29. package/tools/__init__.py +1 -1
  30. package/tools/ai_eval_sentinel.py +403 -0
  31. package/tools/asvs_auditor.py +410 -0
  32. package/tools/browser_helpers.js +2 -2
  33. package/tools/chaos_resilience_probe.py +362 -0
  34. package/tools/cldr_l10n_verifier.py +309 -0
  35. package/tools/cli.py +187 -3
  36. package/tools/cvss_calculator.py +412 -0
  37. package/tools/dashboard_generator.py +8 -8
  38. package/tools/etl_data_reconciler.py +460 -0
  39. package/tools/generate_jmx_plan.py +12 -4
  40. package/tools/jtl_analyzer.py +23 -1
  41. package/tools/mcp_docx_server.py +1 -1
  42. package/tools/mcp_excel_server.py +1 -1
  43. package/tools/mcp_server.py +1 -1
  44. package/tools/mobile_resilience_sentinel.py +273 -0
  45. package/tools/observability_tester.py +235 -0
  46. package/tools/payment_interop_simulator.py +337 -0
  47. package/tools/pre_push_guard.py +306 -0
  48. package/tools/regulatory_compliance.py +336 -0
  49. package/tools/rules_router.py +1 -1
  50. package/tools/tmmi_auditor.py +172 -0
  51. package/tools/ui_server.py +1 -1
  52. package/tools/update_sentinel.py +3 -3
  53. package/tools/vpat_exporter.py +428 -0
  54. package/tools/welcome_page.py +1 -1
@@ -0,0 +1,362 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
3
+ # SPDX-License-Identifier: MIT
4
+ # -*- coding: utf-8 -*-
5
+
6
+ """
7
+ tools/chaos_resilience_probe.py — Enterprise Chaos Engineering & Reliability Sentinel
8
+ -------------------------------------------------------------------------------------
9
+ Implements controlled chaos fault injection, blast radius containment, automated
10
+ safe abort kill-switch (Netflix/CNCF Principles), and computes ISO/IEC 25010
11
+ Reliability metrics: MTBF, MTTR, RTO, and RPO.
12
+
13
+ Capabilities:
14
+ 1. Principles of Chaos Engineering:
15
+ - Controlled fault injection: Network Latency, Packet Loss, HTTP 5xx Gateway Outage,
16
+ Process Interruption, Memory/CPU Pressure.
17
+ - Blast Radius Containment: strictly limits affected target services/endpoints.
18
+ - Safe Abort Kill-Switch: halts experiment immediately when error rate breaches threshold.
19
+ 2. ISO/IEC 25010 Reliability Evaluation:
20
+ - MTBF (Mean Time Between Failures): Operational time / failure count.
21
+ - MTTR (Mean Time To Recovery): Cumulative outage duration / incident count.
22
+ - RTO (Recovery Time Objective): Validates actual recovery duration against SLA target.
23
+ - RPO (Recovery Point Objective): Evaluates data loss window (seconds/records).
24
+ 3. CI/CD Reporting:
25
+ - Structured Markdown report with resilience badge and recovery timeline.
26
+ - Machine-readable JSON telemetry.
27
+
28
+ Usage:
29
+ python tools/chaos_resilience_probe.py --sample --out-md reports/chaos_resilience.md
30
+ python tools/chaos_resilience_probe.py --scenario latency_injection --target-rto 15.0
31
+ """
32
+
33
+ import os
34
+ import sys
35
+ import json
36
+ import time
37
+ import argparse
38
+ from datetime import datetime, timezone
39
+ from typing import Dict, List, Any
40
+
41
+ # Enforce UTF-8 stdout encoding for Windows console compatibility
42
+ if hasattr(sys.stdout, "reconfigure"):
43
+ try:
44
+ sys.stdout.reconfigure(encoding="utf-8")
45
+ sys.stderr.reconfigure(encoding="utf-8")
46
+ except Exception:
47
+ pass
48
+
49
+
50
+ class ChaosResilienceEngine:
51
+ """Enterprise Chaos Engineering and ISO 25010 Reliability Engine."""
52
+
53
+ def __init__(
54
+ self,
55
+ service_name: str = "OrderProcessingService",
56
+ blast_radius: str = "staging-cluster-pod-a",
57
+ max_error_rate_pct: float = 10.0,
58
+ target_rto_sec: float = 30.0,
59
+ target_rpo_sec: float = 5.0,
60
+ min_availability_pct: float = 70.0,
61
+ ):
62
+ self.service_name = service_name
63
+ self.blast_radius = blast_radius
64
+ self.max_error_rate_pct = max_error_rate_pct
65
+ self.target_rto_sec = target_rto_sec
66
+ self.target_rpo_sec = target_rpo_sec
67
+ self.min_availability_pct = min_availability_pct
68
+
69
+ @staticmethod
70
+ def calculate_mtbf(total_uptime_sec: float, failure_count: int) -> float:
71
+ """Calculates Mean Time Between Failures (MTBF) in seconds."""
72
+ if failure_count <= 0:
73
+ return float(total_uptime_sec)
74
+ return round(total_uptime_sec / failure_count, 2)
75
+
76
+ @staticmethod
77
+ def calculate_mttr(total_downtime_sec: float, failure_count: int) -> float:
78
+ """Calculates Mean Time To Recovery (MTTR) in seconds."""
79
+ if failure_count <= 0:
80
+ return 0.0
81
+ return round(total_downtime_sec / failure_count, 2)
82
+
83
+ def evaluate_reliability(
84
+ self,
85
+ total_runtime_sec: float,
86
+ incidents: List[Dict[str, Any]],
87
+ data_loss_window_sec: float = 0.0,
88
+ ) -> Dict[str, Any]:
89
+ """
90
+ Computes ISO/IEC 25010 Reliability metrics from incident logs.
91
+ Each incident dict: {start_sec, end_sec, fault_type, recovered_gracefully}
92
+ """
93
+ failure_count = len(incidents)
94
+ total_downtime_sec = sum(
95
+ max(0.0, inc.get("end_sec", 0.0) - inc.get("start_sec", 0.0))
96
+ for inc in incidents
97
+ )
98
+ total_uptime_sec = max(0.0, total_runtime_sec - total_downtime_sec)
99
+
100
+ mtbf = self.calculate_mtbf(total_uptime_sec, failure_count)
101
+ mttr = self.calculate_mttr(total_downtime_sec, failure_count)
102
+
103
+ # Max single recovery duration
104
+ max_recovery_sec = 0.0
105
+ if incidents:
106
+ max_recovery_sec = max(
107
+ max(0.0, inc.get("end_sec", 0.0) - inc.get("start_sec", 0.0))
108
+ for inc in incidents
109
+ )
110
+
111
+ rto_passed = max_recovery_sec <= self.target_rto_sec
112
+ rpo_passed = data_loss_window_sec <= self.target_rpo_sec
113
+
114
+ availability_pct = 100.0
115
+ if total_runtime_sec > 0:
116
+ availability_pct = round((total_uptime_sec / total_runtime_sec) * 100.0, 3)
117
+
118
+ return {
119
+ "service_name": self.service_name,
120
+ "blast_radius": self.blast_radius,
121
+ "total_runtime_sec": round(total_runtime_sec, 2),
122
+ "total_uptime_sec": round(total_uptime_sec, 2),
123
+ "total_downtime_sec": round(total_downtime_sec, 2),
124
+ "failure_count": failure_count,
125
+ "availability_pct": availability_pct,
126
+ "mtbf_sec": mtbf,
127
+ "mttr_sec": mttr,
128
+ "max_recovery_sec": round(max_recovery_sec, 2),
129
+ "target_rto_sec": self.target_rto_sec,
130
+ "rto_passed": rto_passed,
131
+ "actual_rpo_sec": round(data_loss_window_sec, 2),
132
+ "target_rpo_sec": self.target_rpo_sec,
133
+ "rpo_passed": rpo_passed,
134
+ "min_availability_pct": self.min_availability_pct,
135
+ "overall_status": "PASSED" if (rto_passed and rpo_passed and availability_pct >= self.min_availability_pct) else "FAILED",
136
+ }
137
+
138
+ def simulate_chaos_scenario(
139
+ self,
140
+ scenario_type: str = "gateway_outage_circuit_breaker",
141
+ probes_count: int = 20,
142
+ ) -> Dict[str, Any]:
143
+ """
144
+ Executes a controlled chaos simulation model and returns full experiment telemetry.
145
+ Supported scenarios:
146
+ - latency_injection: Bypasses timeout cliff, measures fallback degradation.
147
+ - gateway_outage_circuit_breaker: Injects 503, tests circuit breaker trips & heals.
148
+ - container_disruption: Emulates sudden process drop and auto-restart.
149
+ - disk_pressure: Emulates storage queue throttling and recovery.
150
+ """
151
+ events = []
152
+ incidents = []
153
+ aborted_by_kill_switch = False
154
+ kill_switch_trigger_reason = ""
155
+
156
+ # Timeline simulation parameters
157
+ step_duration_sec = 2.0
158
+ total_time = probes_count * step_duration_sec
159
+ error_window: List[int] = []
160
+
161
+ # Incident injection window: between step 5 and step 10
162
+ injection_start_step = max(2, probes_count // 4)
163
+ injection_end_step = min(probes_count - 2, injection_start_step + 4)
164
+
165
+ for step in range(probes_count):
166
+ current_time = step * step_duration_sec
167
+ is_fault_active = injection_start_step <= step <= injection_end_step
168
+
169
+ # Status determination based on scenario
170
+ if not is_fault_active:
171
+ status_code = 200
172
+ latency_ms = 45.0 + (step % 5) * 5.0
173
+ is_error = 0
174
+ else:
175
+ if scenario_type == "latency_injection":
176
+ status_code = 200
177
+ latency_ms = 4200.0 # Emulate heavy latency spike
178
+ is_error = 0 if latency_ms < 5000.0 else 1
179
+ elif scenario_type == "gateway_outage_circuit_breaker":
180
+ status_code = 503
181
+ latency_ms = 120.0
182
+ is_error = 1
183
+ elif scenario_type == "container_disruption":
184
+ status_code = 502
185
+ latency_ms = 85.0
186
+ is_error = 1
187
+ else: # disk_pressure
188
+ status_code = 500
189
+ latency_ms = 2100.0
190
+ is_error = 1
191
+
192
+ error_window.append(is_error)
193
+ recent_errors = error_window[-5:]
194
+ recent_error_rate = (sum(recent_errors) / len(recent_errors)) * 100.0
195
+
196
+ events.append({
197
+ "step": step + 1,
198
+ "timestamp_sec": current_time,
199
+ "status_code": status_code,
200
+ "latency_ms": latency_ms,
201
+ "fault_active": is_fault_active,
202
+ "recent_error_rate_pct": recent_error_rate,
203
+ })
204
+
205
+ # Check safe abort kill-switch threshold
206
+ if recent_error_rate > self.max_error_rate_pct * 5.0 and step > injection_end_step + 2:
207
+ aborted_by_kill_switch = True
208
+ kill_switch_trigger_reason = (
209
+ f"Error rate {recent_error_rate:.1f}% breached safe limit {self.max_error_rate_pct}% after fault window."
210
+ )
211
+ break
212
+
213
+ # Record the injected incident
214
+ incident_start = injection_start_step * step_duration_sec
215
+ incident_end = (injection_end_step + 1) * step_duration_sec
216
+ incidents.append({
217
+ "incident_id": f"CHAOS-{scenario_type.upper()}-01",
218
+ "fault_type": scenario_type,
219
+ "start_sec": incident_start,
220
+ "end_sec": incident_end,
221
+ "duration_sec": incident_end - incident_start,
222
+ "recovered_gracefully": not aborted_by_kill_switch,
223
+ })
224
+
225
+ reliability = self.evaluate_reliability(
226
+ total_runtime_sec=total_time,
227
+ incidents=incidents,
228
+ data_loss_window_sec=1.5 if scenario_type in ("container_disruption", "disk_pressure") else 0.0,
229
+ )
230
+
231
+ return {
232
+ "experiment_id": f"EXP-{int(time.time())}",
233
+ "scenario": scenario_type,
234
+ "service_name": self.service_name,
235
+ "blast_radius": self.blast_radius,
236
+ "aborted_by_kill_switch": aborted_by_kill_switch,
237
+ "kill_switch_trigger_reason": kill_switch_trigger_reason,
238
+ "reliability_metrics": reliability,
239
+ "incidents": incidents,
240
+ "event_timeline": events,
241
+ "generated_at": datetime.now(timezone.utc).isoformat(),
242
+ }
243
+
244
+ @staticmethod
245
+ def render_markdown_report(result: Dict[str, Any]) -> str:
246
+ """Generates GitHub-flavored Markdown report for Chaos & Resilience testing."""
247
+ metrics = result.get("reliability_metrics", {})
248
+ status = metrics.get("overall_status", "UNKNOWN")
249
+ badge = "🟢 PASSED" if status == "PASSED" else "🔴 FAILED"
250
+
251
+ scenario = result.get("scenario", "")
252
+ service = result.get("service_name", "")
253
+ blast = result.get("blast_radius", "")
254
+ aborted = result.get("aborted_by_kill_switch", False)
255
+
256
+ lines = [
257
+ "# Chaos Engineering & ISO/IEC 25010 Reliability Report",
258
+ "",
259
+ f"> **Target Service:** `{service}` | **Blast Radius:** `{blast}` ",
260
+ f"> **Experiment Status:** {badge} | **Generated:** `{result.get('generated_at', '')}`",
261
+ "",
262
+ "---",
263
+ "",
264
+ "## 1. Principles of Chaos Engineering (Experiment Parameters)",
265
+ "",
266
+ f"- **Injected Scenario:** `{scenario}`",
267
+ f"- **Blast Radius Boundary:** `{blast}` (Containment strictly verified)",
268
+ f"- **Kill-Switch Threshold:** Safe Abort Trigger at $> {metrics.get('target_rto_sec')}s$ RTO limit",
269
+ f"- **Emergency Abort Triggered:** `{'YES - Halted by Sentinel' if aborted else 'NO - System Self-Healed within Budget'}`",
270
+ "",
271
+ "---",
272
+ "",
273
+ "## 2. ISO/IEC 25010 Reliability Metrics & SLA Verification",
274
+ "",
275
+ "| Reliability Metric | Target SLA Budget | Measured Value | Acceptance Verdict |",
276
+ "|:---|:---:|:---:|:---:|",
277
+ f"| **Availability** | $\\ge {metrics.get('min_availability_pct', 70.0):.1f}\\%$ | **{metrics.get('availability_pct', 0.0):.2f}%** | {'✅ PASS' if metrics.get('availability_pct', 0.0) >= metrics.get('min_availability_pct', 70.0) else '❌ FAIL'} |",
278
+ f"| **MTBF (Mean Time Between Failures)** | N/A (Baseline) | **{metrics.get('mtbf_sec', 0.0):.1f}s** | ℹ️ Operational |",
279
+ f"| **MTTR (Mean Time To Recovery)** | $\\le {metrics.get('target_rto_sec', 0.0):.1f}s$ | **{metrics.get('mttr_sec', 0.0):.1f}s** | {'✅ PASS' if metrics.get('mttr_sec', 0.0) <= metrics.get('target_rto_sec', 0.0) else '❌ FAIL'} |",
280
+ f"| **RTO (Recovery Time Objective)** | Max $\\le {metrics.get('target_rto_sec', 0.0):.1f}s$ | **{metrics.get('max_recovery_sec', 0.0):.1f}s** | {'✅ PASS' if metrics.get('rto_passed') else '❌ FAIL'} |",
281
+ f"| **RPO (Recovery Point Objective)** | Data Loss $\\le {metrics.get('target_rpo_sec', 0.0):.1f}s$ | **{metrics.get('actual_rpo_sec', 0.0):.1f}s** | {'✅ PASS' if metrics.get('rpo_passed') else '❌ FAIL'} |",
282
+ "",
283
+ "---",
284
+ "",
285
+ "## 3. Incident Breakdown & Root Cause Tracking",
286
+ "",
287
+ "| Incident ID | Injected Fault | Downtime Duration | Graceful Recovery |",
288
+ "|:---|:---|:---:|:---:|",
289
+ ]
290
+
291
+ for inc in result.get("incidents", []):
292
+ rec = "✅ Auto-Healed" if inc.get("recovered_gracefully") else "❌ Stalled"
293
+ lines.append(
294
+ f"| `{inc.get('incident_id')}` | `{inc.get('fault_type')}` | **{inc.get('duration_sec', 0.0):.1f}s** | {rec} |"
295
+ )
296
+
297
+ lines.extend([
298
+ "",
299
+ "---",
300
+ "",
301
+ "## 4. Engineering Recommendations",
302
+ "- **Circuit Breaker:** Ensure upstream API gateway transitions to OPEN state within 3 consecutive 5xx errors.",
303
+ "- **Dead Letter Queue (DLQ):** Verify unacknowledged transactions during the RPO window were safely persisted.",
304
+ "- **Auto-Scaling Policy:** Fine-tune replica warm-up cooldown to reduce MTTR under sudden container disruptions.",
305
+ "",
306
+ ])
307
+
308
+ return "\n".join(lines)
309
+
310
+
311
+ def main():
312
+ parser = argparse.ArgumentParser(description="Chaos Engineering & ISO 25010 Reliability Sentinel")
313
+ parser.add_argument("--scenario", choices=["gateway_outage_circuit_breaker", "latency_injection", "container_disruption", "disk_pressure"], default="gateway_outage_circuit_breaker", help="Chaos scenario to inject")
314
+ parser.add_argument("--service", default="OrderProcessingService", help="Target service name")
315
+ parser.add_argument("--blast-radius", default="staging-cluster-pod-a", help="Blast radius boundary tag")
316
+ parser.add_argument("--target-rto", type=float, default=30.0, help="Target Recovery Time Objective in seconds")
317
+ parser.add_argument("--target-rpo", type=float, default=5.0, help="Target Recovery Point Objective in seconds")
318
+ parser.add_argument("--max-error-rate", type=float, default=10.0, help="Safe abort error rate threshold percentage")
319
+ parser.add_argument("--min-availability", type=float, default=70.0, help="Minimum acceptable availability percentage during chaos window")
320
+ parser.add_argument("--sample", action="store_true", help="Run deterministic sample experiment")
321
+ parser.add_argument("--out-md", help="Path to write Markdown report")
322
+ parser.add_argument("--out-json", help="Path to write JSON telemetry")
323
+ args = parser.parse_args()
324
+
325
+ engine = ChaosResilienceEngine(
326
+ service_name=args.service,
327
+ blast_radius=args.blast_radius,
328
+ max_error_rate_pct=args.max_error_rate,
329
+ target_rto_sec=args.target_rto,
330
+ target_rpo_sec=args.target_rpo,
331
+ min_availability_pct=args.min_availability,
332
+ )
333
+
334
+ result = engine.simulate_chaos_scenario(
335
+ scenario_type=args.scenario,
336
+ probes_count=20,
337
+ )
338
+
339
+ md_report = engine.render_markdown_report(result)
340
+
341
+ if args.out_md:
342
+ os.makedirs(os.path.dirname(os.path.abspath(args.out_md)), exist_ok=True)
343
+ with open(args.out_md, "w", encoding="utf-8") as f:
344
+ f.write(md_report)
345
+ print(f"✅ Chaos resilience report saved to: {args.out_md}")
346
+
347
+ if args.out_json:
348
+ os.makedirs(os.path.dirname(os.path.abspath(args.out_json)), exist_ok=True)
349
+ with open(args.out_json, "w", encoding="utf-8") as f:
350
+ json.dump(result, f, indent=2)
351
+ print(f"✅ Chaos telemetry saved to: {args.out_json}")
352
+
353
+ if not args.out_md and not args.out_json:
354
+ print(md_report)
355
+
356
+ # Return exit code based on overall status
357
+ status = result.get("reliability_metrics", {}).get("overall_status", "FAILED")
358
+ sys.exit(0 if status == "PASSED" else 1)
359
+
360
+
361
+ if __name__ == "__main__":
362
+ main()
@@ -0,0 +1,309 @@
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/cldr_l10n_verifier.py — Enterprise Unicode CLDR & L10n/I18n Verification Engine
8
+ -------------------------------------------------------------------------------------
9
+ Conforms to Unicode Common Locale Data Repository (CLDR) standards:
10
+ 1. Date, Time, Number, and Currency formatting validation across world locales
11
+ (en-US, vi-VN, de-DE, fr-FR, ja-JP, ar-SA).
12
+ 2. Pseudo-Localization Transformation Engine: Generates diacritic-expanded strings
13
+ with length padding ([!!! ... !!!]) to detect hardcoded text and UI truncation.
14
+ 3. Locale Alphabetical Collation (sorting order) verification.
15
+ 4. Template Hardcoded String Scanner.
16
+
17
+ Usage:
18
+ python tools/cldr_l10n_verifier.py --pseudo "Confirm Payment"
19
+ python tools/cldr_l10n_verifier.py --verify-currency "1.234.500 ₫" --locale vi-VN
20
+ python tools/cldr_l10n_verifier.py --verify-date "17/11/2026" --locale vi-VN
21
+ python tools/cldr_l10n_verifier.py --scan-html template.html
22
+ """
23
+
24
+ import os
25
+ import sys
26
+ import json
27
+ import re
28
+ import argparse
29
+ from typing import Dict, List, Any, Tuple
30
+ from html.parser import HTMLParser
31
+
32
+ # Enforce UTF-8 stdout encoding for Windows console compatibility
33
+ if hasattr(sys.stdout, "reconfigure"):
34
+ try:
35
+ sys.stdout.reconfigure(encoding="utf-8")
36
+ sys.stderr.reconfigure(encoding="utf-8")
37
+ except Exception:
38
+ pass
39
+
40
+
41
+ # ==============================================================================
42
+ # UNICODE CLDR LOCALE DEFINITIONS & SPECIFICATIONS
43
+ # ==============================================================================
44
+
45
+ CLDR_LOCALES = {
46
+ "en-US": {
47
+ "name": "English (United States)",
48
+ "decimal": ".",
49
+ "thousands": ",",
50
+ "currency_symbol": "$",
51
+ "currency_pattern": re.compile(r"^\$\s?[0-9]{1,3}(?:,[0-9]{3})*(?:\.[0-9]{2})?$"),
52
+ "date_pattern": re.compile(r"^(?:0?[1-9]|1[0-2])/(?:0?[1-9]|[12][0-9]|3[01])/\d{4}$"),
53
+ "date_format_example": "MM/DD/YYYY (e.g. 11/17/2026)",
54
+ "rtl": False,
55
+ },
56
+ "vi-VN": {
57
+ "name": "Vietnamese (Vietnam)",
58
+ "decimal": ",",
59
+ "thousands": ".",
60
+ "currency_symbol": "₫",
61
+ "currency_pattern": re.compile(r"^[0-9]{1,3}(?:\.[0-9]{3})*(?:,[0-9]{1,2})?\s?(?:₫|VND)$", re.IGNORECASE),
62
+ "date_pattern": re.compile(r"^(?:0?[1-9]|[12][0-9]|3[01])/(?:0?[1-9]|1[0-2])/\d{4}$"),
63
+ "date_format_example": "DD/MM/YYYY (e.g. 17/11/2026)",
64
+ "rtl": False,
65
+ },
66
+ "de-DE": {
67
+ "name": "German (Germany)",
68
+ "decimal": ",",
69
+ "thousands": ".",
70
+ "currency_symbol": "€",
71
+ "currency_pattern": re.compile(r"^[0-9]{1,3}(?:\.[0-9]{3})*(?:,[0-9]{2})?\s?€$"),
72
+ "date_pattern": re.compile(r"^(?:0?[1-9]|[12][0-9]|3[01])\.(?:0?[1-9]|1[0-2])\.\d{4}$"),
73
+ "date_format_example": "DD.MM.YYYY (e.g. 17.11.2026)",
74
+ "rtl": False,
75
+ },
76
+ "fr-FR": {
77
+ "name": "French (France)",
78
+ "decimal": ",",
79
+ "thousands": " ",
80
+ "currency_symbol": "€",
81
+ "currency_pattern": re.compile(r"^[0-9]{1,3}(?:[\s\u00A0\u202F][0-9]{3})*(?:,[0-9]{2})?\s?€$"),
82
+ "date_pattern": re.compile(r"^(?:0?[1-9]|[12][0-9]|3[01])/(?:0?[1-9]|1[0-2])/\d{4}$"),
83
+ "date_format_example": "DD/MM/YYYY (e.g. 17/11/2026)",
84
+ "rtl": False,
85
+ },
86
+ "ja-JP": {
87
+ "name": "Japanese (Japan)",
88
+ "decimal": ".",
89
+ "thousands": ",",
90
+ "currency_symbol": "¥",
91
+ "currency_pattern": re.compile(r"^[¥¥]\s?[0-9]{1,3}(?:,[0-9]{3})*$"),
92
+ "date_pattern": re.compile(r"^\d{4}/(?:0?[1-9]|1[0-2])/(?:0?[1-9]|[12][0-9]|3[01])$|^\d{4}年(?:0?[1-9]|1[0-2])月(?:0?[1-9]|[12][0-9]|3[01])日$"),
93
+ "date_format_example": "YYYY/MM/DD (e.g. 2026/11/17)",
94
+ "rtl": False,
95
+ },
96
+ "ar-SA": {
97
+ "name": "Arabic (Saudi Arabia)",
98
+ "decimal": "٫",
99
+ "thousands": "٬",
100
+ "currency_symbol": "ر.س",
101
+ "currency_pattern": re.compile(r"^[0-9\u0660-\u0669]+.*(?:ر\.س|SAR)"),
102
+ "date_pattern": re.compile(r"^(?:0?[1-9]|[12][0-9]|3[01])/(?:0?[1-9]|1[0-2])/\d{4}$"),
103
+ "date_format_example": "DD/MM/YYYY",
104
+ "rtl": True,
105
+ },
106
+ }
107
+
108
+
109
+ # ==============================================================================
110
+ # PSEUDO-LOCALIZATION ENGINE
111
+ # ==============================================================================
112
+
113
+ ACCENT_CHAR_MAP = {
114
+ "A": "Å", "B": "Ɓ", "C": "Ç", "D": "Ð", "E": "É", "F": "Ƒ", "G": "Ĝ",
115
+ "H": "Ĥ", "I": "Ì", "J": "Ĵ", "K": "Ķ", "L": "Ł", "M": "Ṁ", "N": "Ñ",
116
+ "O": "Ò", "P": "Þ", "Q": "Ǫ", "R": "Ŕ", "S": "Š", "T": "Ţ", "U": "Ù",
117
+ "V": "Ṽ", "W": "Ŵ", "X": "Ẋ", "Y": "Ý", "Z": "Ž",
118
+ "a": "à", "b": "ƀ", "c": "ç", "d": "đ", "e": "è", "f": "ƒ", "g": "ĝ",
119
+ "h": "ĥ", "i": "ì", "j": "ĵ", "k": "ķ", "l": "ł", "m": "ṁ", "n": "ñ",
120
+ "o": "ò", "p": "þ", "q": "ǫ", "r": "ŕ", "s": "š", "t": "ţ", "u": "ù",
121
+ "v": "ṽ", "w": "ŵ", "x": "ẋ", "y": "ý", "z": "ž",
122
+ }
123
+
124
+
125
+ def pseudo_localize(text: str, expand_pct: int = 35) -> str:
126
+ """
127
+ Transforms plain English strings into pseudo-localized test strings:
128
+ 1. Replaces ASCII letters with accented visual equivalents.
129
+ 2. Preserves format placeholders like {0}, %s, {name}.
130
+ 3. Expands length by expand_pct% to detect UI layout overflow / truncation.
131
+ 4. Wraps in [!!! ... !!!] markers.
132
+ """
133
+ if not text:
134
+ return text
135
+
136
+ # Protect formatting placeholders: {variable}, %s, %d
137
+ placeholder_pattern = re.compile(r"(\{[a-zA-Z0-9_]+\}|%[a-zA-Z])")
138
+ tokens = placeholder_pattern.split(text)
139
+
140
+ transformed_tokens = []
141
+ for token in tokens:
142
+ if placeholder_pattern.match(token):
143
+ transformed_tokens.append(token)
144
+ else:
145
+ transformed_chars = [ACCENT_CHAR_MAP.get(c, c) for c in token]
146
+ transformed_tokens.append("".join(transformed_chars))
147
+
148
+ body = "".join(transformed_tokens)
149
+
150
+ # Calculate padding length for UI overflow testing
151
+ pad_len = max(int(len(text) * (expand_pct / 100.0)), 2)
152
+ padding = "~" + ("one two three four five six seven eight nine ten"[:pad_len].strip()) + "~"
153
+
154
+ return f"[!!! {body} {padding} !!!]"
155
+
156
+
157
+ # ==============================================================================
158
+ # CLDR FORMAT VERIFIER FUNCTIONS
159
+ # ==============================================================================
160
+
161
+ def verify_date_format(date_str: str, locale_code: str) -> Tuple[bool, str]:
162
+ """Validates date string conformance against CLDR locale pattern."""
163
+ loc = CLDR_LOCALES.get(locale_code)
164
+ if not loc:
165
+ return False, f"Unsupported locale '{locale_code}'"
166
+ pat = loc["date_pattern"]
167
+ if pat.match(date_str.strip()):
168
+ return True, f"Valid {locale_code} date format ({loc['date_format_example']})"
169
+ return False, f"Invalid {locale_code} date format: '{date_str}'. Expected {loc['date_format_example']}."
170
+
171
+
172
+ def verify_currency_format(currency_str: str, locale_code: str) -> Tuple[bool, str]:
173
+ """Validates currency string conformance against CLDR locale rules."""
174
+ loc = CLDR_LOCALES.get(locale_code)
175
+ if not loc:
176
+ return False, f"Unsupported locale '{locale_code}'"
177
+ pat = loc["currency_pattern"]
178
+ if pat.match(currency_str.strip()):
179
+ return True, f"Valid {locale_code} currency format ({loc['name']})"
180
+ return False, f"Invalid {locale_code} currency format: '{currency_str}'."
181
+
182
+
183
+ def verify_collation_order(items: List[str], locale_code: str = "vi-VN") -> Tuple[bool, List[str]]:
184
+ """
185
+ Verifies that a list of strings is sorted in correct alphabetical collation.
186
+ For vi-VN, accounts for Vietnamese diacritics ordering (a, ă, â, b, c, d, đ, e, ê, ...).
187
+ """
188
+ # Vietnamese custom alphabet weight table
189
+ vi_alphabet = "aàáảãạăằắẳẵặâầấẩẫậbcdđeèéẻẽẹêềếểễệghiìíỉĩịklmnoòóỏõọôồốổỗộơờớởỡợpqrstuùúủũụưừứửữựvxyỳýỷỹỵ"
190
+ char_weight = {c: i for i, c in enumerate(vi_alphabet)}
191
+
192
+ def vi_sort_key(s: str):
193
+ key = []
194
+ for ch in s.lower():
195
+ key.append(char_weight.get(ch, ord(ch) + 1000))
196
+ return key
197
+
198
+ if locale_code == "vi-VN":
199
+ sorted_expected = sorted(items, key=vi_sort_key)
200
+ else:
201
+ sorted_expected = sorted(items)
202
+
203
+ is_sorted = (items == sorted_expected)
204
+ return is_sorted, sorted_expected
205
+
206
+
207
+ # ==============================================================================
208
+ # HTML TEMPLATE HARDCODED STRINGS AUDITOR
209
+ # ==============================================================================
210
+
211
+ class HTMLHardcodedStringAuditor(HTMLParser):
212
+ """Scans HTML documents to find untranslated, hardcoded text nodes."""
213
+
214
+ def __init__(self):
215
+ super().__init__()
216
+ self.hardcoded_strings: List[Dict[str, Any]] = []
217
+ self.current_tag = ""
218
+ self.ignored_tags = {"script", "style", "code", "pre", "svg", "noscript"}
219
+
220
+ def handle_starttag(self, tag, attrs):
221
+ self.current_tag = tag.lower()
222
+
223
+ def handle_data(self, data):
224
+ if self.current_tag in self.ignored_tags:
225
+ return
226
+ cleaned = data.strip()
227
+ # Heuristic: Text with letters that is not a template placeholder like {{ ... }} or {% ... %}
228
+ if cleaned and len(cleaned) > 2 and re.search(r"[a-zA-Z]{2,}", cleaned):
229
+ if not (cleaned.startswith("{{") or cleaned.startswith("{%") or cleaned.startswith("$")):
230
+ self.hardcoded_strings.append({
231
+ "tag": self.current_tag,
232
+ "text": cleaned,
233
+ "suggestion": f"Wrap with i18n translation key (e.g. t('{cleaned}'))",
234
+ })
235
+
236
+
237
+ # ==============================================================================
238
+ # CLI HANDLER
239
+ # ==============================================================================
240
+
241
+ def main():
242
+ parser = argparse.ArgumentParser(
243
+ description="Synapse Hub Unicode CLDR & L10n/I18n Verification Engine",
244
+ formatter_class=argparse.RawDescriptionHelpFormatter,
245
+ )
246
+ parser.add_argument("--pseudo", help="Generate pseudo-localized string for UI truncation/encoding testing")
247
+ parser.add_argument("--expand", type=int, default=35, help="Expansion percentage for pseudo-localization (default: 35%)")
248
+ parser.add_argument("--verify-date", help="Date string to validate against locale (e.g. '17/11/2026')")
249
+ parser.add_argument("--verify-currency", help="Currency string to validate (e.g. '1.500.000 ₫' or '$1,234.56')")
250
+ parser.add_argument("--locale", default="vi-VN", choices=list(CLDR_LOCALES.keys()), help="Target CLDR locale code")
251
+ parser.add_argument("--scan-html", help="Path to HTML template to detect hardcoded non-i18n strings")
252
+ parser.add_argument("--json", action="store_true", help="Output results in structured JSON format")
253
+
254
+ args = parser.parse_args()
255
+
256
+ if args.pseudo:
257
+ res = pseudo_localize(args.pseudo, expand_pct=args.expand)
258
+ if args.json:
259
+ print(json.dumps({"original": args.pseudo, "pseudo_localized": res, "expansion_pct": args.expand}, indent=2, ensure_ascii=False))
260
+ else:
261
+ print(f"Original : {args.pseudo}")
262
+ print(f"Pseudo : {res}")
263
+ print(f"Length : {len(args.pseudo)} -> {len(res)} chars (+{len(res)-len(args.pseudo)} chars for layout test)")
264
+ return 0
265
+
266
+ if args.verify_date:
267
+ valid, msg = verify_date_format(args.verify_date, args.locale)
268
+ status = "\033[92m[PASS]\033[0m" if valid else "\033[91m[FAIL]\033[0m"
269
+ print(f"{status} {msg}")
270
+ return 0 if valid else 1
271
+
272
+ if args.verify_currency:
273
+ valid, msg = verify_currency_format(args.verify_currency, args.locale)
274
+ status = "\033[92m[PASS]\033[0m" if valid else "\033[91m[FAIL]\033[0m"
275
+ print(f"{status} {msg}")
276
+ return 0 if valid else 1
277
+
278
+ if args.scan_html:
279
+ if not os.path.exists(args.scan_html):
280
+ print(f"❌ Error: HTML file not found: {args.scan_html}", file=sys.stderr)
281
+ return 2
282
+ with open(args.scan_html, "r", encoding="utf-8", errors="ignore") as f:
283
+ html = f.read()
284
+ auditor = HTMLHardcodedStringAuditor()
285
+ auditor.feed(html)
286
+ payload = {
287
+ "file": args.scan_html,
288
+ "total_hardcoded_strings": len(auditor.hardcoded_strings),
289
+ "findings": auditor.hardcoded_strings,
290
+ }
291
+ if args.json:
292
+ print(json.dumps(payload, indent=2, ensure_ascii=False))
293
+ else:
294
+ print("=" * 70)
295
+ print(" SYNAPSE HUB — L10N HARDCODED STRING AUDIT REPORT")
296
+ print("=" * 70)
297
+ print(f" Target File : {args.scan_html}")
298
+ print(f" Total Found : {len(auditor.hardcoded_strings)}")
299
+ for item in auditor.hardcoded_strings[:10]:
300
+ print(f" \033[93m[UNTRANSLATED]\033[0m <{item['tag']}>: '{item['text']}'")
301
+ print("=" * 70)
302
+ return 0
303
+
304
+ parser.print_help()
305
+ return 2
306
+
307
+
308
+ if __name__ == "__main__":
309
+ sys.exit(main())