@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/utils/pill-string-parser.ts

@@ -0,0 +1,375 @@
+import {
+    type Diagnostics,
+    PropertyAccessShape,
+    TemplateExpressionShape,
+    TemplateSpanShape,
+    type Source,
+} from '@servicenow/sdk-build-core'
+
+export const PILL_REGEX = /\{\{[^}]+\}\}/g
+
+/**
+ * Detects if a string contains data pill expressions
+ * @param value - String to check for pill patterns
+ * @returns 'simple' for single pill, 'template' for text with pills, 'none' for no pills
+ */
+export function detectPillPattern(value: string): 'simple' | 'template' | 'none' {
+    if (!value || typeof value !== 'string') {
+        return 'none'
+    }
+
+    const matches = value.match(PILL_REGEX)
+
+    if (!matches) {
+        return 'none'
+    }
+    // Simple pill: entire string is a single pill (with optional whitespace)
+    if (matches.length === 1 && value.trim() === matches[0].trim()) {
+        return 'simple'
+    }
+    // Template: contains one or more pills mixed with text
+    return 'template'
+}
+
+/**
+ * Represents a parsed data pill expression
+ */
+export interface ParsedPill {
+    prefix: string // "trigger", "flow_variable", "inputs", "outputs", or UUID
+    path: string // "table_name", "array", etc.
+    fullMatch: string
+}
+
+/**
+ * Parses a single pill expression
+ * @param pillString - Input like "{{trigger.table_name}}"
+ * @param allowSchemaReferences - If true, allows schema references without dots (e.g., {{flowVariables}}, {{outputs}}). Used during XML-to-Fluent conversion. Default: false.
+ * @returns Parsed components or null if invalid
+ * @example
+ * parseSinglePill("{{trigger.table_name}}")
+ * // Returns: { prefix: "trigger", path: "table_name", fullMatch: "{{trigger.table_name}}" }
+ */
+export function parseSinglePill(pillString: string, allowSchemaReferences: boolean = false): ParsedPill | null {
+    // Trim whitespace to handle pills with leading/trailing spaces
+    const trimmed = pillString.trim()
+
+    // Remove {{ and }} - match the entire pattern and extract content in between
+    const match = trimmed.match(/^\{\{(.*)\}\}$/)
+    if (!match) {
+        return null
+    }
+    let content = match[1]?.trim()
+
+    if (!content) {
+        return null
+    }
+
+    // Strip type annotation if present (e.g., "trigger.name|string" → "trigger.name")
+    // ServiceNow stores datapills with type annotations that need to be removed
+    const pipeIndex = content.indexOf('|')
+    if (pipeIndex !== -1) {
+        content = content.substring(0, pipeIndex).trim()
+    }
+
+    // Split by first dot: "trigger.table_name" → ["trigger", "table_name"]
+    const dotIndex = content.indexOf('.')
+
+    if (dotIndex === -1) {
+        // No dot - check if this is allowed based on context
+        if (!allowSchemaReferences) {
+            // During Fluent-to-XML or test parsing, pills without dots are invalid
+            return null
+        }
+
+        // During XML-to-Fluent: only allow valid schema references
+        const validSchemaReferences = ['flowVariables', 'outputs']
+
+        if (!validSchemaReferences.includes(content)) {
+            // Invalid pill format - only flowVariables and outputs are valid schema references
+            return null
+        }
+
+        // Return with empty path to indicate this is a schema reference, not a property access
+        return {
+            prefix: content,
+            path: '',
+            fullMatch: trimmed,
+        }
+    }
+
+    const prefix = content.substring(0, dotIndex)
+    const path = content.substring(dotIndex + 1)
+
+    return {
+        prefix,
+        path,
+        fullMatch: trimmed,
+    }
+}
+
+/**
+ * Maps pill prefix to TypeScript property access root
+ * @param prefix - Pill prefix like "trigger", "flow_variable", "subflow", or trigger-specific prefixes like "Created_1", "Updated_1", etc.
+ * @param parameterName - Optional parameter name to use instead of "params" (default: "params")
+ * @returns TypeScript path like "params.trigger" or null if not a known semantic prefix
+ */
+export function mapPillPrefixToTsRoot(prefix: string, parameterName: string = 'params'): string | null {
+    const mapping: Record<string, string> = {
+        trigger: `${parameterName}.trigger`,
+        flow_variable: `${parameterName}.flowVariables`,
+        flowVariables: `${parameterName}.flowVariables`, // Schema reference (no property access)
+        inputs: `${parameterName}.inputs`,
+        outputs: `${parameterName}.outputs`, // Schema reference (no property access)
+        subflow: `${parameterName}.inputs`, // ServiceNow uses {{subflow.x}} for subflow inputs
+
+        // Record triggers (prefixed with trigger name + _1)
+        Created_1: `${parameterName}.trigger`,
+        Updated_1: `${parameterName}.trigger`,
+        'Created or Updated_1': `${parameterName}.trigger`,
+
+        // Scheduled triggers
+        Daily_1: `${parameterName}.trigger`,
+        Weekly_1: `${parameterName}.trigger`,
+        Monthly_1: `${parameterName}.trigger`,
+        Repeat_1: `${parameterName}.trigger`,
+        'Run Once_1': `${parameterName}.trigger`,
+
+        // Application triggers
+        'Inbound Email_1': `${parameterName}.trigger`,
+        'Knowledge Management_1': `${parameterName}.trigger`,
+        'Remote Table Query_1': `${parameterName}.trigger`,
+        'REST API - Asynchronous_1': `${parameterName}.trigger`,
+        'Service Catalog_1': `${parameterName}.trigger`,
+        'SLA Task_1': `${parameterName}.trigger`,
+    }
+
+    return mapping[prefix] ?? null
+}
+
+/**
+ * Checks if prefix is a UUID (action/subflow instance reference)
+ * @param prefix - Prefix to check
+ * @returns True if the prefix matches UUID format
+ */
+export function isUuidPrefix(prefix: string): boolean {
+    // UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+    return uuidRegex.test(prefix)
+}
+
+/**
+ * Creates a PropertyAccessShape from a semantic path like "params.trigger.table_name"
+ * @param path - Dot-separated property path
+ * @param source - Source for the shape
+ * @returns PropertyAccessShape or null if path is invalid
+ */
+export function createPropertyAccessFromPath(path: string, source: Source): PropertyAccessShape | null {
+    const parts = path.split('.')
+
+    if (parts.length < 2) {
+        return null
+    }
+
+    // PropertyAccessShape constructor accepts strings and handles conversion internally
+    // Cast through unknown to satisfy TypeScript (we know parts.length >= 2 from check above)
+    return new PropertyAccessShape({
+        source,
+        elements: parts as unknown as readonly [string, string, ...string[]],
+    })
+}
+
+/**
+ * Creates a TemplateExpressionShape from a template string with pills
+ * @param templateStr - Input like "Hello {{trigger.name}}, your ID is {{trigger.sys_id}}"
+ * @param source - Source for the shape
+ * @param parameterName - Optional parameter name to use instead of "params" (e.g., from ArrowFunction)
+ * @param allowSchemaReferences - If true, allows schema references without dots. Used during XML-to-Fluent conversion. Default: false.
+ * @returns TemplateExpressionShape or null if no valid pills found
+ *
+ * @example
+ * createTemplateExpressionFromPillString(
+ *   "Lead text {{trigger.name}} trail text",
+ *   record,
+ *   diagnostics
+ * )
+ * // Creates: `Lead text ${params.trigger.name} trail text`
+ */
+export function createTemplateExpressionFromPillString(
+    templateStr: string,
+    source: Source,
+    parameterName?: string,
+    allowSchemaReferences: boolean = false
+): TemplateExpressionShape | null {
+    const pillRegex = /\{\{[^}]+\}\}/g
+    const spans: TemplateSpanShape[] = []
+
+    let head = ''
+    let isFirstPill = true
+    let match: RegExpExecArray | null
+
+    // Split template by pills
+    while ((match = pillRegex.exec(templateStr)) !== null) {
+        // Parse the pill and create PropertyAccessShape
+        const parsed = parseSinglePill(match[0], allowSchemaReferences)
+
+        if (!parsed) {
+            // Don't warn - invalid pills are silently ignored and treated as literals
+            continue
+        }
+
+        const tsRoot = mapPillPrefixToTsRoot(parsed.prefix, parameterName)
+
+        if (!tsRoot) {
+            if (isUuidPrefix(parsed.prefix)) {
+                // UUID-based pill - not supported in Phase 1, silently skip
+                // (UUID pills will be added in Phase 3)
+                continue
+            } else {
+                // Unknown prefix - silently skip and treat as literal
+                continue
+            }
+        }
+
+        const fullPath = `${tsRoot}.${parsed.path}`
+        const propAccess = createPropertyAccessFromPath(fullPath, source)
+
+        if (!propAccess) {
+            // Failed to create shape - silently skip
+            continue
+        }
+
+        // First pill: everything before it is the head
+        if (isFirstPill) {
+            head = templateStr.substring(0, match.index)
+            isFirstPill = false
+        }
+
+        // Text after this pill (until next pill or end of string)
+        const nextMatchIndex = pillRegex.lastIndex
+        let literalAfter = ''
+
+        // Look ahead to find next pill or use end of string
+        const remainingStr = templateStr.substring(nextMatchIndex)
+        const nextPillMatch = remainingStr.match(/\{\{[^}]+\}\}/)
+
+        if (nextPillMatch) {
+            literalAfter = remainingStr.substring(0, nextPillMatch.index)
+        } else {
+            literalAfter = remainingStr
+        }
+
+        spans.push(
+            new TemplateSpanShape({
+                source,
+                expression: propAccess,
+                literalText: literalAfter,
+            })
+        )
+    }
+
+    if (spans.length === 0) {
+        return null // No valid pills found
+    }
+
+    return new TemplateExpressionShape({
+        source,
+        literalText: head,
+        spans,
+    })
+}
+
+/**
+ * Converts a data pill string from XML to a TypeScript Shape
+ * Handles both simple pills and template expressions with pills
+ *
+ * @param value - String value from XML (may contain pills)
+ * @param source - Source for shape creation
+ * @param diagnostics - Diagnostics instance (currently unused but kept for future use)
+ * @param parameterName - Optional parameter name to use instead of "params" (e.g., from ArrowFunction)
+ * @param allowSchemaReferences - If true, allows schema references without dots (e.g., {{flowVariables}}, {{outputs}}). Should be true during XML-to-Fluent conversion. Default: true.
+ * @returns PropertyAccessShape, TemplateExpressionShape, or undefined if not a pill
+ *
+ * @example
+ * // Simple pill
+ * convertPillStringToShape("{{trigger.table_name}}", record, diagnostics)
+ * // Returns: PropertyAccessShape for params.trigger.table_name
+ *
+ * // Template
+ * convertPillStringToShape("Hello {{trigger.name}}", record, diagnostics)
+ * // Returns: TemplateExpressionShape for `Hello ${params.trigger.name}`
+ *
+ * // Not a pill
+ * convertPillStringToShape("just text", record, diagnostics)
+ * // Returns: undefined
+ */
+export function convertPillStringToShape(
+    value: string,
+    source: Source,
+    _diagnostics: Diagnostics,
+    parameterName?: string,
+    allowSchemaReferences: boolean = true
+): PropertyAccessShape | TemplateExpressionShape | undefined {
+    const patternType = detectPillPattern(value)
+
+    if (patternType === 'none') {
+        return undefined // Not a pill, handle normally
+    }
+
+    if (patternType === 'simple') {
+        // Simple pill: "{{trigger.table_name}}"
+        const parsed = parseSinglePill(value, allowSchemaReferences)
+
+        if (!parsed) {
+            // Invalid pill format - return undefined to fall back to normal value handling
+            return undefined
+        }
+
+        if (isUuidPrefix(parsed.prefix)) {
+            // UUID-based pill - not supported yet (Phase 3)
+            // Return undefined to fall back to string literal
+            return undefined
+        }
+
+        const tsRoot = mapPillPrefixToTsRoot(parsed.prefix, parameterName)
+
+        if (!tsRoot) {
+            // Unknown pill prefix - return undefined to fall back to normal value handling
+            return undefined
+        }
+
+        // Handle schema references (no property access) like {{flowVariables}} or {{outputs}}
+        if (parsed.path === '') {
+            // This is a schema reference - tsRoot already contains the full path (e.g., "params.flowVariables")
+            const propAccess = createPropertyAccessFromPath(tsRoot, source)
+            if (!propAccess) {
+                return undefined
+            }
+            return propAccess
+        }
+
+        // Handle property access like {{trigger.table_name}}
+        const fullPath = `${tsRoot}.${parsed.path}`
+        const propAccess = createPropertyAccessFromPath(fullPath, source)
+
+        if (!propAccess) {
+            // Failed to create PropertyAccess - return undefined to fall back
+            return undefined
+        }
+
+        return propAccess
+    }
+
+    if (patternType === 'template') {
+        // Template with pills: "Hello {{trigger.name}}"
+        const templateExpr = createTemplateExpressionFromPillString(value, source, parameterName, allowSchemaReferences)
+
+        if (!templateExpr) {
+            // Failed to parse template - return undefined to fall back to normal value
+            return undefined
+        }
+
+        return templateExpr
+    }
+
+    return undefined
+}