context_spook 1.6.0 → 1.7.0

data/spec/fixtures/encode/arrays-nested.json

@@ -0,0 +1,120 @@
+{
+  "version": "4.0",
+  "category": "encode",
+  "description": "Nested and mixed array encoding – arrays of arrays, mixed type arrays, root arrays",
+  "tests": [
+    {
+      "name": "quotes strings containing delimiters in nested arrays",
+      "input": {
+        "pairs": [["a", "b"], ["c,d", "e:f", "true"]]
+      },
+      "expected": "pairs[2]:\n  - [2]: a,b\n  - [3]: \"c,d\",\"e:f\",\"true\"",
+      "specSection": "9.2"
+    },
+    {
+      "name": "encodes empty inner arrays",
+      "input": {
+        "pairs": [[], []]
+      },
+      "expected": "pairs[2]:\n  - [0]:\n  - [0]:",
+      "specSection": "9.2"
+    },
+    {
+      "name": "encodes root-level primitive array",
+      "input": ["x", "y", "true", true, 10],
+      "expected": "[5]: x,y,\"true\",true,10",
+      "specSection": "9.1"
+    },
+    {
+      "name": "encodes root-level array of uniform objects in tabular form",
+      "input": [{ "id": 1 }, { "id": 2 }],
+      "expected": "[2]{id}:\n  1\n  2",
+      "specSection": "9.3"
+    },
+    {
+      "name": "encodes root-level array of non-uniform objects in list form",
+      "input": [{ "id": 1 }, { "id": 2, "name": "Ada" }],
+      "expected": "[2]:\n  - id: 1\n  - id: 2\n    name: Ada",
+      "specSection": "9.4"
+    },
+    {
+      "name": "encodes root-level array mixing primitive, object, and array of objects in list form",
+      "input": ["summary", { "id": 1, "name": "Ada" }, [{ "id": 2 }, { "status": "draft" }]],
+      "expected": "[3]:\n  - summary\n  - id: 1\n    name: Ada\n  - [2]:\n    - id: 2\n    - status: draft",
+      "specSection": "9.4"
+    },
+    {
+      "name": "encodes root-level arrays of arrays",
+      "input": [[1, 2], []],
+      "expected": "[2]:\n  - [2]: 1,2\n  - [0]:",
+      "specSection": "9.2"
+    },
+    {
+      "name": "encodes empty root-level array",
+      "input": [],
+      "expected": "[]",
+      "specSection": "9.1"
+    },
+    {
+      "name": "uses list form for arrays mixing primitives and objects",
+      "input": {
+        "items": [1, { "a": 1 }, "text"]
+      },
+      "expected": "items[3]:\n  - 1\n  - a: 1\n  - text",
+      "specSection": "9.4"
+    },
+    {
+      "name": "uses list form for arrays mixing objects and arrays",
+      "input": {
+        "items": [{ "a": 1 }, [1, 2]]
+      },
+      "expected": "items[2]:\n  - a: 1\n  - [2]: 1,2",
+      "specSection": "9.4"
+    },
+    {
+      "name": "quotes hash-leading string as list item",
+      "input": {
+        "items": ["#x", { "a": 1 }]
+      },
+      "expected": "items[2]:\n  - \"#x\"\n  - a: 1",
+      "specSection": "7.2"
+    },
+    {
+      "name": "uses list form for a tabular-eligible array in list-item position",
+      "input": {
+        "a": [[{ "x": 1 }, { "x": 2 }]]
+      },
+      "expected": "a[1]:\n  - [2]:\n    - x: 1\n    - x: 2",
+      "specSection": "9.4",
+      "note": "A keyless fields-bearing header is valid only at the document root"
+    },
+    {
+      "name": "uses list form for an array of arrays in list-item position",
+      "input": [
+        [
+          [
+            1
+          ]
+        ]
+      ],
+      "expected": "[1]:\n  - [1]:\n    - [1]: 1",
+      "specSection": "9.4"
+    },
+    {
+      "name": "uses list form for an array mixing primitives and objects in list-item position",
+      "input": {
+        "a": [
+          [
+            1,
+            {
+              "x": 1
+            }
+          ],
+          2
+        ]
+      },
+      "expected": "a[2]:\n  - [2]:\n    - 1\n    - x: 1\n  - 2",
+      "specSection": "9.4"
+    }
+  ]
+}

