Add FML syntax validation endpoint with comprehensive error reporting

[Copilot]

This PR implements a new syntax validation endpoint for FHIR Mapping Language (FML) content that provides detailed error reporting without the overhead of full StructureMap compilation.

Problem

The existing FML Runner could only validate FML syntax as part of the full compilation process. This meant developers had to wait for the entire compilation to complete just to discover basic syntax errors, and error messages were often generic without precise location information.

Solution

Added a dedicated syntax validation endpoint that:

• Validates FML syntax independently without performing full compilation
• Provides precise error locations with line and column numbers
• Returns FHIR-compliant responses using OperationOutcome resources
• Offers structured error codes for programmatic handling
• Includes helpful warnings for best practices

Implementation Details

New REST API Endpoint

POST /api/v1/validate-syntax
Content-Type: application/json

{
  "fmlContent": "map \"http://example.org/test\" = \"Test\"\n\ngroup main(source src, target tgt {"
}

Valid syntax response:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "information",
    "code": "informational",
    "diagnostics": "FML syntax is valid"
  }]
}

Invalid syntax response with precise error location:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "syntax",
    "diagnostics": "Expected ')' after group inputs",
    "location": ["line 3, column 40"],
    "extension": [{
      "url": "http://hl7.org/fhir/StructureDefinition/operationoutcome-issue-code",
      "valueString": "MISSING_GROUP_RPAREN"
    }]
  }]
}

Core Library Enhancements

• Enhanced FML Compiler: Added validateSyntax() method with detailed error recovery
• New Types: FmlSyntaxValidationResult, FmlSyntaxError, FmlSyntaxWarning
• Comprehensive Validation: Checks map declarations, brace matching, group structures
• Position Tracking: Accurate line/column reporting for all syntax elements

MCP Tool Support

Added validate_fml_syntax tool to the Model Context Protocol interface for AI-assisted development workflows.

Error Detection Capabilities

The validator detects and reports:

• Missing or malformed map declarations
• Unmatched braces and parentheses
• Invalid group structures and input parameters
• Syntax errors in uses/imports/prefix statements
• Malformed conceptmap declarations

Testing

• 12 comprehensive unit tests covering valid/invalid syntax scenarios
• 8 REST API integration tests verifying FHIR compliance
• Manual testing with complex real-world FML examples
• All tests passing with full coverage of error conditions

Benefits

• Faster Development: Immediate syntax feedback without compilation overhead
• Better Error Messages: Precise locations help developers fix issues quickly
• FHIR Compliance: Standard OperationOutcome format for interoperability
• Multiple Access Methods: Available via REST API and MCP tools

This enhancement significantly improves the developer experience when working with FHIR Mapping Language by providing fast, accurate syntax validation with actionable error messages.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• scarf.sh
  • Triggering command: node ./report.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>add syntax validation endoint</issue_title>
<issue_description>add endpoint in services library (and then REST and MCP corresponding) to validate the syntax of a fhir mapping language content. should give useul error messages when failed.

</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #3

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.