Add tests and docs for bit_map element

flexca · flexca · commit ba43e3405aae · 2026-04-15T20:48:53.000+03:00
diff --git a/core/src/main/java/com/github/flexca/enot/core/parser/EnotParser.java b/core/src/main/java/com/github/flexca/enot/core/parser/EnotParser.java
@@ -2,10 +2,8 @@
 
 import com.github.flexca.enot.core.EnotContext;
 import com.github.flexca.enot.core.exception.EnotParsingException;
-import com.github.flexca.enot.core.expression.ConditionExpressionParser;
 import com.github.flexca.enot.core.registry.EnotElementBodyResolver;
 import com.github.flexca.enot.core.registry.EnotElementSpecification;
-import com.github.flexca.enot.core.registry.EnotRegistry;
 import com.github.flexca.enot.core.registry.EnotTypeSpecification;
 import com.github.flexca.enot.core.element.EnotElement;
 import com.github.flexca.enot.core.element.attribute.EnotAttribute;
@@ -156,6 +154,11 @@ private Optional<EnotElement> parseElement(ObjectNode jsonElement, String parent
             elementBody.ifPresent(element::setBody);
         } else {
             try {
+
+                String compositeIdentifier = bodyResolver.getUniqueCompositeIdentifier(element);
+                if (StringUtils.isNotBlank(compositeIdentifier)) {
+                    // TODO: detect cyclic dependency
+                }
                 element.setBody(bodyResolver.resolveBody(element, enotContext));
             } catch(Exception e) {
                 jsonErrors.add(EnotJsonError.of(parentPath + "/" + ENOT_ELEMENT_BODY_NAME,
diff --git a/core/src/main/java/com/github/flexca/enot/core/registry/EnotElementBodyResolver.java b/core/src/main/java/com/github/flexca/enot/core/registry/EnotElementBodyResolver.java
@@ -3,7 +3,61 @@
 import com.github.flexca.enot.core.EnotContext;
 import com.github.flexca.enot.core.element.EnotElement;
 
+/**
+ * Strategy interface for resolving an element's body dynamically at parse time.
+ *
+ * <p>Certain element types — most notably {@code system/reference} — do not carry
+ * their body inline in the template. Instead, the body must be fetched or computed
+ * when the element is first encountered during parsing. Implementations of this
+ * interface encapsulate that resolution logic.
+ *
+ * <p>The interface also participates in <b>cyclic-dependency detection</b>. Because
+ * body resolution may itself trigger further parsing (e.g. a reference that includes
+ * another template which in turn references the first), the parser tracks a set of
+ * identifiers that are currently being resolved. Implementations that can participate
+ * in such cycles must return a non-{@code null} identifier from
+ * {@link #getUniqueCompositeIdentifier}; the parser uses this value to detect and
+ * report cycles before a {@link StackOverflowError} can occur.
+ */
 public interface EnotElementBodyResolver {
 
+    /**
+     * Returns a unique identifier for the given element that the parser uses to
+     * detect cyclic dependencies during resolution.
+     *
+     * <p>The returned string must uniquely identify the specific external resource
+     * or body this element resolves to. For {@code system/reference} elements this
+     * is typically a composite of the reference type and identifier, for example
+     * {@code "test_resources:json/asn1/rfc/san/san-dns.json"}.
+     *
+     * <p>If cycle detection is not applicable for this resolver implementation,
+     * return {@code null}. The parser will skip cycle detection for that element.
+     *
+     * @param element the element whose resolution identity is needed
+     * @return a non-empty string that uniquely identifies the resolution target,
+     *         or {@code null} if cycle detection is not required
+     */
+    String getUniqueCompositeIdentifier(EnotElement element);
+
+    /**
+     * Resolves and returns the body for the given element at parse time.
+     *
+     * <p>This method is called by the parser when it encounters an element whose
+     * {@link com.github.flexca.enot.core.types.system.SystemKind} has a registered
+     * body resolver. The returned value replaces the element's inline body and is
+     * stored directly on the parsed {@link EnotElement}.
+     *
+     * <p>Implementations may perform I/O, invoke further parsing via
+     * {@link EnotContext#getEnotParser()}, or compute the body from the element's
+     * attributes. When further parsing is involved, cyclic-dependency detection via
+     * {@link #getUniqueCompositeIdentifier} should be implemented to prevent
+     * infinite recursion.
+     *
+     * @param element      the element whose body is to be resolved
+     * @param enotContext  the current parsing context, providing access to the
+     *                     registry, parser, serializer, and expression engine
+     * @return the resolved body; the concrete type depends on the element kind
+     *         (e.g. {@code List<EnotElement>} for {@code system/reference})
+     */
     Object resolveBody(EnotElement element, EnotContext enotContext);
 }
diff --git a/core/src/main/java/com/github/flexca/enot/core/types/system/SystemReferenceBodyResolver.java b/core/src/main/java/com/github/flexca/enot/core/types/system/SystemReferenceBodyResolver.java
@@ -7,11 +7,43 @@
 import com.github.flexca.enot.core.registry.EnotElementReferenceResolver;
 import com.github.flexca.enot.core.types.system.attribute.SystemAttribute;
 
+/**
+ * {@link EnotElementBodyResolver} for {@code system/reference} elements.
+ *
+ * <p>Resolves the body by delegating to the {@link com.github.flexca.enot.core.registry.EnotElementReferenceResolver}
+ * registered in the {@link com.github.flexca.enot.core.registry.EnotRegistry} for the element's
+ * {@code reference_type} attribute. The resolver is looked up at parse time, so all reference
+ * types must be registered before parsing begins.
+ *
+ * <p>The composite identifier returned by {@link #getUniqueCompositeIdentifier} is
+ * {@code "<reference_type>:<reference_identifier>"}, which makes cycles across different
+ * reference type implementations distinguishable.
+ */
 public class SystemReferenceBodyResolver implements EnotElementBodyResolver {
 
+    @Override
+    public String getUniqueCompositeIdentifier(EnotElement element) {
+
+        String referenceType = getReferenceType(element);
+        String referenceIdentifier = getReferenceIdentifier(element);
+        return referenceType + ":" + referenceIdentifier;
+    }
+
     @Override
     public Object resolveBody(EnotElement element, EnotContext enotContext) {
 
+        String referenceType = getReferenceType(element);
+        EnotElementReferenceResolver referenceResolver = enotContext.getEnotRegistry().getElementReferenceResolver(referenceType);
+        if(referenceResolver == null) {
+            throw new EnotInvalidArgumentException("no registered EnotElementReferenceResolver found for reference type: "
+                    + referenceType);
+        }
+        String referenceIdentifier = getReferenceIdentifier(element);
+        return referenceResolver.resolve(referenceIdentifier, enotContext);
+    }
+
+    private String getReferenceType(EnotElement element) {
+
         Object referenceType = element.getAttribute(SystemAttribute.REFERENCE_TYPE);
         if (referenceType == null) {
             throw new EnotInvalidArgumentException("attribute " + SystemAttribute.REFERENCE_TYPE.getName()
@@ -20,12 +52,10 @@ public Object resolveBody(EnotElement element, EnotContext enotContext) {
         if (!(referenceType instanceof String)) {
             throw new EnotInvalidArgumentException("attribute " + SystemAttribute.REFERENCE_TYPE.getName() + " must be string");
         }
+        return (String) referenceType;
+    }
 
-        EnotElementReferenceResolver referenceResolver = enotContext.getEnotRegistry().getElementReferenceResolver((String) referenceType);
-        if(referenceResolver == null) {
-            throw new EnotInvalidArgumentException("no registered EnotElementReferenceResolver found for reference type: "
-                    + referenceType);
-        }
+    private String getReferenceIdentifier(EnotElement element) {
 
         Object referenceIdentifier = element.getAttribute(SystemAttribute.REFERENCE_IDENTIFIER);
         if (referenceIdentifier == null) {
@@ -36,7 +66,6 @@ public Object resolveBody(EnotElement element, EnotContext enotContext) {
             throw new EnotInvalidArgumentException("attribute " + SystemAttribute.REFERENCE_IDENTIFIER.getName()
                     + " must be string");
         }
-
-        return referenceResolver.resolve((String) referenceIdentifier, enotContext);
+        return (String) referenceIdentifier;
     }
 }
diff --git a/core/src/main/java/com/github/flexca/enot/core/types/system/serializer/SystemBitMapSerializer.java b/core/src/main/java/com/github/flexca/enot/core/types/system/serializer/SystemBitMapSerializer.java
@@ -91,15 +91,15 @@ private byte[] inputToBytes(List<ElementSerializationResult> serializedBody, Byt
             }
             bitCount++;
             if (bitCount >= 8) {
-                int index = ByteOrder.LITTLE_ENDIAN.equals(byteOrder) ? byteCount : (bytesLength - byteCount - 1);
+                int index = ByteOrder.BIG_ENDIAN.equals(byteOrder) ? byteCount : (bytesLength - byteCount - 1);
                 bytes[index] = (byte) (byteValue & 0xFF);
                 byteValue = 0;
                 bitCount = 0;
                 byteCount++;
             }
         }
         if (serializedBody.size() % 8 != 0) {
-            int index = ByteOrder.LITTLE_ENDIAN.equals(byteOrder) ? byteCount : (bytesLength - byteCount - 1);
+            int index = ByteOrder.BIG_ENDIAN.equals(byteOrder) ? byteCount : (bytesLength - byteCount - 1);
             bytes[index] = (byte) (byteValue & 0xFF);
         }
         return bytes;
diff --git a/core/src/test/java/com/github/flexca/enot/core/serializer/EnotSerializerSuccessCasesTest.java b/core/src/test/java/com/github/flexca/enot/core/serializer/EnotSerializerSuccessCasesTest.java
@@ -20,6 +20,7 @@
 import org.junit.jupiter.api.Test;
 import tools.jackson.databind.ObjectMapper;
 
+import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
@@ -177,10 +178,132 @@ void testSerializeX509ValidityMixedDates() throws Exception {
         assertThat(seq.getObjectAt(1)).isInstanceOf(ASN1GeneralizedTime.class);
     }
 
+    // -----------------------------------------------------------------------
+    // bit_map — 4 combinations of bit_order × byte_order
+    //
+    // byte_order and bit_order describe the INPUT data layout.
+    // Output is always big-endian MSB-first (standard Java / network byte order).
+    //
+    // Logical value: [0xFE, 0xCA]  (big-endian output)
+    //   0xFE = 1111_1110,  0xCA = 1100_1010
+    //
+    // -----------------------------------------------------------------------
+
+    @Test
+    void testBitMapMsbFirstBigEndian() throws Exception {
+        // Input already in big-endian MSB-first order — no reordering needed.
+        // group[0]=0xFE=[1,1,1,1,1,1,1,0] → bytes[0]
+        // group[1]=0xCA=[1,1,0,0,1,0,1,0] → bytes[1]
+        List<Boolean> bits = List.of(
+                true,  true, true,  true,  true, true,  true, false,
+                true,  true, false, false, true, false, true, false);
+
+        byte[] result = serializeBitMap("big_endian", "msb_first", bits);
+        assertThat(result).isEqualTo(new byte[]{(byte) 0xFE, (byte) 0xCA});
+    }
+
+    @Test
+    void testBitMapMsbFirstLittleEndian() throws Exception {
+        // Input is little-endian (LSB group first) MSB-first within each byte.
+        // Serializer reverses byte groups to produce big-endian output.
+        // group[0]=0xCA=[1,1,0,0,1,0,1,0] → reversed → bytes[1]
+        // group[1]=0xFE=[1,1,1,1,1,1,1,0] → reversed → bytes[0]
+        List<Boolean> bits = List.of(
+                true, true, false, false, true, false, true, false,
+                true, true, true,  true,  true, true,  true, false);
+
+        byte[] result = serializeBitMap("little_endian", "msb_first", bits);
+        assertThat(result).isEqualTo(new byte[]{(byte) 0xFE, (byte) 0xCA});
+    }
+
+    @Test
+    void testBitMapLsbFirstBigEndian() throws Exception {
+        // Input is big-endian, LSB-first within each byte.
+        // 0xFE=1111_1110: bit0=0,bit1=1..bit7=1 → [F,T,T,T,T,T,T,T]
+        // 0xCA=1100_1010: bit0=0,bit1=1,bit2=0,bit3=1,bit4=0,bit5=0,bit6=1,bit7=1 → [F,T,F,T,F,F,T,T]
+        List<Boolean> bits = List.of(
+                false, true, true,  true, true, true,  true, true,
+                false, true, false, true, false, false, true, true);
+
+        byte[] result = serializeBitMap("big_endian", "lsb_first", bits);
+        assertThat(result).isEqualTo(new byte[]{(byte) 0xFE, (byte) 0xCA});
+    }
+
+    @Test
+    void testBitMapLsbFirstLittleEndian() throws Exception {
+        // Input is little-endian LSB-first — both orderings reversed vs output.
+        // group[0]=0xCA(LSB first)=[F,T,F,T,F,F,T,T] → reversed → bytes[1]
+        // group[1]=0xFE(LSB first)=[F,T,T,T,T,T,T,T] → reversed → bytes[0]
+        List<Boolean> bits = List.of(
+                false, true, false, true, false, false, true, true,
+                false, true, true,  true, true,  true,  true, true);
+
+        byte[] result = serializeBitMap("little_endian", "lsb_first", bits);
+        assertThat(result).isEqualTo(new byte[]{(byte) 0xFE, (byte) 0xCA});
+    }
+
+    @Test
+    void testBitMapPartialByteSingleGroup() throws Exception {
+        // 5 bits, big_endian msb_first: [1,0,1,1,0] packed from bit7 downward
+        // = 1011_0000 = 0xB0, remaining 3 bits are zero
+        List<Boolean> bits = List.of(true, false, true, true, false);
+
+        byte[] result = serializeBitMap("big_endian", "msb_first", bits);
+        assertThat(result).hasSize(1);
+        assertThat(result).isEqualTo(new byte[]{(byte) 0xB0});
+    }
+
+    @Test
+    void testBitMapPartialByteAfterCompleteGroup() throws Exception {
+        // 10 bits, big_endian msb_first:
+        // group[0] = [1,1,1,1,1,1,1,0] = 0xFE (complete) → bytes[0]
+        // partial   = [1,1]             = 1100_0000 = 0xC0  → bytes[1]
+        List<Boolean> bits = List.of(
+                true, true, true, true, true, true, true, false,
+                true, true);
+
+        byte[] result = serializeBitMap("big_endian", "msb_first", bits);
+        assertThat(result).hasSize(2);
+        assertThat(result).isEqualTo(new byte[]{(byte) 0xFE, (byte) 0xC0});
+    }
+
     // -----------------------------------------------------------------------
     // helpers
     // -----------------------------------------------------------------------
 
+    private byte[] serializeBitMap(String byteOrder, String bitOrder, List<Boolean> bits) throws Exception {
+        // Build body as JSON array of individually named placeholders: ["${b0}", "${b1}", ...]
+        // This avoids the ContextNode wrapping issue that occurs when a single placeholder
+        // resolves to a List — individual primitive params unwrap cleanly.
+        StringBuilder bodyArray = new StringBuilder("[");
+        for (int i = 0; i < bits.size(); i++) {
+            if (i > 0) bodyArray.append(",");
+            bodyArray.append("\"${b").append(i).append("}\"");
+        }
+        bodyArray.append("]");
+
+        String json = """
+                {
+                  "type": "system",
+                  "attributes": {
+                    "kind": "bit_map",
+                    "byte_order": "%s",
+                    "bit_order": "%s"
+                  },
+                  "body": %s
+                }
+                """.formatted(byteOrder, bitOrder, bodyArray);
+
+        Map<String, Object> params = new HashMap<>();
+        for (int i = 0; i < bits.size(); i++) {
+            params.put("b" + i, bits.get(i));
+        }
+
+        List<byte[]> result = enotSerializer.serialize(json, ctx(params), enotContext);
+        assertThat(result).hasSize(1);
+        return result.get(0);
+    }
+
     /** Parses one DER blob and asserts SET { SEQUENCE { OID(2.5.4.11), UTF8String(expectedUnit) } } */
     private void assertOrgUnitDer(byte[] der, String expectedUnit) throws Exception {
         ASN1Set set = (ASN1Set) ASN1Primitive.fromByteArray(der);
diff --git a/docs/format/system.md b/docs/format/system.md
@@ -217,20 +217,34 @@ Converts an ordered list of boolean values into a compact bit-field byte
 array. Each boolean in the `body` array maps to one bit in declaration
 order.
 
+**`byte_order` and `bit_order` describe the input data layout.**
+The output is always in **big-endian, MSB-first** order — standard Java /
+network byte order — regardless of the input layout.
+
+| Attribute | Effect on input interpretation |
+|-----------|-------------------------------|
+| `byte_order: "big_endian"` | First group of 8 booleans → most-significant byte of output (no reordering) |
+| `byte_order: "little_endian"` | First group of 8 booleans → least-significant byte; groups are reversed in the output |
+| `bit_order: "msb_first"` | First boolean in a group = bit 7 (most significant bit) |
+| `bit_order: "lsb_first"` | First boolean in a group = bit 0 (least significant bit) |
+
 **Attributes:**
 
 | Attribute | Required | Description |
 |-----------|----------|-------------|
 | `kind` | ✅ | `"bit_map"` |
-| `byte_order` | ✅ | `"big_endian"` or `"little_endian"` |
-| `bit_order` | ✅ | `"msb_first"` or `"lsb_first"` |
+| `byte_order` | ✅ | `"big_endian"` or `"little_endian"` — describes input byte group order |
+| `bit_order` | ✅ | `"msb_first"` or `"lsb_first"` — describes input bit order within each byte |
 
 **Body:** a JSON array of boolean placeholders or literals.
 
 The output is raw binary and is almost always wrapped in a
 `bit_string` ASN.1 element.
 
-**Example — X.509 Key Usage extension:**
+**Example — X.509 Key Usage extension (RFC 5280):**
+
+The Key Usage bit string is defined MSB-first in a single byte, so both
+`byte_order` and `bit_order` are `"big_endian"` / `"msb_first"`:
 
 ```json
 {
@@ -240,8 +254,8 @@ The output is raw binary and is almost always wrapped in a
     "type": "system",
     "attributes": {
       "kind": "bit_map",
-      "byte_order": "little_endian",
-      "bit_order": "lsb_first"
+      "byte_order": "big_endian",
+      "bit_order": "msb_first"
     },
     "body": [
       "${key_usage.digital_signature}",
@@ -264,8 +278,8 @@ The output is raw binary and is almost always wrapped in a
 {
   "key_usage": {
     "digital_signature": true,
-    "key_encipherment": true,
     "non_repudiation": false,
+    "key_encipherment": true,
     "data_encipherment": false,
     "key_agreement": false,
     "key_cert_sign": false,

Original file line number	Diff line number	Diff line change
`@@ -91,15 +91,15 @@ private byte[] inputToBytes(List<ElementSerializationResult> serializedBody, Byt`
`91`	`91`	`}`
`92`	`92`	`bitCount++;`
`93`	`93`	`if (bitCount >= 8) {`
`94`		`- int index = ByteOrder.LITTLE_ENDIAN.equals(byteOrder) ? byteCount : (bytesLength - byteCount - 1);`
	`94`	`+ int index = ByteOrder.BIG_ENDIAN.equals(byteOrder) ? byteCount : (bytesLength - byteCount - 1);`
`95`	`95`	`bytes[index] = (byte) (byteValue & 0xFF);`
`96`	`96`	`byteValue = 0;`
`97`	`97`	`bitCount = 0;`
`98`	`98`	`byteCount++;`
`99`	`99`	`}`
`100`	`100`	`}`
`101`	`101`	`if (serializedBody.size() % 8 != 0) {`
`102`		`- int index = ByteOrder.LITTLE_ENDIAN.equals(byteOrder) ? byteCount : (bytesLength - byteCount - 1);`
	`102`	`+ int index = ByteOrder.BIG_ENDIAN.equals(byteOrder) ? byteCount : (bytesLength - byteCount - 1);`
`103`	`103`	`bytes[index] = (byte) (byteValue & 0xFF);`
`104`	`104`	`}`
`105`	`105`	`return bytes;`