synthra 0.1.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 (302) hide show
  1. checksums.yaml +7 -0
  2. data/.rspec +4 -0
  3. data/.rubocop.yml +40 -0
  4. data/.yardopts +18 -0
  5. data/ACCESS_DOCS.md +116 -0
  6. data/ADVANCED_FEATURES_SUMMARY.md +245 -0
  7. data/CHANGELOG.md +498 -0
  8. data/CODE_OF_CONDUCT.md +122 -0
  9. data/CONTRIBUTING.md +307 -0
  10. data/DOCUMENTATION.md +204 -0
  11. data/DOCUMENTATION_GUIDE.md +194 -0
  12. data/LICENSE +22 -0
  13. data/README.md +1458 -0
  14. data/Rakefile +128 -0
  15. data/benchmark/README.md +591 -0
  16. data/benchmark/batch_generation.rb +63 -0
  17. data/benchmark/engine_comparison.rb +295 -0
  18. data/benchmark/single_record.rb +108 -0
  19. data/benchmark/streaming.rb +74 -0
  20. data/docs/ACTIVERECORD_INFERENCE.md +524 -0
  21. data/docs/API_SERVER.md +278 -0
  22. data/docs/CONFIG_FILE.md +315 -0
  23. data/docs/DATA_CONTRACTS.md +312 -0
  24. data/docs/ENHANCED_REPL.md +304 -0
  25. data/docs/FACTORY_BOT.md +271 -0
  26. data/docs/GITHUB_ACTION.md +420 -0
  27. data/docs/GRAPHQL_EXPORT.md +303 -0
  28. data/docs/GRAPHQL_FEDERATION.md +651 -0
  29. data/docs/HOW_TO_GENERATE_DOCS.md +252 -0
  30. data/docs/LSP.md +189 -0
  31. data/docs/MIGRATION_GENERATOR.md +547 -0
  32. data/docs/MOCK_SERVER.md +280 -0
  33. data/docs/NATIVE_ENGINE.md +298 -0
  34. data/docs/OPENAPI_EXPORT.md +252 -0
  35. data/docs/PERFORMANCE_MODE.md +228 -0
  36. data/docs/PERSONAS.md +547 -0
  37. data/docs/PROPERTY_TESTING.md +284 -0
  38. data/docs/PROTOBUF_EXPORT.md +276 -0
  39. data/docs/QUALITY_METRICS.md +555 -0
  40. data/docs/QUICK_REFERENCE.md +88 -0
  41. data/docs/RAILS_ENGINE.md +404 -0
  42. data/docs/RAILS_INTEGRATION.md +454 -0
  43. data/docs/README.md +175 -0
  44. data/docs/REPL_QUICK_REFERENCE.md +149 -0
  45. data/docs/RUST_INTEGRATION_GUIDE.md +1376 -0
  46. data/docs/SCENARIOS.md +576 -0
  47. data/docs/SECURITY_TESTING.md +318 -0
  48. data/docs/SNAPSHOT_TESTING.md +308 -0
  49. data/docs/STRING_TEXT_TYPES_REFERENCE.md +512 -0
  50. data/docs/TERRAFORM_EXPORT.md +447 -0
  51. data/docs/TIME_TRAVEL.md +507 -0
  52. data/docs/USAGE_GUIDE.md +980 -0
  53. data/docs/WEBHOOK_SIMULATOR.md +579 -0
  54. data/docs/advanced_features.md +183 -0
  55. data/docs/api_reference.md +153 -0
  56. data/docs/behaviors.md +138 -0
  57. data/docs/best_practices.md +191 -0
  58. data/docs/dsl_reference.md +172 -0
  59. data/docs/examples.md +162 -0
  60. data/docs/generation_modes.md +125 -0
  61. data/docs/getting_started.md +92 -0
  62. data/docs/index.html +177 -0
  63. data/docs/strategic/CLOUD_REGISTRY_ARCHITECTURE.md +268 -0
  64. data/docs/strategic/SIMD_OPTIMIZATION_STRATEGY.md +153 -0
  65. data/docs/troubleshooting.md +215 -0
  66. data/docs/type_reference.md +224 -0
  67. data/examples/hostile_mode_demo.rb +64 -0
  68. data/exe/synthra +6 -0
  69. data/ext/synthra_native/Cargo.lock +972 -0
  70. data/ext/synthra_native/Cargo.toml +46 -0
  71. data/ext/synthra_native/extconf.rb +41 -0
  72. data/ext/synthra_native/src/generator.rs +397 -0
  73. data/ext/synthra_native/src/lib.rs +229 -0
  74. data/ext/synthra_native/src/types.rs +1485 -0
  75. data/lib/generators/synthra/install_generator.rb +86 -0
  76. data/lib/generators/synthra/templates/api_response.dsl +15 -0
  77. data/lib/generators/synthra/templates/fake_data.rake +116 -0
  78. data/lib/generators/synthra/templates/synthra.yml +31 -0
  79. data/lib/generators/synthra/templates/synthra_support.rb +19 -0
  80. data/lib/generators/synthra/templates/user.dsl +11 -0
  81. data/lib/synthra/activerecord_inference.rb +394 -0
  82. data/lib/synthra/api.rb +381 -0
  83. data/lib/synthra/api_server.rb +718 -0
  84. data/lib/synthra/behaviors/applicator.rb +165 -0
  85. data/lib/synthra/behaviors/base.rb +155 -0
  86. data/lib/synthra/behaviors/close_connection.rb +60 -0
  87. data/lib/synthra/behaviors/deprecated.rb +100 -0
  88. data/lib/synthra/behaviors/failure.rb +69 -0
  89. data/lib/synthra/behaviors/latency.rb +103 -0
  90. data/lib/synthra/behaviors/partial_data.rb +83 -0
  91. data/lib/synthra/behaviors/randomize_order.rb +74 -0
  92. data/lib/synthra/behaviors/registry.rb +238 -0
  93. data/lib/synthra/behaviors/simulate_error.rb +79 -0
  94. data/lib/synthra/cli/commands/base.rb +105 -0
  95. data/lib/synthra/cli/commands/diff.rb +227 -0
  96. data/lib/synthra/cli/commands/docs.rb +67 -0
  97. data/lib/synthra/cli/commands/export.rb +150 -0
  98. data/lib/synthra/cli/commands/generate.rb +72 -0
  99. data/lib/synthra/cli/commands/import.rb +80 -0
  100. data/lib/synthra/cli/commands/lint.rb +53 -0
  101. data/lib/synthra/cli/commands/live.rb +57 -0
  102. data/lib/synthra/cli/commands/seed.rb +99 -0
  103. data/lib/synthra/cli/commands/validate.rb +28 -0
  104. data/lib/synthra/cli.rb +2471 -0
  105. data/lib/synthra/config_file.rb +129 -0
  106. data/lib/synthra/configuration.rb +281 -0
  107. data/lib/synthra/contracts_registry.rb +408 -0
  108. data/lib/synthra/database_seeder.rb +268 -0
  109. data/lib/synthra/deterministic_ids.rb +218 -0
  110. data/lib/synthra/documentation_generator.rb +414 -0
  111. data/lib/synthra/engine.rb +251 -0
  112. data/lib/synthra/errors.rb +1169 -0
  113. data/lib/synthra/export/base.rb +85 -0
  114. data/lib/synthra/export/csv.rb +101 -0
  115. data/lib/synthra/export/graphql.rb +266 -0
  116. data/lib/synthra/export/graphql_federation.rb +377 -0
  117. data/lib/synthra/export/graphviz.rb +258 -0
  118. data/lib/synthra/export/javascript.rb +327 -0
  119. data/lib/synthra/export/json_data.rb +61 -0
  120. data/lib/synthra/export/json_schema.rb +290 -0
  121. data/lib/synthra/export/openapi.rb +514 -0
  122. data/lib/synthra/export/protobuf.rb +483 -0
  123. data/lib/synthra/export/python.rb +560 -0
  124. data/lib/synthra/export/sql.rb +381 -0
  125. data/lib/synthra/export/sql_insert.rb +152 -0
  126. data/lib/synthra/export/terraform.rb +501 -0
  127. data/lib/synthra/export/type_mapping.rb +389 -0
  128. data/lib/synthra/export/typescript.rb +300 -0
  129. data/lib/synthra/export/xml_data.rb +104 -0
  130. data/lib/synthra/export/yaml_data.rb +56 -0
  131. data/lib/synthra/export.rb +404 -0
  132. data/lib/synthra/factory_bot_integration.rb +157 -0
  133. data/lib/synthra/field.rb +440 -0
  134. data/lib/synthra/functions/registry.rb +104 -0
  135. data/lib/synthra/generator/context.rb +372 -0
  136. data/lib/synthra/generator/engine.rb +336 -0
  137. data/lib/synthra/generator/faker_adapter.rb +425 -0
  138. data/lib/synthra/generator/modes.rb +444 -0
  139. data/lib/synthra/generator/resolver.rb +256 -0
  140. data/lib/synthra/generator/rng.rb +273 -0
  141. data/lib/synthra/generator/streamer.rb +63 -0
  142. data/lib/synthra/generator/uniqueness.rb +118 -0
  143. data/lib/synthra/initializer.rb +97 -0
  144. data/lib/synthra/limits.rb +279 -0
  145. data/lib/synthra/live_preview.rb +518 -0
  146. data/lib/synthra/loader_config.rb +78 -0
  147. data/lib/synthra/lsp/server.rb +689 -0
  148. data/lib/synthra/migration_generator.rb +301 -0
  149. data/lib/synthra/mixin.rb +174 -0
  150. data/lib/synthra/mock_server.rb +458 -0
  151. data/lib/synthra/native_engine.rb +304 -0
  152. data/lib/synthra/openapi_importer.rb +228 -0
  153. data/lib/synthra/output/json_formatter.rb +40 -0
  154. data/lib/synthra/output/ndjson_formatter.rb +55 -0
  155. data/lib/synthra/parser/ast.rb +1287 -0
  156. data/lib/synthra/parser/lexer.rb +1152 -0
  157. data/lib/synthra/parser/parser.rb +1664 -0
  158. data/lib/synthra/parser/tokens.rb +461 -0
  159. data/lib/synthra/performance_mode.rb +364 -0
  160. data/lib/synthra/personas.rb +397 -0
  161. data/lib/synthra/property_testing.rb +172 -0
  162. data/lib/synthra/quality_metrics.rb +405 -0
  163. data/lib/synthra/rails_test_helper.rb +248 -0
  164. data/lib/synthra/registry.rb +533 -0
  165. data/lib/synthra/relationships.rb +193 -0
  166. data/lib/synthra/repl/enhanced_repl.rb +607 -0
  167. data/lib/synthra/repl/formatter.rb +191 -0
  168. data/lib/synthra/scenarios.rb +423 -0
  169. data/lib/synthra/schema.rb +605 -0
  170. data/lib/synthra/schema_inheritance.rb +104 -0
  171. data/lib/synthra/schema_versioning.rb +212 -0
  172. data/lib/synthra/snapshot_testing.rb +199 -0
  173. data/lib/synthra/time_travel.rb +338 -0
  174. data/lib/synthra/type_definitions.rb +274 -0
  175. data/lib/synthra/types/address_location/addresses.rb +125 -0
  176. data/lib/synthra/types/address_location/airports.rb +200 -0
  177. data/lib/synthra/types/address_location/banks_hospitals.rb +207 -0
  178. data/lib/synthra/types/address_location/locations.rb +406 -0
  179. data/lib/synthra/types/base.rb +48 -0
  180. data/lib/synthra/types/commerce_products/commerce.rb +119 -0
  181. data/lib/synthra/types/commerce_products/companies.rb +71 -0
  182. data/lib/synthra/types/commerce_products/construction.rb +126 -0
  183. data/lib/synthra/types/commerce_products/products.rb +205 -0
  184. data/lib/synthra/types/core/collections.rb +513 -0
  185. data/lib/synthra/types/core/defaults.rb +76 -0
  186. data/lib/synthra/types/core/enums.rb +102 -0
  187. data/lib/synthra/types/core/identifiers.rb +445 -0
  188. data/lib/synthra/types/core/primitives.rb +586 -0
  189. data/lib/synthra/types/core/references.rb +466 -0
  190. data/lib/synthra/types/core/sequences.rb +304 -0
  191. data/lib/synthra/types/crypto/crypto.rb +162 -0
  192. data/lib/synthra/types/date_time/dates.rb +387 -0
  193. data/lib/synthra/types/finance_banking/banking.rb +424 -0
  194. data/lib/synthra/types/finance_banking/credit_cards.rb +24 -0
  195. data/lib/synthra/types/finance_banking/identifiers.rb +93 -0
  196. data/lib/synthra/types/formula.rb +184 -0
  197. data/lib/synthra/types/health_medical/medical.rb +150 -0
  198. data/lib/synthra/types/hostile_payloads.rb +122 -0
  199. data/lib/synthra/types/json_array.rb +51 -0
  200. data/lib/synthra/types/media_entertainment/media.rb +62 -0
  201. data/lib/synthra/types/naughty_string.rb +30 -0
  202. data/lib/synthra/types/personal_names/chinese.rb +41 -0
  203. data/lib/synthra/types/personal_names/identifiers.rb +187 -0
  204. data/lib/synthra/types/personal_names/names.rb +246 -0
  205. data/lib/synthra/types/personal_names/national_id.rb +89 -0
  206. data/lib/synthra/types/personal_names/titles_suffixes.rb +41 -0
  207. data/lib/synthra/types/regex.rb +248 -0
  208. data/lib/synthra/types/registry.rb +182 -0
  209. data/lib/synthra/types/repeating_element.rb +50 -0
  210. data/lib/synthra/types/scenario.rb +29 -0
  211. data/lib/synthra/types/technology_internet/apps.rb +67 -0
  212. data/lib/synthra/types/technology_internet/communication.rb +162 -0
  213. data/lib/synthra/types/technology_internet/devices.rb +80 -0
  214. data/lib/synthra/types/technology_internet/formats.rb +139 -0
  215. data/lib/synthra/types/technology_internet/networking.rb +143 -0
  216. data/lib/synthra/types/template.rb +92 -0
  217. data/lib/synthra/types/text_content/business.rb +128 -0
  218. data/lib/synthra/types/text_content/colors.rb +70 -0
  219. data/lib/synthra/types/text_content/misc.rb +237 -0
  220. data/lib/synthra/types/text_content/security.rb +130 -0
  221. data/lib/synthra/types/text_content/text_generation.rb +532 -0
  222. data/lib/synthra/types/travel/travel.rb +150 -0
  223. data/lib/synthra/utils/string_distance.rb +133 -0
  224. data/lib/synthra/validator/dsl_validator.rb +339 -0
  225. data/lib/synthra/validator/path_validator.rb +615 -0
  226. data/lib/synthra/version.rb +35 -0
  227. data/lib/synthra/webhook_simulator.rb +341 -0
  228. data/lib/synthra.rb +259 -0
  229. data/schemas/address.dsl +16 -0
  230. data/schemas/api_response.dsl +8 -0
  231. data/schemas/error_payload.dsl +9 -0
  232. data/schemas/order.dsl +10 -0
  233. data/schemas/order_item.dsl +8 -0
  234. data/schemas/payment.dsl +11 -0
  235. data/schemas/social_post.dsl +13 -0
  236. data/schemas/user.dsl +10 -0
  237. data/scripts/batch_fix_all.rb +96 -0
  238. data/scripts/delete_old_files.rb +32 -0
  239. data/scripts/fix_all_grouped_files.rb +137 -0
  240. data/scripts/fix_all_indentation.rb +48 -0
  241. data/scripts/fix_all_syntax.rb +124 -0
  242. data/scripts/fix_grouped_files.rb +184 -0
  243. data/scripts/fix_syntax_errors.rb +108 -0
  244. data/scripts/group_domain_types.rb +112 -0
  245. data/scripts/group_domain_types_fixed.rb +150 -0
  246. data/scripts/merge_domains_to_one_file.rb +68 -0
  247. data/scripts/move_existing_types.rb +130 -0
  248. data/scripts/split_grouped_types.rb +142 -0
  249. data/tech_docs/README.md +134 -0
  250. data/tech_docs/advanced/streaming.md +405 -0
  251. data/tech_docs/advanced/thread_safety.md +253 -0
  252. data/tech_docs/api/overview.md +485 -0
  253. data/tech_docs/appendices/type_chart.md +193 -0
  254. data/tech_docs/basic_concepts.md +383 -0
  255. data/tech_docs/behaviors/overview.md +346 -0
  256. data/tech_docs/dsl/complex_types.md +790 -0
  257. data/tech_docs/dsl/core_types.md +464 -0
  258. data/tech_docs/dsl/datetime_types.md +325 -0
  259. data/tech_docs/dsl/field_modifiers.md +414 -0
  260. data/tech_docs/dsl/grammar.md +431 -0
  261. data/tech_docs/dsl/schema_definition.md +399 -0
  262. data/tech_docs/export/README.md +276 -0
  263. data/tech_docs/installation.md +273 -0
  264. data/tech_docs/integration/ci_cd.md +707 -0
  265. data/tech_docs/integration/ci_cd_guide.md +579 -0
  266. data/tech_docs/integration/factory_bot.md +485 -0
  267. data/tech_docs/integration/rails.md +630 -0
  268. data/tech_docs/integration/rspec.md +449 -0
  269. data/tech_docs/modes/overview.md +350 -0
  270. data/tech_docs/performance/NATIVE_RUST_EXTENSION.md +1270 -0
  271. data/tech_docs/performance/OPTIMIZATION_GUIDE.md +901 -0
  272. data/tech_docs/quick_start.md +256 -0
  273. data/tech_docs/templates/README.md +805 -0
  274. data/tech_docs/tutorials/advanced.md +371 -0
  275. data/tech_docs/tutorials/getting_started.md +189 -0
  276. data/tech_docs/tutorials/intermediate.md +231 -0
  277. data/tech_docs/tutorials/template_gallery.md +569 -0
  278. data/tech_example/01_basic_usage.rb +238 -0
  279. data/tech_example/02_types_demo.rb +336 -0
  280. data/tech_example/04_cli_usage.md +429 -0
  281. data/tech_example/05_database_seeding.rb +283 -0
  282. data/tech_example/07_rspec_integration.rb +359 -0
  283. data/tech_example/10_custom_types.rb +387 -0
  284. data/tech_example/12_behaviors.rb +372 -0
  285. data/tech_example/13_twitter_dm_example.rb +120 -0
  286. data/tech_example/14_exact_json_structure.rb +253 -0
  287. data/tech_example/16_lsp_server.rb +56 -0
  288. data/tech_example/17_property_testing.rb +92 -0
  289. data/tech_example/18_enhanced_repl.rb +120 -0
  290. data/tech_example/19_security_fuzzing.rb +145 -0
  291. data/tech_example/NEW_FEATURES.md +169 -0
  292. data/tech_example/README.md +118 -0
  293. data/tech_example/schemas/api_response.dsl +123 -0
  294. data/tech_example/schemas/ecommerce.dsl +121 -0
  295. data/tech_example/schemas/twitter_dm.dsl +109 -0
  296. data/tech_example/schemas/user.dsl +36 -0
  297. data/vscode-extension/README.md +246 -0
  298. data/vscode-extension/language-configuration.json +31 -0
  299. data/vscode-extension/package.json +55 -0
  300. data/vscode-extension/snippets/fakedatadsl.json +198 -0
  301. data/vscode-extension/syntaxes/fakedatadsl.tmLanguage.json +128 -0
  302. metadata +478 -0
