@teevee98/synapse-hub 0.0.0-stage → 3.8.2

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 (369) hide show
  1. package/.agents/agents/api-engineer.md +67 -0
  2. package/.agents/agents/failure-analyst.md +75 -0
  3. package/.agents/agents/live-explorer.md +70 -0
  4. package/.agents/agents/orchestrator.md +104 -0
  5. package/.agents/agents/perf-engineer.md +74 -0
  6. package/.agents/agents/pom-crafter.md +112 -0
  7. package/.agents/agents/quality-gatekeeper.md +87 -0
  8. package/.agents/agents/test-designer.md +73 -0
  9. package/.agents/agents/test-runner.md +67 -0
  10. package/.agents/rules/author-integrity-guard.md +33 -0
  11. package/.agents/rules/communication-style.md +18 -0
  12. package/.agents/rules/context-engineering.md +37 -0
  13. package/.agents/rules/git-push-protocol.md +33 -0
  14. package/.agents/rules/graphify.md +14 -0
  15. package/.agents/rules/lessons-learned.md +25 -0
  16. package/.agents/rules/mandatory-playwright-live.md +25 -0
  17. package/.agents/rules/mobile_appium_rules.md +43 -0
  18. package/.agents/rules/performance_testing_rules.md +35 -0
  19. package/.agents/rules/skill-precedence.md +29 -0
  20. package/.agents/rules/systematic-debugging.md +36 -0
  21. package/.agents/skills/actor-qa-swarm/SKILL.md +77 -0
  22. package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json +12 -0
  23. package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +88 -0
  24. package/.agents/skills/agent-orchestration-multi-agent-optimize/examples/swarm_workload_config.json +15 -0
  25. package/.agents/skills/agentless-qa-repair/SKILL.md +69 -0
  26. package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json +17 -0
  27. package/.agents/skills/agentless-qa-repair/examples/three_phase_repair_workflow.md +40 -0
  28. package/.agents/skills/antigravity-test-sentinel/SKILL.md +63 -0
  29. package/.agents/skills/antigravity-test-sentinel/examples/dod_gate_policy.json +11 -0
  30. package/.agents/skills/antigravity-test-sentinel/examples/sprint_dod_enforcement.md +47 -0
  31. package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
  32. package/.agents/skills/api-network-mocking-interception/examples/network_route_stub.json +9 -0
  33. package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +80 -0
  34. package/.agents/skills/api-spec-to-e2e-matrix/examples/sample_openapi.json +19 -0
  35. package/.agents/skills/architecture-decision-records/SKILL.md +64 -0
  36. package/.agents/skills/architecture-decision-records/examples/0001-record-architecture-decisions.md +12 -0
  37. package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +75 -0
  38. package/.agents/skills/auth-session-and-cookie-manager/examples/multi_role_auth_matrix.md +70 -0
  39. package/.agents/skills/auth-session-and-cookie-manager/examples/storage_state_sample.json +11 -0
  40. package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +85 -0
  41. package/.agents/skills/backend-load-and-stress-patterns/examples/k6_load_test_sample.js +13 -0
  42. package/.agents/skills/backend-load-and-stress-patterns/references/k6_load_template.js +82 -0
  43. package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
  44. package/.agents/skills/bats-testing-patterns/examples/cli_runner_test.bats +6 -0
  45. package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
  46. package/.agents/skills/clean-pom-crafter/SKILL.md +110 -0
  47. package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
  48. package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
  49. package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
  50. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +9 -0
  51. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +52 -0
  52. package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +881 -0
  53. package/.agents/skills/consumer-driven-contract-testing/SKILL.md +147 -0
  54. package/.agents/skills/consumer-driven-contract-testing/examples/order_service_pact.json +45 -0
  55. package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
  56. package/.agents/skills/db-state-verifier-and-seeder/examples/db_fixture_seed.json +12 -0
  57. package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
  58. package/.agents/skills/e2e-testing-patterns/examples/playwright_sharded_config.ts +12 -0
  59. package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
  60. package/.agents/skills/event-stream-qa-orchestrator/SKILL.md +79 -0
  61. package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl +2 -0
  62. package/.agents/skills/failure-autopsy-and-healing/SKILL.md +66 -0
  63. package/.agents/skills/failure-autopsy-and-healing/examples/closed_loop_healing_walkthrough.md +48 -0
  64. package/.agents/skills/failure-autopsy-and-healing/examples/sample_junit_failure.xml +8 -0
  65. package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
  66. package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
  67. package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +83 -0
  68. package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
  69. package/.agents/skills/file-and-report-validator/examples/sample_export_schema.json +14 -0
  70. package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
  71. package/.agents/skills/flaky-test-sentinel-and-quarantine/examples/quarantine_registry.json +11 -0
  72. package/.agents/skills/gherkin-to-suite/SKILL.md +103 -0
  73. package/.agents/skills/gherkin-to-suite/examples/checkout.feature +39 -0
  74. package/.agents/skills/gherkin-to-suite/examples/suite_report_sample.json +334 -0
  75. package/.agents/skills/github-actions-templates/SKILL.md +77 -0
  76. package/.agents/skills/github-actions-templates/examples/matrix_test_pipeline.yml +8 -0
  77. package/.agents/skills/graphify-impact-analyzer/SKILL.md +76 -0
  78. package/.agents/skills/graphify-impact-analyzer/examples/dependency_blast_radius.json +8 -0
  79. package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
  80. package/.agents/skills/katalon-cli-runner/examples/headless_kre_exec.sh +3 -0
  81. package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
  82. package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
  83. package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
  84. package/.agents/skills/lam-script-generator/SKILL.md +123 -0
  85. package/.agents/skills/lam-script-generator/examples/user_story_sample.md +8 -0
  86. package/.agents/skills/lean-code-ladder/SKILL.md +94 -0
  87. package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md +37 -0
  88. package/.agents/skills/lean-impact-scoreboard/SKILL.md +48 -0
  89. package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md +20 -0
  90. package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md +15 -0
  91. package/.agents/skills/meta-prompt-crafter/SKILL.md +107 -0
  92. package/.agents/skills/meta-prompt-crafter/examples/qa_prompt_template.md +35 -0
  93. package/.agents/skills/mipro-prompt-compiler/SKILL.md +59 -0
  94. package/.agents/skills/mipro-prompt-compiler/examples/compiled_module_sample.json +22 -0
  95. package/.agents/skills/mipro-prompt-compiler/examples/dspy_assertion_optimizer_case.md +46 -0
  96. package/.agents/skills/mobile-appium-som/SKILL.md +88 -0
  97. package/.agents/skills/mobile-appium-som/examples/BaseScreen.java +88 -0
  98. package/.agents/skills/mobile-appium-som/examples/LoginScreen.java +46 -0
  99. package/.agents/skills/mobile-appium-som/examples/TC_MobileLogin.java +43 -0
  100. package/.agents/skills/persistent-planning-files/SKILL.md +108 -0
  101. package/.agents/skills/persistent-planning-files/examples/task_plan_example.md +56 -0
  102. package/.agents/skills/playwright-live-interaction/SKILL.md +131 -0
  103. package/.agents/skills/playwright-live-interaction/examples/live_probe_script.js +5 -0
  104. package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
  105. package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
  106. package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
  107. package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
  108. package/.agents/skills/playwright-webapp-testing/SKILL.md +93 -0
  109. package/.agents/skills/playwright-webapp-testing/examples/server_lifecycle_playwright.py +63 -0
  110. package/.agents/skills/qa-aci-interface/SKILL.md +67 -0
  111. package/.agents/skills/qa-aci-interface/examples/surgical_code_window_walkthrough.md +40 -0
  112. package/.agents/skills/qa-aci-interface/examples/surgical_edit_sample.json +12 -0
  113. package/.agents/skills/qa-memory-os/SKILL.md +80 -0
  114. package/.agents/skills/qa-memory-os/examples/archival_memory_sample.json +21 -0
  115. package/.agents/skills/rbt-manual-testing/SKILL.md +137 -0
  116. package/.agents/skills/rbt-manual-testing/examples/checkout_rbt_manual_suite.md +25 -0
  117. package/.agents/skills/rbt-manual-testing/references/field_validation_checklist.md +29 -0
  118. package/.agents/skills/repo-quality-audit/SKILL.md +68 -0
  119. package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md +15 -0
  120. package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md +33 -0
  121. package/.agents/skills/review-spec/SKILL.md +60 -0
  122. package/.agents/skills/review-spec/examples/pocock_grilling_decision_rubric.md +40 -0
  123. package/.agents/skills/review-spec/examples/sample_spec_review.md +33 -0
  124. package/.agents/skills/security-dast-sentinel/SKILL.md +119 -0
  125. package/.agents/skills/security-dast-sentinel/examples/dast_scan_config.json +10 -0
  126. package/.agents/skills/security-dast-sentinel/references/AI-AND-LLM.md +113 -0
  127. package/.agents/skills/security-dast-sentinel/references/ATTACK-CLASSES.md +89 -0
  128. package/.agents/skills/security-dast-sentinel/references/dast_recipes.ts +33 -0
  129. package/.agents/skills/self-healing-locator/SKILL.md +86 -0
  130. package/.agents/skills/self-healing-locator/examples/aom_diff_sample.json +16 -0
  131. package/.agents/skills/senior-code-review/SKILL.md +108 -0
  132. package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md +29 -0
  133. package/.agents/skills/skillspector-security-guard/SKILL.md +57 -0
  134. package/.agents/skills/skillspector-security-guard/examples/audit_threat_vectors_report.json +35 -0
  135. package/.agents/skills/skillspector-security-guard/examples/safe_mcp_config.json +12 -0
  136. package/.agents/skills/surgical-coding-principles/SKILL.md +89 -0
  137. package/.agents/skills/surgical-coding-principles/examples/surgical_vs_scope_creep.md +46 -0
  138. package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
  139. package/.agents/skills/synthetic-test-data-generator/examples/idempotent_data_recipe.json +9 -0
  140. package/.agents/skills/systematic-debugging/SKILL.md +100 -0
  141. package/.agents/skills/systematic-debugging/examples/four_phase_case.md +44 -0
  142. package/.agents/skills/technical-debt-harvester/SKILL.md +70 -0
  143. package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md +25 -0
  144. package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md +20 -0
  145. package/.agents/skills/test-driven-development/SKILL.md +114 -0
  146. package/.agents/skills/test-driven-development/examples/red_green_refactor_qa.md +78 -0
  147. package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
  148. package/.agents/skills/token-and-context-optimizer/examples/distilled_log_sample.txt +3 -0
  149. package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md +49 -0
  150. package/.agents/skills/tot-exploratory-testing/SKILL.md +59 -0
  151. package/.agents/skills/tot-exploratory-testing/examples/payment_gateway_tot_tree.json +62 -0
  152. package/.agents/skills/tot-exploratory-testing/examples/tot_graph_sample.json +35 -0
  153. package/.agents/skills/verification-before-completion/SKILL.md +100 -0
  154. package/.agents/skills/verification-before-completion/examples/evidence_log_example.md +46 -0
  155. package/.agents/skills/visual-regression-sentinel/SKILL.md +82 -0
  156. package/.agents/skills/visual-regression-sentinel/examples/visual_mask_rules.json +9 -0
  157. package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
  158. package/.agents/skills/wcag-audit-patterns/examples/wcag_compliance_checklist.json +10 -0
  159. package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
  160. package/.agents/skills/web-agent-gym-benchmarking/SKILL.md +62 -0
  161. package/.agents/skills/web-agent-gym-benchmarking/examples/benchmark_report_sample.json +22 -0
  162. package/.agents/skills/web-agent-gym-benchmarking/examples/enterprise_tasks_suite.json +38 -0
  163. package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
  164. package/.agents/skills/web-vitals-and-performance-profiler/examples/cwv_budget_policy.json +6 -0
  165. package/.agents/skills/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +118 -0
  166. package/.agents/templates/completion_report.md +57 -0
  167. package/.agents/workflows/analyze_requirement_document.md +18 -0
  168. package/.agents/workflows/export_testcases_excel.md +32 -0
  169. package/.agents/workflows/generate_combinatorial_test_data.md +28 -0
  170. package/.agents/workflows/generate_cross_module_test_plan.md +37 -0
  171. package/.agents/workflows/generate_manual_testcases_rbt.md +56 -0
  172. package/.agents/workflows/generate_requirements_from_website.md +25 -0
  173. package/.agents/workflows/generate_testcases_from_requirements.md +21 -0
  174. package/.agents/workflows/graphify.md +10 -0
  175. package/.agents/workflows/test-impact.md +15 -0
  176. package/.agents/workflows/verify.md +34 -0
  177. package/.cursor/rules/agents.mdc +16 -0
  178. package/.cursor/rules/language.mdc +7 -0
  179. package/.cursor/rules/synapse-qa.mdc +24 -0
  180. package/.cursorrules +27 -0
  181. package/.dockerignore +53 -0
  182. package/.pre-commit-hooks.yaml +14 -0
  183. package/.windsurfrules +26 -0
  184. package/AGENTS.md +86 -0
  185. package/CLAUDE.md +54 -0
  186. package/Dockerfile +81 -0
  187. package/LICENSE +52 -0
  188. package/NOTICE +264 -0
  189. package/README.en.md +172 -0
  190. package/README.md +171 -2
  191. package/action.yml +51 -0
  192. package/agentskills.json +16 -0
  193. package/bin/agent-qa.js +138 -0
  194. package/docker-compose.yml +74 -0
  195. package/docs/ARCHITECTURE.en.md +197 -0
  196. package/docs/ARCHITECTURE.md +198 -0
  197. package/docs/CI_CD_INTEGRATION.en.md +170 -0
  198. package/docs/CI_CD_INTEGRATION.md +170 -0
  199. package/docs/CLI_REFERENCE.en.md +175 -0
  200. package/docs/CLI_REFERENCE.md +177 -0
  201. package/docs/CONTRIBUTING.en.md +49 -0
  202. package/docs/CONTRIBUTING.md +49 -0
  203. package/docs/PERFORMANCE_AUDIT_REPORT.md +784 -0
  204. package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
  205. package/docs/QUALITY_GATES.en.md +121 -0
  206. package/docs/QUALITY_GATES.md +121 -0
  207. package/docs/TOKEN_QUOTA_PLAYBOOK.md +41 -0
  208. package/docs/TOOL_CATALOG.md +129 -0
  209. package/docs/adopted-ecosystem-tools.md +96 -0
  210. package/docs/research/EXTERNAL_AGENT_SKILLS_SURVEY.md +1062 -0
  211. package/docs/research/agent_skill_training_analysis.md +1359 -0
  212. package/docs/schemas/synapse.config.schema.json +87 -0
  213. package/package.json +94 -4
  214. package/plugin.json +31 -0
  215. package/scripts/generate_skill_examples.py +244 -0
  216. package/scripts/install.ps1 +112 -0
  217. package/scripts/install_global_plugin.ps1 +94 -0
  218. package/scripts/install_global_plugin.sh +49 -0
  219. package/scripts/lint_skills.ps1 +57 -0
  220. package/scripts/package_dist.py +337 -0
  221. package/scripts/setup.sh +59 -0
  222. package/scripts/update_hub.ps1 +19 -0
  223. package/scripts/update_hub.sh +15 -0
  224. package/skills_manifest.json +854 -0
  225. package/synapse.config.json +32 -0
  226. package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +111 -0
  227. package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
  228. package/templates/ai_bridges/CLAUDE.md +54 -0
  229. package/templates/ai_bridges/copilot-instructions.md +20 -0
  230. package/templates/ai_bridges/cursor_synapse_qa.mdc +24 -0
  231. package/templates/ai_bridges/windsurfrules +26 -0
  232. package/templates/ci/github-actions-synapse.yml +95 -0
  233. package/templates/ci/gitlab-ci-synapse.yml +16 -0
  234. package/templates/ui/index.html +1069 -0
  235. package/templates/welcome.html.tmpl +2079 -0
  236. package/tools/.infer_baseline.json +30 -0
  237. package/tools/TOOLS_RUNBOOK.md +1553 -0
  238. package/tools/TOOL_CATALOG.json +1769 -0
  239. package/tools/__init__.py +43 -0
  240. package/tools/_openapi_parser.py +158 -0
  241. package/tools/agent_canary.py +525 -0
  242. package/tools/agentless_patcher.py +417 -0
  243. package/tools/analyze_project.py +258 -0
  244. package/tools/api_drift_sentinel.py +208 -0
  245. package/tools/api_fuzzer.py +762 -0
  246. package/tools/author_integrity.py +184 -0
  247. package/tools/auto_heal.py +271 -0
  248. package/tools/auto_heal_reflexion.py +532 -0
  249. package/tools/autogen_qa_broker.py +844 -0
  250. package/tools/benchmark_swarm_context.py +394 -0
  251. package/tools/browser_helpers.js +746 -0
  252. package/tools/browsergym_eval.py +236 -0
  253. package/tools/bug_reporter.py +252 -0
  254. package/tools/bump_version.py +423 -0
  255. package/tools/cache_resolver.py +1214 -0
  256. package/tools/check_env.py +426 -0
  257. package/tools/check_version_sync.py +256 -0
  258. package/tools/ci_healing_hook.py +126 -0
  259. package/tools/cli.py +1598 -0
  260. package/tools/config_decoupler.py +253 -0
  261. package/tools/contract_validator.py +141 -0
  262. package/tools/core/__init__.py +70 -0
  263. package/tools/core/adapters.py +431 -0
  264. package/tools/core/circuit_breaker.py +263 -0
  265. package/tools/core/cli_runtime.py +66 -0
  266. package/tools/core/file_lock.py +159 -0
  267. package/tools/core/i18n.py +394 -0
  268. package/tools/core/memory_bus.py +905 -0
  269. package/tools/core/process_supervisor.py +332 -0
  270. package/tools/core/telemetry.py +329 -0
  271. package/tools/count_tokens.py +1267 -0
  272. package/tools/create_mock_docx.py +104 -0
  273. package/tools/dashboard_generator.py +2419 -0
  274. package/tools/db_sandbox.py +675 -0
  275. package/tools/debt_harvester.py +237 -0
  276. package/tools/distill_log.py +161 -0
  277. package/tools/dspy_qa_signatures.py +356 -0
  278. package/tools/e2e_flow_prober.py +132 -0
  279. package/tools/export_postman_collection.py +945 -0
  280. package/tools/flaky_detector.py +389 -0
  281. package/tools/fsm_enforcer.py +450 -0
  282. package/tools/fsm_middleware.py +401 -0
  283. package/tools/fuzz_payloads.py +197 -0
  284. package/tools/generate_allure_report.py +88 -0
  285. package/tools/generate_api_matrix.py +193 -0
  286. package/tools/generate_jmx_plan.py +1322 -0
  287. package/tools/generate_sbom.py +252 -0
  288. package/tools/generate_tc_from_story.py +203 -0
  289. package/tools/generate_test_reports.py +133 -0
  290. package/tools/generate_tool_catalog.py +482 -0
  291. package/tools/gherkin_suite.py +758 -0
  292. package/tools/git_pre_commit_guard.py +298 -0
  293. package/tools/goldfish_review.py +366 -0
  294. package/tools/heal/__init__.py +28 -0
  295. package/tools/heal_pr_automator.py +220 -0
  296. package/tools/heuristic_locator_matcher.py +351 -0
  297. package/tools/hub_publisher.py +623 -0
  298. package/tools/humanize_linter.py +438 -0
  299. package/tools/infer_linter.py +977 -0
  300. package/tools/init_config.py +307 -0
  301. package/tools/interview_story.py +116 -0
  302. package/tools/jira_sync.py +566 -0
  303. package/tools/jtl_analyzer.py +474 -0
  304. package/tools/lint/__init__.py +30 -0
  305. package/tools/lint_ai_docs.py +374 -0
  306. package/tools/lookup_tc.py +165 -0
  307. package/tools/lookup_xpath.py +167 -0
  308. package/tools/matrix_sharder.py +148 -0
  309. package/tools/mcp/__init__.py +18 -0
  310. package/tools/mcp_docx_server.ps1 +13 -0
  311. package/tools/mcp_docx_server.py +851 -0
  312. package/tools/mcp_excel_server.ps1 +13 -0
  313. package/tools/mcp_excel_server.py +441 -0
  314. package/tools/mcp_server.py +724 -0
  315. package/tools/md_to_xlsx.py +327 -0
  316. package/tools/micro_mutator.py +887 -0
  317. package/tools/mipro_assertion_tuner.py +210 -0
  318. package/tools/network_mock_shield.py +311 -0
  319. package/tools/newman_analyzer.py +384 -0
  320. package/tools/omni_emitter.py +579 -0
  321. package/tools/omni_parser.py +450 -0
  322. package/tools/omni_transpiler.py +168 -0
  323. package/tools/openxml_guard.py +438 -0
  324. package/tools/output_formatter.py +182 -0
  325. package/tools/package_release.py +325 -0
  326. package/tools/perf/__init__.py +24 -0
  327. package/tools/pinpoint_failure.py +190 -0
  328. package/tools/project_state.py +171 -0
  329. package/tools/qa_event_stream.py +358 -0
  330. package/tools/repo_map.py +346 -0
  331. package/tools/report/__init__.py +32 -0
  332. package/tools/reversible_sandbox.py +344 -0
  333. package/tools/safety_firewall.py +437 -0
  334. package/tools/security_coverage_ledger.py +538 -0
  335. package/tools/security_scanner.py +229 -0
  336. package/tools/senior_code_review.py +393 -0
  337. package/tools/setup_project.py +770 -0
  338. package/tools/skill_collision_guard.py +304 -0
  339. package/tools/skill_profiles.py +217 -0
  340. package/tools/skill_vault.py +481 -0
  341. package/tools/skillspector.py +1278 -0
  342. package/tools/smart_visual_masker.py +132 -0
  343. package/tools/spec_drift_sentinel.py +438 -0
  344. package/tools/swe_qa_aci.py +369 -0
  345. package/tools/synapse_observer.py +485 -0
  346. package/tools/synapse_qa_bench.py +190 -0
  347. package/tools/sync_agent_rules.py +274 -0
  348. package/tools/telemetry_correlator.py +397 -0
  349. package/tools/template_excel_exporter.py +514 -0
  350. package/tools/templates/jmeter-distributed/README.md +54 -0
  351. package/tools/templates/jmeter-distributed/docker-compose.yml +83 -0
  352. package/tools/test_impact.py +419 -0
  353. package/tools/test_memory_os.py +462 -0
  354. package/tools/textgrad_mutation_optimizer.py +237 -0
  355. package/tools/tms_sync_bridge.py +834 -0
  356. package/tools/tot_exploratory_tester.py +239 -0
  357. package/tools/trace_data_flow.py +240 -0
  358. package/tools/traffic_session_converter.py +256 -0
  359. package/tools/trend_analytics.py +314 -0
  360. package/tools/ui_server.py +401 -0
  361. package/tools/universal_ir.py +488 -0
  362. package/tools/update_sentinel.py +383 -0
  363. package/tools/validate_groovy_scripts.py +173 -0
  364. package/tools/verify_all.py +1259 -0
  365. package/tools/visual_diff_canvas.py +143 -0
  366. package/tools/visual_som_helper.py +550 -0
  367. package/tools/watch_mode.py +308 -0
  368. package/tools/wcag_audit.py +239 -0
  369. package/tools/welcome_page.py +290 -0
