///|
/// Reason why a JSON array or object could not use TOON tabular/keyed-tabular compression.
#derive(Eq, @debug.Debug)
pub(all) enum FallbackReason {
NonUniformObjectKeys(String)
NonPrimitiveColumn(String)
SingleEntryKeyedObject
MixedElementTypes
ListItemPosition
EmptyCollection
}
///|
/// Path-level diagnostic explaining why a nested collection fell back from
/// compact tabular encoding.
#derive(Eq, @debug.Debug)
pub(all) struct FallbackFinding {
path : String
reason : FallbackReason
item_count : Int32
explanation : String
}
///|
/// Summary of tabular eligibility across a JSON payload.
#derive(Eq, @debug.Debug)
pub(all) struct StructuralAudit {
tabular_items : Int32
non_tabular_items : Int32
array_tabular_blocks : Int32
keyed_tabular_blocks : Int32
tabular_coverage_pct : Double
fallbacks : Array[FallbackFinding]
}
///|
priv struct AuditAcc {
mut tabular_items : Int32
mut non_tabular_items : Int32
mut array_tabular_blocks : Int32
mut keyed_tabular_blocks : Int32
fallbacks : Array[FallbackFinding]
}
///|
fn child_path(parent : String, key : String) -> String {
if parent == "$" {
key
} else {
"\{parent}.\{key}"
}
}
///|
fn audit_list_items(arr : Array[Json], path : String, acc : AuditAcc) -> Unit {
for idx, item in arr {
audit_node(item, "\{path}[\{idx}]", acc, list_item=true)
}
}
///|
fn diagnose_array_fallback(
arr : Array[Json],
path : String,
acc : AuditAcc,
) -> Unit {
if arr.is_empty() {
acc.fallbacks.push({
path,
reason: EmptyCollection,
item_count: 0,
explanation: "empty array emits '[]' rather than tabular rows",
})
return
}
// Check if all primitive (inline primitive array is already compact, not a tabular failure)
let mut all_prim = true
let mut all_obj = true
for item in arr {
match item {
Null | True | False | Number(_, ..) | String(_) => all_obj = false
Object(m) => {
all_prim = false
if m.is_empty() {
all_obj = false
}
}
Array(_) => {
all_prim = false
all_obj = false
}
}
}
if all_prim {
return
}
acc.non_tabular_items += arr.length()
if !all_obj {
acc.fallbacks.push({
path,
reason: MixedElementTypes,
item_count: arr.length(),
explanation: "contains non-object, empty-object, or nested-array elements; uses list form ('- ')",
})
audit_list_items(arr, path, acc)
return
}
// All non-empty objects: pinpoint first mismatched key or non-uniform column
guard arr[0] is Object(first_obj) else { return }
for i in 1.. {
acc.fallbacks.push({
path,
reason: NonPrimitiveColumn(k),
item_count: arr.length(),
explanation: "column '\{k}' (first seen at [\{i}]) holds an array, preventing tabular flattening",
})
audit_list_items(arr, path, acc)
return
}
_ => ()
}
}
}
acc.fallbacks.push({
path,
reason: NonPrimitiveColumn("nested"),
item_count: arr.length(),
explanation: "a nested object column has non-uniform sub-keys across elements; falls back to list form",
})
audit_list_items(arr, path, acc)
}
///|
fn is_leaf_record_object(obj : Map[String, Json]) -> Bool {
if obj.is_empty() {
return false
}
for _, v in obj {
match v {
Array(_) | Object(_) => return false
_ => ()
}
}
true
}
///|
fn audit_node(
value : Json,
path : String,
acc : AuditAcc,
list_item~ : Bool = false,
) -> Unit {
match value {
Null | True | False | Number(_, ..) | String(_) => ()
Array(arr) =>
match @encode.extract_tabular_fields(arr) {
Some(_) if list_item => {
acc.non_tabular_items += arr.length()
acc.fallbacks.push({
path,
reason: ListItemPosition,
item_count: arr.length(),
explanation: "an array used as a list item must use list form",
})
audit_list_items(arr, path, acc)
}
Some(_) => {
acc.tabular_items += arr.length()
acc.array_tabular_blocks += 1
}
None => diagnose_array_fallback(arr, path, acc)
}
Object(obj) =>
match @encode.extract_keyed_tabular_fields(obj) {
Some(_) if !list_item => {
acc.tabular_items += obj.length()
acc.keyed_tabular_blocks += 1
}
fields => {
if fields is Some(_) {
acc.non_tabular_items += obj.length()
acc.fallbacks.push({
path,
reason: ListItemPosition,
item_count: obj.length(),
explanation: "an anonymous list object must write its fields individually",
})
} else if obj.length() == 1 {
for _, v in obj {
if v is Object(sub) && is_leaf_record_object(sub) {
acc.non_tabular_items += 1
acc.fallbacks.push({
path,
reason: SingleEntryKeyedObject,
item_count: 1,
explanation: "object has only 1 entry (< 2 minimum for TOON 4.4 keyed tabular '[N:]')",
})
}
}
}
for k, v in obj {
audit_node(v, child_path(path, k), acc)
}
}
}
}
}
///|
/// Audits a JSON document to measure tabular coverage and pinpoint exact paths
/// that fall back from TOON tabular or ยง9.5 keyed-tabular compression.
pub fn audit_structure(value : Json) -> StructuralAudit {
let acc : AuditAcc = {
tabular_items: 0,
non_tabular_items: 0,
array_tabular_blocks: 0,
keyed_tabular_blocks: 0,
fallbacks: [],
}
audit_node(value, "$", acc)
let total = acc.tabular_items + acc.non_tabular_items
let coverage = if total == 0 {
0.0
} else {
acc.tabular_items.to_double() * 100.0 / total.to_double()
}
{
tabular_items: acc.tabular_items,
non_tabular_items: acc.non_tabular_items,
array_tabular_blocks: acc.array_tabular_blocks,
keyed_tabular_blocks: acc.keyed_tabular_blocks,
tabular_coverage_pct: coverage,
fallbacks: acc.fallbacks,
}
}