feat: Add query property to AnalyticEntry with privacy masking

Add GraphQL query string tracking to AnalyticEntry for analyzing query
complexity and structure patterns. Implements secure-by-default literal
masking to protect against accidental data leakage through inline values.

Changes:
- Add `query: String?` property to AnalyticEntry
- Add `maskQueryLiterals: Bool` to AnalyticsConfiguration (default: true)
- Implement query masking algorithm that:
  - Masks string literals ("admin" → "***")
  - Masks number literals (123 → ***)
  - Preserves variable references ($userId)
  - Preserves query structure for complexity analysis
- Wire query parameter through FTNetworkTracer
- Add 7 comprehensive tests for query masking functionality
- Update CLAUDE.md documentation

Privacy Levels:
- .none/.private: Query included with optional literal masking
- .sensitive: Query set to nil (most restrictive)

Breaking Changes: None (purely additive)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: Šimon Šesták

CLAUDE.md

@@ -76,11 +76,18 @@ Located in `Sources/FTNetworkTracer/Analytics/`
 **AnalyticsConfiguration** - Privacy controls
 - Define sensitive query parameters, headers, and JSON body keys
 - URL masking automatically strips sensitive query parameters and masks path segments
-- Header/body/variables masking replaces sensitive values with `***MASKED***`
+- Header/body/variables masking replaces sensitive values with `***`
+- GraphQL query literal masking enabled by default (`maskQueryLiterals: true`)
+  - Masks string literals (`"admin"` → `"***"`) and number literals (`123` → `***`)
+  - Preserves query structure, field selections, and variable references (`$userId`)
+  - Can be disabled with `maskQueryLiterals: false` for teams confident queries contain no sensitive data
 
 **AnalyticEntry** - Masked data
 - All masking happens at initialization time based on configuration
 - Variables are deep-masked (handles nested dictionaries and arrays)
+- GraphQL queries include `query` property with literal masking applied
+  - `.none`/`.private` privacy: Query included with optional literal masking
+  - `.sensitive` privacy: Query set to `nil` (most restrictive)
 
 ### Data Flow
 
@@ -105,6 +112,9 @@ Located in `Sources/FTNetworkTracer/Analytics/`
 - Logging: Privacy controlled via `OSLogPrivacy` levels
 - Analytics: Privacy via automatic masking in `AnalyticEntry` initializer
 - Masking is irreversible - once masked data is created, original data is gone
+- GraphQL query masking: Secure by default with `maskQueryLiterals: true`
+  - Removes literal values from queries while preserving structure for complexity analysis
+  - Consistent with variable masking behavior
 
 ## Platform Support
 

Sources/FTNetworkTracer/Analytics/AnalyticEntry.swift