data/spec/fixtures/encode/arrays-objects.json

@@ -0,0 +1,160 @@
+{
+  "version": "4.0",
+  "category": "encode",
+  "description": "Arrays of objects encoding – list form for non-uniform objects and complex structures",
+  "tests": [
+    {
+      "name": "uses list form for objects with different fields",
+      "input": {
+        "items": [
+          { "id": 1, "name": "First" },
+          { "id": 2, "name": "Second", "extra": true }
+        ]
+      },
+      "expected": "items[2]:\n  - id: 1\n    name: First\n  - id: 2\n    name: Second\n    extra: true",
+      "specSection": "9.4"
+    },
+    {
+      "name": "preserves field order in list items",
+      "input": {
+        "items": [
+          { "nums": [1, 2, 3], "name": "Ada" },
+          { "name": "Ada", "nums": [1, 2, 3] }
+        ]
+      },
+      "expected": "items[2]:\n  - nums[3]: 1,2,3\n    name: Ada\n  - name: Ada\n    nums[3]: 1,2,3",
+      "specSection": "10"
+    },
+    {
+      "name": "uses list form for objects containing arrays of arrays",
+      "input": {
+        "items": [
+          { "matrix": [[1, 2], [3, 4]], "name": "grid" }
+        ]
+      },
+      "expected": "items[1]:\n  - matrix[2]:\n      - [2]: 1,2\n      - [2]: 3,4\n    name: grid",
+      "specSection": "10"
+    },
+    {
+      "name": "uses tabular form for a list-item object's first field, with and without sibling fields",
+      "input": {
+        "items": [
+          { "users": [{ "id": 1, "name": "Ada" }, { "id": 2, "name": "Bob" }], "status": "active" },
+          { "users": [{ "id": 3, "name": "Cy" }, { "id": 4, "name": "Dee" }] }
+        ]
+      },
+      "expected": "items[2]:\n  - users[2]{id,name}:\n      1,Ada\n      2,Bob\n    status: active\n  - users[2]{id,name}:\n      3,Cy\n      4,Dee",
+      "specSection": "10",
+      "note": "Tabular header on hyphen line with rows at depth +2 and sibling fields at depth +1"
+    },
+    {
+      "name": "uses list form for nested object arrays with mismatched keys",
+      "input": {
+        "items": [
+          { "users": [{ "id": 1, "name": "Ada" }, { "id": 2 }], "status": "active" }
+        ]
+      },
+      "expected": "items[1]:\n  - users[2]:\n      - id: 1\n        name: Ada\n      - id: 2\n    status: active",
+      "specSection": "10"
+    },
+    {
+      "name": "places empty arrays on the hyphen line when first and at field depth when later",
+      "input": {
+        "items": [
+          { "data": [], "name": "Ada" },
+          { "name": "Bob", "data": [] }
+        ]
+      },
+      "expected": "items[2]:\n  - data: []\n    name: Ada\n  - name: Bob\n    data: []",
+      "specSection": "10"
+    },
+    {
+      "name": "uses field order from first object for tabular headers",
+      "input": {
+        "items": [
+          { "a": 1, "b": 2, "c": 3 },
+          { "c": 30, "b": 20, "a": 10 }
+        ]
+      },
+      "expected": "items[2]{a,b,c}:\n  1,2,3\n  10,20,30",
+      "specSection": "9.3"
+    },
+    {
+      "name": "uses list form when one object has nested field",
+      "input": {
+        "items": [
+          { "id": 1, "data": "string" },
+          { "id": 2, "data": { "nested": true } }
+        ]
+      },
+      "expected": "items[2]:\n  - id: 1\n    data: string\n  - id: 2\n    data:\n      nested: true",
+      "specSection": "9.4"
+    },
+    {
+      "name": "uses list form for arrays containing empty objects",
+      "input": {
+        "items": [{}, {}]
+      },
+      "expected": "items[2]:\n  -\n  -",
+      "specSection": "9.4",
+      "note": "Empty objects are excluded from tabular detection (§9.3), so the array uses list form with bare hyphen markers (§10)"
+    },
+    {
+      "name": "encodes a keyed-eligible object in a tabular column as a nested field group",
+      "input": {
+        "a": [
+          {
+            "t": {
+              "p": {
+                "x": 1
+              },
+              "q": {
+                "x": 2
+              }
+            },
+            "other": 9
+          }
+        ]
+      },
+      "expected": "a[1]{t{p{x},q{x}},other}:\n  1,2,9",
+      "specSection": "9.5",
+      "note": "Keyed tabular form is mandated in object-field and root positions, not in a column",
+      "minSpecVersion": "4.1"
+    },
+    {
+      "name": "places an empty object first field on the hyphen line",
+      "input": {
+        "items": [
+          {
+            "a": {},
+            "b": 1
+          }
+        ]
+      },
+      "expected": "items[1]:\n  - a:\n    b: 1",
+      "specSection": "10"
+    },
+    {
+      "name": "uses tabular form for a later field of a list-item object",
+      "input": {
+        "items": [
+          {
+            "id": 1,
+            "users": [
+              {
+                "id": 1,
+                "name": "Ada"
+              },
+              {
+                "id": 2,
+                "name": "Bob"
+              }
+            ]
+          }
+        ]
+      },
+      "expected": "items[1]:\n  - id: 1\n    users[2]{id,name}:\n      1,Ada\n      2,Bob",
+      "specSection": "10"
+    }
+  ]
+}

