@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-12-analyze-source-structure.md

@@ -1,518 +1,518 @@
-# Module 12: Analyze Source Structure
-
-**Level:** Beginner  
-**Category:** Command Line  
-**Time:** 10 minutes
-
-## Overview
-
-The `analyze-source-structure` CLI tool helps you understand your source data structure and generate mapping configuration suggestions. It supports XML, JSON, CSV, and Parquet files.
-
----
-
-## Why Use This Tool?
-
-**Common Problems:**
-- ❌ "I don't know what paths to use in my mapping config"
-- ❌ "How does this XML get parsed by the SDK?"
-- ❌ "I need to understand the structure before writing mappings"
-- ❌ "My mapping isn't working - is the path correct?"
-
-**Solution:**
-- ✅ Analyze your source file first
-- ✅ See the exact parsed structure
-- ✅ Get suggested mapping paths
-- ✅ Generate a starter template
-
----
-
-## Quick Start
-
-### Basic Analysis
-
-```bash
-# Analyze XML file (auto-detects format)
-fc-connect analyze-source-structure --file ./sample.xml
-
-# Analyze JSON
-fc-connect analyze-source-structure --file ./data.json
-
-# Analyze CSV
-fc-connect analyze-source-structure --file ./inventory.csv --format csv
-
-# Analyze Parquet
-fc-connect analyze-source-structure --file ./data.parquet --format parquet
-```
-
----
-
-## Command Reference
-
-### Required Options
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `--file, -f` | Source file to analyze | `--file ./order.xml` |
-
-### Optional Options
-
-| Option | Description | Default | Example |
-|--------|-------------|---------|---------|
-| `--format` | File format (auto-detected if not provided) | Auto-detect | `--format xml` |
-| `--output, -o` | Generate mapping template file | None | `--output ./mapping.json` |
-| `--show-structure` | Display parsed structure | `false` | `--show-structure` |
-| `--show-json` | Display structure as JSON | `false` | `--show-json` |
-| `--direction` | Mapping direction | `extract` | `--direction ingest` |
-| `--mapper` | Mapper type | `universal` | `--mapper graphql` |
-| `--markdown [path]` | Generate comprehensive markdown documentation | None | `--markdown` or `--markdown ./docs/analysis.md` |
-| `--docs [path]` | Alias for `--markdown` | None | `--docs` |
-| `--help, -h` | Show help message | - | `--help` |
-
----
-
-## Examples by Format
-
-### XML Analysis
-
-**Input XML (`order.xml`):**
-```xml
-<Order id="ORD-001">
-  <Customer>
-    <Name>John Doe</Name>
-    <Email>john@example.com</Email>
-  </Customer>
-  <Items>
-    <Item sku="SKU-001" qty="2" />
-    <Item sku="SKU-002" qty="1" />
-  </Items>
-</Order>
-```
-
-**Command:**
-```bash
-fc-connect analyze-source-structure --file ./order.xml --show-structure
-```
-
-**Output:**
-```
-╔═══════════════════════════════════════════════════════════════════════╗
-║  Source Structure Analysis                                           ║
-╚═══════════════════════════════════════════════════════════════════════╝
-
-📊 Parsed JavaScript Object Structure:
-
-{
-  "Order": {
-    "@id": "ORD-001",
-    "Customer": {
-      "Name": "John Doe",
-      "Email": "john@example.com"
-    },
-    "Items": {
-      "Item": [
-        { "@sku": "SKU-001", "@qty": "2" },
-        { "@sku": "SKU-002", "@qty": "1" }
-      ]
-    }
-  }
-}
-
-🔍 Available Mapping Paths:
-
-  🏷️  Order.@id
-  📄 Order.Customer.Name
-  📄 Order.Customer.Email
-  📋 Order.Items.Item[] (array)
-  🏷️  @sku
-  🏷️  @qty
-
-📋 Structure Insights:
-
-  Root Element(s): Order
-  Arrays Detected: 1
-    - Order.Items.Item[] (array)
-  Attributes Detected: 3
-    - Order.@id
-    - @sku
-    - @qty
-```
-
----
-
-### JSON Analysis
-
-**Input JSON (`products.json`):**
-```json
-{
-  "products": [
-    {
-      "id": "PROD-001",
-      "name": "Widget",
-      "price": 19.99,
-      "category": {
-        "id": "CAT-001",
-        "name": "Electronics"
-      }
-    },
-    {
-      "id": "PROD-002",
-      "name": "Gadget",
-      "price": 29.99,
-      "category": {
-        "id": "CAT-001",
-        "name": "Electronics"
-      }
-    }
-  ]
-}
-```
-
-**Command:**
-```bash
-fc-connect analyze-source-structure --file ./products.json --show-json
-```
-
-**Output:**
-```
-🔍 Available Mapping Paths:
-
-  📋 products[] (array)
-  📄 id
-  📄 name
-  📄 price
-  📄 category.id
-  📄 category.name
-
-📋 Structure Insights:
-
-  Root Element(s): products
-  Arrays Detected: 1
-    - products[] (array)
-```
-
----
-
-### CSV Analysis
-
-**Input CSV (`inventory.csv`):**
-```csv
-sku,location,quantity,status
-SKU-001,WH-001,100,available
-SKU-002,WH-001,50,reserved
-SKU-003,WH-002,200,available
-```
-
-**Command:**
-```bash
-fc-connect analyze-source-structure --file ./inventory.csv --format csv --show-structure
-```
-
-**Output:**
-```
-ℹ️  CSV has 3 rows - analyzing first 100 rows only
-
-📊 Parsed JavaScript Object Structure:
-
-Array of records (showing first record):
-
-{
-  "sku": "SKU-001",
-  "location": "WH-001",
-  "quantity": "100",
-  "status": "available"
-}
-
-... and 2 more record(s)
-
-🔍 Available Mapping Paths:
-
-  📄 sku
-  📄 location
-  📄 quantity
-  📄 status
-
-📋 Structure Insights:
-
-  Format: Array of records (3 record(s) analyzed)
-  Record Fields: sku, location, quantity, status
-  Total Fields: 4
-```
-
----
-
-### Parquet Analysis
-
-**Command:**
-```bash
-fc-connect analyze-source-structure --file ./inventory.parquet --format parquet
-```
-
-**Output:**
-```
-🔍 Available Mapping Paths:
-
-  📄 productRef
-  📄 locationRef
-  📄 quantity
-  📄 availableQuantity
-  📄 reservedQuantity
-
-📋 Structure Insights:
-
-  Format: Array of records (100 record(s) analyzed)
-  Record Fields: productRef, locationRef, quantity, availableQuantity, reservedQuantity
-  Total Fields: 5
-```
-
----
-
-## Generating Mapping Templates
-
-### Generate UniversalMapper Template (Extract)
-
-```bash
-fc-connect analyze-source-structure \
-  --file ./inventory.xml \
-  --format xml \
-  --direction extract \
-  --mapper universal \
-  --output ./inventory-mapping.json
-```
-
-**Generated Template (`inventory-mapping.json`):**
-```json
-{
-  "version": "1.0.0",
-  "description": "Generated mapping template from XML analysis",
-  "direction": "extract",
-  "sourceFormat": "graphql",
-  "fields": {
-    "locationRef": {
-      "source": "ItemInventory.FacilityId",
-      "comment": "Extracted from ItemInventory.FacilityId",
-      "resolver": "sdk.trim"
-    },
-    "productRef": {
-      "source": "ItemInventory.Item.ItemId.ClientItemId",
-      "comment": "Extracted from ItemInventory.Item.ItemId.ClientItemId",
-      "resolver": "sdk.trim"
-    },
-    "quantity": {
-      "source": "ItemInventory.Item.SellableQuantity",
-      "comment": "Extracted from ItemInventory.Item.SellableQuantity",
-      "resolver": "sdk.parseInt"
-    },
-    "items": {
-      "source": "ItemInventory.Item[]",
-      "isArray": true,
-      "comment": "Array field - extracted from ItemInventory.Item[]",
-      "fields": {
-        "SellableQuantity": {
-          "source": "SellableQuantity",
-          "comment": "Array item field - extracted from ItemInventory.Item.SellableQuantity (item is already context)",
-          "resolver": "sdk.parseInt"
-        },
-        "ItemId": {
-          "source": "ItemId",
-          "comment": "Array item field - extracted from ItemInventory.Item.ItemId.ClientItemId (item is already context)"
-        }
-      }
-    }
-  }
-}
-```
-
-**Note:** Resolvers are automatically detected and included based on data types:
-- Numbers → `sdk.parseInt` or `sdk.parseFloat`
-- Dates → `sdk.parseDate`
-- Strings → `sdk.trim` (or `sdk.lowercase` for emails/codes)
-
----
-
-### Generate GraphQLMutationMapper Template (Ingest)
-
-```bash
-fc-connect analyze-source-structure \
-  --file ./order.xml \
-  --format xml \
-  --direction ingest \
-  --mapper graphql \
-  --output ./order-mapping.json
-```
-
-**Generated Template (`order-mapping.json`):**
-```json
-{
-  "version": "1.0.0",
-  "description": "Generated mapping template from XML analysis",
-  "direction": "ingest",
-  "sourceFormat": "xml",
-  "mutation": "TODO_MUTATION_NAME",
-  "comment": "TODO: Replace TODO_MUTATION_NAME with actual GraphQL mutation name",
-  "fields": {
-    "orderId[]": {
-      "source": "Order.Items.Item",
-      "comment": "Array field - extracted from Order.Items.Item",
-      "fields": {
-        "itemField": {
-          "source": "$.fieldName",
-          "comment": "TODO: Map fields from array items - use $. prefix for item context"
-        }
-      }
-    }
-  }
-}
-```
-
-**Note:** For GraphQLMutationMapper Pattern 2 (`mapWithNodes()`), arrays support both syntaxes:
-- **Recommended:** `isArray: true` property (consistent with UniversalMapper and Pattern 1)
-- **Legacy:** `fieldName[]` suffix (still supported for backward compatibility)
-
-Both produce identical results. Use `isArray: true` for consistency across all mappers.
-
----
-
-## Workflow Integration
-
-### Complete Mapping Workflow
-
-```bash
-# Step 1: Analyze source file
-fc-connect analyze-source-structure \
-  --file ./order.xml \
-  --show-structure \
-  --output ./order-template.json
-
-# Step 2: Review and edit template
-# ... manually edit order-template.json ...
-
-# Step 3: (Optional) Generate target mapping from GraphQL mutation
-fc-connect generate-mutation-mapping \
-  --file ./createOrder.graphql \
-  --schema ./fluent-schema.json \
-  --output ./target-mapping.json
-
-# Step 4: Combine source analysis + target schema
-# ... merge paths from order-template.json into target-mapping.json ...
-
-# Step 5: Validate mapping
-fc-connect validate-schema \
-  --mapping ./order-mapping.json \
-  --schema ./fluent-schema.json
-```
-
----
-
-## Understanding Output
-
-### Mapping Paths Format
-
-| Icon | Meaning | Example |
-|------|---------|---------|
-| 📄 | Regular field | `Order.Customer.Name` |
-| 🏷️  | XML attribute | `Order.@id` |
-| 📋 | Array field | `Order.Items.Item[] (array)` |
-
-### Path Syntax
-
-- **Regular fields:** `Order.Customer.Name` → Use as-is: `"source": "Order.Customer.Name"`
-- **XML attributes:** `Order.@id` → Use with `@`: `"source": "Order.@id"`
-- **Arrays:** `Order.Items.Item[]` → Use `isArray: true` (UniversalMapper) or `fieldName[]` (GraphQLMutationMapper Pattern 2)
-- **Array item fields:** Inside array context, use `$.fieldName` prefix
-
----
-
-## Tips & Best Practices
-
-### 1. Always Analyze First
-
-```bash
-# ✅ Good: Analyze before writing mapping
-fc-connect analyze-source-structure --file ./data.xml --show-structure
-
-# ❌ Bad: Guessing paths without analysis
-```
-
-### 2. Use Generated Templates as Starting Point
-
-```bash
-# Generate template (resolvers are automatically included!)
-fc-connect analyze-source-structure \
-  --file ./data.xml \
-  --output ./mapping-template.json
-
-# Edit template:
-# - Replace field names with target names
-# - Review and adjust suggested resolvers (already included based on data types)
-# - Configure array item mappings
-# - Add required/defaultValue flags
-```
-
-**Automatic Resolver Detection:**
-The tool automatically detects data types and suggests appropriate resolvers:
-- **Numbers** → `sdk.parseInt` (integers) or `sdk.parseFloat` (decimals)
-- **Dates** → `sdk.parseDate` (detects ISO8601 and common date formats)
-- **Strings** → `sdk.trim` (most strings) or `sdk.lowercase` (emails/codes)
-- Detection uses both field values and field names (e.g., "quantity" → parseInt, "price" → parseFloat)
-
-### 3. Verify Complex Structures
-
-```bash
-# For complex XML with attributes
-fc-connect analyze-source-structure \
-  --file ./complex.xml \
-  --show-json
-```
-
-### 4. Understand Array Normalization
-
-The tool helps identify arrays, but remember:
-- XML: Single element = object, Multiple = array
-- Always normalize: `Array.isArray(items) ? items : items ? [items] : []`
-
----
-
-## Troubleshooting
-
-### Issue: "File not found"
-
-**Solution:**
-```bash
-# Use absolute path or check current directory
-fc-connect analyze-source-structure --file /full/path/to/file.xml
-```
-
-### Issue: "Could not detect file format"
-
-**Solution:**
-```bash
-# Explicitly specify format
-fc-connect analyze-source-structure --file ./data --format xml
-```
-
-### Issue: CSV/Parquet shows limited records
-
-**Explanation:**
-- Tool analyzes first 100 rows/records to avoid huge outputs
-- Structure is consistent across all records
-- You can analyze full file in your code
-
-### Issue: Generated template has incomplete array mappings
-
-**Explanation:**
-- Template shows placeholder for array item fields
-- You need to manually configure nested `fields` for array items
-- See array mapping documentation for details
-
----
-
-## Related Documentation
-
-- **[Mapping JavaScript Objects](../../mapping/mapping-javascript-objects.md)** - Understanding how mapping works and ETL flow
-- **[Generate Mutation Mapping](./api-reference-11-cli-tools.md#generate-mutation-mapping)** - Generate target-side templates
-- **[XML Parser Guide](../../parsers/modules/02-core-guides-parsers-04-xml-parser.md)** - XML parsing details
-
----
-
-**Last Updated:** 2025-01-16
-
+# Module 12: Analyze Source Structure
+
+**Level:** Beginner  
+**Category:** Command Line  
+**Time:** 10 minutes
+
+## Overview
+
+The `analyze-source-structure` CLI tool helps you understand your source data structure and generate mapping configuration suggestions. It supports XML, JSON, CSV, and Parquet files.
+
+---
+
+## Why Use This Tool?
+
+**Common Problems:**
+- ❌ "I don't know what paths to use in my mapping config"
+- ❌ "How does this XML get parsed by the SDK?"
+- ❌ "I need to understand the structure before writing mappings"
+- ❌ "My mapping isn't working - is the path correct?"
+
+**Solution:**
+- ✅ Analyze your source file first
+- ✅ See the exact parsed structure
+- ✅ Get suggested mapping paths
+- ✅ Generate a starter template
+
+---
+
+## Quick Start
+
+### Basic Analysis
+
+```bash
+# Analyze XML file (auto-detects format)
+fc-connect analyze-source-structure --file ./sample.xml
+
+# Analyze JSON
+fc-connect analyze-source-structure --file ./data.json
+
+# Analyze CSV
+fc-connect analyze-source-structure --file ./inventory.csv --format csv
+
+# Analyze Parquet
+fc-connect analyze-source-structure --file ./data.parquet --format parquet
+```
+
+---
+
+## Command Reference
+
+### Required Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--file, -f` | Source file to analyze | `--file ./order.xml` |
+
+### Optional Options
+
+| Option | Description | Default | Example |
+|--------|-------------|---------|---------|
+| `--format` | File format (auto-detected if not provided) | Auto-detect | `--format xml` |
+| `--output, -o` | Generate mapping template file | None | `--output ./mapping.json` |
+| `--show-structure` | Display parsed structure | `false` | `--show-structure` |
+| `--show-json` | Display structure as JSON | `false` | `--show-json` |
+| `--direction` | Mapping direction | `extract` | `--direction ingest` |
+| `--mapper` | Mapper type | `universal` | `--mapper graphql` |
+| `--markdown [path]` | Generate comprehensive markdown documentation | None | `--markdown` or `--markdown ./docs/analysis.md` |
+| `--docs [path]` | Alias for `--markdown` | None | `--docs` |
+| `--help, -h` | Show help message | - | `--help` |
+
+---
+
+## Examples by Format
+
+### XML Analysis
+
+**Input XML (`order.xml`):**
+```xml
+<Order id="ORD-001">
+  <Customer>
+    <Name>John Doe</Name>
+    <Email>john@example.com</Email>
+  </Customer>
+  <Items>
+    <Item sku="SKU-001" qty="2" />
+    <Item sku="SKU-002" qty="1" />
+  </Items>
+</Order>
+```
+
+**Command:**
+```bash
+fc-connect analyze-source-structure --file ./order.xml --show-structure
+```
+
+**Output:**
+```
+╔═══════════════════════════════════════════════════════════════════════╗
+║  Source Structure Analysis                                           ║
+╚═══════════════════════════════════════════════════════════════════════╝
+
+📊 Parsed JavaScript Object Structure:
+
+{
+  "Order": {
+    "@id": "ORD-001",
+    "Customer": {
+      "Name": "John Doe",
+      "Email": "john@example.com"
+    },
+    "Items": {
+      "Item": [
+        { "@sku": "SKU-001", "@qty": "2" },
+        { "@sku": "SKU-002", "@qty": "1" }
+      ]
+    }
+  }
+}
+
+🔍 Available Mapping Paths:
+
+  🏷️  Order.@id
+  📄 Order.Customer.Name
+  📄 Order.Customer.Email
+  📋 Order.Items.Item[] (array)
+  🏷️  @sku
+  🏷️  @qty
+
+📋 Structure Insights:
+
+  Root Element(s): Order
+  Arrays Detected: 1
+    - Order.Items.Item[] (array)
+  Attributes Detected: 3
+    - Order.@id
+    - @sku
+    - @qty
+```
+
+---
+
+### JSON Analysis
+
+**Input JSON (`products.json`):**
+```json
+{
+  "products": [
+    {
+      "id": "PROD-001",
+      "name": "Widget",
+      "price": 19.99,
+      "category": {
+        "id": "CAT-001",
+        "name": "Electronics"
+      }
+    },
+    {
+      "id": "PROD-002",
+      "name": "Gadget",
+      "price": 29.99,
+      "category": {
+        "id": "CAT-001",
+        "name": "Electronics"
+      }
+    }
+  ]
+}
+```
+
+**Command:**
+```bash
+fc-connect analyze-source-structure --file ./products.json --show-json
+```
+
+**Output:**
+```
+🔍 Available Mapping Paths:
+
+  📋 products[] (array)
+  📄 id
+  📄 name
+  📄 price
+  📄 category.id
+  📄 category.name
+
+📋 Structure Insights:
+
+  Root Element(s): products
+  Arrays Detected: 1
+    - products[] (array)
+```
+
+---
+
+### CSV Analysis
+
+**Input CSV (`inventory.csv`):**
+```csv
+sku,location,quantity,status
+SKU-001,WH-001,100,available
+SKU-002,WH-001,50,reserved
+SKU-003,WH-002,200,available
+```
+
+**Command:**
+```bash
+fc-connect analyze-source-structure --file ./inventory.csv --format csv --show-structure
+```
+
+**Output:**
+```
+ℹ️  CSV has 3 rows - analyzing first 100 rows only
+
+📊 Parsed JavaScript Object Structure:
+
+Array of records (showing first record):
+
+{
+  "sku": "SKU-001",
+  "location": "WH-001",
+  "quantity": "100",
+  "status": "available"
+}
+
+... and 2 more record(s)
+
+🔍 Available Mapping Paths:
+
+  📄 sku
+  📄 location
+  📄 quantity
+  📄 status
+
+📋 Structure Insights:
+
+  Format: Array of records (3 record(s) analyzed)
+  Record Fields: sku, location, quantity, status
+  Total Fields: 4
+```
+
+---
+
+### Parquet Analysis
+
+**Command:**
+```bash
+fc-connect analyze-source-structure --file ./inventory.parquet --format parquet
+```
+
+**Output:**
+```
+🔍 Available Mapping Paths:
+
+  📄 productRef
+  📄 locationRef
+  📄 quantity
+  📄 availableQuantity
+  📄 reservedQuantity
+
+📋 Structure Insights:
+
+  Format: Array of records (100 record(s) analyzed)
+  Record Fields: productRef, locationRef, quantity, availableQuantity, reservedQuantity
+  Total Fields: 5
+```
+
+---
+
+## Generating Mapping Templates
+
+### Generate UniversalMapper Template (Extract)
+
+```bash
+fc-connect analyze-source-structure \
+  --file ./inventory.xml \
+  --format xml \
+  --direction extract \
+  --mapper universal \
+  --output ./inventory-mapping.json
+```
+
+**Generated Template (`inventory-mapping.json`):**
+```json
+{
+  "version": "1.0.0",
+  "description": "Generated mapping template from XML analysis",
+  "direction": "extract",
+  "sourceFormat": "graphql",
+  "fields": {
+    "locationRef": {
+      "source": "ItemInventory.FacilityId",
+      "comment": "Extracted from ItemInventory.FacilityId",
+      "resolver": "sdk.trim"
+    },
+    "productRef": {
+      "source": "ItemInventory.Item.ItemId.ClientItemId",
+      "comment": "Extracted from ItemInventory.Item.ItemId.ClientItemId",
+      "resolver": "sdk.trim"
+    },
+    "quantity": {
+      "source": "ItemInventory.Item.SellableQuantity",
+      "comment": "Extracted from ItemInventory.Item.SellableQuantity",
+      "resolver": "sdk.parseInt"
+    },
+    "items": {
+      "source": "ItemInventory.Item[]",
+      "isArray": true,
+      "comment": "Array field - extracted from ItemInventory.Item[]",
+      "fields": {
+        "SellableQuantity": {
+          "source": "SellableQuantity",
+          "comment": "Array item field - extracted from ItemInventory.Item.SellableQuantity (item is already context)",
+          "resolver": "sdk.parseInt"
+        },
+        "ItemId": {
+          "source": "ItemId",
+          "comment": "Array item field - extracted from ItemInventory.Item.ItemId.ClientItemId (item is already context)"
+        }
+      }
+    }
+  }
+}
+```
+
+**Note:** Resolvers are automatically detected and included based on data types:
+- Numbers → `sdk.parseInt` or `sdk.parseFloat`
+- Dates → `sdk.parseDate`
+- Strings → `sdk.trim` (or `sdk.lowercase` for emails/codes)
+
+---
+
+### Generate GraphQLMutationMapper Template (Ingest)
+
+```bash
+fc-connect analyze-source-structure \
+  --file ./order.xml \
+  --format xml \
+  --direction ingest \
+  --mapper graphql \
+  --output ./order-mapping.json
+```
+
+**Generated Template (`order-mapping.json`):**
+```json
+{
+  "version": "1.0.0",
+  "description": "Generated mapping template from XML analysis",
+  "direction": "ingest",
+  "sourceFormat": "xml",
+  "mutation": "TODO_MUTATION_NAME",
+  "comment": "TODO: Replace TODO_MUTATION_NAME with actual GraphQL mutation name",
+  "fields": {
+    "orderId[]": {
+      "source": "Order.Items.Item",
+      "comment": "Array field - extracted from Order.Items.Item",
+      "fields": {
+        "itemField": {
+          "source": "$.fieldName",
+          "comment": "TODO: Map fields from array items - use $. prefix for item context"
+        }
+      }
+    }
+  }
+}
+```
+
+**Note:** For GraphQLMutationMapper Pattern 2 (`mapWithNodes()`), arrays support both syntaxes:
+- **Recommended:** `isArray: true` property (consistent with UniversalMapper and Pattern 1)
+- **Legacy:** `fieldName[]` suffix (still supported for backward compatibility)
+
+Both produce identical results. Use `isArray: true` for consistency across all mappers.
+
+---
+
+## Workflow Integration
+
+### Complete Mapping Workflow
+
+```bash
+# Step 1: Analyze source file
+fc-connect analyze-source-structure \
+  --file ./order.xml \
+  --show-structure \
+  --output ./order-template.json
+
+# Step 2: Review and edit template
+# ... manually edit order-template.json ...
+
+# Step 3: (Optional) Generate target mapping from GraphQL mutation
+fc-connect generate-mutation-mapping \
+  --file ./createOrder.graphql \
+  --schema ./fluent-schema.json \
+  --output ./target-mapping.json
+
+# Step 4: Combine source analysis + target schema
+# ... merge paths from order-template.json into target-mapping.json ...
+
+# Step 5: Validate mapping
+fc-connect validate-schema \
+  --mapping ./order-mapping.json \
+  --schema ./fluent-schema.json
+```
+
+---
+
+## Understanding Output
+
+### Mapping Paths Format
+
+| Icon | Meaning | Example |
+|------|---------|---------|
+| 📄 | Regular field | `Order.Customer.Name` |
+| 🏷️  | XML attribute | `Order.@id` |
+| 📋 | Array field | `Order.Items.Item[] (array)` |
+
+### Path Syntax
+
+- **Regular fields:** `Order.Customer.Name` → Use as-is: `"source": "Order.Customer.Name"`
+- **XML attributes:** `Order.@id` → Use with `@`: `"source": "Order.@id"`
+- **Arrays:** `Order.Items.Item[]` → Use `isArray: true` (UniversalMapper) or `fieldName[]` (GraphQLMutationMapper Pattern 2)
+- **Array item fields:** Inside array context, use `$.fieldName` prefix
+
+---
+
+## Tips & Best Practices
+
+### 1. Always Analyze First
+
+```bash
+# ✅ Good: Analyze before writing mapping
+fc-connect analyze-source-structure --file ./data.xml --show-structure
+
+# ❌ Bad: Guessing paths without analysis
+```
+
+### 2. Use Generated Templates as Starting Point
+
+```bash
+# Generate template (resolvers are automatically included!)
+fc-connect analyze-source-structure \
+  --file ./data.xml \
+  --output ./mapping-template.json
+
+# Edit template:
+# - Replace field names with target names
+# - Review and adjust suggested resolvers (already included based on data types)
+# - Configure array item mappings
+# - Add required/defaultValue flags
+```
+
+**Automatic Resolver Detection:**
+The tool automatically detects data types and suggests appropriate resolvers:
+- **Numbers** → `sdk.parseInt` (integers) or `sdk.parseFloat` (decimals)
+- **Dates** → `sdk.parseDate` (detects ISO8601 and common date formats)
+- **Strings** → `sdk.trim` (most strings) or `sdk.lowercase` (emails/codes)
+- Detection uses both field values and field names (e.g., "quantity" → parseInt, "price" → parseFloat)
+
+### 3. Verify Complex Structures
+
+```bash
+# For complex XML with attributes
+fc-connect analyze-source-structure \
+  --file ./complex.xml \
+  --show-json
+```
+
+### 4. Understand Array Normalization
+
+The tool helps identify arrays, but remember:
+- XML: Single element = object, Multiple = array
+- Always normalize: `Array.isArray(items) ? items : items ? [items] : []`
+
+---
+
+## Troubleshooting
+
+### Issue: "File not found"
+
+**Solution:**
+```bash
+# Use absolute path or check current directory
+fc-connect analyze-source-structure --file /full/path/to/file.xml
+```
+
+### Issue: "Could not detect file format"
+
+**Solution:**
+```bash
+# Explicitly specify format
+fc-connect analyze-source-structure --file ./data --format xml
+```
+
+### Issue: CSV/Parquet shows limited records
+
+**Explanation:**
+- Tool analyzes first 100 rows/records to avoid huge outputs
+- Structure is consistent across all records
+- You can analyze full file in your code
+
+### Issue: Generated template has incomplete array mappings
+
+**Explanation:**
+- Template shows placeholder for array item fields
+- You need to manually configure nested `fields` for array items
+- See array mapping documentation for details
+
+---
+
+## Related Documentation
+
+- **[Mapping JavaScript Objects](../../mapping/mapping-javascript-objects.md)** - Understanding how mapping works and ETL flow
+- **[Generate Mutation Mapping](./api-reference-11-cli-tools.md#generate-mutation-mapping)** - Generate target-side templates
+- **[XML Parser Guide](../../parsers/modules/02-core-guides-parsers-04-xml-parser.md)** - XML parsing details
+
+---
+
+**Last Updated:** 2025-01-16
+