@@ -0,0 +1,132 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ Smart Visual Masker & Anti-Flake Visual Engine
4
+ ----------------------------------------------
5
+ Eliminates 99% of false alarms in Visual Regression Testing.
6
+ Automatically disables dynamic CSS animations, freezes SVG spinners,
7
+ and masks fluctuating UI elements (timestamps, clocks, avatars, ad banners).
8
+ """
9
+
10
+ import json
11
+ import argparse
12
+ from typing import List, Optional
13
+
14
+
15
+ class SmartVisualMasker:
16
+ """Enterprise Visual Regression Anti-Flake & Dynamic Masking Engine."""
17
+
18
+ ANTI_FLAKE_CSS = """
19
+ *, *::before, *::after {
20
+ transition-property: none !important;
21
+ transform: none !important;
22
+ animation: none !important;
23
+ caret-color: transparent !important;
24
+ scroll-behavior: auto !important;
25
+ }
26
+ """
27
+
28
+ DEFAULT_MASK_SELECTORS = [
29
+ # Timestamps and dates
30
+ "time",
31
+ ".timestamp",
32
+ ".date-time",
33
+ ".clock",
34
+ "[data-testid*='date']",
35
+ "[data-testid*='time']",
36
+ "[class*='countdown']",
37
+ # Random avatars & dynamic user content
38
+ ".avatar",
39
+ "img.user-avatar",
40
+ "[data-testid*='avatar']",
41
+ # Ads and third-party widgets
42
+ ".ad-banner",
43
+ ".advertisement",
44
+ "iframe[id*='google']",
45
+ # Skeleton loaders & spinners
46
+ ".skeleton",
47
+ ".loading-placeholder",
48
+ ".spinner"
49
+ ]
50
+
51
+ @classmethod
52
+ def get_anti_flake_css(cls) -> str:
53
+ """Returns normalized CSS string to freeze all animations and transitions."""
54
+ return cls.ANTI_FLAKE_CSS.strip()
55
+
56
+ @classmethod
57
+ def generate_playwright_ts_options(cls, additional_selectors: Optional[List[str]] = None) -> str:
58
+ """
59
+ Generates Playwright TypeScript assertion options with masking and disabled animations.
60
+ """
61
+ selectors = cls.DEFAULT_MASK_SELECTORS + (additional_selectors or [])
62
+ locators_ts = ",\n ".join([f"page.locator('{sel}')" for sel in selectors])
63
+
64
+ return f"""await expect(page).toHaveScreenshot('visual-baseline.png', {{
65
+ animations: 'disabled',
66
+ caret: 'hide',
67
+ scale: 'css',
68
+ maxDiffPixelRatio: 0.01,
69
+ mask: [
70
+ {locators_ts}
71
+ ]
72
+ }});"""
73
+
74
+ @classmethod
75
+ def generate_browser_mask_script(cls, selectors: Optional[List[str]] = None) -> str:
76
+ """
77
+ Generates JavaScript snippet to run inside the live browser
78
+ to immediately freeze DOM animations and paint solid black masks
79
+ over dynamic timestamp/avatar elements.
80
+ """
81
+ target_selectors = selectors or cls.DEFAULT_MASK_SELECTORS
82
+ selectors_json = json.dumps(target_selectors)
83
+ return f"""(() => {{
84
+ // 1. Inject anti-flake styles
85
+ const style = document.createElement('style');
86
+ style.innerHTML = `{cls.get_anti_flake_css()}`;
87
+ document.head.appendChild(style);
88
+
89
+ // 2. Solid mask for dynamic elements
90
+ const selectors = {selectors_json};
91
+ let maskedCount = 0;
92
+ selectors.forEach(sel => {{
93
+ document.querySelectorAll(sel).forEach(el => {{
94
+ el.style.backgroundColor = '#000000';
95
+ el.style.color = '#000000';
96
+ el.style.visibility = 'visible';
97
+ el.setAttribute('data-visual-masked', 'true');
98
+ maskedCount++;
99
+ }});
100
+ }});
101
+ return {{ status: 'OK', maskedCount }};
102
+ }})();"""
103
+
104
+
105
+ def main():
106
+ parser = argparse.ArgumentParser(description="Smart Visual Masker & Anti-Flake Visual Engine")
107
+ parser.add_argument("--css", action="store_true", help="Print anti-flake CSS")
108
+ parser.add_argument("--js-script", action="store_true", help="Print browser in-page masking JavaScript")
109
+ parser.add_argument("--playwright-snippet", action="store_true", help="Generate Playwright TS visual assertion snippet")
110
+ parser.add_argument("--mask", action="append", default=[], help="Additional CSS selectors to mask")
111
+
112
+ args = parser.parse_args()
113
+
114
+ if args.css:
115
+ print(SmartVisualMasker.get_anti_flake_css())
116
+ elif args.js_script:
117
+ print(SmartVisualMasker.generate_browser_mask_script(args.mask or None))
118
+ elif args.playwright_snippet:
119
+ print(SmartVisualMasker.generate_playwright_ts_options(args.mask or None))
120
+ else:
121
+ print("======================================================================")
122
+ print(" SMART VISUAL MASKER & ANTI-FLAKE VISUAL ENGINE")
123
+ print("======================================================================")
124
+ print("Default Masked Selectors:")
125
+ for sel in SmartVisualMasker.DEFAULT_MASK_SELECTORS:
126
+ print(f" • {sel}")
127
+ print("\nUse --css, --js-script, or --playwright-snippet for code output.")
128
+ print("======================================================================")
129
+
130
+
131
+ if __name__ == "__main__":
132
+ main()
@@ -0,0 +1,438 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thįŗæ Vị (@TeeVee998). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
5
+
6
+ """
7
+ tools/spec_drift_sentinel.py — Spec-to-Code Drift Sentinel
8
+ ---------------------------------------------------------
9
+ Inspired by Google's Elephant-Goldfish Model (egm-drift-report).
10
+ Audits whether the actual test automation code accurately implements the approved
11
+ specification, detecting Deficit Drift (missing assertions) and Scope Drift (unauthorized bloat).
12
+
13
+ Metrics:
14
+ - Deficit Drift: Requirements / Criteria present in spec but missing in test code.
15
+ - Scope Drift: Test actions / workflows in code that have no grounding in the spec.
16
+ - Alignment Score: Percentage of spec criteria satisfied minus scope drift penalty.
17
+
18
+ Usage:
19
+ python tools/spec_drift_sentinel.py --spec <spec_file> --code <test_file_or_dir>
20
+ python tools/spec_drift_sentinel.py --spec <spec_file> --code <test_file> --markdown SPEC_DRIFT_REPORT.md
21
+ python tools/spec_drift_sentinel.py --spec <spec_file> --code <test_file> --json
22
+ """
23
+
24
+ import os
25
+ import sys
26
+ import re
27
+ import json
28
+ import argparse
29
+ from typing import List, Dict, Any, Tuple
30
+
31
+ if hasattr(sys.stdout, 'reconfigure'):
32
+ try:
33
+ sys.stdout.reconfigure(encoding='utf-8')
34
+ sys.stderr.reconfigure(encoding='utf-8')
35
+ except Exception:
36
+ pass
37
+
38
+
39
+ def extract_spec_criteria(spec_text: str) -> List[Dict[str, Any]]:
40
+ """
41
+ Extracts individual criteria, scenarios, or acceptance points from Markdown or Gherkin.
42
+ """
43
+ criteria = []
44
+ lines = spec_text.splitlines()
45
+
46
+ current_section = "General"
47
+ idx = 1
48
+
49
+ for line in lines:
50
+ stripped = line.strip()
51
+ if not stripped:
52
+ continue
53
+
54
+ # Header detection
55
+ if stripped.startswith("#"):
56
+ current_section = stripped.lstrip("#").strip()
57
+ continue
58
+
59
+ # Gherkin Scenario
60
+ if re.match(r'^(Scenario|Scenario Outline):\s*(.+)', stripped, re.IGNORECASE):
61
+ match = re.match(r'^(Scenario|Scenario Outline):\s*(.+)', stripped, re.IGNORECASE)
62
+ criteria.append({
63
+ "id": f"AC-{idx:02d}",
64
+ "type": "scenario",
65
+ "section": current_section,
66
+ "text": match.group(2).strip(),
67
+ "raw": stripped
68
+ })
69
+ idx += 1
70
+ continue
71
+
72
+ # Acceptance criteria checklist: - [ ] or - [x] or * [ ]
73
+ if re.match(r'^[-*]\s*\[[ xX]\]\s*(.+)', stripped):
74
+ match = re.match(r'^[-*]\s*\[[ xX]\]\s*(.+)', stripped)
75
+ criteria.append({
76
+ "id": f"AC-{idx:02d}",
77
+ "type": "checklist",
78
+ "section": current_section,
79
+ "text": match.group(1).strip(),
80
+ "raw": stripped
81
+ })
82
+ idx += 1
83
+ continue
84
+
85
+ # Bullet criteria: - Criterion or 1. Criterion with keywords
86
+ if re.match(r'^(\d+\.|\-|\*)\s+(should|must|verify|assert|expect|khi|phải|kiểm tra)\s+(.+)', stripped, re.IGNORECASE):
87
+ criteria.append({
88
+ "id": f"AC-{idx:02d}",
89
+ "type": "bullet",
90
+ "section": current_section,
91
+ "text": stripped,
92
+ "raw": stripped
93
+ })
94
+ idx += 1
95
+ continue
96
+
97
+ # Gherkin Then / And assert steps
98
+ if re.match(r'^(Then|And)\s+(the\s+)?(system|page|user|message|response|status|button|element)\s+(should|must|will|is|displays?|returns?)\s+(.+)', stripped, re.IGNORECASE):
99
+ criteria.append({
100
+ "id": f"AC-{idx:02d}",
101
+ "type": "gherkin_then",
102
+ "section": current_section,
103
+ "text": stripped,
104
+ "raw": stripped
105
+ })
106
+ idx += 1
107
+ continue
108
+
109
+ # Fallback if no structured AC was found: split into paragraphs with assertions
110
+ if not criteria:
111
+ for line in lines:
112
+ stripped = line.strip()
113
+ if any(k in stripped.lower() for k in ["assert", "expect", "verify", "mong đợi", "kiểm tra", "kįŗæt quįŗ£"]):
114
+ criteria.append({
115
+ "id": f"AC-{idx:02d}",
116
+ "type": "heuristic",
117
+ "section": current_section,
118
+ "text": stripped,
119
+ "raw": stripped
120
+ })
121
+ idx += 1
122
+
123
+ return criteria
124
+
125
+
126
+ def extract_code_tokens_and_assertions(code_text: str) -> Tuple[List[str], List[str]]:
127
+ """
128
+ Extracts keywords, method calls, and assertion statements from test script code.
129
+ """
130
+ assertions = []
131
+ actions = []
132
+
133
+ # Assertion lines regex (Groovy, TS, Python, Java)
134
+ assert_regex = re.compile(
135
+ r'(\bassert\b.*|\bexpect\(.*|\.should\(.*|WebUI\.verify.*|assertThat.*|assertEquals.*|assertTrue.*)',
136
+ re.IGNORECASE
137
+ )
138
+
139
+ action_regex = re.compile(
140
+ r'(\b\w+Page\.\w+\(.*\)|WebUI\.click.*|WebUI\.setText.*|await\s+\w+\.\w+\(.*\)|page\.\w+\(.*\))',
141
+ re.IGNORECASE
142
+ )
143
+
144
+ for line in code_text.splitlines():
145
+ line_clean = line.strip()
146
+ if not line_clean or line_clean.startswith("//") or line_clean.startswith("#"):
147
+ continue
148
+
149
+ if assert_regex.search(line_clean):
150
+ assertions.append(line_clean)
151
+ elif action_regex.search(line_clean):
152
+ actions.append(line_clean)
153
+
154
+ return assertions, actions
155
+
156
+
157
+ def split_camel_case(text: str) -> str:
158
+ """Splits camelCase and PascalCase identifiers into space-separated words."""
159
+ return re.sub(r'([a-z0-9])([A-Z])', r'\1 \2', text)
160
+
161
+
162
+ def normalize_stem(word: str) -> str:
163
+ """Simple heuristic stemmer for English suffixes to match singular/plural and verb tenses."""
164
+ w = word.lower()
165
+ if len(w) > 4:
166
+ if w.endswith("ing"):
167
+ return w[:-3]
168
+ if w.endswith("ies"):
169
+ return w[:-3] + "y"
170
+ if w.endswith("es"):
171
+ return w[:-2]
172
+ if w.endswith("ed"):
173
+ return w[:-2]
174
+ if w.endswith("s") and not w.endswith("ss"):
175
+ return w[:-1]
176
+ return w
177
+
178
+
179
+ def tokenize_text(text: str) -> set:
180
+ """Extracts meaningful normalized words from text with camelCase splitting."""
181
+ expanded = split_camel_case(text)
182
+ words = re.findall(r'[a-zA-Z0-9_\u00C0-\u1EF9]+', expanded.lower())
183
+ stop_words = {
184
+ "the", "a", "an", "is", "are", "in", "on", "at", "to", "for", "with",
185
+ "and", "or", "then", "when", "given", "should", "must", "be", "cį»§a",
186
+ "vĆ ", "lĆ ", "khi", "thƬ", "được", "có", "trong", "trĆŖn", "cho", "user"
187
+ }
188
+ tokens = set()
189
+ for w in words:
190
+ if w not in stop_words and len(w) > 2:
191
+ tokens.add(normalize_stem(w))
192
+ return tokens
193
+
194
+
195
+ def compute_drift(spec_criteria: List[Dict[str, Any]], code_files: List[Tuple[str, str]]) -> Dict[str, Any]:
196
+ """
197
+ Computes Deficit Drift, Scope Drift, and Alignment Score.
198
+ """
199
+ all_code_assertions = []
200
+ all_code_actions = []
201
+ combined_code = ""
202
+
203
+ for file_path, content in code_files:
204
+ assertions, actions = extract_code_tokens_and_assertions(content)
205
+ all_code_assertions.extend([(file_path, a) for a in assertions])
206
+ all_code_actions.extend([(file_path, a) for a in actions])
207
+ combined_code += "\n" + content
208
+
209
+ code_tokens = tokenize_text(combined_code)
210
+
211
+ covered_criteria = []
212
+ deficit_drift = []
213
+
214
+ for crit in spec_criteria:
215
+ crit_tokens = tokenize_text(crit["text"])
216
+ if not crit_tokens:
217
+ continue
218
+
219
+ matched_tokens = crit_tokens.intersection(code_tokens)
220
+ overlap_ratio = len(matched_tokens) / len(crit_tokens)
221
+
222
+ # Check if any assertion matches keywords
223
+ has_assertion_anchor = any(
224
+ len(crit_tokens.intersection(tokenize_text(a[1]))) >= 1
225
+ for a in all_code_assertions
226
+ )
227
+
228
+ if overlap_ratio >= 0.4 or has_assertion_anchor:
229
+ covered_criteria.append({
230
+ "criterion": crit,
231
+ "matched_tokens": list(matched_tokens),
232
+ "overlap_ratio": round(overlap_ratio, 2)
233
+ })
234
+ else:
235
+ deficit_drift.append({
236
+ "criterion": crit,
237
+ "missing_tokens": list(crit_tokens - matched_tokens),
238
+ "overlap_ratio": round(overlap_ratio, 2)
239
+ })
240
+
241
+ # Scope drift: identify code actions that don't match any spec keywords
242
+ scope_drift = []
243
+ all_spec_tokens = set()
244
+ for crit in spec_criteria:
245
+ all_spec_tokens.update(tokenize_text(crit["text"]))
246
+
247
+ for file_path, action in all_code_actions:
248
+ action_tokens = tokenize_text(action)
249
+ if not action_tokens:
250
+ continue
251
+ spec_overlap = action_tokens.intersection(all_spec_tokens)
252
+ # Action is considered scope creep if it introduces totally unrelated verbs
253
+ if len(spec_overlap) == 0 and not any(w in action.lower() for w in ["navigateto", "open", "close", "wait", "delay", "sleep"]):
254
+ scope_drift.append({
255
+ "file": file_path,
256
+ "action": action,
257
+ "reason": "Action method not grounded in any specification criterion."
258
+ })
259
+
260
+ total_spec = len(spec_criteria)
261
+ if total_spec == 0:
262
+ alignment_score = 100.0 if not code_files else 0.0
263
+ else:
264
+ coverage_pct = (len(covered_criteria) / total_spec) * 100.0
265
+ penalty = min(20.0, len(scope_drift) * 3.0)
266
+ alignment_score = max(0.0, round(coverage_pct - penalty, 2))
267
+
268
+ passed = (len(deficit_drift) == 0) and (alignment_score >= 80.0)
269
+
270
+ return {
271
+ "total_criteria": total_spec,
272
+ "covered_count": len(covered_criteria),
273
+ "deficit_drift_count": len(deficit_drift),
274
+ "scope_drift_count": len(scope_drift),
275
+ "alignment_score": alignment_score,
276
+ "passed": passed,
277
+ "status": "ALIGNED" if passed else "DRIFT_DETECTED",
278
+ "covered_criteria": covered_criteria,
279
+ "deficit_drift": deficit_drift,
280
+ "scope_drift": scope_drift,
281
+ "assertion_count": len(all_code_assertions)
282
+ }
283
+
284
+
285
+ def generate_markdown_report(result: Dict[str, Any], spec_file: str, code_path: str) -> str:
286
+ md = []
287
+ md.append("# SPEC-TO-CODE DRIFT REPORT")
288
+ md.append("> Generated autonomously by Synapse-Hub `tools/spec_drift_sentinel.py` ")
289
+ md.append(f"> **Specification:** `{spec_file}` | **Code Target:** `{code_path}` \n")
290
+ md.append("---")
291
+
292
+ status_icon = "āœ…" if result["passed"] else "āŒ"
293
+ md.append(f"## šŸ“Š Executive Summary: {status_icon} [{result['status']}]")
294
+ md.append(f"- **Alignment Score:** `{result['alignment_score']}%` (Pass threshold: >= 80% & zero Deficit Drift)")
295
+ md.append(f"- **Total Spec Criteria:** {result['total_criteria']}")
296
+ md.append(f"- **Covered Criteria:** {result['covered_count']}")
297
+ md.append(f"- **Deficit Drift (Missing in Code):** {result['deficit_drift_count']}")
298
+ md.append(f"- **Scope Drift (Extraneous in Code):** {result['scope_drift_count']}")
299
+ md.append(f"- **Extracted Code Assertions:** {result['assertion_count']}\n")
300
+
301
+ md.append("---")
302
+ md.append("## šŸ” Deficit Drift Analysis (Unsatisfied Requirements)")
303
+ if result["deficit_drift"]:
304
+ md.append("| ID | Section | Criterion Text | Status |")
305
+ md.append("| :--- | :--- | :--- | :--- |")
306
+ for item in result["deficit_drift"]:
307
+ crit = item["criterion"]
308
+ md.append(f"| `{crit['id']}` | {crit['section']} | {crit['text']} | āŒ **MISSING IN CODE** |")
309
+ else:
310
+ md.append("āœ… **Zero Deficit Drift detected.** 100% of specification criteria are grounded in test code.")
311
+
312
+ md.append("\n---")
313
+ md.append("## āš ļø Scope Drift Analysis (Extraneous Code Actions)")
314
+ if result["scope_drift"]:
315
+ md.append("| File | Extraneous Action | Reason |")
316
+ md.append("| :--- | :--- | :--- |")
317
+ for s in result["scope_drift"][:10]:
318
+ md.append(f"| `{os.path.basename(s['file'])}` | `{s['action'][:60]}` | {s['reason']} |")
319
+ else:
320
+ md.append("āœ… **Zero Scope Drift detected.** No ungrounded code bloat found.")
321
+
322
+ return "\n".join(md)
323
+
324
+
325
+ def print_cli_report(result: Dict[str, Any], spec_file: str, code_path: str):
326
+ print("=" * 70)
327
+ print(" SPEC-TO-CODE DRIFT SENTINEL — ALIGNMENT & FIDELITY AUDIT")
328
+ print(" Inspired by Google Elephant-Goldfish Model (EGM)")
329
+ print("=" * 70)
330
+ print(f"Spec File : {spec_file}")
331
+ print(f"Code Target : {code_path}")
332
+ print(f"Alignment Score : {result['alignment_score']}%")
333
+ status_icon = "āœ…" if result["passed"] else "āŒ"
334
+ print(f"Verdict : {status_icon} [{result['status']}] (DoD Requirement: Zero Deficit Drift)")
335
+ print("-" * 70)
336
+ print(f" • Criteria Evaluated : {result['total_criteria']}")
337
+ print(f" • Criteria Satisfied : {result['covered_count']}/{result['total_criteria']}")
338
+ print(f" • Deficit Drift : {result['deficit_drift_count']} missing item(s)")
339
+ print(f" • Scope Drift : {result['scope_drift_count']} extraneous action(s)")
340
+ print(f" • Code Assertions : {result['assertion_count']} detected")
341
+ print("-" * 70)
342
+
343
+ if result["total_criteria"] == 0:
344
+ print("āš ļø Warning: No testable acceptance criteria, scenarios, or assertions were discovered in spec.")
345
+ elif result["deficit_drift"]:
346
+ print("āŒ Deficit Drift Items (Requirements missing assertions in code):")
347
+ for item in result["deficit_drift"]:
348
+ crit = item["criterion"]
349
+ print(f" • [{crit['id']}] ({crit['section']}): {crit['text']}")
350
+ else:
351
+ print("āœ… Zero Deficit Drift. All spec criteria are reflected in code.")
352
+
353
+ if result["scope_drift"]:
354
+ print(f"\nāš ļø Scope Drift Detected ({len(result['scope_drift'])} actions with no spec anchor):")
355
+ for s in result["scope_drift"][:5]:
356
+ print(f" • {os.path.basename(s['file'])}: {s['action'][:60]}")
357
+ print("=" * 70)
358
+
359
+
360
+ def collect_code_files(code_path: str) -> List[Tuple[str, str]]:
361
+ files = []
362
+ valid_exts = {".groovy", ".ts", ".js", ".py", ".java"}
363
+
364
+ if os.path.isfile(code_path):
365
+ try:
366
+ with open(code_path, "r", encoding="utf-8", errors="replace") as f:
367
+ files.append((code_path, f.read()))
368
+ except Exception as e:
369
+ print(f"Warning: Could not read code file {code_path}: {e}", file=sys.stderr)
370
+ elif os.path.isdir(code_path):
371
+ for root, _, filenames in os.walk(code_path):
372
+ if any(p in root for p in [".git", "node_modules", "Reports", "build", "dist"]):
373
+ continue
374
+ for fname in filenames:
375
+ ext = os.path.splitext(fname)[1].lower()
376
+ if ext in valid_exts:
377
+ full_p = os.path.join(root, fname)
378
+ try:
379
+ with open(full_p, "r", encoding="utf-8", errors="replace") as f:
380
+ files.append((full_p, f.read()))
381
+ except (OSError, UnicodeDecodeError) as err:
382
+ sys.stderr.write(f"Warning: skipped {fname}: {err}\n")
383
+ return files
384
+
385
+
386
+ def main():
387
+ parser = argparse.ArgumentParser(
388
+ description="Spec-to-Code Drift Sentinel — Audits code alignment against test specifications."
389
+ )
390
+ parser.add_argument("--spec", required=True, help="Path to specification file (Markdown or Gherkin .feature)")
391
+ parser.add_argument("--code", required=True, help="Path to test script or directory of test scripts")
392
+ parser.add_argument("--markdown", "-m", help="Path to export Markdown drift report (e.g. SPEC_DRIFT_REPORT.md)")
393
+ parser.add_argument("--json", action="store_true", help="Output machine-readable JSON format")
394
+
395
+ args = parser.parse_args()
396
+
397
+ if not os.path.isfile(args.spec):
398
+ print(f"Error: Specification file not found: {args.spec}", file=sys.stderr)
399
+ sys.exit(1)
400
+
401
+ try:
402
+ with open(args.spec, "r", encoding="utf-8", errors="replace") as f:
403
+ spec_text = f.read()
404
+ except Exception as e:
405
+ print(f"Error reading spec file {args.spec}: {e}", file=sys.stderr)
406
+ sys.exit(1)
407
+
408
+ spec_criteria = extract_spec_criteria(spec_text)
409
+ code_files = collect_code_files(args.code)
410
+
411
+ if not code_files:
412
+ print(f"Error: No valid test code files found at {args.code}", file=sys.stderr)
413
+ sys.exit(1)
414
+
415
+ result = compute_drift(spec_criteria, code_files)
416
+
417
+ if args.markdown:
418
+ md_content = generate_markdown_report(result, args.spec, args.code)
419
+ try:
420
+ out_dir = os.path.dirname(os.path.abspath(args.markdown))
421
+ if out_dir:
422
+ os.makedirs(out_dir, exist_ok=True)
423
+ with open(args.markdown, "w", encoding="utf-8") as f:
424
+ f.write(md_content)
425
+ print(f"šŸ“ Markdown drift report exported to: {args.markdown}")
426
+ except OSError as e:
427
+ print(f"Warning: Could not write markdown report: {e}", file=sys.stderr)
428
+
429
+ if args.json:
430
+ print(json.dumps(result, indent=2, ensure_ascii=False))
431
+ else:
432
+ print_cli_report(result, args.spec, args.code)
433
+
434
+ sys.exit(0 if result["passed"] else 1)
435
+
436
+
437
+ if __name__ == "__main__":
438
+ main()