data/spec/fixtures/encode/arrays-primitive.json

@@ -0,0 +1,95 @@
+{
+  "version": "4.0",
+  "category": "encode",
+  "description": "Primitive array encoding – inline arrays of strings, numbers, booleans",
+  "tests": [
+    {
+      "name": "encodes mixed primitive arrays inline",
+      "input": {
+        "data": ["x", "y", true, 10]
+      },
+      "expected": "data[4]: x,y,true,10",
+      "specSection": "9.1"
+    },
+    {
+      "name": "encodes empty arrays",
+      "input": {
+        "items": []
+      },
+      "expected": "items: []",
+      "specSection": "9.1"
+    },
+    {
+      "name": "encodes empty string keys for inline arrays",
+      "input": {
+        "": [1, 2, 3]
+      },
+      "expected": "\"\"[3]: 1,2,3",
+      "specSection": "9.1"
+    },
+    {
+      "name": "encodes empty string keys for empty arrays",
+      "input": {
+        "": []
+      },
+      "expected": "\"\": []",
+      "specSection": "9.1"
+    },
+    {
+      "name": "encodes empty string in single-item array",
+      "input": {
+        "items": [""]
+      },
+      "expected": "items[1]: \"\"",
+      "specSection": "9.1"
+    },
+    {
+      "name": "encodes empty string in multi-item array",
+      "input": {
+        "items": ["a", "", "b"]
+      },
+      "expected": "items[3]: a,\"\",b",
+      "specSection": "9.1"
+    },
+    {
+      "name": "encodes whitespace-only strings in arrays",
+      "input": {
+        "items": [" ", "  "]
+      },
+      "expected": "items[2]: \" \",\"  \"",
+      "specSection": "9.1"
+    },
+    {
+      "name": "quotes array strings with comma",
+      "input": {
+        "items": ["a", "b,c", "d:e"]
+      },
+      "expected": "items[3]: a,\"b,c\",\"d:e\"",
+      "specSection": "9.1"
+    },
+    {
+      "name": "quotes strings that look like literals or numbers in arrays",
+      "input": {
+        "items": ["x", "true", "42", "-3.14"]
+      },
+      "expected": "items[4]: x,\"true\",\"42\",\"-3.14\"",
+      "specSection": "9.1"
+    },
+    {
+      "name": "quotes strings with structural meanings in arrays",
+      "input": {
+        "items": ["[5", "x]", "- item", "{key", "y}"]
+      },
+      "expected": "items[5]: \"[5\",\"x]\",\"- item\",\"{key\",\"y}\"",
+      "specSection": "9.1"
+    },
+    {
+      "name": "quotes hash-leading string in inline array",
+      "input": {
+        "tags": ["#a", "b"]
+      },
+      "expected": "tags[2]: \"#a\",b",
+      "specSection": "7.2"
+    }
+  ]
+}

