Merge pull request #151 from cipherstash/eql-markdown-fixes

Eql markdown fixes

Author: tobyhede

Doxyfile

@@ -81,7 +81,9 @@ SHOW_NAMESPACES        = YES
 #---------------------------------------------------------------------------
 
 JAVADOC_AUTOBRIEF      = YES
-OPTIMIZE_OUTPUT_FOR_C  = YES
+# Changed from YES to NO to support SQL function overloading
+# C doesn't support overloading, but SQL does (like C++)
+OPTIMIZE_OUTPUT_FOR_C  = NO
 
 # Disable some C++-specific features that don't apply to SQL
 BUILTIN_STL_SUPPORT    = NO

tasks/docs/generate/test_xml_to_markdown.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+Tests for xml-to-markdown.py parsing
+
+These tests verify critical parsing fixes:
+1. Operator function names extracted from brief description
+2. Variants links don't self-reference when exact match missing
+3. Parameter name/type extraction handles SQL backwards syntax
+"""
+
+import sys
+from pathlib import Path
+
+# Add parent dir to path to import the module
+sys.path.insert(0, str(Path(__file__).parent))
+
+def test_operator_name_extraction():
+    """Test that operator names are extracted from brief description"""
+    from xml.etree import ElementTree as ET
+
+    # Mock XML for operator function
+    xml_str = '''
+    <memberdef kind="function">
+        <name>eql_v2</name>
+        <briefdescription>
+            <para>-&gt;&gt; operator with encrypted selector</para>
+        </briefdescription>
+        <detaileddescription></detaileddescription>
+    </memberdef>
+    '''
+
+    memberdef = ET.fromstring(xml_str)
+
+    # Import process_function (would need to refactor to make testable)
+    # For now, just verify the XML structure we expect
+    name = memberdef.find('name').text
+    brief = memberdef.find('briefdescription/para').text
+
+    assert name == "eql_v2", f"Expected 'eql_v2', got '{name}'"
+    assert "operator" in brief, f"Expected 'operator' in brief, got '{brief}'"
+
+    # Extract operator (this is what the fix does)
+    import re
+    op_match = re.match(r'^([^\s]+)\s+operator', brief.strip())
+    assert op_match, f"Failed to match operator pattern in '{brief}'"
+
+    # XML entities are decoded by ElementTree, so we get '->>',not '&gt;&gt;'
+    extracted_op = op_match.group(1)
+    assert extracted_op == "->>", f"Expected '->>', got '{extracted_op}'"
+
+    print("✓ Operator name extraction test passed")
+
+def test_variants_no_self_reference():
+    """Test that Variants don't link to themselves when variant missing"""
+
+    # Simulate scenario:
+    # - Function: bloom_filter(eql_v2_encrypted)
+    # - Variants: eql_v2.bloom_filter(jsonb)
+    # - But bloom_filter(jsonb) doesn't exist in docs
+
+    all_functions = [
+        {
+            'name': 'bloom_filter',
+            'signature': 'bloom_filter(eql_v2_encrypted)',
+            'params': [{'type': 'eql_v2_encrypted'}]
+        }
+    ]
+
+    # Build index like the code does
+    func_by_sig = {}
+    for func in all_functions:
+        param_types = ', '.join([p['type'] for p in func['params'] if p.get('type')])
+        sig_key = f"{func['name']}({param_types})"
+        func_by_sig[sig_key] = func
+
+    # Test matching
+    func_name = "bloom_filter"
+    params_str = "jsonb"
+    param_list = [p.strip() for p in params_str.split(',') if p.strip()]
+    sig_key = f"{func_name}({', '.join(param_list)})"
+
+    matched_func = func_by_sig.get(sig_key)
+
+    # Should NOT match because parameters are different
+    assert matched_func is None, "Should not match bloom_filter(jsonb) to bloom_filter(eql_v2_encrypted)"
+
+    # Verify the correct signature is indexed
+    assert 'bloom_filter(eql_v2_encrypted)' in func_by_sig
+    assert 'bloom_filter(jsonb)' not in func_by_sig
+
+    print("✓ Variants no self-reference test passed")
+
+def test_param_name_type_swap():
+    """Test that SQL parameter name/type are correctly swapped"""
+    from xml.etree import ElementTree as ET
+
+    # In SQL: func(val eql_v2_encrypted)
+    # But Doxygen XML has: <type>val</type> <declname>eql_v2_encrypted</declname>
+    xml_str = '''
+    <param>
+        <type><ref>val</ref></type>
+        <declname>eql_v2_encrypted</declname>
+    </param>
+    '''
+
+    param = ET.fromstring(xml_str)
+
+    # Extract like the code does
+    param_type_elem = param.find('type')
+    param_declname_elem = param.find('declname')
+    ref_elem = param_type_elem.find('ref')
+
+    # Name is in <ref> child of <type>
+    actual_name = ref_elem.text.strip() if ref_elem is not None else ""
+    # Type is in <declname>
+    actual_type = param_declname_elem.text.strip() if param_declname_elem is not None else ""
+
+    assert actual_name == "val", f"Expected name 'val', got '{actual_name}'"
+    assert actual_type == "eql_v2_encrypted", f"Expected type 'eql_v2_encrypted', got '{actual_type}'"
+
+    print("✓ Parameter name/type swap test passed")
+
+def test_schema_qualified_type():
+    """Test that schema-qualified types like eql_v2.ore_block are parsed correctly"""
+    from xml.etree import ElementTree as ET
+
+    # For eql_v2.ore_block_u64_8_256:
+    # <type><ref>a</ref> eql_v2.</type> <declname>ore_block_u64_8_256</declname>
+    xml_str = '''
+    <param>
+        <type><ref>a</ref> eql_v2.</type>
+        <declname>ore_block_u64_8_256</declname>
+    </param>
+    '''
+
+    param = ET.fromstring(xml_str)
+
+    param_type_elem = param.find('type')
+    param_declname_elem = param.find('declname')
+    ref_elem = param_type_elem.find('ref')
+
+    # Name from ref
+    actual_name = ref_elem.text.strip() if ref_elem is not None else ""
+
+    # Type from tail + declname
+    type_parts = []
+    if ref_elem is not None and ref_elem.tail:
+        type_parts.append(ref_elem.tail.strip())
+    if param_declname_elem is not None:
+        type_parts.append(param_declname_elem.text.strip())
+    actual_type = ''.join(type_parts)
+
+    assert actual_name == "a", f"Expected name 'a', got '{actual_name}'"
+    assert actual_type == "eql_v2.ore_block_u64_8_256", f"Expected 'eql_v2.ore_block_u64_8_256', got '{actual_type}'"
+
+    print("✓ Schema-qualified type test passed")
+
+if __name__ == '__main__':
+    print("Running xml-to-markdown tests...\n")
+
+    try:
+        test_operator_name_extraction()
+        test_variants_no_self_reference()
+        test_param_name_type_swap()
+        test_schema_qualified_type()
+
+        print("\n✅ All tests passed!")
+        sys.exit(0)
+    except AssertionError as e:
+        print(f"\n❌ Test failed: {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"\n❌ Error running tests: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)