xlsform2lstsv 0.2.0

package/README.md

@@ -0,0 +1,228 @@
+[![npm version](https://img.shields.io/npm/v/xlsform2lstsv)](https://www.npmjs.com/package/xlsform2lstsv)
+
+
+# xlsform2lstsv
+
+Convert XLSForm surveys to LimeSurvey TSV format. 
+
+[!WARNING]  
+
+- This package is still WIP and not all features of xlsform have been implemented and verified.
+- While importing is tested in an automated fashion (see `scripts/test-compatibility-safe.ts`), this only verifies whether all questions were successfully imported, but not if e.g. validation and relevance expressions were transformed correctly. To be safe, always use the "Survey logic view" in the LimeSurvey GUI.
+- If you want question and choice names to be the same in LimeSurvey, make them <=5 chars (this is a LimeSurvey requiremtn)
+
+
+## Implemented features
+
+- Question Types and Choices (see `src/processors/TypeMapper.ts` for how this library maps XLSForm types to LimeSurvey types)
+  - everything but the types specified in `UNIMPLEMENTED_TYPES` in `src/xlsformConverter.ts`
+  - record types ❌ (start, end, today, device_id, username, phonenumber, email)
+
+- Settings sheet 
+  - -> LS Survey Global Parameters (only name of survey)  ✅
+  - -> Survey Language-Specific Parameters (default language is first row, other rows are extracted from label translations)  ✅
+
+- Question Groups  ✅
+  - Group level relevance ✅
+  - Nested groups: LimeSurvey does not support nested groups. Parent-only groups (groups that contain only child groups and no direct questions) are automatically flattened — their label is converted to a note question (type X) in the first child group.
+
+- Hints (normal) ✅
+
+- `label` and `hint` translations ✅
+
+- XPath -> ExpressionScript/EM 🟡
+  - see src/converters/xpathTranspiler.ts for how operators and functions are mapped
+  - its a complex task to ensure the transpiler covers everything and we currently cannot guarantee error free/complete transpiling 
+
+- constraint_message ❌
+- XLSForms Calculation ❌
+- XLSForms Trigger ❌
+- Repeats ❌
+- LimeSurvey Assessments ❌
+- LimeSurvey Quotas ❌
+- LimeSurvey Quota language settings ❌
+- LimeSurvey Quota members ❌
+- XLSForms Appearances 🟡
+  - `multiline` on text questions → LimeSurvey type `T` (Long free text) ✅
+  - `likert` on select_one → kept as `L` (no LimeSurvey visual equivalent) ✅
+  - `label`/`list-nolabel` → LimeSurvey matrix question type `F` ✅
+  - `field-list` on groups → silently ignored (format=A already shows everything on one page) ✅
+  - Other appearances (e.g. `minimal`, `compact`, `horizontal`) trigger a warning and are ignored
+- Additional columns ❌
+- guidance_hint ❌
+
+## Transformation defaults and limitations
+
+XLSForm and LimeSurvey differ in how they model surveys. Some information is lost or transformed during conversion, and some defaults are applied:
+
+- **Survey format**: The output defaults to "All in one" mode (`format=A`), displaying all groups and questions on a single page.
+- **Nested groups**: LimeSurvey does not support nested groups. Parent-only groups (containing only child groups, no direct questions) are flattened — their label becomes a note question (type X) in the first child group.
+- **Field name truncation**: LimeSurvey limits question codes to 20 characters and answer codes to 5 characters. Longer names are truncated (underscores removed first, then cut to length).
+- **Record/metadata types**: XLSForm `start`, `end`, `today`, `deviceid` etc. are silently skipped — LimeSurvey handles these internally.
+- **Appearances**: Most XLSForm `appearance` values have no LimeSurvey equivalent and are ignored (a warning is logged). Supported appearances: `multiline` on text questions maps to type `T` (Long free text); `likert` on select_one is accepted silently (stays type `L`); `label`/`list-nolabel` is converted to LimeSurvey's matrix question type (`F`); `field-list` on groups is a no-op since format=A already shows everything on one page.
+- **Multilingual row ordering**: Rows are grouped by language within each group (all base-language rows first, then translations) to work around a LimeSurvey TSV importer bug that resets question ordering counters on translation rows.
+
+## Installation
+
+```bash
+npm install xlsform2lstsv
+```
+
+## Quick Start
+
+The XFormParser provides direct XLS/XLSX file support:
+
+```typescript
+import { XFormParser } from 'xlsform2lstsv';
+
+// Parse XLS/XLSX file and convert to TSV
+const tsv = await XFormParser.convertXLSFileToTSV('path/to/survey.xlsx');
+
+// Or parse XLS/XLSX data directly
+const xlsxData = fs.readFileSync('path/to/survey.xlsx');
+const tsv = await XFormParser.convertXLSDataToTSV(xlsxData);
+```
+
+**Methods:**
+- `convertXLSFileToTSV(filePath, config)`: Direct conversion from file
+- `convertXLSDataToTSV(data, config)`: Direct conversion from buffer
+- `parseXLSFile(filePath)`: Parse to structured arrays
+- `parseXLSData(data)`: Parse buffer to structured arrays
+
+### Using Arrays 
+
+A different entry point accepts XLSForm data as JavaScript arrays:
+
+```typescript
+import { XLSFormToTSVConverter } from 'xlsform2lstsv';
+
+const converter = new XLSFormToTSVConverter();
+const tsv = converter.convert(surveyData, choicesData, settingsData);
+```
+
+**Parameters:**
+- `surveyData`: Array of survey rows (questions, groups, etc.)
+- `choicesData`: Array of choice/option data  
+- `settingsData`: Array of survey settings
+
+**Returns:** TSV string suitable for LimeSurvey import
+
+## Development Setup
+
+### Prerequisites
+
+- see `package.json`
+- Docker and Docker Compose (for integration testing)
+- Python 3.9+ with uv package manager (for integration testing)
+
+### Initial Setup
+
+```bash
+# Clone repository
+git clone https://github.com/CorrelAid/xlsform2lstsv.git
+cd xlsform2lstsv
+
+# Install Node.js dependencies
+npm install
+
+# Install Git hooks (automatic on npm install)
+npx husky install
+
+# Build the project
+npm run build
+```
+
+### Development Tools
+
+- **TypeScript**: Primary language
+- **Vitest**: Unit testing framework
+- **ESLint**: Code linting
+- **Prettier**: Code formatting
+- **Husky**: Git hooks management
+- **Commitlint**: Commit message validation
+
+## Development Workflow
+
+### Unit Testing
+
+**Running Tests**:
+```bash
+# Run all unit tests
+npm test
+
+# Run tests with watch mode 
+npm test -- --watch
+
+# Run specific test file
+npm test -- src/test/textTypes.test.ts
+
+# Run tests with coverage report
+npm test -- --coverage
+
+# Debug specific test
+npm test -- --debug src/test/numericTypes.test.ts
+```
+
+
+### Integration Testing
+
+Integration tests verify that generated TSV files can be successfully imported into LimeSurvey.
+
+To test all versions specified in `scripts/src/config/version.js`:
+
+```bash
+npm run test-compatibility
+```
+
+To test specific versions, set the `SPECIFIC_VERSIONS` environment variable:
+
+```bash
+SPECIFIC_VERSIONS="6.16.4,6.17.0" npm run test-compatibility
+```
+
+
+### Commit Message Format
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+## Releasing
+
+Pushing a `v*` tag to GitHub triggers automatic npm publishing via GitHub Actions.
+
+### Steps
+
+1. **Bump the version**:
+   ```bash
+   npm version patch   # 0.1.0 → 0.1.1 (bug fixes)
+   npm version minor   # 0.1.0 → 0.2.0 (new features)
+   npm version major   # 0.1.0 → 1.0.0 (breaking changes)
+   ```
+   This updates `package.json` and `package-lock.json`, creates a commit, and creates a `vX.Y.Z` tag.
+
+2. **Push the commit and tag**:
+   ```bash
+   git push && git push origin vX.Y.Z
+   ```
+
+3. **GitHub Actions** will build and publish the package to npm.
+
+### Requirements
+
+- `NPM_TOKEN` secret must be configured in the GitHub repository settings
+- Tags must follow the `v*` pattern (e.g., `v0.2.0`)
+
+## Limesurvey Resources
+
+- Limesurvey TSV Import Code: https://github.com/LimeSurvey/LimeSurvey/blob/50870a0767a3b132344a195bcaa354be82eecddf/application/helpers/admin/import_helper.php#L3836
+- Limesurvey DB Structure: https://github.com/LimeSurvey/LimeSurvey/blob/master/installer/create-database.php
+- LimeSurvey Expressions: 
+    - https://github.com/LimeSurvey/LimeSurvey/blob/0715c161c40d741da68fc670dd89d71026b37c07/application/helpers/expressions/em_core_helper.php
+    - https://www.limesurvey.org/manual/ExpressionScript_examples
+    - https://www.limesurvey.org/manual/ExpressionScript_-_Presentation
+    - https://www.limesurvey.org/manual/Expression_Manager
+    - https://www.limesurvey.org/manual/ExpressionScript_for_developers
+- https://www.limesurvey.org/manual/Expression_Manager#Access_to_Variables
+- https://www.limesurvey.org/manual/ExpressionScript_-_Presentation
+- https://www.limesurvey.org/blog/tutorials/creating-limesurvey-questionnaires-in-micorsoft-excel
+- https://www.limesurvey.org/manual/Tab_Separated_Value_survey_structure
+

package/dist/config/ConfigManager.js

@@ -0,0 +1,43 @@
+import { deepMerge } from '../utils/helpers.js';
+import { defaultConfig } from './types.js';
+export class ConfigManager {
+    constructor(config) {
+        this.config = this.mergeConfig(config || {});
+    }
+    mergeConfig(partialConfig) {
+        return deepMerge(structuredClone(defaultConfig), partialConfig);
+    }
+    getConfig() {
+        return this.config;
+    }
+    getDefaults() {
+        return this.config.defaults;
+    }
+    getAdvancedOptions() {
+        return {
+            autoCreateGroups: true, // Always auto-create groups (hardcoded)
+            handleRepeats: this.config.handleRepeats ?? 'warn',
+            debugLogging: this.config.debugLogging ?? false
+        };
+    }
+    /**
+     * Update configuration at runtime
+     */
+    updateConfig(partialConfig) {
+        this.config = this.mergeConfig(partialConfig);
+    }
+    /**
+     * Validate configuration
+     */
+    validateConfig() {
+        const { defaults } = this.config;
+        // Validate handleRepeats if provided
+        if (this.config.handleRepeats && !['warn', 'error', 'ignore'].includes(this.config.handleRepeats)) {
+            throw new Error(`Invalid handleRepeats option: ${this.config.handleRepeats}`);
+        }
+        // Validate defaults
+        if (!defaults.language || defaults.language.length !== 2) {
+            throw new Error('defaults.language must be a 2-character language code');
+        }
+    }
+}

package/dist/config/types.js

@@ -0,0 +1,13 @@
+/**
+ * Default configuration with sensible defaults
+ */
+export const defaultConfig = {
+    handleRepeats: 'warn',
+    debugLogging: false,
+    defaults: {
+        language: 'en',
+        groupName: 'Questions',
+        surveyTitle: 'Untitled Survey',
+        description: ''
+    }
+};

package/dist/converters/xpathTranspiler.js

@@ -0,0 +1,403 @@
+/**
+ * XPath to LimeSurvey Expression Transpiler
+ *
+ * This module provides functions to transpile XPath expressions from XLSForm
+ * to LimeSurvey Expression Manager syntax using AST-based transformation.
+ *
+ * The transpiler uses js-xpath library to parse XPath expressions into AST,
+ * then recursively transforms the AST nodes to LimeSurvey-compatible syntax.
+ */
+/**
+ * Sanitize field names by removing underscores and hyphens to match LimeSurvey's naming conventions
+ */
+function sanitizeName(name) {
+    return name.replace(/[_-]/g, '');
+}
+/**
+ * Transpiles jsxpath AST nodes to LimeSurvey expression syntax
+ *
+ * This function takes the Abstract Syntax Tree (AST) nodes produced by the jsxpath library
+ * and converts them to LimeSurvey-compatible expression syntax. The jsxpath library
+ * returns different node structures depending on the type of XPath expression:
+ *
+ * - Function calls: Objects with 'id' property (e.g., count(), concat(), regex())
+ * - Binary operations: Objects with 'type' property (e.g., <=, >=, =, and, or)
+ * - Variable references: Objects with 'steps' arrays containing axis/name info
+ * - Literal values: Objects with 'value' property containing the actual value
+ *
+ * The function recursively processes the AST, handling each node type appropriately
+ * and converting XPath syntax to LimeSurvey Expression Manager syntax.
+ *
+ * @param node - The AST node from jsxpath.parse()
+ * @returns The transpiled LimeSurvey expression string
+ * @throws Error if an unsupported node structure is encountered
+ */
+function transpile(node) {
+    if (!node)
+        return '';
+    // https://getodk.github.io/xforms-spec/#xpath-functions
+    // to https://www.limesurvey.org/manual/ExpressionScript_-_Presentation (see implemented functions)
+    if (node.id) {
+        switch (node.id) {
+            case 'count':
+                return `count(${node.args?.map(arg => transpile(arg)).join(', ') || ''})`;
+            case 'concat':
+                return node.args?.map(arg => transpile(arg)).join(' + ') || '';
+            case 'regex':
+                return `regexMatch(${node.args?.map(arg => transpile(arg)).join(', ') || ''})`;
+            case 'contains':
+                // Custom handling for contains
+                if (node.args?.length === 2) {
+                    return `contains(${transpile(node.args[0])}, ${transpile(node.args[1])})`;
+                }
+                break;
+            case 'selected':
+                // Handle selected(${field}, 'value') -> (field=="value")
+                if (node.args?.length === 2) {
+                    const fieldArg = node.args[0];
+                    const valueArg = node.args[1];
+                    const fieldName = transpile(fieldArg);
+                    let value = transpile(valueArg);
+                    // Remove any existing quotes and use double quotes
+                    value = value.replace(/^['"]|['"]$/g, "");
+                    return `(${sanitizeName(fieldName)}=="${value}")`;
+                }
+                break;
+            case 'string':
+                // string() function - just return the argument
+                if (node.args?.length === 1) {
+                    return transpile(node.args[0]);
+                }
+                break;
+            case 'number':
+                // number() function - just return the argument
+                if (node.args?.length === 1) {
+                    return transpile(node.args[0]);
+                }
+                break;
+            case 'floor':
+                if (node.args?.length === 1) {
+                    return `floor(${transpile(node.args[0])})`;
+                }
+                break;
+            case 'ceiling':
+                if (node.args?.length === 1) {
+                    return `ceil(${transpile(node.args[0])})`;
+                }
+                break;
+            case 'round':
+                if (node.args?.length === 1) {
+                    return `round(${transpile(node.args[0])})`;
+                }
+                break;
+            case 'sum':
+                if (node.args?.length === 1) {
+                    return `sum(${transpile(node.args[0])})`;
+                }
+                break;
+            case 'substring':
+                if (node.args && node.args.length >= 2) {
+                    const stringArg = transpile(node.args[0]);
+                    const startArg = transpile(node.args[1]);
+                    const lengthArg = node.args.length > 2 ? transpile(node.args[2]) : '';
+                    return `substr(${stringArg}, ${startArg}${lengthArg ? ', ' + lengthArg : ''})`;
+                }
+                break;
+            case 'string-length':
+                if (node.args?.length === 1) {
+                    return `strlen(${transpile(node.args[0])})`;
+                }
+                break;
+            case 'starts-with':
+                if (node.args?.length === 2) {
+                    return `startsWith(${transpile(node.args[0])}, ${transpile(node.args[1])})`;
+                }
+                break;
+            case 'ends-with':
+                if (node.args?.length === 2) {
+                    return `endsWith(${transpile(node.args[0])}, ${transpile(node.args[1])})`;
+                }
+                break;
+            case 'not':
+                if (node.args?.length === 1) {
+                    return `!(${transpile(node.args[0])})`;
+                }
+                break;
+            case 'if':
+                if (node.args?.length === 3) {
+                    return `(${transpile(node.args[0])} ? ${transpile(node.args[1])} : ${transpile(node.args[2])})`;
+                }
+                break;
+            case 'today':
+                return 'today()';
+            case 'now':
+                return 'now()';
+            default:
+                throw new Error(`Unsupported function: ${node.id}`);
+        }
+    }
+    // https://getodk.github.io/xforms-spec/#xpath-operators 
+    // to https://www.limesurvey.org/manual/ExpressionScript_-_Presentation (see syntax)
+    if (node.type) {
+        switch (node.type) {
+            // Comparison operators
+            case '<=':
+                return `${transpile(node.left)} <= ${transpile(node.right)}`;
+            case '>=':
+                return `${transpile(node.left)} >= ${transpile(node.right)}`;
+            case '=':
+            case '==':
+                return `${transpile(node.left)} == ${transpile(node.right)}`;
+            case '!=':
+                return `${transpile(node.left)} != ${transpile(node.right)}`;
+            case '<':
+                return `${transpile(node.left)} < ${transpile(node.right)}`;
+            case '>':
+                return `${transpile(node.left)} > ${transpile(node.right)}`;
+            // Arithmetic operators
+            case '+':
+                return `${transpile(node.left)} + ${transpile(node.right)}`;
+            case '-':
+                return `${transpile(node.left)} - ${transpile(node.right)}`;
+            case '*':
+                return `${transpile(node.left)} * ${transpile(node.right)}`;
+            case 'div':
+                return `${transpile(node.left)} / ${transpile(node.right)}`;
+            case 'mod':
+                return `${transpile(node.left)} % ${transpile(node.right)}`;
+            // Logical operators
+            case 'and':
+                return `${transpile(node.left)} and ${transpile(node.right)}`;
+            case 'or':
+                return `${transpile(node.left)} or ${transpile(node.right)}`;
+            // Unsupported operators
+            case '|':
+            case '/':
+            case '//':
+            case '[]':
+            case '..':
+            case '@':
+            case '::':
+            case ',':
+                throw new Error(`Unsupported XPath operator: ${node.type}`);
+            default:
+                throw new Error(`Unsupported operator: ${node.type}`);
+        }
+    }
+    // Handle variable references (jsxpath returns step objects)
+    if (node.steps && node.steps.length > 0) {
+        const step = node.steps[0];
+        if (step.name) {
+            return sanitizeName(step.name);
+        }
+        // Handle self reference (.)
+        if (step.axis === 'self') {
+            return 'self';
+        }
+    }
+    // Handle literal values
+    if (node.value !== undefined) {
+        // Handle numeric literals
+        if (typeof node.value === 'object' && node.value._ !== undefined) {
+            return node.value._;
+        }
+        // Handle string literals
+        if (typeof node.value === 'string') {
+            // Check if this is a string literal with quotes (valueDisplay contains the quoted version)
+            if (node.valueDisplay) {
+                return node.valueDisplay;
+            }
+            // For plain string values without quotes, return as-is
+            return node.value;
+        }
+    }
+    throw new Error(`Unsupported node structure: ${JSON.stringify(node)}`);
+}
+/**
+ * Convert XPath expression to LimeSurvey Expression Manager syntax
+ *
+ * @param xpathExpr - The XPath expression to convert
+ * @returns LimeSurvey Expression Manager syntax, or null if conversion fails
+ */
+export async function xpathToLimeSurvey(xpathExpr) {
+    if (!xpathExpr || xpathExpr.trim() === '') {
+        return '1'; // Default relevance expression
+    }
+    // Preprocess XLSForm template syntax to standard XPath
+    let processedExpr = xpathExpr;
+    // Convert ${field} to field references (supports hyphens and other chars in names)
+    processedExpr = processedExpr.replace(/\$\{([^}]+)\}/g, (match, fieldName) => {
+        return sanitizeName(fieldName);
+    });
+    // Convert selected(${field}, 'value') to selected(field, 'value')
+    processedExpr = processedExpr.replace(/selected\(\s*\$\{([^}]+)\}\s*,\s*['"]([^'"]+)['"]\s*\)/g, (match, fieldName, value) => {
+        return `selected(${sanitizeName(fieldName)}, '${value}')`;
+    });
+    try {
+        // Import js-xpath using dynamic import with CommonJS interop
+        const jxpathModule = await import('js-xpath');
+        const jxpath = jxpathModule.default || jxpathModule;
+        if (!jxpath || !jxpath.parse) {
+            throw new Error('js-xpath module does not export parse function');
+        }
+        const parsed = jxpath.parse(processedExpr);
+        return transpile(parsed);
+    }
+    catch (error) {
+        console.error(`Transpilation error: ${error.message}`);
+        return '1';
+    }
+}
+/**
+ * Convert XPath constraint to LimeSurvey validation pattern
+ *
+ * @param constraint - The XPath constraint expression
+ * @returns Validation pattern (regex or EM equation)
+ */
+export async function convertConstraint(constraint) {
+    if (!constraint)
+        return '';
+    try {
+        // Preprocess the expression to handle field references and special cases
+        let processedExpr = constraint;
+        // Convert ${field} to field references
+        processedExpr = processedExpr.replace(/\$\{(\w+)\}/g, (match, fieldName) => {
+            return sanitizeName(fieldName);
+        });
+        // Convert selected(${field}, 'value') to selected(field, 'value')
+        processedExpr = processedExpr.replace(/selected\(\s*\$\{(\w+)\}\s*,\s*['"]([^'"]+)['"]\s*\)/g, (match, fieldName, value) => {
+            return `selected(${sanitizeName(fieldName)}, '${value}')`;
+        });
+        // Special handling for regexMatch function
+        const regexMatchPattern = /regexMatch\(\s*([^)]+)\s*\)/;
+        const regexMatchMatch = processedExpr.match(regexMatchPattern);
+        if (regexMatchMatch) {
+            // Parse the regexMatch arguments
+            const args = parseRegexMatchArguments(regexMatchMatch[1]);
+            if (args.length >= 2) {
+                const [firstArg, secondArg] = args;
+                // Check if the first argument looks like a logical expression (contains operators)
+                const logicalOperators = ['>=', '<=', '>', '<', '=', '!=', 'and', 'or'];
+                const isLogicalExpression = logicalOperators.some(op => firstArg.includes(op) &&
+                    // Make sure it's not part of a regex pattern (e.g., [0-9])
+                    !(firstArg.includes('[') && firstArg.includes(']')));
+                if (isLogicalExpression) {
+                    // Extract the logical expression and return it
+                    return firstArg.replace(/^"|"$/g, ''); // Remove quotes
+                }
+                else {
+                    // Check if this is a valid regexMatch call (pattern first, field second)
+                    // If the second argument looks like a field reference and first like a pattern, handle it
+                    const isFieldReference = secondArg === '.' || /^\w+$/.test(secondArg);
+                    const looksLikePattern = firstArg.includes('^') || firstArg.includes('$') ||
+                        (firstArg.includes('[') && firstArg.includes(']'));
+                    if (isFieldReference && looksLikePattern) {
+                        // Handle as a real regexMatch function
+                        // Convert . to self in the field argument
+                        const processedFieldArg = secondArg.replace(/\./g, 'self');
+                        // Convert double quotes to single quotes for consistency
+                        const processedPatternArg = firstArg.replace(/^"|"$/g, "'")
+                            .replace(/\\'/g, "'"); // Handle escaped quotes
+                        return `regexMatch(${processedPatternArg}, ${processedFieldArg})`;
+                    }
+                    else {
+                        // Invalid argument order or unsupported pattern
+                        return '';
+                    }
+                }
+            }
+        }
+        // Parse and transpile using AST
+        const jxpathModule = await import('js-xpath');
+        const jxpath = jxpathModule.default || jxpathModule;
+        if (!jxpath || !jxpath.parse) {
+            throw new Error('js-xpath module does not export parse function');
+        }
+        const parsed = jxpath.parse(processedExpr);
+        if (!parsed) {
+            // If parsing fails but doesn't throw, we handle it explicitly.
+            throw new Error(`jxpath.parse returned null/undefined for constraint: "${processedExpr}"`);
+        }
+        const converted = transpile(parsed);
+        return converted;
+    }
+    catch (error) {
+        console.error(`Constraint conversion error: ${error.message}`);
+        return '';
+    }
+    // If all else fails, return empty
+    return '';
+}
+/**
+ * Parse arguments from a regexMatch function call
+ * Handles quoted strings and field references
+ */
+function parseRegexMatchArguments(argsString) {
+    const args = [];
+    let currentArg = '';
+    let inQuotes = false;
+    let quoteChar = '';
+    let parenDepth = 0;
+    for (let i = 0; i < argsString.length; i++) {
+        const char = argsString[i];
+        if ((char === '"' || char === "'") && (i === 0 || argsString[i - 1] !== '\\')) {
+            if (!inQuotes) {
+                // Start of quoted string
+                inQuotes = true;
+                quoteChar = char;
+                currentArg += char;
+            }
+            else if (char === quoteChar) {
+                // End of quoted string
+                inQuotes = false;
+                currentArg += char;
+            }
+            else {
+                currentArg += char;
+            }
+        }
+        else if (char === '(' && !inQuotes) {
+            parenDepth++;
+            currentArg += char;
+        }
+        else if (char === ')' && !inQuotes) {
+            parenDepth--;
+            currentArg += char;
+        }
+        else if (char === ',' && !inQuotes && parenDepth === 0) {
+            // Argument separator
+            args.push(currentArg.trim());
+            currentArg = '';
+        }
+        else {
+            currentArg += char;
+        }
+    }
+    // Add the last argument
+    if (currentArg.trim()) {
+        args.push(currentArg.trim());
+    }
+    return args;
+}
+/**
+ * Convert XPath relevance expression to LimeSurvey Expression Manager syntax
+ *
+ * @param xpath - The XPath relevance expression
+ * @returns LimeSurvey Expression Manager syntax
+ */
+export async function convertRelevance(xpathExpr) {
+    if (!xpathExpr)
+        return '1';
+    // Preprocess: normalize operators to lowercase for jsxpath compatibility
+    let normalizedXPath = xpathExpr
+        .replace(/\bAND\b/gi, 'and')
+        .replace(/\bOR\b/gi, 'or');
+    const result = await xpathToLimeSurvey(normalizedXPath);
+    // Handle edge case: selected() with just {field} (without $)
+    if (result && result.includes('selected(')) {
+        return result.replace(/selected\s*\(\s*\{(\w+)\}\s*,\s*["']([^'"]+)["']\s*\)/g, (_match, fieldName, value) => {
+            return `(${sanitizeName(fieldName)}="${value}")`;
+        });
+    }
+    return result || '1';
+}