feat(review): add versioned JSON comparison reports

This commit is contained in:
Jan Petykiewicz 2026-11-15 10:38:48 -08:00
commit 248f6bcff7

View file

@ -0,0 +1,206 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Klamath diff report version 1",
"description": "Object-profile comparison evidence, not a layout serialization. Unknown additional fields are permitted for compatible extensions.",
"type": "object",
"required": ["schema_version", "kind", "producer", "comparison_profile", "inputs", "scope", "coordinates", "status", "result", "exit_code", "summary", "report_selection", "layer_legend", "library_changes", "layer_name_changes", "cell_changes", "hierarchy", "diagnostics"],
"properties": {
"schema_version": {"const": 1},
"kind": {"const": "diff"},
"producer": {
"type": "object", "required": ["name", "version"],
"properties": {"name": {"const": "klamath"}, "version": {"type": "string"}}
},
"comparison_profile": {"type": "string"},
"inputs": {
"type": "object", "required": ["old", "new"],
"properties": {"old": {"$ref": "#/$defs/input"}, "new": {"$ref": "#/$defs/input"}}
},
"scope": {
"type": "object", "required": ["top", "cell", "layer"],
"properties": {"top": {"type": ["string", "null"]}, "cell": {"type": ["string", "null"]}, "layer": {"$ref": "#/$defs/nullableLayer"}}
},
"coordinates": {
"type": "object", "required": ["unit", "frame", "bounds"],
"properties": {"unit": {"const": "database_unit"}, "frame": {"const": "cell_local"}, "bounds": {"const": "coordinate_envelope"}}
},
"status": {"enum": ["complete", "incomplete", "failed"]},
"result": {"enum": ["equal", "different", "unknown"]},
"exit_code": {"enum": [0, 1, 2]},
"summary": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/summary"}]},
"report_selection": {"$ref": "#/$defs/selection"},
"layer_legend": {
"type": "array", "items": {
"type": "object", "required": ["layer", "name"],
"properties": {"layer": {"$ref": "#/$defs/layer"}, "name": {"type": "string"}}
}
},
"library_changes": {"type": "array", "items": {"$ref": "#/$defs/libraryChange"}},
"layer_name_changes": {
"type": "array", "items": {
"type": "object", "required": ["layer", "before", "after"],
"properties": {"layer": {"$ref": "#/$defs/layer"}, "before": {"type": ["string", "null"]}, "after": {"type": ["string", "null"]}}
}
},
"cell_changes": {"type": "array", "items": {"$ref": "#/$defs/cellChange"}},
"hierarchy": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/graph"}]},
"diagnostics": {"type": "array", "items": {"$ref": "#/$defs/diagnostic"}}
},
"allOf": [
{
"if": {"properties": {"status": {"const": "complete"}}},
"then": {
"properties": {"result": {"enum": ["equal", "different"]}, "summary": {"$ref": "#/$defs/summary", "properties": {"counts": {"const": "exact"}}}, "diagnostics": {"maxItems": 0}},
"if": {"properties": {"result": {"const": "equal"}}},
"then": {"properties": {"exit_code": {"const": 0}}},
"else": {"properties": {"exit_code": {"const": 1}}}
},
"else": {"properties": {"exit_code": {"const": 2}, "diagnostics": {"minItems": 1}}}
},
{
"if": {"properties": {"status": {"const": "incomplete"}}},
"then": {"properties": {"result": {"enum": ["different", "unknown"]}, "summary": {"$ref": "#/$defs/summary", "properties": {"counts": {"const": "observed"}}}}}
},
{
"if": {"properties": {"status": {"const": "failed"}}},
"then": {"properties": {"result": {"const": "unknown"}, "summary": {"type": "null"}, "library_changes": {"maxItems": 0}, "layer_name_changes": {"maxItems": 0}, "cell_changes": {"maxItems": 0}, "hierarchy": {"type": "null"}}}
}
],
"$defs": {
"decimal": {"type": "string", "pattern": "^(0|[1-9][0-9]*)$"},
"hex": {"type": "string", "pattern": "^0x([0-9a-f]{2})*$"},
"uint16": {"type": "integer", "minimum": 0, "maximum": 65535},
"int32": {"type": "integer", "minimum": -2147483648, "maximum": 2147483647},
"layer": {
"type": "object", "required": ["number", "purpose"],
"properties": {"number": {"$ref": "#/$defs/uint16"}, "purpose": {"$ref": "#/$defs/uint16"}}
},
"nullableLayer": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/layer"}]},
"point": {"type": "array", "minItems": 2, "maxItems": 2, "items": {"$ref": "#/$defs/int32"}},
"fields": {"type": "array", "items": {"$ref": "#/$defs/field"}},
"field": {
"type": "object", "required": ["tag", "name", "encoding", "value", "payload_hex"],
"properties": {
"tag": {"$ref": "#/$defs/uint16"}, "name": {"type": "string"},
"encoding": {"enum": ["xy", "uint16", "int16", "int32", "bits", "real8", "ascii", "none", "bytes"]},
"payload_hex": {"$ref": "#/$defs/hex"},
"value": {"type": ["array", "string", "null"]}
},
"allOf": [
{"if": {"properties": {"encoding": {"const": "xy"}}}, "then": {"properties": {"value": {"type": "array", "items": {"$ref": "#/$defs/point"}}}}},
{"if": {"properties": {"encoding": {"enum": ["uint16", "bits"]}}}, "then": {"properties": {"value": {"type": "array", "items": {"$ref": "#/$defs/uint16"}}}}},
{"if": {"properties": {"encoding": {"const": "int16"}}}, "then": {"properties": {"value": {"type": "array", "items": {"type": "integer", "minimum": -32768, "maximum": 32767}}}}},
{"if": {"properties": {"encoding": {"const": "int32"}}}, "then": {"properties": {"value": {"type": "array", "items": {"$ref": "#/$defs/int32"}}}}},
{"if": {"properties": {"encoding": {"const": "real8"}}}, "then": {"properties": {"value": {"type": "array", "items": {"type": ["number", "null"]}}}}},
{"if": {"properties": {"encoding": {"const": "ascii"}}}, "then": {"properties": {"value": {"type": ["string", "null"]}}}},
{"if": {"properties": {"encoding": {"enum": ["none", "bytes"]}}}, "then": {"properties": {"value": {"type": "null"}}}}
]
},
"input": {
"type": "object", "required": ["path", "path_encoded_hex", "present", "units"],
"properties": {
"path": {"type": ["string", "null"]},
"path_encoded_hex": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/hex"}]},
"present": {"type": ["boolean", "null"]},
"units": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/field"}]}
}
},
"summary": {
"type": "object", "required": ["counts", "changed_cells", "removed_objects", "added_objects", "layer_name_changes", "library_field_changes"],
"properties": {
"counts": {"enum": ["exact", "observed"]},
"changed_cells": {"$ref": "#/$defs/decimal"}, "removed_objects": {"$ref": "#/$defs/decimal"}, "added_objects": {"$ref": "#/$defs/decimal"},
"layer_name_changes": {"$ref": "#/$defs/decimal"}, "library_field_changes": {"$ref": "#/$defs/decimal"}
}
},
"selection": {
"type": "object", "required": ["cell", "layer", "max_objects", "truncated", "filtered_cells", "filtered_objects", "limited_objects", "emitted_objects"],
"properties": {
"cell": {"type": ["string", "null"]}, "layer": {"$ref": "#/$defs/nullableLayer"},
"max_objects": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/decimal"}]}, "truncated": {"type": "boolean"},
"filtered_cells": {"$ref": "#/$defs/decimal"}, "filtered_objects": {"$ref": "#/$defs/decimal"},
"limited_objects": {"$ref": "#/$defs/decimal"}, "emitted_objects": {"$ref": "#/$defs/decimal"}
}
},
"libraryChange": {
"oneOf": [
{
"type": "object", "required": ["field", "tag", "before", "after"],
"properties": {"field": {"const": "presence"}, "tag": {"type": "null"}, "before": {"type": "boolean"}, "after": {"type": "boolean"}}
},
{
"type": "object", "required": ["field", "tag", "before", "after"],
"properties": {"field": {"type": "string"}, "tag": {"$ref": "#/$defs/uint16"}, "before": {"$ref": "#/$defs/fields"}, "after": {"$ref": "#/$defs/fields"}}
}
]
},
"source": {
"type": "object", "required": ["side", "byte_offset", "end_offset"],
"properties": {"side": {"enum": ["old", "new"]}, "byte_offset": {"$ref": "#/$defs/decimal"}, "end_offset": {"$ref": "#/$defs/decimal"}}
},
"property": {
"type": "object", "required": ["attribute", "value", "payload_hex"],
"properties": {"attribute": {"$ref": "#/$defs/uint16"}, "value": {"type": ["string", "null"]}, "payload_hex": {"$ref": "#/$defs/hex"}}
},
"object": {
"type": "object", "required": ["id", "kind", "tag", "source", "layer", "bounds", "target", "origin", "width", "counts", "fields", "properties"],
"properties": {
"id": {"type": "string"}, "kind": {"type": "string"}, "tag": {"$ref": "#/$defs/uint16"}, "source": {"$ref": "#/$defs/source"},
"layer": {"$ref": "#/$defs/nullableLayer"},
"bounds": {"oneOf": [{"type": "null"}, {"type": "array", "minItems": 4, "maxItems": 4, "items": {"$ref": "#/$defs/int32"}}]},
"target": {"type": ["string", "null"]}, "origin": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/point"}]},
"width": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/int32"}]},
"counts": {"oneOf": [{"type": "null"}, {"type": "array", "minItems": 2, "maxItems": 2, "items": {"type": "integer", "minimum": 1, "maximum": 32767}}]},
"fields": {"$ref": "#/$defs/fields"}, "properties": {"type": "array", "items": {"$ref": "#/$defs/property"}}
}
},
"replacement": {
"type": "object", "required": ["removed", "added", "match_rule", "explanation", "field_changes", "properties_changed"],
"properties": {
"removed": {"type": "string"}, "added": {"type": "string"}, "match_rule": {"type": "string"}, "explanation": {"type": "string"}, "properties_changed": {"type": "boolean"},
"field_changes": {"type": "array", "items": {
"type": "object", "required": ["tag", "before", "after"],
"properties": {"tag": {"$ref": "#/$defs/uint16"}, "before": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/field"}]}, "after": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/field"}]}}
}}
}
},
"cellSide": {
"oneOf": [{"type": "null"}, {
"type": "object", "required": ["byte_offset", "attributes"],
"properties": {"byte_offset": {"$ref": "#/$defs/decimal"}, "attributes": {"$ref": "#/$defs/fields"}}
}]
},
"cellChange": {
"type": "object", "required": ["name", "before", "after", "attributes_changed", "removed", "added", "replacements"],
"properties": {
"name": {"type": "string"}, "before": {"$ref": "#/$defs/cellSide"}, "after": {"$ref": "#/$defs/cellSide"}, "attributes_changed": {"type": "boolean"},
"removed": {"type": "array", "items": {"$ref": "#/$defs/object"}}, "added": {"type": "array", "items": {"$ref": "#/$defs/object"}},
"replacements": {"type": "array", "items": {"$ref": "#/$defs/replacement"}}
}
},
"diagnostic": {
"type": "object", "required": ["code", "severity", "message", "side", "byte_offset", "cell", "layer", "target"],
"properties": {
"code": {"type": "string"}, "severity": {"const": "error"}, "message": {"type": "string"}, "side": {"enum": ["old", "new", null]},
"byte_offset": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/decimal"}]}, "cell": {"type": ["string", "null"]},
"layer": {"$ref": "#/$defs/nullableLayer"}, "target": {"type": ["string", "null"]}
}
},
"graph": {
"type": "object", "required": ["nodes", "edges"],
"properties": {
"nodes": {"type": "array", "items": {
"type": "object", "required": ["cell", "before", "after", "change"],
"properties": {
"cell": {"type": "string"}, "before": {"enum": ["included", "outside_scope", "unresolved", "absent"]}, "after": {"enum": ["included", "outside_scope", "unresolved", "absent"]},
"change": {"enum": ["direct", "affected", "unchanged"]}
}
}},
"edges": {"type": "array", "items": {
"type": "object", "required": ["parent", "target", "before_count", "after_count", "reference_changed"],
"properties": {"parent": {"type": "string"}, "target": {"type": "string"}, "before_count": {"$ref": "#/$defs/decimal"}, "after_count": {"$ref": "#/$defs/decimal"}, "reference_changed": {"type": "boolean"}}
}}
}
}
}
}