synthra 0.1.0

data/docs/STRING_TEXT_TYPES_REFERENCE.md

@@ -0,0 +1,512 @@
+# FakeDataDSL: String & Text Types Reference
+
+Complete reference for all string-related types in the FakeDataDSL gem. Each type inherits from `Types::Base` and implements `generate_random`, `generate_edge`, and `generate_invalid`.
+
+---
+
+## Table of Contents
+
+1. [Core Text Types](#1-core-text-types)
+2. [Structured Text (Words, Sentences, Paragraphs)](#2-structured-text-words-sentences-paragraphs)
+3. [Business & Marketing Text](#3-business--marketing-text)
+4. [Message & Social Text](#4-message--social-text)
+5. [Security & Hash Types](#5-security--hash-types)
+6. [Color Types](#6-color-types)
+7. [Miscellaneous String Types](#7-miscellaneous-string-types)
+8. [Special-Purpose String Types](#8-special-purpose-string-types)
+9. [Parser Argument Reference](#9-parser-argument-reference)
+
+---
+
+## 1. Core Text Types
+
+### `text` / `string`
+
+**Location:** `lib/fake_data_dsl/types/core/primitives.rb`  
+**Alias:** `string` maps to `text` for OpenAPI/contract compatibility
+
+**Description:** Generates random readable text with optional length constraints and locale support. Uses Faker for locale-specific text.
+
+#### Arguments (from parser)
+
+| Arg | Type | DSL Example | Description |
+|-----|------|-------------|-------------|
+| `:range` | `Range` | `text(1..10)` | Character length range |
+| `:min` | Integer | `text(min: 50, max: 200)` | Minimum character length |
+| `:max` | Integer | `text(min: 50, max: 200)` | Maximum character length |
+| `:value` | Integer | `text(100)` | Exact character length |
+| `:locale` | Symbol | `text(ar)` | Locale code (stored when `text(ar)` parsed) |
+| `:language` | Symbol | `text(locale: :ar)` | Locale alias |
+| `:lang` | Symbol | `text(lang: :ar)` | Locale alias |
+
+#### Implementation
+
+- **Length extraction:** `extract_length(args)` reads `:range`, `:min`/`:max`, or `:value` (default `[10, 100]`)
+- **Locale resolution:** `args[:locale] || args[:language] || args[:lang] || args[:value]` (when `:value` is a Symbol like `:ar`)
+- **Generation:** Uses `faker_english_words` (Lovecraft, Company.bs, Commerce) for English; `faker_localized_words` (Name, Address, Company) for other locales
+- **Truncation:** When explicit length is set, output is truncated to `[min_len, max_len]` characters
+
+#### Supported locales
+
+`en`, `ar`, `es`, `fr`, `de`, `it`, `pt`, `ru`, `zh`, `ja`, `ko`, `hi` (and extended forms like `en_us`, `ar_sa`, etc.)
+
+#### DSL examples
+
+```
+bio: text(50..200)
+reason_ar: text(ar)
+reason_ar: text(ar, 1..10)
+title: text(en, 5..50)
+```
+
+---
+
+## 2. Structured Text (Words, Sentences, Paragraphs)
+
+**Location:** `lib/fake_data_dsl/types/text_content/text_generation.rb`
+
+### `words`
+
+**Description:** Space-separated words (3–10 by default).
+
+#### Arguments
+
+| Arg | Type | Default | Description |
+|-----|------|---------|-------------|
+| `:min` | Integer | 3 | Minimum word count |
+| `:max` | Integer | 10 | Maximum word count |
+
+#### Implementation
+
+- Uses `faker_adapter(context)` if available → `adapter.characters(number: rng.int(3, 10))` per word
+- Else `Faker::Lorem.words(number: count).join(" ")`
+
+#### DSL example
+
+```
+tags: words(min: 2, max: 5)
+```
+
+---
+
+### `sentences`
+
+**Description:** One or more sentences (1–5 by default).
+
+#### Arguments
+
+| Arg | Type | Default | Description |
+|-----|------|---------|-------------|
+| `:min` | Integer | 1 | Minimum sentence count |
+| `:max` | Integer | 5 | Maximum sentence count |
+
+#### Implementation
+
+- With adapter: `count.times.map { adapter.characters(number: rng.int(20, 100)) }.join(". ") + "."`
+- Else: `Faker::Lorem.sentences(number: count).join(" ")`
+
+#### DSL example
+
+```
+summary: sentences(min: 1, max: 3)
+```
+
+---
+
+### `paragraphs`
+
+**Description:** One or more paragraphs separated by `\n\n` (1–3 by default).
+
+#### Arguments
+
+| Arg | Type | Default | Description |
+|-----|------|---------|-------------|
+| `:min` | Integer | 1 | Minimum paragraph count |
+| `:max` | Integer | 3 | Maximum paragraph count |
+
+#### Implementation
+
+- With adapter: `count.times.map { adapter.characters(number: rng.int(50, 200)) }.join("\n\n")`
+- Else: `Faker::Lorem.paragraphs(number: count).join("\n\n")`
+
+#### DSL example
+
+```
+article: paragraphs(min: 2, max: 5)
+```
+
+---
+
+## 3. Business & Marketing Text
+
+**Location:** `lib/fake_data_dsl/types/text_content/business.rb`
+
+### `buzzword`
+
+**Description:** Single business buzzword (e.g. "Synergy", "Leverage", "Disrupt").
+
+- Uses `Faker::Company.buzzword` or adapter's `buzzword`
+- Fallback: hardcoded `BUZZWORDS` array
+
+---
+
+### `catch_phrase`
+
+**Description:** Company-style catch phrase (e.g. "Think Different", "Just Do It").
+
+- Uses `Faker::Company.catch_phrase` or adapter
+- Fallback: hardcoded `PHRASES` array
+
+---
+
+### `slogan`
+
+**Description:** Brand slogan (e.g. "I'm Lovin' It", "Finger Lickin' Good").
+
+- Uses adapter's `slogan` or `Faker::Company.catch_phrase`
+- Fallback: hardcoded `SLOGANS` array
+
+---
+
+### `fake_company_name`
+
+**Description:** Company name.
+
+- Uses adapter's `company_name` or `Faker::Company.name`
+- Fallback: hardcoded list
+
+---
+
+## 4. Message & Social Text
+
+**Location:** `lib/fake_data_dsl/types/text_content/text_generation.rb`
+
+### `message_text`
+
+**Description:** Chat/DM-style messages with locale support.
+
+#### Arguments
+
+| Arg | Type | Description |
+|-----|------|-------------|
+| `:locale` | Symbol/String | `en`, `ar`, `es`, `fr` |
+| `:language` | Symbol | Locale alias |
+| `:lang` | Symbol | Locale alias |
+| `:locales` | Array | Mixed locales |
+| `:mixed` | Array | Mixed locales |
+| `locale: "en,ar"` | String | Comma-separated locales |
+
+#### Implementation
+
+- Static per-locale pools: `SAMPLE_MESSAGES_EN`, `SAMPLE_MESSAGES_AR`, `SAMPLE_MESSAGES_ES`, `SAMPLE_MESSAGES_FR`
+- 50% Faker, 50% static; Faker uses `Lorem`, `Company.catch_phrase`, `Quote.famous_last_words`, etc.
+- Arabic: templates with `Faker::Name`, `Faker::Company`, `Faker::Address` in `:ar`
+- Mixed: randomly selects locale then picks message from that pool
+
+---
+
+### `hashtag_text`
+
+**Description:** Hashtag-style text without `#`.
+
+- Uses adapter's `internet.slug` (hyphens removed) or hardcoded `HASHTAGS` list
+
+---
+
+### `social_handle`
+
+**Description:** Username-style handle without `@`.
+
+- Uses adapter's `internet.username` or `Faker::Internet.username(specifier: 5..15)`
+- Fallback: `"user_#{rng.int(1000, 99999)}"`
+
+---
+
+## 5. Security & Hash Types
+
+**Location:** `lib/fake_data_dsl/types/text_content/security.rb`
+
+### `password`
+
+**Description:** Random password with configurable character requirements.
+
+#### Arguments
+
+| Arg | Type | Default | Description |
+|-----|------|---------|-------------|
+| `:min_length` | Integer | 8 | Minimum length |
+| `:min_upper` | Integer | 1 | Minimum uppercase letters |
+| `:min_lower` | Integer | 1 | Minimum lowercase letters |
+| `:min_numbers` | Integer | 1 | Minimum digits |
+| `:min_symbols` | Integer | 0 | Minimum symbols |
+
+#### Implementation
+
+- Builds password from required char sets, then shuffles with RNG
+
+---
+
+### `password_hash`
+
+**Description:** bcrypt-like hash string (60 chars, `$2a$10$` prefix).
+
+- Random alphanumeric + `./` for the hash part
+
+---
+
+### `md5`
+
+**Description:** 32-character hex MD5-like string.
+
+---
+
+### `sha1`
+
+**Description:** 40-character hex SHA1-like string.
+
+---
+
+### `sha256`
+
+**Description:** 64-character hex SHA256-like string.
+
+---
+
+### `encrypt`
+
+**Description:** Base64-like encrypted-looking string (20–40 chars).
+
+---
+
+## 6. Color Types
+
+**Location:** `lib/fake_data_dsl/types/text_content/colors.rb`
+
+### `color`
+
+**Description:** Color name (e.g. "Red", "Blue").
+
+- Uses `Faker::Commerce.color` or adapter's `color`
+- Fallback: hardcoded `COLORS` array
+
+---
+
+### `hex_color`
+
+**Description:** 6-digit hex color (e.g. `#A1B2C3`).
+
+- Random hex digits
+
+---
+
+### `short_hex_color`
+
+**Description:** 3-digit short hex color (e.g. `#F00`).
+
+---
+
+## 7. Miscellaneous String Types
+
+**Location:** `lib/fake_data_dsl/types/text_content/misc.rb`
+
+### `avatar`
+
+**Description:** Avatar image URL (pravatar.cc).
+
+#### Arguments
+
+| Arg | Type | Default |
+|-----|------|---------|
+| `:height` | Integer | 200 |
+| `:width` | Integer | 200 |
+
+- Format: `https://i.pravatar.cc/#{width}?img=#{rng.int(1, 70)}`
+
+---
+
+### `file_name`
+
+**Description:** File name with extension (e.g. `document_42.pdf`).
+
+- Name from fixed list; random number; extension from `EXTENSIONS`
+
+---
+
+### `frequency`
+
+**Description:** Frequency label ("Daily", "Weekly", "Monthly", etc.).
+
+- From hardcoded `FREQUENCIES` array
+
+---
+
+### `linkedin_skill`
+
+**Description:** Skill label (e.g. "JavaScript", "React", "AWS").
+
+- From hardcoded `SKILLS` array
+
+---
+
+### `nato_phonetic`
+
+**Description:** NATO phonetic alphabet words (e.g. "Alpha Bravo Charlie").
+
+#### Arguments
+
+| Arg | Type | Default |
+|-----|------|---------|
+| `:min` | Integer | 1 |
+| `:max` | Integer | 5 |
+
+---
+
+### `university`
+
+**Description:** University name (e.g. "Harvard University").
+
+---
+
+### `blank`
+
+**Description:** Always returns `""`.
+
+---
+
+### `race`
+
+**Description:** Race/ethnicity category string.
+
+---
+
+### `department_corporate`
+
+**Description:** Corporate department name (e.g. "Engineering", "Sales").
+
+---
+
+### `department_retail`
+
+**Description:** Retail department name (e.g. "Electronics", "Clothing").
+
+---
+
+## 8. Special-Purpose String Types
+
+### `naughty_string`
+
+**Location:** `lib/fake_data_dsl/types/naughty_string.rb`
+
+**Description:** Strings for security/edge-case testing.
+
+#### Arguments
+
+| Arg | Type | Values | Description |
+|-----|------|--------|-------------|
+| `:category` | Symbol | `:sql`, `:xss`, `:path`, `:default` | Attack category |
+
+- `sql`: SQL injection samples  
+- `xss`: XSS samples  
+- `path`: Path traversal samples  
+- `default`: empty, null, undefined, control chars  
+
+---
+
+### `regex`
+
+**Location:** `lib/fake_data_dsl/types/regex.rb`
+
+**Description:** String matching a regex pattern (limited support).
+
+#### Arguments
+
+| Arg | Type | Description |
+|-----|------|-------------|
+| `:pattern` | String/Regexp | Regex pattern |
+
+- Supports simple patterns (e.g. phone `^\d{3}-\d{3}-\d{4}$`, digits)
+- Fallback: `"generated_string"`
+
+---
+
+### `indices_pair`
+
+**Location:** `lib/fake_data_dsl/types/text_content/text_generation.rb`
+
+**Description:** `[start, end]` pair for text entity positions.
+
+- `start = rng.int(0, 100)`, `length = rng.int(5, 30)` → `[start, start + length]`
+
+---
+
+### `empty_array`
+
+**Location:** `lib/fake_data_dsl/types/text_content/text_generation.rb`
+
+**Description:** Always returns `[]` (not a string; listed for completeness).
+
+---
+
+## 9. Parser Argument Reference
+
+The parser (`lib/fake_data_dsl/parser/parser.rb`) produces `type_args` from DSL:
+
+| Token | Stored as | Example |
+|-------|-----------|---------|
+| `1..10` | `args[:range] = 1..10` | `text(1..10)` |
+| `min: 5, max: 20` | `args[:min]=5`, `args[:max]=20` | `text(min: 5, max: 20)` |
+| `100` | `args[:value] = 100` | `text(100)` |
+| `ar` (locale code) | `args[:locale] = :ar` | `text(ar)` |
+| `name: value` | `args[name] = value` | `text(locale: :ar)` |
+| `"string"` | `args[:path] = "string"` | Used by references |
+| `30%` | `args[:probability] = 30` | Used by boolean |
+
+**Multiple args (comma-separated):**
+
+```
+text(ar, 1..10)   → { locale: :ar, range: 1..10 }
+text(1..10, ar)   → { range: 1..10, locale: :ar }
+words(min: 2, max: 5)  → { min: 2, max: 5 }
+```
+
+---
+
+## Type Base Contract
+
+All types extend `Types::Base`:
+
+```ruby
+def generate(rng, context, args, mode)
+  case mode
+  when :random then generate_random(rng, context, args)
+  when :edge   then generate_edge(rng, context, args)
+  when :invalid then generate_invalid(rng, context, args)
+  when :hostile then generate_hostile(rng, context, args)
+  else generate_random(rng, context, args)
+  end
+end
+```
+
+- **`generate_random`** – normal fake data (required)
+- **`generate_edge`** – edge cases (empty, single char, etc.)
+- **`generate_invalid`** – invalid values (nil, wrong type)
+- **`generate_hostile`** – security-style payloads (optional; `text` overrides)
+
+---
+
+## File Locations Summary
+
+| Category | File |
+|----------|------|
+| Core text | `types/core/primitives.rb` |
+| Words, sentences, paragraphs, message_text, hashtag_text, social_handle, indices_pair, empty_array | `types/text_content/text_generation.rb` |
+| Buzzword, catch_phrase, slogan, fake_company_name | `types/text_content/business.rb` |
+| Avatar, file_name, frequency, linkedin_skill, nato_phonetic, row_number, sql_expression, university, blank, race, department_* | `types/text_content/misc.rb` |
+| Password, password_hash, md5, sha1, sha256, encrypt | `types/text_content/security.rb` |
+| Color, hex_color, short_hex_color | `types/text_content/colors.rb` |
+| Naughty string | `types/naughty_string.rb` |
+| Regex | `types/regex.rb` |
+
+---
+
+*Last updated: 2026-02*