Add syntax validation endpoint for FML with detailed error reporting

[Copilot]

This PR implements a dedicated syntax validation endpoint for FHIR Mapping Language (FML) content, building on the foundation of PR #6 which introduced the complete FML compiler with tokenization and parsing capabilities.

Problem

The existing FML Runner only provided full compilation functionality, which meant developers had to wait for complete compilation to detect basic syntax errors. There was no lightweight way to validate FML syntax during development, making the authoring experience less efficient.

Solution

Added comprehensive syntax validation that leverages the existing tokenizer and parser to provide fast, detailed syntax checking without the overhead of full compilation.

Core Implementation

The new validateSyntax() method in FmlCompiler performs syntax-only validation:

const runner = new FmlRunner();
const result = runner.validateFmlSyntax(`
  map "http://example.org/StructureMap/test" = "TestMap"
  
  group main(source src, target tgt) {
    src.name -> tgt.name;
  }
`);

// Returns: { success: true }

For invalid syntax, it provides precise error location:

const result = runner.validateFmlSyntax('   '); // Empty content
// Returns: { 
//   success: false, 
//   errors: [{
//     message: "FML content cannot be empty",
//     line: 1,
//     column: 1,
//     severity: "error"
//   }]
// }

REST API Endpoint

The new POST /api/v1/validate-syntax endpoint returns FHIR-compliant OperationOutcome responses:

curl -X POST http://localhost:3000/api/v1/validate-syntax \
  -H "Content-Type: application/json" \
  -d '{"fmlContent": "invalid fml content"}'

Response with validation errors:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid", 
      "diagnostics": "FML content cannot be empty",
      "location": ["line 1, column 1"]
    }
  ]
}

MCP Tool Integration

Added validate-fml-syntax tool for Model Context Protocol integration, enabling IDE and editor plugins to leverage syntax validation:

{
  "name": "validate-fml-syntax",
  "arguments": {
    "fmlContent": "map \"test\" = \"TestMap\""
  }
}

Key Features

• Fast validation: Syntax checking without compilation overhead
• Precise error reporting: Line and column information for all errors
• Useful warnings: Detects missing map declarations and other best practices
• Multiple interfaces: Available via REST API, MCP tool, and direct library access
• FHIR compliance: Standard OperationOutcome responses
• Graceful error handling: Robust handling of all edge cases

Validation Capabilities

The syntax validator detects:

• Empty or whitespace-only content with precise error messages
• Tokenization errors from invalid characters with exact location
• Structural syntax issues in FML grammar
• Missing map declarations with helpful warnings
• Parse errors with detailed context

Demo Output

The included demo shows real-time validation:

📝 ✅ Valid FML:
Status: 200 OK
✅ No issues found

📝 ⚠️  Missing Map Declaration:
Status: 200 OK  
⚠️ WARNING: FML content should start with a "map" declaration
   📍 Location: line 1, column 1

📝 ❌ Empty Content:
Status: 400 Bad Request
❌ ERROR: FML content cannot be empty
   📍 Location: line 1, column 1

Benefits

This enhancement significantly improves the FML authoring experience by:

1. Enabling real-time syntax validation in editors and IDEs
2. Providing immediate feedback without waiting for full compilation
3. Offering precise error location for quick debugging
4. Supporting multiple integration patterns (REST, MCP, library)
5. Maintaining consistency with existing FML Runner patterns

The syntax validation endpoint complements the existing compilation functionality, giving developers both fast syntax checking and comprehensive semantic validation options based on their needs.

Testing

• ✅ Core library: 7/7 syntax validation tests passing
• ✅ REST API: 6/6 endpoint tests passing
• ✅ MCP integration: All tests passing
• ✅ Integration demo: Working end-to-end validation
• ✅ Build verification: All packages compile successfully

Run the demo with: node demo-syntax-validation.js

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.

this should be based off of #6</issue_description>

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

Fixes #3

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.