data/docs/index.html ADDED
@@ -0,0 +1,177 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>FakeDataDSL Documentation Index</title>
7
+ <style>
8
+ body {
9
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
10
+ line-height: 1.6;
11
+ max-width: 1200px;
12
+ margin: 0 auto;
13
+ padding: 20px;
14
+ background: #f5f5f5;
15
+ }
16
+ .container {
17
+ background: white;
18
+ padding: 40px;
19
+ border-radius: 8px;
20
+ box-shadow: 0 2px 4px rgba(0,0,0,0.1);
21
+ }
22
+ h1 {
23
+ color: #2c3e50;
24
+ border-bottom: 3px solid #3498db;
25
+ padding-bottom: 10px;
26
+ }
27
+ h2 {
28
+ color: #34495e;
29
+ margin-top: 30px;
30
+ }
31
+ .doc-grid {
32
+ display: grid;
33
+ grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
34
+ gap: 20px;
35
+ margin-top: 20px;
36
+ }
37
+ .doc-card {
38
+ border: 1px solid #ddd;
39
+ border-radius: 6px;
40
+ padding: 20px;
41
+ background: #fafafa;
42
+ transition: transform 0.2s, box-shadow 0.2s;
43
+ }
44
+ .doc-card:hover {
45
+ transform: translateY(-2px);
46
+ box-shadow: 0 4px 8px rgba(0,0,0,0.1);
47
+ }
48
+ .doc-card h3 {
49
+ margin-top: 0;
50
+ color: #2c3e50;
51
+ }
52
+ .doc-card a {
53
+ color: #3498db;
54
+ text-decoration: none;
55
+ font-weight: bold;
56
+ }
57
+ .doc-card a:hover {
58
+ text-decoration: underline;
59
+ }
60
+ .doc-card p {
61
+ color: #666;
62
+ font-size: 0.9em;
63
+ }
64
+ .nav-links {
65
+ margin-top: 30px;
66
+ padding-top: 20px;
67
+ border-top: 1px solid #ddd;
68
+ }
69
+ .nav-links a {
70
+ color: #3498db;
71
+ text-decoration: none;
72
+ margin-right: 20px;
73
+ }
74
+ .nav-links a:hover {
75
+ text-decoration: underline;
76
+ }
77
+ </style>
78
+ </head>
79
+ <body>
80
+ <div class="container">
81
+ <h1>📚 FakeDataDSL Documentation</h1>
82
+ <p>Welcome to the FakeDataDSL documentation! This page provides quick access to all guides and references.</p>
83
+
84
+ <h2>🚀 Getting Started</h2>
85
+ <div class="doc-grid">
86
+ <div class="doc-card">
87
+ <h3><a href="../doc/file.getting_started.html">Getting Started</a></h3>
88
+ <p>Quick start guide for FakeDataDSL. Learn how to install, define schemas, and generate data.</p>
89
+ </div>
90
+ <div class="doc-card">
91
+ <h3><a href="../doc/file.USAGE_GUIDE.html">Usage Guide</a></h3>
92
+ <p>Complete guide on DSL syntax, types, formulas, unique constraints, and options with examples.</p>
93
+ </div>
94
+ <div class="doc-card">
95
+ <h3><a href="../doc/file.QUICK_REFERENCE.html">Quick Reference</a></h3>
96
+ <p>Quick reference card with common syntax and examples for quick lookup.</p>
97
+ </div>
98
+ </div>
99
+
100
+ <h2>📖 Reference Guides</h2>
101
+ <div class="doc-grid">
102
+ <div class="doc-card">
103
+ <h3><a href="../doc/file.dsl_reference.html">DSL Reference</a></h3>
104
+ <p>Complete reference for the FakeDataDSL syntax, including all field types and modifiers.</p>
105
+ </div>
106
+ <div class="doc-card">
107
+ <h3><a href="../doc/file.type_reference.html">Type Reference</a></h3>
108
+ <p>Comprehensive list of all available data types with examples and usage.</p>
109
+ </div>
110
+ <div class="doc-card">
111
+ <h3><a href="../doc/file.api_reference.html">API Reference</a></h3>
112
+ <p>Programmatic API documentation for using FakeDataDSL in Ruby code.</p>
113
+ </div>
114
+ </div>
115
+
116
+ <h2>🎯 Feature Guides</h2>
117
+ <div class="doc-grid">
118
+ <div class="doc-card">
119
+ <h3><a href="../doc/file.behaviors.html">Behaviors Guide</a></h3>
120
+ <p>Learn how to use behaviors like latency, failure simulation, and partial data.</p>
121
+ </div>
122
+ <div class="doc-card">
123
+ <h3><a href="../doc/file.generation_modes.html">Generation Modes</a></h3>
124
+ <p>Understand random, edge, invalid, and mixed generation modes for testing.</p>
125
+ </div>
126
+ <div class="doc-card">
127
+ <h3><a href="../doc/file.advanced_features.html">Advanced Features</a></h3>
128
+ <p>Cross-schema references, custom functions, streaming, and more advanced topics.</p>
129
+ </div>
130
+ </div>
131
+
132
+ <h2>💡 Examples & Best Practices</h2>
133
+ <div class="doc-grid">
134
+ <div class="doc-card">
135
+ <h3><a href="../doc/file.examples.html">Examples</a></h3>
136
+ <p>Real-world examples for e-commerce, social media, healthcare, and financial applications.</p>
137
+ </div>
138
+ <div class="doc-card">
139
+ <h3><a href="../doc/file.best_practices.html">Best Practices</a></h3>
140
+ <p>Tips and recommendations for using FakeDataDSL effectively.</p>
141
+ </div>
142
+ <div class="doc-card">
143
+ <h3><a href="../doc/file.troubleshooting.html">Troubleshooting</a></h3>
144
+ <p>Common issues and solutions when using FakeDataDSL.</p>
145
+ </div>
146
+ </div>
147
+
148
+ <h2>🔧 Additional Resources</h2>
149
+ <div class="doc-grid">
150
+ <div class="doc-card">
151
+ <h3><a href="../doc/file.HOW_TO_GENERATE_DOCS.html">How to Generate Docs</a></h3>
152
+ <p>Guide on generating and accessing YARD documentation.</p>
153
+ </div>
154
+ <div class="doc-card">
155
+ <h3><a href="../doc/index.html">YARD API Documentation</a></h3>
156
+ <p>Complete API reference generated from code comments.</p>
157
+ </div>
158
+ <div class="doc-card">
159
+ <h3><a href="../doc/file_list.html">All Files</a></h3>
160
+ <p>Complete list of all documentation files.</p>
161
+ </div>
162
+ </div>
163
+
164
+ <div class="nav-links">
165
+ <h2>🔗 Quick Links</h2>
166
+ <p>
167
+ <a href="../doc/index.html">YARD Index</a>
168
+ <a href="../doc/class_list.html">All Classes</a>
169
+ <a href="../doc/method_list.html">All Methods</a>
170
+ <a href="../doc/file_list.html">All Files</a>
171
+ <a href="../README.md">Project README</a>
172
+ </p>
173
+ </div>
174
+ </div>
175
+ </body>
176
+ </html>
177
+
data/docs/strategic/CLOUD_REGISTRY_ARCHITECTURE.md ADDED
@@ -0,0 +1,268 @@
1
+ # Cloud Schema Registry Architecture
2
+ # =============================================================================
3
+ #
4
+ # Strategic architecture for a Central Schema Registry Service to enable
5
+ # schema sharing across teams and organizations at scale (50+ engineers).
6
+ #
7
+ # Status: Architecture Planning Phase
8
+ # Target: Future v2.0+ feature
9
+ #
10
+ # =============================================================================
11
+
12
+ ## Problem Statement
13
+
14
+ As FakeDataDSL adoption scales to 50+ engineers:
15
+ - Git-based schema sharing becomes cumbersome
16
+ - Schema versioning conflicts increase
17
+ - Cross-team schema discovery is difficult
18
+ - Contract testing requires manual coordination
19
+
20
+ ## Solution: Central Schema Registry
21
+
22
+ A centralized service for publishing, versioning, and discovering schemas
23
+ across teams and organizations.
24
+
25
+ ## Architecture Overview
26
+
27
+ ```
28
+ ┌─────────────────────────────────────────────────────────────┐
29
+ │ Schema Registry Service │
30
+ │ (REST API + gRPC + WebSocket for real-time updates) │
31
+ ├─────────────────────────────────────────────────────────────┤
32
+ │ Features: │
33
+ │ - Schema publishing (User v1.0, Order v2.3) │
34
+ │ - Version management (semantic versioning) │
35
+ │ - Schema discovery (search, browse, tags) │
36
+ │ - Contract testing (Frontend ↔ Backend validation) │
37
+ │ - Access control (team-based permissions) │
38
+ └─────────────────────────────────────────────────────────────┘
39
+ │
40
+ │ HTTP/gRPC
41
+ │
42
+ ┌─────────────────────┴─────────────────────┐
43
+ │ │
44
+ ┌───────▼────────┐ ┌────────▼───────┐
45
+ │ Backend Team │ │ Frontend Team │
46
+ │ Publishes: │ │ Consumes: │
47
+ │ User v1.0 │ │ User v1.0 │
48
+ │ Order v2.3 │ │ (for mocks) │
49
+ └────────────────┘ └────────────────┘
50
+ ```
51
+
52
+ ## Core Features
53
+
54
+ ### 1. Schema Publishing
55
+
56
+ ```ruby
57
+ # Backend team publishes schema
58
+ FakeDataDSL::Registry::Cloud.publish(
59
+ schema: user_schema,
60
+ version: "1.0.0",
61
+ team: "backend",
62
+ tags: ["user", "authentication"],
63
+ description: "User authentication schema"
64
+ )
65
+ ```
66
+
67
+ ### 2. Schema Discovery
68
+
69
+ ```ruby
70
+ # Frontend team discovers schemas
71
+ schemas = FakeDataDSL::Registry::Cloud.search(
72
+ tags: ["user"],
73
+ team: "backend",
74
+ version: ">=1.0.0"
75
+ )
76
+
77
+ # Load schema for mocking
78
+ user_schema = FakeDataDSL::Registry::Cloud.fetch("User", version: "1.0.0")
79
+ ```
80
+
81
+ ### 3. Ref() with Remote Lookup
82
+
83
+ ```ruby
84
+ # Ref() automatically resolves from registry if not found locally
85
+ # user.dsl
86
+ Order:
87
+ user_id: Ref(User.id) # Looks up User schema from registry if not local
88
+ ```
89
+
90
+ ### 4. Contract Testing
91
+
92
+ ```ruby
93
+ # Frontend generates mocks using exact backend schema
94
+ backend_schema = FakeDataDSL::Registry::Cloud.fetch("User", team: "backend", version: "1.0.0")
95
+ mock_data = backend_schema.generate_many(100)
96
+
97
+ # Validate frontend handles backend schema correctly
98
+ expect(frontend_component).to_handle_schema(backend_schema)
99
+ ```
100
+
101
+ ## API Design
102
+
103
+ ### REST API
104
+
105
+ ```
106
+ POST /api/v1/schemas # Publish schema
107
+ GET /api/v1/schemas/:name # Get schema
108
+ GET /api/v1/schemas/:name/versions # List versions
109
+ GET /api/v1/schemas?team=backend # Search schemas
110
+ PUT /api/v1/schemas/:name/:version # Update schema
111
+ DELETE /api/v1/schemas/:name/:version # Deprecate schema
112
+ ```
113
+
114
+ ### gRPC API (for high-performance clients)
115
+
116
+ ```protobuf
117
+ service SchemaRegistry {
118
+ rpc PublishSchema(PublishRequest) returns (PublishResponse);
119
+ rpc GetSchema(GetSchemaRequest) returns (Schema);
120
+ rpc SearchSchemas(SearchRequest) returns (SearchResponse);
121
+ rpc WatchSchema(WatchRequest) returns (stream SchemaUpdate);
122
+ }
123
+ ```
124
+
125
+ ## Implementation Phases
126
+
127
+ ### Phase 1: Local Registry Cache (MVP)
128
+
129
+ - Client-side caching of fetched schemas
130
+ - HTTP client for schema fetching
131
+ - Fallback to local schemas if registry unavailable
132
+
133
+ ```ruby
134
+ # lib/fake_data_dsl/registry/cloud.rb
135
+ module FakeDataDSL
136
+ module Registry
137
+ class Cloud
138
+ def self.fetch(name, version: nil, team: nil)
139
+ # Try cache first
140
+ # Then HTTP fetch
141
+ # Fallback to local registry
142
+ end
143
+ end
144
+ end
145
+ end
146
+ ```
147
+
148
+ ### Phase 2: Full Registry Service
149
+
150
+ - REST API server (Ruby/Rails or Go)
151
+ - Schema storage (PostgreSQL with JSONB)
152
+ - Version management
153
+ - Search and discovery
154
+ - Authentication/authorization
155
+
156
+ ### Phase 3: Advanced Features
157
+
158
+ - Real-time schema updates (WebSocket)
159
+ - Schema diff visualization
160
+ - Contract testing framework
161
+ - Schema analytics (usage, versions, teams)
162
+
163
+ ## Data Model
164
+
165
+ ```sql
166
+ CREATE TABLE schemas (
167
+ id UUID PRIMARY KEY,
168
+ name VARCHAR(255) NOT NULL,
169
+ version VARCHAR(50) NOT NULL,
170
+ team VARCHAR(100) NOT NULL,
171
+ dsl_content TEXT NOT NULL,
172
+ compiled_json JSONB NOT NULL,
173
+ tags TEXT[],
174
+ description TEXT,
175
+ published_at TIMESTAMP NOT NULL,
176
+ deprecated_at TIMESTAMP,
177
+ UNIQUE(name, version, team)
178
+ );
179
+
180
+ CREATE INDEX idx_schemas_name ON schemas(name);
181
+ CREATE INDEX idx_schemas_team ON schemas(team);
182
+ CREATE INDEX idx_schemas_tags ON schemas USING GIN(tags);
183
+ ```
184
+
185
+ ## Client Integration
186
+
187
+ ### Configuration
188
+
189
+ ```ruby
190
+ FakeDataDSL.configure do |config|
191
+ config.registry_url = "https://registry.company.com"
192
+ config.registry_token = ENV["REGISTRY_TOKEN"]
193
+ config.registry_team = "backend"
194
+ config.registry_cache_ttl = 3600 # 1 hour
195
+ end
196
+ ```
197
+
198
+ ### Automatic Resolution
199
+
200
+ ```ruby
201
+ # Ref() automatically resolves from registry
202
+ registry = FakeDataDSL::Registry.new
203
+ registry.load_file("user.dsl") # Local schema
204
+
205
+ # Order.dsl references User - automatically fetched from registry
206
+ registry.load_file("order.dsl") # Ref(User.id) resolves from registry
207
+ ```
208
+
209
+ ## Security & Access Control
210
+
211
+ - **Authentication**: API tokens per team
212
+ - **Authorization**: Team-based access control
213
+ - **Schema Privacy**: Private schemas (team-only) vs public schemas
214
+ - **Rate Limiting**: Prevent abuse
215
+
216
+ ## Deployment Options
217
+
218
+ ### Option 1: SaaS (Hosted Service)
219
+
220
+ - FakeDataDSL team hosts registry
221
+ - Free tier + paid tiers
222
+ - Multi-tenant architecture
223
+
224
+ ### Option 2: Self-Hosted
225
+
226
+ - Docker container
227
+ - Kubernetes deployment
228
+ - On-premises installation
229
+
230
+ ### Option 3: Hybrid
231
+
232
+ - Local registry for internal schemas
233
+ - Cloud registry for public/shared schemas
234
+
235
+ ## Success Metrics
236
+
237
+ - **Adoption**: 50+ engineers using registry
238
+ - **Performance**: <100ms schema fetch latency
239
+ - **Reliability**: 99.9% uptime
240
+ - **Usage**: 1000+ schema versions published
241
+
242
+ ## Migration Path
243
+
244
+ 1. **Phase 1**: Add client library (backward compatible)
245
+ 2. **Phase 2**: Deploy registry service (optional)
246
+ 3. **Phase 3**: Teams migrate schemas to registry
247
+ 4. **Phase 4**: Registry becomes primary source
248
+
249
+ ## Open Questions
250
+
251
+ 1. **Schema Format**: Store DSL or compiled JSON?
252
+ - **Recommendation**: Both (DSL for human editing, JSON for fast loading)
253
+
254
+ 2. **Versioning Strategy**: Semantic versioning or timestamp-based?
255
+ - **Recommendation**: Semantic versioning (1.0.0, 1.1.0, 2.0.0)
256
+
257
+ 3. **Conflict Resolution**: What if two teams publish same schema name?
258
+ - **Recommendation**: Namespace by team (backend/User vs frontend/User)
259
+
260
+ 4. **Backward Compatibility**: How to handle breaking changes?
261
+ - **Recommendation**: Major version bumps (1.0.0 → 2.0.0) + deprecation warnings
262
+
263
+ ## References
264
+
265
+ - JSON Schema Registry patterns
266
+ - Docker Registry architecture
267
+ - NPM registry design
268
+ - Maven Central Repository
data/docs/strategic/SIMD_OPTIMIZATION_STRATEGY.md ADDED
@@ -0,0 +1,153 @@
1
+ # SIMD-Accelerated Generation Strategy
2
+ # =============================================================================
3
+ #
4
+ # Strategic plan for SIMD (Single Instruction, Multiple Data) optimizations
5
+ # in the Rust native engine to achieve 20-30% additional performance for
6
+ # massive datasets (100M+ records).
7
+ #
8
+ # Status: Strategic Planning Phase
9
+ # Target: Rust native engine (ext/fake_data_dsl_native/)
10
+ #
11
+ # =============================================================================
12
+
13
+ ## Overview
14
+
15
+ SIMD instructions allow processing multiple data elements in parallel using
16
+ specialized CPU instructions. For FakeDataDSL, SIMD can accelerate:
17
+
18
+ 1. **UUID Generation** - Generate 4 UUIDs per SIMD operation (AVX-512)
19
+ 2. **Number Formatting** - Parallel integer-to-string conversion
20
+ 3. **JSON Serialization** - Vectorized string escaping and formatting
21
+ 4. **String Operations** - Parallel character manipulation
22
+
23
+ ## Target Hot Paths
24
+
25
+ ### 1. UUID Generation (Highest Impact)
26
+
27
+ **Current**: Sequential UUID generation using `uuid` crate
28
+ **SIMD Opportunity**: Generate 4-8 UUIDs per operation using AVX-512
29
+
30
+ ```rust
31
+ // Pseudo-code for SIMD UUID generation
32
+ #[target_feature(enable = "avx512f")]
33
+ unsafe fn generate_uuid_batch_simd(count: usize) -> Vec<Uuid> {
34
+ // Generate 4 UUIDs per SIMD operation
35
+ // Use AVX-512 for 512-bit operations
36
+ }
37
+ ```
38
+
39
+ **Expected Speedup**: 3-4x for UUID-heavy schemas
40
+
41
+ ### 2. Number Formatting
42
+
43
+ **Current**: Sequential integer-to-string conversion
44
+ **SIMD Opportunity**: Format multiple integers in parallel
45
+
46
+ ```rust
47
+ // Use SIMD for parallel number formatting
48
+ // Process 8-16 integers per operation
49
+ ```
50
+
51
+ **Expected Speedup**: 2-3x for number-heavy schemas
52
+
53
+ ### 3. JSON Serialization
54
+
55
+ **Current**: Sequential character-by-character escaping
56
+ **SIMD Opportunity**: Vectorized string escaping
57
+
58
+ ```rust
59
+ // Use SIMD to escape multiple characters in parallel
60
+ // Detect special characters (", \, \n, etc.) in batches
61
+ ```
62
+
63
+ **Expected Speedup**: 1.5-2x for JSON output
64
+
65
+ ## Implementation Strategy
66
+
67
+ ### Phase 1: UUID SIMD (Highest ROI)
68
+
69
+ 1. **Research**: Evaluate `simd-uuid` crate or implement custom AVX-512 UUID generation
70
+ 2. **Benchmark**: Measure current UUID generation throughput
71
+ 3. **Implement**: Add SIMD UUID generation path
72
+ 4. **Validate**: Ensure deterministic output with seeds
73
+ 5. **Deploy**: Feature flag for SIMD UUID generation
74
+
75
+ ### Phase 2: Number Formatting SIMD
76
+
77
+ 1. **Research**: Evaluate `itoa` SIMD optimizations or custom implementation
78
+ 2. **Implement**: Parallel integer formatting
79
+ 3. **Benchmark**: Compare against current implementation
80
+
81
+ ### Phase 3: JSON Serialization SIMD
82
+
83
+ 1. **Research**: Evaluate `simd-json` or custom SIMD escaping
84
+ 2. **Implement**: Vectorized string escaping
85
+ 3. **Benchmark**: Measure JSON serialization throughput
86
+
87
+ ## Technical Considerations
88
+
89
+ ### CPU Feature Detection
90
+
91
+ ```rust
92
+ // Runtime CPU feature detection
93
+ if is_x86_feature_detected!("avx512f") {
94
+ use_simd_path()
95
+ } else if is_x86_feature_detected!("avx2") {
96
+ use_avx2_path()
97
+ } else {
98
+ use_scalar_path()
99
+ }
100
+ ```
101
+
102
+ ### Fallback Strategy
103
+
104
+ - Always provide scalar fallback for CPUs without SIMD support
105
+ - Use runtime feature detection, not compile-time
106
+ - Gracefully degrade on older CPUs
107
+
108
+ ### Determinism
109
+
110
+ - SIMD operations must maintain deterministic output with seeds
111
+ - Ensure same seed produces same output regardless of SIMD path
112
+ - Test determinism across different CPU architectures
113
+
114
+ ## Performance Targets
115
+
116
+ | Operation | Current | SIMD Target | Speedup |
117
+ |-----------|---------|-------------|---------|
118
+ | UUID generation | ~500K/sec | ~2M/sec | 4x |
119
+ | Number formatting | ~1M/sec | ~2.5M/sec | 2.5x |
120
+ | JSON serialization | ~300K/sec | ~500K/sec | 1.7x |
121
+ | Overall (mixed) | ~3.5M/sec | ~4.5M/sec | 1.3x |
122
+
123
+ ## Implementation Timeline
124
+
125
+ - **Q1**: Research and prototype UUID SIMD
126
+ - **Q2**: Implement and benchmark UUID SIMD
127
+ - **Q3**: Add number formatting SIMD
128
+ - **Q4**: Add JSON serialization SIMD
129
+
130
+ ## Risks & Mitigation
131
+
132
+ 1. **CPU Compatibility**: Not all CPUs support AVX-512
133
+ - **Mitigation**: Runtime detection with fallback
134
+
135
+ 2. **Complexity**: SIMD code is harder to maintain
136
+ - **Mitigation**: Extensive tests, clear documentation
137
+
138
+ 3. **Determinism**: SIMD operations must be deterministic
139
+ - **Mitigation**: Careful seed handling, comprehensive tests
140
+
141
+ ## Success Metrics
142
+
143
+ - 20-30% overall performance improvement for 100M+ record generation
144
+ - No regression on CPUs without SIMD support
145
+ - Maintain 100% deterministic output with seeds
146
+ - Zero increase in memory usage
147
+
148
+ ## References
149
+
150
+ - Intel AVX-512 Programming Reference
151
+ - Rust SIMD Working Group: https://github.com/rust-lang/stdsimd
152
+ - `simd-json` crate for JSON optimization patterns
153
+ - `simd-uuid` research papers