@@ -19,6 +19,7 @@ public struct AnalyticEntry: NetworkEntry {
     /// Additional context for GraphQL operations
     public let operationName: String?
     public let variables: [String: any Sendable]?
+    public let query: String?
 
     public init(
         type: EntryType,
@@ -29,6 +30,7 @@ public struct AnalyticEntry: NetworkEntry {
         requestId: String = UUID().uuidString,
         operationName: String? = nil,
         variables: [String: any Sendable]? = nil,
+        query: String? = nil,
         configuration: AnalyticsConfiguration = AnalyticsConfiguration.default
     ) {
         // Create masked type with masked URL
@@ -50,5 +52,6 @@ public struct AnalyticEntry: NetworkEntry {
         self.requestId = requestId
         self.operationName = operationName
         self.variables = configuration.maskVariables(variables)
+        self.query = configuration.maskQuery(query)
     }
 }

Sources/FTNetworkTracer/Analytics/AnalyticsConfiguration.swift

@@ -8,6 +8,10 @@ import Foundation
 public struct AnalyticsConfiguration: Sendable {
     /// The privacy level for data masking.
     public let privacy: AnalyticsPrivacy
+
+    /// Whether to mask literal values in GraphQL queries (default: true for security).
+    public let maskQueryLiterals: Bool
+
     private let unmaskedHeaders: Set<String>
     private let unmaskedUrlQueries: Set<String>
     private let unmaskedBodyParams: Set<String>
@@ -16,16 +20,19 @@ public struct AnalyticsConfiguration: Sendable {
     ///
     /// - Parameters:
     ///   - privacy: The privacy level for data masking.
+    ///   - maskQueryLiterals: Whether to mask literal values in GraphQL queries (default: true).
     ///   - unmaskedHeaders: A set of header keys that should not be masked.
     ///   - unmaskedUrlQueries: A set of URL query parameter keys that should not be masked.
     ///   - unmaskedBodyParams: A set of body/variable parameter keys that should not be masked.
     public init(
         privacy: AnalyticsPrivacy,
+        maskQueryLiterals: Bool = true,
         unmaskedHeaders: Set<String> = [],
         unmaskedUrlQueries: Set<String> = [],
         unmaskedBodyParams: Set<String> = []
     ) {
         self.privacy = privacy
+        self.maskQueryLiterals = maskQueryLiterals
         self.unmaskedHeaders = unmaskedHeaders
         self.unmaskedUrlQueries = unmaskedUrlQueries
         self.unmaskedBodyParams = unmaskedBodyParams
@@ -161,4 +168,128 @@ public struct AnalyticsConfiguration: Sendable {
             return "***"
         }
     }
+
+    func maskQuery(_ query: String?) -> String? {
+        guard let query else {
+            return nil
+        }
+
+        switch privacy {
+        case .none, .private:
+            return maskQueryLiterals ? maskQueryLiteralValues(query) : query
+        case .sensitive:
+            return nil
+        }
+    }
+
+    private func maskQueryLiteralValues(_ query: String) -> String {
+        var result = ""
+        var insideString = false
+        var insideParentheses = false
+        var currentToken = ""
+        var escapeNext = false
+
+        for char in query {
+            // Handle escape sequences in strings
+            if escapeNext {
+                if insideString {
+                    currentToken.append(char)
+                } else {
+                    result.append(char)
+                }
+                escapeNext = false
+                continue
+            }
+
+            if char == "\\" {
+                escapeNext = true
+                if insideString {
+                    currentToken.append(char)
+                } else {
+                    result.append(char)
+                }
+                continue
+            }
+
+            switch char {
+            case "\"":
+                if insideParentheses && !insideString {
+                    // Start of string literal in arguments
+                    insideString = true
+                    currentToken = "\""
+                } else if insideString {
+                    // End of string literal - mask it
+                    insideString = false
+                    result.append("\"***\"")
+                    currentToken = ""
+                } else {
+                    result.append(char)
+                }
+
+            case "(":
+                result.append(currentToken)
+                result.append(char)
+                currentToken = ""
+                insideParentheses = true
+
+            case ")":
+                // Flush any pending number literal
+                if insideParentheses && !currentToken.isEmpty {
+                    if isNumericLiteral(currentToken) {
+                        result.append("***")
+                    } else {
+                        result.append(currentToken)
+                    }
+                }
+                result.append(char)
+                currentToken = ""
+                insideParentheses = false
+
+            case " ", "\n", "\t", ",", ":":
+                if insideString {
+                    // Inside string literal - accumulate character
+                    currentToken.append(char)
+                } else {
+                    // Delimiter - check if we have a pending number literal
+                    if insideParentheses && !currentToken.isEmpty {
+                        if isNumericLiteral(currentToken) {
+                            result.append("***")
+                        } else {
+                            result.append(currentToken)
+                        }
+                        currentToken = ""
+                    }
+                    result.append(char)
+                }
+
+            default:
+                if insideString {
+                    // Inside string literal - accumulate but don't output
+                    currentToken.append(char)
+                } else if insideParentheses {
+                    // Might be building a number literal or variable reference
+                    currentToken.append(char)
+                } else {
+                    // Outside arguments - pass through
+                    result.append(char)
+                }
+            }
+        }
+
+        // Handle any remaining token
+        if !currentToken.isEmpty {
+            result.append(currentToken)
+        }
+
+        return result
+    }
+
+    private func isNumericLiteral(_ token: String) -> Bool {
+        let trimmed = token.trimmingCharacters(in: .whitespaces)
+        // Check if it's a number (int or float) but not a variable reference
+        guard !trimmed.isEmpty && !trimmed.hasPrefix("$") else {
+            return false
+        }
+        return Double(trimmed) != nil
+    }
 }

Sources/FTNetworkTracer/FTNetworkTracer.swift

@@ -201,6 +201,7 @@ public class FTNetworkTracer {
                 requestId: requestId,
                 operationName: operationName,
                 variables: variables,
+                query: query,
                 configuration: analytics.configuration
             )
             analytics.track(analyticEntry)