data/spec/fixtures/encode/arrays-tabular.json

@@ -0,0 +1,182 @@
+{
+  "version": "4.0",
+  "category": "encode",
+  "description": "Tabular array encoding – arrays of uniform objects with primitive values",
+  "tests": [
+    {
+      "name": "encodes arrays of uniform objects in tabular form",
+      "input": {
+        "items": [
+          { "sku": "A1", "qty": 2, "price": 9.99 },
+          { "sku": "B2", "qty": 1, "price": 14.5 }
+        ]
+      },
+      "expected": "items[2]{sku,qty,price}:\n  A1,2,9.99\n  B2,1,14.5",
+      "specSection": "9.3"
+    },
+    {
+      "name": "encodes null values in tabular form",
+      "input": {
+        "items": [
+          { "id": 1, "value": null },
+          { "id": 2, "value": "test" }
+        ]
+      },
+      "expected": "items[2]{id,value}:\n  1,null\n  2,test",
+      "specSection": "9.3"
+    },
+    {
+      "name": "quotes strings containing delimiters in tabular rows",
+      "input": {
+        "items": [
+          { "sku": "A,1", "desc": "cool", "qty": 2 },
+          { "sku": "B2", "desc": "wip: test", "qty": 1 }
+        ]
+      },
+      "expected": "items[2]{sku,desc,qty}:\n  \"A,1\",cool,2\n  B2,\"wip: test\",1",
+      "specSection": "9.3"
+    },
+    {
+      "name": "quotes ambiguous strings in tabular rows",
+      "input": {
+        "items": [
+          { "id": 1, "status": "true" },
+          { "id": 2, "status": "false" }
+        ]
+      },
+      "expected": "items[2]{id,status}:\n  1,\"true\"\n  2,\"false\"",
+      "specSection": "9.3"
+    },
+    {
+      "name": "encodes tabular arrays with keys needing quotes",
+      "input": {
+        "items": [
+          { "order:id": 1, "full name": "Ada" },
+          { "order:id": 2, "full name": "Bob" }
+        ]
+      },
+      "expected": "items[2]{\"order:id\",\"full name\"}:\n  1,Ada\n  2,Bob",
+      "specSection": "9.3"
+    },
+    {
+      "name": "encodes tabular arrays with empty string keys",
+      "input": {
+        "": [
+          { "id": 1, "name": "Ada" },
+          { "id": 2, "name": "Bob" }
+        ]
+      },
+      "expected": "\"\"[2]{id,name}:\n  1,Ada\n  2,Bob",
+      "specSection": "9.3"
+    },
+    {
+      "name": "quotes hash-leading string in tabular cell",
+      "input": {
+        "items": [{ "tag": "#a" }, { "tag": "b" }]
+      },
+      "expected": "items[2]{tag}:\n  \"#a\"\n  b",
+      "specSection": "7.2",
+      "note": "Unquoted, the first row would read as a comment line on decode"
+    },
+    {
+      "name": "collapses a uniform nested object column into a nested field group",
+      "input": {
+        "orders": [
+          { "id": 1, "customer": { "name": "Ada", "country": "DK" }, "total": 99 },
+          { "id": 2, "customer": { "country": "UK", "name": "Bob" }, "total": 149 }
+        ]
+      },
+      "expected": "orders[2]{id,customer{name,country},total}:\n  1,Ada,DK,99\n  2,Bob,UK,149",
+      "specSection": "9.3"
+    },
+    {
+      "name": "collapses sibling nested field groups with depth-first row layout",
+      "input": {
+        "shipments": [
+          { "id": "s1", "sender": { "name": "ACME", "city": "Berlin" }, "receiver": { "name": "Globex", "city": "Oslo" } }
+        ]
+      },
+      "expected": "shipments[1]{id,sender{name,city},receiver{name,city}}:\n  s1,ACME,Berlin,Globex,Oslo",
+      "specSection": "9.3"
+    },
+    {
+      "name": "collapses nested field groups recursively without a depth cap",
+      "input": {
+        "items": [
+          { "id": 1, "geo": { "point": { "lat": 1.5, "lon": 2.5 } } },
+          { "id": 2, "geo": { "point": { "lat": 3, "lon": 4 } } }
+        ]
+      },
+      "expected": "items[2]{id,geo{point{lat,lon}}}:\n  1,1.5,2.5\n  2,3,4",
+      "specSection": "9.3"
+    },
+    {
+      "name": "uses the active delimiter inside nested field groups",
+      "input": {
+        "orders": [
+          { "id": 1, "customer": { "name": "Ada", "country": "DK" }, "total": 99 },
+          { "id": 2, "customer": { "name": "Bob", "country": "UK" }, "total": 149 }
+        ]
+      },
+      "options": { "delimiter": "|" },
+      "expected": "orders[2|]{id|customer{name|country}|total}:\n  1|Ada|DK|99\n  2|Bob|UK|149",
+      "specSection": "9.3"
+    },
+    {
+      "name": "quotes subfield names inside nested field groups per key encoding",
+      "input": {
+        "items": [
+          { "id": 1, "customer": { "full name": "Ada", "country": "UK" } }
+        ]
+      },
+      "expected": "items[1]{id,customer{\"full name\",country}}:\n  1,Ada,UK",
+      "specSection": "9.3"
+    },
+    {
+      "name": "falls back to list form when nested object keys differ per row",
+      "input": {
+        "entries": [
+          { "id": 1, "meta": { "a": 1 } },
+          { "id": 2, "meta": { "b": 2 } }
+        ]
+      },
+      "expected": "entries[2]:\n  - id: 1\n    meta:\n      a: 1\n  - id: 2\n    meta:\n      b: 2",
+      "specSection": "9.3",
+      "note": "The meta column is not nested-uniform (differing key sets), so the whole array uses §9.4"
+    },
+    {
+      "name": "falls back to list form when a column mixes null and objects",
+      "input": {
+        "orders": [
+          { "id": 1, "customer": { "name": "Ada" } },
+          { "id": 2, "customer": null }
+        ]
+      },
+      "expected": "orders[2]:\n  - id: 1\n    customer:\n      name: Ada\n  - id: 2\n    customer: null",
+      "specSection": "9.3",
+      "note": "A null cell is a primitive, so the customer column is neither uniform-primitive nor nested-uniform"
+    },
+    {
+      "name": "falls back to list form when a nested object contains an array",
+      "input": {
+        "orders": [
+          { "id": 1, "customer": { "name": "Ada", "tags": ["x"] } }
+        ]
+      },
+      "expected": "orders[1]:\n  - id: 1\n    customer:\n      name: Ada\n      tags[1]: x",
+      "specSection": "9.3",
+      "note": "Array values disqualify a column; rows must contain only primitive cells"
+    },
+    {
+      "name": "falls back to list form when a nested column contains an empty object",
+      "input": {
+        "items": [
+          { "id": 1, "meta": {} }
+        ]
+      },
+      "expected": "items[1]:\n  - id: 1\n    meta:",
+      "specSection": "9.3",
+      "note": "Nested-uniform requires non-empty objects, mirroring the empty-object exclusion for elements"
+    }
+  ]
+}