feat: Add interpretation trace mode for step-by-step rule execution visibility

[MagPasulke]

Summary

Add an optional trace mode to the interpretation engine that returns step-by-step details of how each rule in a RuleSet was evaluated against the input string. When enabled via ?trace=true on the HTTP API, the response includes a trace array alongside the existing results.

Example Response (trace enabled)

{
  "rulesetId": "GS1_DATAMATRIX",
  "input": "01034531200000111719112510ABC123",
  "results": [
    { "targetField": "GTIN", "value": "03453120000011" },
    { "targetField": "EXPIRY_DATE", "value": "2019-11-25" },
    { "targetField": "BATCH", "value": "ABC123" }
  ],
  "trace": {
    "totalRules": 4,
    "matchedRules": 3,
    "steps": [
      {
        "step": 1,
        "ruleId": "010",
        "type": "MATCH",
        "targetField": "GTIN",
        "regex": "01(\\d{14})",
        "offset": 0,
        "matched": true,
        "capturedGroup": "03453120000011",
        "matchPosition": { "start": 0, "end": 16 },
        "resultValue": "03453120000011"
      },
      {
        "step": 2,
        "ruleId": "020",
        "type": "MATCH",
        "targetField": "EXPIRY_RAW",
        "regex": "17(\\d{6})",
        "offset": 0,
        "matched": true,
        "capturedGroup": "191125",
        "matchPosition": { "start": 16, "end": 24 },
        "resultValue": "191125"
      },
      {
        "step": 3,
        "ruleId": "030",
        "type": "REPLACE",
        "targetField": "EXPIRY_DATE",
        "regex": "(\\d{2})(\\d{2})(\\d{2})",
        "replacePattern": "20$1-$2-$3",
        "offset": 0,
        "sourceValue": "191125",
        "matched": true,
        "resultValue": "2019-11-25"
      },
      {
        "step": 4,
        "ruleId": "040",
        "type": "MATCH",
        "targetField": "BATCH",
        "regex": "10([A-Za-z0-9]{1,20})",
        "offset": 0,
        "matched": true,
        "capturedGroup": "ABC123",
        "matchPosition": { "start": 24, "end": 32 },
        "resultValue": "ABC123"
      }
    ]
  }
}

Implementation Suggestions

Data Model (new objects)

Object	Type	Description
zasis_trace_step	Structure	Single trace entry: step#, rule_id, type, regex, target_field, matched, raw_match, position_start, position_end, result_value, source_value (for REPLACE), offset_pre, offset_post
zasis_tt_trace	Table Type	Standard table of zasis_trace_step

Changes to Existing Objects

Object	Change
zasis_interpret_output	Add optional field trace TYPE zasis_tt_trace
zasis_if_interpreter~execute	Add optional parameter with_trace TYPE abap_bool DEFAULT abap_false
zasis_cl_interpreter	Inside the rule LOOP, conditionally collect trace data; use FIND ... MATCH OFFSET ... MATCH LENGTH for position tracking in MATCH rules
zasis_cl_http_handler_core	Parse ?trace=true query parameter; pass to interpreter; serialize trace in JSON response

Design Principles

• Zero overhead when off — IF with_trace = abap_true guard around trace collection; no extra allocations or regex calls when disabled
• Same execution path — Trace observes existing logic, does not alter rule evaluation behavior
• Optional in response — JSON serializer skips empty trace field; existing consumers see no change
• Position tracking — Replace match() with FIND ... RESULTS to capture match offset/length (only when trace is active, or always if the overhead is negligible)

Affected Layers

1. dm — New structure + table type
2. bo — Interpreter interface + implementation
3. srv — HTTP handler query param parsing + JSON serialization
4. tests — Unit tests for trace output, ICF integration tests for ?trace=true endpoint

[MagPasulke]

Regex Implementation Approach — Comparison

Investigation into whether to migrate from current match()/replace() built-ins to CL_ABAP_MATCHER or FIND...PCRE...RESULTS for trace mode (and potentially general mode).

Key Finding: CL_ABAP_MATCHER is NOT transpilable

The @abaplint/runtime (which powers npm run unit) has no JS implementation of CL_ABAP_MATCHER. Using it would break the local unit test feedback loop entirely — tests would only run on the SAP system.

Both CL_ABAP_MATCHER and CL_ABAP_REGEX are Level A released for ABAP Cloud ✅ — but transpiler support is the blocker.

Comparison Table

Approach	Transpiler support	Trace capability (offset, submatch, position)	REPLACE no-match bug fix	Migration risk	Code complexity
CL_ABAP_MATCHER	❌ No runtime impl	✅ Full	✅ find_next() returns abap_false	🔴 High — breaks npm run unit	Clean OO API
FIND...PCRE...RESULTS (trace path only)	✅ Full	✅ Full	Only in trace path	🟡 Low	Two code branches
FIND...PCRE...RESULTS (migrate both paths)	✅ Full	✅ Full	✅ sy-subrc = 4 on no match	🟢 Low	Single unified path
Keep match()/replace() (status quo)	✅ Full	❌ None (no metadata)	❌ Bug remains	⚪ Zero	Simplest

What each approach provides for trace

• match() built-in: Returns matched substring only. No offset, no length, no capture group separation. Cannot distinguish "which part was the capture group" from "full match".
• FIND...PCRE...MATCH OFFSET...MATCH LENGTH...SUBMATCHES: Returns offset (position in string), length of match, and individual submatch (capture group) values. Fully supported by transpiler.
• CL_ABAP_MATCHER: Same data via get_offset(), get_length(), get_submatch(1), get_match(). Cleanest API but not transpilable.

REPLACE no-match detection bug (existing)

Current code uses string comparison to detect no-match:

IF result_replace NE string_to_be_interpreted.
  " match happened
ENDIF.

This fails when replacement produces output identical to input. Both CL_ABAP_MATCHER and FIND...PCRE solve this definitively (find_next() = abap_false / sy-subrc = 4).

Recommendation under discussion

Option B: Migrate both paths to FIND...PCRE — single code path, fixes REPLACE bug, full trace data always available, zero transpiler risk. Trace mode just adds collection logic around already-computed data.