Fix: Enum schema generation bugs (raw values and backticks)

[ecito]

Description

This PR fixes two bugs in enum schema generation that caused incompatibility with Swift's Codable:

Bug 1: String-backed enums using case names instead of raw values

String-backed enums (enum Size: String { case small = "sm" }) were generating schemas with case names (["small"]) instead of raw values (["sm"]). This broke compatibility with Codable, which uses raw values for encoding/decoding.

Example:

enum Size: String {
  case small = "sm"
  case medium = "md"
}

• Before: {"type": "string", "enum": ["small", "medium"]} ❌
• After: {"type": "string", "enum": ["sm", "md"]} ✅

This ensures generated schemas validate JSON that Swift's standard JSONDecoder can decode.

Bug 2: Backticked identifiers including backticks in schemas

Backticked Swift identifiers (e.g., case \default`) were incorrectly including the backticks in JSON schemas, generating "`default`"instead of"default"`.

Example:

enum Keywords {
  case `default`
  case `public`
}

• Before: {"type": "string", "enum": ["\default`", "`public`"]}` ❌
• After: {"type": "string", "enum": ["default", "public"]} ✅

Both fixes ensure the generated schemas match Swift's Codable behavior.

Changes Made

Core Implementation

• SchemableEnumCase.swift: Added raw value extraction logic to capture String raw values from enum cases
• SchemaGenerator.swift:
  • Added String.trimmingBackticks() extension to strip backticks from identifiers
  • Updated enum schema generation to use raw values when present
  • Updated switch case matching to use raw values instead of case names

Documentation

• Macros.md: Enhanced enum documentation with separate sections for:
  • Simple enums (without raw values)
  • String-backed enums (with raw values)
  • Enums with associated values
  • Added clear examples showing the correct behavior and emphasizing Codable compatibility

Tests

• PollExampleTests.swift: Updated test data to use correct raw values ("Parental Guidance Suggested 13+" instead of "pg13")
• Regenerated snapshots: Updated schema snapshots to reflect correct enum values
• BacktickEnumTests.swift: Added macro expansion tests for backticked enum cases
• BacktickEnumIntegrationTests.swift: Added integration tests covering:
  • Schema generation for backticked enums (with and without raw values)
  • JSON parsing/validation with backticked enums
  • Verification that backticks are properly stripped

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Testing

All tests pass:

• ✅ Macro expansion tests (BacktickEnumTests)
• ✅ Integration tests (BacktickEnumIntegrationTests, PollExampleTests)
• ✅ Existing enum tests continue to pass
• ✅ Schema generation matches Codable behavior

Test Coverage

• Enums without raw values continue to work correctly
• String-backed enums now correctly use raw values
• Mixed enums (some cases with custom raw values, some implicit) work correctly
• Backticked identifiers are properly handled
• JSON parsing/validation works with corrected schemas

Additional Notes

Impact

This is a correctness fix with no breaking changes to the API:

• The macro syntax remains unchanged
• Existing code continues to compile
• Only the generated schemas change to be correct

However, if users were relying on the incorrect behavior (schemas with case names for String-backed enums), their schemas will change. This is the correct behavior, as the previous output was incompatible with Codable.

Related Files Changed

7 files changed, 278 insertions(+), 15 deletions(-)

Sources/JSONSchemaBuilder/Documentation.docc/Articles/Macros.md
Sources/JSONSchemaMacro/Schemable/SchemaGenerator.swift
Sources/JSONSchemaMacro/Schemable/SchemableEnumCase.swift
Tests/JSONSchemaIntegrationTests/BacktickEnumIntegrationTests.swift (new)
Tests/JSONSchemaIntegrationTests/PollExampleTests.swift
Tests/JSONSchemaIntegrationTests/__Snapshots__/PollExampleTests/defintion.1.json
Tests/JSONSchemaMacroTests/BacktickEnumTests.swift (new)

Verification Steps

To verify the fix works correctly:

1. Raw values test:

   @Schemable
   enum Size: String {
     case small = "sm"
     case medium = "md"
   }
   
   // Schema now correctly has: "enum": ["sm", "md"]

2. Backticks test:

   @Schemable
   enum Keywords {
     case `default`
     case `public`
   }
   
   // Schema now correctly has: "enum": ["default", "public"]

3. Codable compatibility:

   let json = "{\"size\": \"sm\"}"
   let decoded = try JSONDecoder().decode(Product.self, from: json.data(using: .utf8)!)
   // Now works! Schema validates the same JSON that Codable accepts