feat(review): add versioned JSON comparison reports

This commit is contained in:
Jan Petykiewicz 2026-11-15 10:38:48 -08:00
commit 248f6bcff7
16 changed files with 2312 additions and 43 deletions

View file

@ -13,6 +13,7 @@ crate-type = ["cdylib", "rlib"]
[dependencies] [dependencies]
byteorder = "^1" byteorder = "^1"
arrow = {version = "^54", features = ["ffi"]} arrow = {version = "^54", features = ["ffi"]}
serde_json = "1"
[profile.release] [profile.release]

View file

@ -56,7 +56,7 @@ schema, offset definitions, and ID assignment.
## Layout review CLI ## Layout review CLI
The review CLI uses the existing Rust dependencies: The review CLI is a standalone Rust executable:
```sh ```sh
cargo build --bin klamath cargo build --bin klamath
@ -67,6 +67,8 @@ target/debug/klamath diff old.gds new.gds --hierarchy mermaid --max-changes 20
target/debug/klamath hierarchy chip.gds --format mermaid --depth 4 target/debug/klamath hierarchy chip.gds --format mermaid --depth 4
target/debug/klamath diff old.gds new.gds --top CHIP --layer 1/0 target/debug/klamath diff old.gds new.gds --top CHIP --layer 1/0
target/debug/klamath diff old.gds new.gds --show-layer 1/0 target/debug/klamath diff old.gds new.gds --show-layer 1/0
target/debug/klamath diff old.gds new.gds --format json
target/debug/klamath diff old.gds new.gds --format json --hierarchy graph
target/debug/klamath name-layers chip.gds named.gds --cell CHIP --carrier 900/7 --name 1:0:WG target/debug/klamath name-layers chip.gds named.gds --cell CHIP --carrier 900/7 --name 1:0:WG
``` ```
@ -98,6 +100,16 @@ and **2** for invalid input or incomplete comparison. `--max-changes` limits the
number of object details displayed, not the comparison. Source offsets are number of object details displayed, not the comparison. Source offsets are
included in changed-object reports for tracing changes back to record dumps. included in changed-object reports for tracing changes back to record dumps.
`diff --format json` emits a versioned report with typed before/after evidence,
structured diagnostics, and independent comparison status and completeness.
JSON includes all changes by default. Explicit display filters and `--max-changes`
record omitted evidence without changing totals or exit status. `--hierarchy graph`
adds the complete scoped reference graph, with symbolic array multiplicities;
`--depth` applies to text output only. Timestamp-only changes still return 0.
Input and argument errors also produce JSON when requested. See the
[report contract](docs/diff-reports.md) and
[version 1 JSON Schema](docs/diff-report-v1.schema.json).
Unmatched objects are paired for explanation only when candidates are unique by Unmatched objects are paired for explanation only when candidates are unique by
type/layer/bounding box, then by type/layer among the remaining objects. type/layer/bounding box, then by type/layer among the remaining objects.
References additionally match by target. Ambiguous groups stay additions and References additionally match by target. Ambiguous groups stay additions and

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"}}
}}
}
}
}
}

185
docs/diff-reports.md Normal file
View file

@ -0,0 +1,185 @@
# Machine-readable diff reports
```sh
klamath diff before.gds after.gds --format json > report.json
klamath diff before.gds after.gds --format json --hierarchy graph
klamath diff before.gds after.gds --format json --top CHIP --layer 1/0
```
The command writes one UTF-8 JSON document followed by a newline to stdout.
Comparison diagnostics belong to that document. Output write failures are
reported on stderr and return 2; interrupted output is not a valid report.
JSON output currently belongs to `diff`; `dump`, `hierarchy`, and the Git
external driver retain their existing text interfaces. No external process is
used to produce a report.
The [version 1 JSON Schema](diff-report-v1.schema.json) defines the structure.
[Golden reports](../tests/golden/report-geometry.json) illustrate complete
evidence; other `report-*.json` goldens cover equality, metadata, incomplete
comparison, and failure. Their producer version is replaced with `test` so
package version changes do not alter the fixtures.
## Versions and determinism
`schema_version` describes the report structure. `comparison_profile` names the
equality rules, currently `klamath-object-v2`. `producer.version` identifies the
implementation. These versions are independent. Consumers interpreting equality
must understand the comparison profile as well as the schema.
Compatible additions may introduce optional fields. Consumers should ignore
unfamiliar additional fields and handle unfamiliar diagnostic codes and matching
rules without treating them as equality. Removed fields or changed meanings
require a new schema version. The schema intentionally permits additional fields.
For the same inputs, paths, options, and producer version, serialization is
deterministic. Cells, layer pairs, fields, properties, and graph edges are sorted.
Duplicate objects and properties remain separate occurrences. Reports contain
no generation timestamp or required content fingerprint.
## Result and exit status
| `status` | `result` | Exit code | Interpretation |
| --- | --- | --- | --- |
| `complete` | `equal` | 0 | Equal under the recorded profile and scope. |
| `complete` | `different` | 1 | Differences found. |
| `incomplete` | `different` | 2 | Definite differences found, with comparison limitations. |
| `incomplete` | `unknown` | 2 | Equality cannot be established. |
| `failed` | `unknown` | 2 | No comparison result is available. |
Unsupported records, future metadata versions, unresolved references, and
hierarchy cycles make the comparison incomplete. Malformed input, read errors,
invalid scopes, and invalid command arguments produce failed reports. CI must
check completeness as well as differences. An exit code of 1 is a normal
comparison outcome, including when stdout is redirected to a report file.
Library and cell timestamps are excluded from the comparison profile. A valid,
complete timestamp-only comparison returns 0. Raw record dumps remain available
for examining those timestamps.
`summary` counts the entire scoped comparison, before display selection. Its
`counts` is `exact` for a complete comparison and `observed` for an incomplete
one. Failed reports have a null summary and empty change arrays. Replacement
suggestions and affected ancestors never add to change counts.
## Scope, selection, and numbers
`scope` records the actual `top`, `cell`, and numeric `layer` selectors. Null
means unrestricted. The complete file is parsed before applying scope, so an
invalid record outside the selected subtree still fails the command.
`report_selection` records display-only `cell`, `layer`, and `max_objects`.
JSON has no default object limit. Explicit `--max-changes N` limits the total
number of emitted object occurrences across both sides. Removals precede
additions within each cell. `filtered_cells`, `filtered_objects`,
`limited_objects`, and `emitted_objects` explain evidence selection. `truncated`
is true if filtering or a limit omits any changed cell or object. Library and
layer-name changes, diagnostics, summaries, and the optional graph are retained.
A replacement is emitted only when both linked objects are included.
All aggregate counts, limits, and byte offsets are unsigned decimal **strings**.
This avoids loss of precision in JSON consumers using binary64 numbers.
Coordinates, numeric tags, layer/type pairs, widths, and array dimensions are
bounded integers represented as JSON numbers. Null means absent or unavailable;
zero and empty arrays do not imply absence.
`inputs.old` and `inputs.new` contain input paths, presence, and UNITS fields.
Presence is distinct from an empty library. The Rust API also supports absent
Git revisions using `Document::empty_like`; no units are invented for absent
inputs. Failed reports may have null presence and units. Argument failures can
lack input/selection context because the command could not be parsed.
Paths are UTF-8 when representable. Otherwise `path` is null and
`path_encoded_hex` preserves Rust's platform-native encoded path bytes, prefixed
with `0x`. This is platform-dependent evidence rather than a portable path name.
## Change evidence
`library_changes` records changed header fields as typed before/after arrays.
Library presence changes use the special field `presence`, a null tag, and
boolean before/after values. Units are not rescaled to a common grid.
`layer_name_changes` records numeric pairs with before/after names. A layer
pair is `{ "number": 1, "purpose": 0 }`, where purpose is DATATYPE, TEXTTYPE,
BOXTYPE, or NODETYPE according to the object kind. `layer_legend` contains
unchanged names available in the scope. Embedded annotation labels are excluded
from ordinary object changes. A metadata rename appears once.
Each `cell_changes` entry has its name, nullable before/after cell records,
attribute evidence, removed and added objects, and replacement suggestions.
A null cell side means the cell is absent in that scope. An existing empty
cell has a byte offset and an empty attribute array.
Each object retains:
- Its kind and numeric tag, numeric layer pair, target cell, and coordinate envelope.
- Its original source side and byte range `[byte_offset, end_offset)`.
- Typed field records and the sorted property multiset, including duplicates.
- Convenience fields for text/reference origin, path/text width, and reference
array dimensions. SREF dimensions are `[1, 1]`; the kind and retained fields
distinguish an SREF from a one-element AREF and explicit fields from omission.
Coordinates are cell-local integer database units. `bounds` contains
`[xmin, ymin, xmax, ymax]` of stored coordinates. It excludes path stroke width,
rendered text dimensions, and recursively transformed target geometry.
Equal envelopes do not establish geometric equality. Unit changes must be
considered before deriving physical movements or dimensions.
A retained field has a numeric `tag`, convenience `name`, `encoding`, decoded
`value`, and `payload_hex`. The numeric tag is authoritative; names are display
aids. XY values are arrays of `[x, y]` pairs. Other numeric fields are arrays
of their declared type. Unsupported encodings retain bytes with a null value.
String and property values are null if their bytes are not valid UTF-8;
`payload_hex` always preserves them without replacement characters.
Payloads follow the comparison profile: boundary/box rings use canonical start
and winding, string padding is removed, and fields/properties are sorted. They
are comparison evidence, not a verbatim serialization of the source records.
REAL8 payload encodings are retained exactly alongside their decoded values.
Explicit defaults and omitted fields remain distinct. Source ranges allow raw
record inspection when original encoding or order is needed.
Replacement suggestions link report-local removed/added IDs, with a `match_rule`,
typed `field_changes`, and `properties_changed`. Their explanation is optional
for consumers to display and must not be parsed. Current matching rules are
`unique_kind_layer_bounds`, `unique_kind_layer`, and `unique_kind_target`.
These are explanatory matches, not persistent identity or shape equivalence.
Ambiguous candidates stay independent removals and additions. IDs are unique
within a report and have no meaning across reports.
## Diagnostics and hierarchy
Diagnostics have `code`, `severity`, `message`, input `side`, original byte
offset, cell, layer, and target context. Unknown context is null. Messages are
for display; codes and context support automation. Current limitation codes are
`unsupported_record`, `unsupported_metadata_version`, `unresolved_reference`,
`hierarchy_cycle`, and `scope_mismatch`. Failure codes are `invalid_input`,
`io_error`, `invalid_scope`, and `command_error`. Fatal parser errors currently
retain their location in the human message; their structured byte offset is
null. Consumers must not depend on message wording.
`--hierarchy graph` includes the full scoped union graph of both revisions.
Otherwise `hierarchy` is null. Nodes are keyed by cell name, with per-side
states `included`, `outside_scope`, `unresolved`, or `absent`. Their `change`
is `direct`, `affected` through a descendant, or `unchanged`.
Edges record parent, target, before/after direct placement counts, and whether
the underlying reference records changed. AREF columns times rows contribute
symbolically; arrays are never expanded. Counts are direct edge multiplicities,
not recursively accumulated placements. Shared cells occur once. Removed edges
remain visible, and ancestors are computed over the union of both revisions.
Graph content is independent of display filters and object limits. Text depth
limits and ASCII/Mermaid choices do not apply to JSON graphs.
## Development
`cargo test --test review` checks report semantics, CLI behavior, and versioned
goldens. To intentionally regenerate report goldens after reviewing a contract
change, run:
```sh
KLAMATH_UPDATE_REPORT_GOLDENS=1 cargo test --test review machine_reports_match_versioned_goldens
```
Schema validators can validate the goldens or actual CLI output against
`diff-report-v1.schema.json`. Schema validation does not replace semantic checks
such as replacement links, summary totals, or status/exit-code agreement.

View file

@ -1,3 +1,4 @@
use klamath_rs_ext::review::report::{ReportInputs, ReportOptions, failure_report};
use klamath_rs_ext::review::{ use klamath_rs_ext::review::{
Comparison, DisplayFilter, Document, Scope, dump_records, hierarchy, parse_layer, Comparison, DisplayFilter, Document, Scope, dump_records, hierarchy, parse_layer,
parse_layer_name, write_layer_names, parse_layer_name, write_layer_names,
@ -7,12 +8,13 @@ use std::{
ffi::OsString, ffi::OsString,
fs, fs,
io::{self, Write}, io::{self, Write},
path::PathBuf,
process::ExitCode, process::ExitCode,
}; };
const HELP: &str = "Usage: const HELP: &str = "Usage:
klamath dump FILE [--records] klamath dump FILE [--records]
klamath diff OLD NEW [--top NAME] [--cell NAME] [--layer L/T]\n [--show-cell NAME] [--show-layer L/T] [--hierarchy ascii|mermaid|none]\n [--max-changes N] [--depth N] klamath diff OLD NEW [--top NAME] [--cell NAME] [--layer L/T]\n [--show-cell NAME] [--show-layer L/T] [--hierarchy ascii|mermaid|none|graph]\n [--max-changes N] [--depth N] [--format text|json]
klamath hierarchy FILE [--format ascii|mermaid] [--depth N] [--top NAME]\n klamath git-diff [OPTIONS] -- PATH OLD OLD_OID OLD_MODE NEW NEW_OID NEW_MODE klamath hierarchy FILE [--format ascii|mermaid] [--depth N] [--top NAME]\n klamath git-diff [OPTIONS] -- PATH OLD OLD_OID OLD_MODE NEW NEW_OID NEW_MODE
klamath name-layers INPUT OUTPUT --cell NAME --carrier L/T --name L:T:NAME ... klamath name-layers INPUT OUTPUT --cell NAME --carrier L/T --name L:T:NAME ...
@ -85,8 +87,57 @@ fn stdout(output: &str) -> Result<(), String> {
.map_err(|e| e.to_string()) .map_err(|e| e.to_string())
} }
fn run() -> Result<u8, String> { fn json_stdout(report: &serde_json::Value) -> Result<(), String> {
let args: Vec<_> = std::env::args_os().skip(1).collect(); let mut output = io::stdout().lock();
serde_json::to_writer_pretty(&mut output, report).map_err(|e| e.to_string())?;
output.write_all(b"\n").map_err(|e| e.to_string())
}
fn json_diff(paths: &[OsString], scope: &Scope, options: &ReportOptions) -> Result<u8, String> {
let inputs = ReportInputs {
old: Some(PathBuf::from(&paths[0])),
new: Some(PathBuf::from(&paths[1])),
};
let comparison = || {
let read = |index, side| {
fs::read(&paths[index])
.map_err(|e| ("io_error", format!("{:?}: {e}", paths[index]), Some(side)))
};
let old_bytes = read(0, "old")?;
let new_bytes = read(1, "new")?;
let old = Document::parse(&old_bytes).map_err(|e| ("invalid_input", e, Some("old")))?;
let new = Document::parse(&new_bytes).map_err(|e| ("invalid_input", e, Some("new")))?;
scope
.validate_pair(&old, &new)
.map_err(|e| ("invalid_scope", e, None))?;
let old = old
.selected(scope, true)
.map_err(|e| ("invalid_scope", e, Some("old")))?;
let new = new
.selected(scope, true)
.map_err(|e| ("invalid_scope", e, Some("new")))?;
let diff = Comparison::between(&old, &new);
Ok::<_, (&str, String, Option<&str>)>((
diff.json_report(&old, &new, &inputs, options),
diff.exit_code(),
))
};
let (report, status) = match comparison() {
Ok(result) => result,
Err((code, message, side)) => (
failure_report(&inputs, scope, options, code, &message, side),
2,
),
};
if let Err(error) = json_stdout(&report) {
// Once output starts, never append a second report on a write failure.
eprintln!("klamath: {error}");
return Ok(2);
}
Ok(status)
}
fn run(args: &[OsString]) -> Result<u8, String> {
if args.is_empty() || args[0] == "--help" || args[0] == "-h" { if args.is_empty() || args[0] == "--help" || args[0] == "-h" {
stdout(HELP)?; stdout(HELP)?;
return Ok(0); return Ok(0);
@ -111,7 +162,10 @@ fn run() -> Result<u8, String> {
"ascii".to_string() "ascii".to_string()
}; };
let mut max_changes = 100; let mut max_changes = 100;
let mut explicit_max = None;
let mut output_format = "text".to_string();
let mut depth = 8; let mut depth = 8;
let mut explicit_depth = false;
let mut paths = Vec::new(); let mut paths = Vec::new();
let mut literal = false; let mut literal = false;
let mut i = 1; let mut i = 1;
@ -128,22 +182,25 @@ fn run() -> Result<u8, String> {
return Ok(0); return Ok(0);
} }
Some("--records") if command == "dump" => raw = true, Some("--records") if command == "dump" => raw = true,
Some("--top") => scope.top = Some(value(&args, &mut i)?), Some("--top") => scope.top = Some(value(args, &mut i)?),
Some("--cell") => scope.cell = Some(value(&args, &mut i)?), Some("--cell") => scope.cell = Some(value(args, &mut i)?),
Some("--layer") => scope.layer = Some(parse_layer(&value(&args, &mut i)?)?), Some("--layer") => scope.layer = Some(parse_layer(&value(args, &mut i)?)?),
Some("--show-cell") if compare => show.cell = Some(value(&args, &mut i)?), Some("--show-cell") if compare => show.cell = Some(value(args, &mut i)?),
Some("--show-layer") if compare => { Some("--show-layer") if compare => {
show.layer = Some(parse_layer(&value(&args, &mut i)?)?) show.layer = Some(parse_layer(&value(args, &mut i)?)?)
} }
Some("--hierarchy") if compare => format = value(&args, &mut i)?, Some("--hierarchy") if compare => format = value(args, &mut i)?,
Some("--format") if command == "hierarchy" => format = value(&args, &mut i)?, Some("--format") if command == "hierarchy" => format = value(args, &mut i)?,
Some("--format") if command == "diff" => output_format = value(args, &mut i)?,
Some("--max-changes") if compare => { Some("--max-changes") if compare => {
max_changes = value(&args, &mut i)? max_changes = value(args, &mut i)?
.parse() .parse()
.map_err(|_| "invalid change limit")? .map_err(|_| "invalid change limit")?;
explicit_max = Some(max_changes);
} }
Some("--depth") if command != "dump" => { Some("--depth") if command != "dump" => {
depth = value(&args, &mut i)?.parse().map_err(|_| "invalid depth")? depth = value(args, &mut i)?.parse().map_err(|_| "invalid depth")?;
explicit_depth = true;
} }
Some(s) if s.starts_with('-') => return Err(format!("unknown option {s:?}")), Some(s) if s.starts_with('-') => return Err(format!("unknown option {s:?}")),
_ => paths.push(args[i].clone()), _ => paths.push(args[i].clone()),
@ -153,6 +210,25 @@ fn run() -> Result<u8, String> {
if paths.len() != expected && !(command == "git-diff" && paths.len() == 9) { if paths.len() != expected && !(command == "git-diff" && paths.len() == 9) {
return Err(HELP.to_string()); return Err(HELP.to_string());
} }
if !matches!(output_format.as_str(), "text" | "json") {
return Err("diff format must be text or json".to_string());
}
if output_format == "json" {
if !matches!(format.as_str(), "none" | "graph") || explicit_depth {
return Err(
"JSON accepts --hierarchy graph|none; --depth applies to text output".to_string(),
);
}
return json_diff(
&paths,
&scope,
&ReportOptions {
filter: show,
max_objects: explicit_max,
hierarchy: format == "graph",
},
);
}
if !matches!(format.as_str(), "ascii" | "mermaid" | "none") if !matches!(format.as_str(), "ascii" | "mermaid" | "none")
|| (command == "hierarchy" && format == "none") || (command == "hierarchy" && format == "none")
{ {
@ -248,11 +324,51 @@ fn run() -> Result<u8, String> {
}) })
} }
fn wants_json(args: &[OsString]) -> bool {
if args.first().is_none_or(|arg| arg != "diff") {
return false;
}
let mut format = None;
let mut i = 1;
while i < args.len() {
match args[i].to_str() {
Some("--") => break,
Some("--format") => {
format = args.get(i + 1).and_then(|v| v.to_str());
i += 1;
}
Some(
"--top" | "--cell" | "--layer" | "--show-cell" | "--show-layer" | "--hierarchy"
| "--max-changes" | "--depth",
) => i += 1,
_ => (),
}
i += 1;
}
format == Some("json")
}
fn main() -> ExitCode { fn main() -> ExitCode {
match run() { let args: Vec<_> = std::env::args_os().skip(1).collect();
let json = wants_json(&args);
match run(&args) {
Ok(status) => ExitCode::from(status), Ok(status) => ExitCode::from(status),
Err(message) => { Err(message) => {
eprintln!("klamath: {message}"); if json {
let report = failure_report(
&ReportInputs::default(),
&Scope::default(),
&ReportOptions::default(),
"command_error",
&message,
None,
);
if let Err(error) = json_stdout(&report) {
eprintln!("klamath: {error}");
}
} else {
eprintln!("klamath: {message}");
}
ExitCode::from(2) ExitCode::from(2)
} }
} }

View file

@ -14,6 +14,31 @@ mod selection;
pub use selection::{DisplayFilter, Scope}; pub use selection::{DisplayFilter, Scope};
mod changes; mod changes;
pub use changes::Replacement; pub use changes::Replacement;
pub mod report;
/// A comparison limitation with source context independent of its wording.
#[derive(Clone, Debug)]
pub struct Diagnostic {
pub code: &'static str,
pub message: String,
pub offset: Option<usize>,
pub cell: Option<String>,
pub layer: Option<Layer>,
pub target: Option<String>,
}
impl Diagnostic {
fn at(code: &'static str, offset: usize, message: String) -> Self {
Self {
code,
message: error(offset, message),
offset: Some(offset),
cell: None,
layer: None,
target: None,
}
}
}
pub const PROFILE: &str = "klamath-object-v2"; pub const PROFILE: &str = "klamath-object-v2";
pub const LAYER_SENTINEL: &str = "KLAMATH_LAYER_NAMES_V1"; pub const LAYER_SENTINEL: &str = "KLAMATH_LAYER_NAMES_V1";
@ -45,7 +70,7 @@ pub struct Object<'a> {
pub multiplicity: u64, pub multiplicity: u64,
key: Key<'a>, key: Key<'a>,
metadata: bool, metadata: bool,
issues: Vec<String>, issues: Vec<Diagnostic>,
} }
impl Object<'_> { impl Object<'_> {
@ -76,7 +101,7 @@ pub struct Cell<'a> {
pub end_offset: usize, pub end_offset: usize,
pub objects: Vec<Object<'a>>, pub objects: Vec<Object<'a>>,
attributes: Vec<(u16, &'a [u8])>, attributes: Vec<(u16, &'a [u8])>,
issues: Vec<String>, issues: Vec<Diagnostic>,
} }
#[derive(Debug)] #[derive(Debug)]
@ -86,8 +111,9 @@ pub struct Document<'a> {
pub layer_names: BTreeMap<Layer, String>, pub layer_names: BTreeMap<Layer, String>,
/// Unsupported features or invalid reference graphs prevent an equality claim. /// Unsupported features or invalid reference graphs prevent an equality claim.
pub issues: Vec<String>, pub issues: Vec<String>,
pub diagnostics: Vec<Diagnostic>,
header: Vec<(u16, &'a [u8])>, header: Vec<(u16, &'a [u8])>,
global_issues: Vec<String>, global_issues: Vec<Diagnostic>,
known_cells: BTreeSet<String>, known_cells: BTreeSet<String>,
pub scope: Scope, pub scope: Scope,
present: bool, present: bool,
@ -246,7 +272,7 @@ fn allowed_field(kind: u16, tag: u16) -> bool {
} }
} }
fn object<'a>(records: &[Record<'a>], issues: &mut Vec<String>) -> Result<Object<'a>, String> { fn object<'a>(records: &[Record<'a>], issues: &mut Vec<Diagnostic>) -> Result<Object<'a>, String> {
let first = &records[0]; let first = &records[0];
let mut fields = Vec::new(); let mut fields = Vec::new();
let mut properties = Vec::new(); let mut properties = Vec::new();
@ -264,7 +290,8 @@ fn object<'a>(records: &[Record<'a>], issues: &mut Vec<String>) -> Result<Object
continue; continue;
} }
if !allowed_field(first.tag, record.tag) { if !allowed_field(first.tag, record.tag) {
issues.push(error( issues.push(Diagnostic::at(
"unsupported_record",
record.offset, record.offset,
format!( format!(
"unsupported record 0x{:04x} in {}", "unsupported record 0x{:04x} in {}",
@ -424,6 +451,7 @@ impl<'a> Document<'a> {
cells: BTreeMap::new(), cells: BTreeMap::new(),
layer_names: BTreeMap::new(), layer_names: BTreeMap::new(),
issues: Vec::new(), issues: Vec::new(),
diagnostics: Vec::new(),
header: Vec::new(), header: Vec::new(),
global_issues: Vec::new(), global_issues: Vec::new(),
known_cells: BTreeSet::new(), known_cells: BTreeSet::new(),
@ -461,7 +489,8 @@ impl<'a> Document<'a> {
| RTAG_SRFNAME | RTAG_SRFNAME
| RTAG_LIBSECUR | RTAG_LIBSECUR
) { ) {
doc.global_issues.push(error( doc.global_issues.push(Diagnostic::at(
"unsupported_record",
record.offset, record.offset,
format!("unsupported library record 0x{:04x}", record.tag), format!("unsupported library record 0x{:04x}", record.tag),
)); ));
@ -534,7 +563,8 @@ impl<'a> Document<'a> {
return Err(error(record.offset, "missing ENDSTR")); return Err(error(record.offset, "missing ENDSTR"));
} }
if record.tag != RTAG_STRCLASS { if record.tag != RTAG_STRCLASS {
cell.issues.push(error( cell.issues.push(Diagnostic::at(
"unsupported_record",
record.offset, record.offset,
format!("unsupported cell record 0x{:04x}", record.tag), format!("unsupported cell record 0x{:04x}", record.tag),
)); ));
@ -571,9 +601,10 @@ impl<'a> Document<'a> {
for object in cell.objects.iter_mut().filter(|o| o.kind == RTAG_TEXT) { for object in cell.objects.iter_mut().filter(|o| o.kind == RTAG_TEXT) {
let text = object.field(RTAG_STRING).unwrap(); let text = object.field(RTAG_STRING).unwrap();
if text.starts_with(b"KLAMATH_LAYER_NAMES_") && text != LAYER_SENTINEL.as_bytes() { if text.starts_with(b"KLAMATH_LAYER_NAMES_") && text != LAYER_SENTINEL.as_bytes() {
object.issues.push(error( object.issues.push(Diagnostic::at(
"unsupported_metadata_version",
object.offset, object.offset,
"unsupported layer-name metadata version", "unsupported layer-name metadata version".to_string(),
)); ));
} }
} }
@ -613,13 +644,26 @@ impl<'a> Document<'a> {
} }
fn check_graph(&mut self) { fn check_graph(&mut self) {
let edges = self.edges(); let mut unresolved = BTreeMap::new();
for (parent, target) in edges.keys() { for (parent, cell) in &self.cells {
if !self.known_cells.contains(target) { for object in &cell.objects {
self.issues if let Some(target) = &object.target
.push(format!("cell {parent:?}: unresolved reference {target:?}")); && !self.known_cells.contains(target)
{
unresolved.entry((parent, target)).or_insert(object.offset);
}
} }
} }
for ((parent, target), offset) in unresolved {
self.diagnostics.push(Diagnostic {
code: "unresolved_reference",
message: format!("cell {parent:?}: unresolved reference {target:?}"),
offset: Some(offset),
cell: Some(parent.clone()),
layer: None,
target: Some(target.clone()),
});
}
let mut state = BTreeMap::<&str, u8>::new(); let mut state = BTreeMap::<&str, u8>::new();
for root in self.cells.keys() { for root in self.cells.keys() {
let mut stack = vec![(root.as_str(), false)]; let mut stack = vec![(root.as_str(), false)];
@ -631,8 +675,14 @@ impl<'a> Document<'a> {
match state.get(name) { match state.get(name) {
Some(2) => continue, Some(2) => continue,
Some(1) => { Some(1) => {
self.issues self.diagnostics.push(Diagnostic {
.push(format!("cyclic hierarchy involving {name:?}")); code: "hierarchy_cycle",
message: format!("cyclic hierarchy involving {name:?}"),
offset: self.cells.get(name).map(|c| c.offset),
cell: Some(name.to_string()),
layer: None,
target: None,
});
continue; continue;
} }
_ => (), _ => (),
@ -723,9 +773,28 @@ fn format_records(records: &[Record<'_>]) -> String {
out out
} }
/// A retained comparison field. Polygon coordinates and string padding follow
/// the comparison profile; REAL encodings and unsupported payloads are exact.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct FieldValue {
pub tag: u16,
pub data: Vec<u8>,
}
fn owned_fields<'a>(fields: impl IntoIterator<Item = (u16, &'a [u8])>) -> Vec<FieldValue> {
fields
.into_iter()
.map(|(tag, data)| FieldValue {
tag,
data: data.to_vec(),
})
.collect()
}
#[derive(Debug)] #[derive(Debug)]
pub struct ObjectChange { pub struct ObjectChange {
pub offset: usize, pub offset: usize,
pub end_offset: usize,
pub kind: u16, pub kind: u16,
pub layer: Option<Layer>, pub layer: Option<Layer>,
pub bounds: Option<Bounds>, pub bounds: Option<Bounds>,
@ -734,12 +803,15 @@ pub struct ObjectChange {
pub width: Option<i32>, pub width: Option<i32>,
pub counts: Option<[u16; 2]>, pub counts: Option<[u16; 2]>,
pub description: String, pub description: String,
pub fields: Vec<FieldValue>,
pub properties: Vec<(u16, Vec<u8>)>,
} }
impl From<&Object<'_>> for ObjectChange { impl From<&Object<'_>> for ObjectChange {
fn from(object: &Object<'_>) -> Self { fn from(object: &Object<'_>) -> Self {
Self { Self {
offset: object.offset, offset: object.offset,
end_offset: object.end_offset,
kind: object.kind, kind: object.kind,
layer: object.layer, layer: object.layer,
bounds: object.bounds, bounds: object.bounds,
@ -754,12 +826,27 @@ impl From<&Object<'_>> for ObjectChange {
.field(RTAG_WIDTH) .field(RTAG_WIDTH)
.map(|data| i32::from_be_bytes(data.try_into().unwrap())), .map(|data| i32::from_be_bytes(data.try_into().unwrap())),
counts: object.target.as_ref().map(|_| { counts: object.target.as_ref().map(|_| {
object if object.kind == RTAG_AREF {
.field(RTAG_COLROW) let data = object.field(RTAG_COLROW).unwrap();
.map(|data| [integer(&data[..2]), integer(&data[2..])]) [integer(&data[..2]), integer(&data[2..])]
.unwrap_or([1, 1]) } else {
[1, 1]
}
}), }),
description: object.description(), description: object.description(),
fields: owned_fields(
object
.key
.fields
.iter()
.map(|(tag, data)| (*tag, data.as_ref())),
),
properties: object
.key
.properties
.iter()
.map(|(a, v)| (*a, v.to_vec()))
.collect(),
} }
} }
} }
@ -770,6 +857,8 @@ pub struct CellChange {
pub old_offset: Option<usize>, pub old_offset: Option<usize>,
pub new_offset: Option<usize>, pub new_offset: Option<usize>,
pub attributes_changed: bool, pub attributes_changed: bool,
pub old_attributes: Vec<FieldValue>,
pub new_attributes: Vec<FieldValue>,
pub removed: Vec<ObjectChange>, pub removed: Vec<ObjectChange>,
pub added: Vec<ObjectChange>, pub added: Vec<ObjectChange>,
pub replacements: Vec<Replacement>, pub replacements: Vec<Replacement>,
@ -785,6 +874,9 @@ pub struct LayerNameChange {
#[derive(Debug)] #[derive(Debug)]
pub struct LibraryFieldChange { pub struct LibraryFieldChange {
pub field: String, pub field: String,
pub tag: Option<u16>,
pub old_fields: Vec<FieldValue>,
pub new_fields: Vec<FieldValue>,
pub old: Vec<String>, pub old: Vec<String>,
pub new: Vec<String>, pub new: Vec<String>,
} }
@ -821,6 +913,9 @@ impl Comparison {
if old.present != new.present { if old.present != new.present {
result.library_fields.push(LibraryFieldChange { result.library_fields.push(LibraryFieldChange {
field: "presence".to_string(), field: "presence".to_string(),
tag: None,
old_fields: Vec::new(),
new_fields: Vec::new(),
old: vec![if old.present { "present" } else { "absent" }.to_string()], old: vec![if old.present { "present" } else { "absent" }.to_string()],
new: vec![if new.present { "present" } else { "absent" }.to_string()], new: vec![if new.present { "present" } else { "absent" }.to_string()],
}); });
@ -852,6 +947,9 @@ impl Comparison {
if a != b { if a != b {
result.library_fields.push(LibraryFieldChange { result.library_fields.push(LibraryFieldChange {
field: tag_name(tag), field: tag_name(tag),
tag: Some(tag),
old_fields: owned_fields(a.iter().map(|data| (tag, *data))),
new_fields: owned_fields(b.iter().map(|data| (tag, *data))),
old: a.iter().map(|data| format_data(tag, data)).collect(), old: a.iter().map(|data| format_data(tag, data)).collect(),
new: b.iter().map(|data| format_data(tag, data)).collect(), new: b.iter().map(|data| format_data(tag, data)).collect(),
}); });
@ -881,6 +979,12 @@ impl Comparison {
old_offset: a.map(|c| c.offset), old_offset: a.map(|c| c.offset),
new_offset: b.map(|c| c.offset), new_offset: b.map(|c| c.offset),
attributes_changed: a.map(|c| &c.attributes) != b.map(|c| &c.attributes), attributes_changed: a.map(|c| &c.attributes) != b.map(|c| &c.attributes),
old_attributes: owned_fields(
a.into_iter().flat_map(|c| c.attributes.iter().copied()),
),
new_attributes: owned_fields(
b.into_iter().flat_map(|c| c.attributes.iter().copied()),
),
removed: Vec::new(), removed: Vec::new(),
added: Vec::new(), added: Vec::new(),
replacements: Vec::new(), replacements: Vec::new(),

View file

@ -5,6 +5,8 @@ pub struct Replacement {
pub removed: usize, pub removed: usize,
pub added: usize, pub added: usize,
pub explanation: String, pub explanation: String,
/// Explanation matching is never object identity or geometric equivalence.
pub match_rule: &'static str,
} }
type Group = (u16, Option<Layer>, Option<String>, Option<Bounds>); type Group = (u16, Option<Layer>, Option<String>, Option<Bounds>);
@ -54,6 +56,13 @@ pub(super) fn replacements(old: &[ObjectChange], new: &[ObjectChange]) -> Vec<Re
removed: i, removed: i,
added: j, added: j,
explanation: explain(&old[i], &new[j]), explanation: explain(&old[i], &new[j]),
match_rule: if old[i].target.is_some() {
"unique_kind_target"
} else if bounds {
"unique_kind_layer_bounds"
} else {
"unique_kind_layer"
},
}); });
used_old.insert(i); used_old.insert(i);
used_new.insert(j); used_new.insert(j);

385
src/review/report.rs Normal file
View file

@ -0,0 +1,385 @@
//! Versioned machine-readable diff reports. No consumer needs to parse prose.
use super::*;
use serde_json::{Value, json};
use std::path::{Path, PathBuf};
pub const SCHEMA_VERSION: u32 = 1;
#[derive(Clone, Debug, Default)]
pub struct ReportInputs {
pub old: Option<PathBuf>,
pub new: Option<PathBuf>,
}
/// Limits affect evidence only. The default includes every changed object.
#[derive(Clone, Debug, Default)]
pub struct ReportOptions {
pub filter: DisplayFilter,
pub max_objects: Option<usize>,
pub hierarchy: bool,
}
fn layer(pair: Layer) -> Value {
json!({"number": pair.0, "purpose": pair.1})
}
fn scope(value: &Scope) -> Value {
json!({"top": value.top, "cell": value.cell, "layer": value.layer.map(layer)})
}
fn input(path: Option<&Path>, doc: Option<&Document<'_>>) -> Value {
let units = doc
.filter(|d| d.present)
.and_then(|d| d.header.iter().find(|(tag, _)| *tag == RTAG_UNITS))
.map(|(tag, data)| field(*tag, data));
json!({
"path": path.and_then(Path::to_str),
"path_encoded_hex": path.filter(|p| p.to_str().is_none())
.map(|p| hex(p.as_os_str().as_encoded_bytes())),
"present": doc.map(|d| d.present),
"units": units
})
}
fn envelope(inputs: &ReportInputs, selection: &Scope, options: &ReportOptions) -> Value {
json!({
"schema_version": SCHEMA_VERSION,
"kind": "diff",
"producer": {"name": "klamath", "version": env!("CARGO_PKG_VERSION")},
"comparison_profile": PROFILE,
"inputs": {"old": input(inputs.old.as_deref(), None), "new": input(inputs.new.as_deref(), None)},
"scope": scope(selection),
"coordinates": {"unit": "database_unit", "frame": "cell_local", "bounds": "coordinate_envelope"},
"status": "failed",
"result": "unknown",
"exit_code": 2,
"summary": null,
"report_selection": {
"cell": options.filter.cell,
"layer": options.filter.layer.map(layer),
"max_objects": options.max_objects.map(|n| n.to_string()),
"truncated": false,
"filtered_cells": "0", "filtered_objects": "0", "limited_objects": "0", "emitted_objects": "0"
},
"layer_legend": [],
"library_changes": [], "layer_name_changes": [], "cell_changes": [],
"hierarchy": null,
"diagnostics": []
})
}
/// Input/selection failures still produce a valid report. Unknown locations are
/// null rather than inferred by parsing an error's human-readable message.
pub fn failure_report(
inputs: &ReportInputs,
selection: &Scope,
options: &ReportOptions,
code: &str,
message: &str,
side: Option<&str>,
) -> Value {
let mut report = envelope(inputs, selection, options);
report["diagnostics"] = json!([{
"code": code, "severity": "error", "message": message,
"side": side, "byte_offset": null, "cell": null, "layer": null, "target": null
}]);
report
}
fn field(tag: u16, data: &[u8]) -> Value {
let (encoding, value) = if tag == RTAG_XY && data.len().is_multiple_of(8) {
("xy", json!(points(data)))
} else if matches!(
tag,
RTAG_LAYER | RTAG_DATATYPE | RTAG_TEXTTYPE | RTAG_NODETYPE | RTAG_BOXTYPE
) && data.len().is_multiple_of(2)
{
(
"uint16",
json!(data.chunks_exact(2).map(integer).collect::<Vec<_>>()),
)
} else {
match tag & 0xff {
0 if data.is_empty() => ("none", Value::Null),
1 if data.len().is_multiple_of(2) => (
"bits",
json!(data.chunks_exact(2).map(integer).collect::<Vec<_>>()),
),
2 if data.len().is_multiple_of(2) => (
"int16",
json!(
data.chunks_exact(2)
.map(|v| i16::from_be_bytes(v.try_into().unwrap()))
.collect::<Vec<_>>()
),
),
3 if data.len().is_multiple_of(4) => (
"int32",
json!(
data.chunks_exact(4)
.map(|v| i32::from_be_bytes(v.try_into().unwrap()))
.collect::<Vec<_>>()
),
),
5 if data.len().is_multiple_of(8) => (
"real8",
json!(
data.chunks_exact(8)
.map(|v| decode_real8(u64::from_be_bytes(v.try_into().unwrap())))
.collect::<Vec<_>>()
),
),
6 => ("ascii", json!(std::str::from_utf8(data).ok())),
_ => ("bytes", Value::Null),
}
};
json!({"tag": tag, "name": tag_name(tag), "encoding": encoding, "value": value, "payload_hex": hex(data)})
}
fn fields(values: &[FieldValue]) -> Vec<Value> {
values.iter().map(|f| field(f.tag, &f.data)).collect()
}
fn object(value: &ObjectChange, id: &str, side: &str) -> Value {
json!({
"id": id, "kind": kind_name(value.kind), "tag": value.kind,
"source": {"side": side, "byte_offset": value.offset.to_string(), "end_offset": value.end_offset.to_string()},
"layer": value.layer.map(layer), "bounds": value.bounds, "target": value.target,
"origin": value.origin.filter(|_| matches!(value.kind, RTAG_SREF | RTAG_AREF | RTAG_TEXT)), "width": value.width, "counts": value.counts,
"fields": fields(&value.fields),
"properties": value.properties.iter().map(|(attribute, bytes)| json!({
"attribute": attribute, "value": std::str::from_utf8(bytes).ok(), "payload_hex": hex(bytes)
})).collect::<Vec<_>>()
})
}
fn field_changes(old: &ObjectChange, new: &ObjectChange) -> Vec<Value> {
let a: BTreeMap<_, _> = old.fields.iter().map(|f| (f.tag, &f.data)).collect();
let b: BTreeMap<_, _> = new.fields.iter().map(|f| (f.tag, &f.data)).collect();
a.keys()
.chain(b.keys())
.copied()
.collect::<BTreeSet<_>>()
.into_iter()
.filter(|tag| a.get(tag) != b.get(tag))
.map(|tag| {
json!({
"tag": tag,
"before": a.get(&tag).map(|data| field(tag, data)),
"after": b.get(&tag).map(|data| field(tag, data))
})
})
.collect()
}
impl Comparison {
/// Render evidence from the same documents used to construct this comparison.
/// IDs are local to this report, not persistent object identities.
pub fn json_report(
&self,
old: &Document<'_>,
new: &Document<'_>,
inputs: &ReportInputs,
options: &ReportOptions,
) -> Value {
let mut report = envelope(inputs, &self.scope, options);
report["inputs"] = json!({"old": input(inputs.old.as_deref(), Some(old)), "new": input(inputs.new.as_deref(), Some(new))});
let different = !self.cells.is_empty()
|| !self.library_fields.is_empty()
|| !self.layer_names.is_empty();
report["status"] = json!(if self.issues.is_empty() {
"complete"
} else {
"incomplete"
});
report["result"] = json!(if different {
"different"
} else if self.is_equal() {
"equal"
} else {
"unknown"
});
report["exit_code"] = json!(self.exit_code());
report["summary"] = json!({
"counts": if self.issues.is_empty() { "exact" } else { "observed" },
"changed_cells": self.cells.len().to_string(),
"removed_objects": self.cells.iter().map(|c| c.removed.len()).sum::<usize>().to_string(),
"added_objects": self.cells.iter().map(|c| c.added.len()).sum::<usize>().to_string(),
"layer_name_changes": self.layer_names.len().to_string(),
"library_field_changes": self.library_fields.len().to_string()
});
report["layer_legend"] = json!(
self.layer_legend
.iter()
.map(|(pair, name)| json!({"layer": layer(*pair), "name": name}))
.collect::<Vec<_>>()
);
report["layer_name_changes"] = json!(
self.layer_names
.iter()
.map(|c| json!({
"layer": layer(c.layer), "before": c.old, "after": c.new
}))
.collect::<Vec<_>>()
);
report["library_changes"] = json!(self.library_fields.iter().map(|c| {
if c.tag.is_none() {
json!({"field": "presence", "tag": null, "before": old.present, "after": new.present})
} else {
json!({"field": c.field, "tag": c.tag, "before": fields(&c.old_fields), "after": fields(&c.new_fields)})
}
}).collect::<Vec<_>>());
let (mut emitted, mut filtered_objects, mut limited, mut filtered_cells) =
(0_usize, 0_usize, 0_usize, 0_usize);
let mut cells = Vec::new();
for (cell_index, cell) in self.cells.iter().enumerate() {
if options
.filter
.cell
.as_ref()
.is_some_and(|name| name != &cell.name)
{
filtered_cells += 1;
filtered_objects += cell.removed.len() + cell.added.len();
continue;
}
let (mut removed, mut added) = (Vec::new(), Vec::new());
let mut shown = BTreeSet::new();
for (side, objects, output) in [
("old", &cell.removed, &mut removed),
("new", &cell.added, &mut added),
] {
for (index, change) in objects.iter().enumerate() {
if options
.filter
.layer
.is_some_and(|l| change.layer != Some(l))
{
filtered_objects += 1;
} else if options.max_objects.is_some_and(|max| emitted >= max) {
limited += 1;
} else {
let id = format!("c{cell_index}:{side}:{index}");
output.push(object(change, &id, side));
shown.insert(id);
emitted += 1;
}
}
}
let replacements: Vec<_> = cell.replacements.iter().filter_map(|r| {
let a = format!("c{cell_index}:old:{}", r.removed);
let b = format!("c{cell_index}:new:{}", r.added);
(shown.contains(&a) && shown.contains(&b)).then(|| json!({
"removed": a, "added": b, "match_rule": r.match_rule,
"explanation": r.explanation,
"field_changes": field_changes(&cell.removed[r.removed], &cell.added[r.added]),
"properties_changed": cell.removed[r.removed].properties != cell.added[r.added].properties
}))
}).collect();
cells.push(json!({
"name": cell.name,
"before": cell.old_offset.map(|offset| json!({"byte_offset": offset.to_string(), "attributes": fields(&cell.old_attributes)})),
"after": cell.new_offset.map(|offset| json!({"byte_offset": offset.to_string(), "attributes": fields(&cell.new_attributes)})),
"attributes_changed": cell.attributes_changed,
"removed": removed, "added": added, "replacements": replacements
}));
}
report["cell_changes"] = json!(cells);
report["report_selection"]["truncated"] =
json!(filtered_cells > 0 || filtered_objects > 0 || limited > 0);
for (key, count) in [
("filtered_cells", filtered_cells),
("filtered_objects", filtered_objects),
("limited_objects", limited),
("emitted_objects", emitted),
] {
report["report_selection"][key] = json!(count.to_string());
}
let mut diagnostics: Vec<_> = [("old", old), ("new", new)]
.into_iter()
.flat_map(|(side, doc)| {
doc.diagnostics.iter().map(move |d| {
json!({
"code": d.code, "severity": "error", "message": d.message, "side": side,
"byte_offset": d.offset.map(|n| n.to_string()), "cell": d.cell,
"layer": d.layer.map(layer), "target": d.target
})
})
})
.collect();
if old.scope != new.scope {
diagnostics.push(json!({"code": "scope_mismatch", "severity": "error", "message": "comparison scopes differ", "side": null, "byte_offset": null, "cell": null, "layer": null, "target": null}));
}
report["diagnostics"] = json!(diagnostics);
if options.hierarchy {
report["hierarchy"] = graph(old, new, self);
}
report
}
}
fn graph(old: &Document<'_>, new: &Document<'_>, diff: &Comparison) -> Value {
let a = old.edges();
let b = new.edges();
let edges: BTreeSet<_> = a.keys().chain(b.keys()).cloned().collect();
let names: BTreeSet<_> = old
.cells
.keys()
.chain(new.cells.keys())
.cloned()
.chain(
edges
.iter()
.flat_map(|(parent, child)| [parent.clone(), child.clone()]),
)
.collect();
let direct: BTreeSet<_> = diff.cells.iter().map(|c| c.name.clone()).collect();
let mut affected = direct.clone();
let mut parents = BTreeMap::<&str, Vec<&str>>::new();
for (parent, child) in &edges {
parents.entry(child).or_default().push(parent);
}
let mut pending: Vec<_> = direct.iter().cloned().collect();
while let Some(child) = pending.pop() {
for parent in parents.get(child.as_str()).into_iter().flatten() {
if affected.insert((*parent).to_string()) {
pending.push((*parent).to_string());
}
}
}
let changed_refs: BTreeSet<_> = diff
.cells
.iter()
.flat_map(|c| {
c.removed
.iter()
.chain(&c.added)
.filter_map(|o| o.target.as_ref().map(|t| (c.name.clone(), t.clone())))
})
.collect();
let a_targets: BTreeSet<_> = a.keys().map(|(_, t)| t.as_str()).collect();
let b_targets: BTreeSet<_> = b.keys().map(|(_, t)| t.as_str()).collect();
let state = |doc: &Document<'_>, targets: &BTreeSet<&str>, name: &String| {
if doc.cells.contains_key(name) {
"included"
} else if doc.known_cells.contains(name) {
"outside_scope"
} else if targets.contains(name.as_str()) {
"unresolved"
} else {
"absent"
}
};
json!({
"nodes": names.iter().map(|name| json!({
"cell": name, "before": state(old, &a_targets, name), "after": state(new, &b_targets, name),
"change": if direct.contains(name) { "direct" } else if affected.contains(name) { "affected" } else { "unchanged" }
})).collect::<Vec<_>>(),
"edges": edges.iter().map(|edge| json!({
"parent": edge.0, "target": edge.1,
"before_count": a.get(edge).copied().unwrap_or(0).to_string(),
"after_count": b.get(edge).copied().unwrap_or(0).to_string(),
"reference_changed": changed_refs.contains(edge)
})).collect::<Vec<_>>()
})
}

View file

@ -63,6 +63,7 @@ impl<'a> Document<'a> {
cells: BTreeMap::new(), cells: BTreeMap::new(),
layer_names: BTreeMap::new(), layer_names: BTreeMap::new(),
issues: Vec::new(), issues: Vec::new(),
diagnostics: Vec::new(),
header: self.header.clone(), header: self.header.clone(),
global_issues: Vec::new(), global_issues: Vec::new(),
known_cells: BTreeSet::new(), known_cells: BTreeSet::new(),
@ -84,17 +85,26 @@ impl<'a> Document<'a> {
} }
pub(super) fn refresh_issues(&mut self) { pub(super) fn refresh_issues(&mut self) {
self.issues = self.global_issues.clone(); self.diagnostics = self.global_issues.clone();
for (name, cell) in &self.cells { for (name, cell) in &self.cells {
for issue in cell for issue in &cell.issues {
.issues let mut issue = issue.clone();
.iter() issue.cell = Some(name.clone());
.chain(cell.objects.iter().flat_map(|o| &o.issues)) issue.message = format!("cell {name:?}: {}", issue.message);
{ self.diagnostics.push(issue);
self.issues.push(format!("cell {name:?}: {issue}")); }
for object in &cell.objects {
for issue in &object.issues {
let mut issue = issue.clone();
issue.cell = Some(name.clone());
issue.layer = object.layer;
issue.message = format!("cell {name:?}: {}", issue.message);
self.diagnostics.push(issue);
}
} }
} }
self.check_graph(); self.check_graph();
self.issues = self.diagnostics.iter().map(|d| d.message.clone()).collect();
} }
/// Project a parsed document. Missing selectors are allowed only for one /// Project a parsed document. Missing selectors are allowed only for one

View file

@ -0,0 +1,78 @@
{
"cell_changes": [],
"comparison_profile": "klamath-object-v2",
"coordinates": {
"bounds": "coordinate_envelope",
"frame": "cell_local",
"unit": "database_unit"
},
"diagnostics": [],
"exit_code": 0,
"hierarchy": null,
"inputs": {
"new": {
"path": "after.gds",
"path_encoded_hex": null,
"present": true,
"units": {
"encoding": "real8",
"name": "UNITS",
"payload_hex": "0x3f04189374bc6a7f3a044b82fa09b5a5",
"tag": 773,
"value": [
0.001,
9.999999999999999e-10
]
}
},
"old": {
"path": "before.gds",
"path_encoded_hex": null,
"present": true,
"units": {
"encoding": "real8",
"name": "UNITS",
"payload_hex": "0x3f04189374bc6a7f3a044b82fa09b5a5",
"tag": 773,
"value": [
0.001,
9.999999999999999e-10
]
}
}
},
"kind": "diff",
"layer_legend": [],
"layer_name_changes": [],
"library_changes": [],
"producer": {
"name": "klamath",
"version": "test"
},
"report_selection": {
"cell": null,
"emitted_objects": "0",
"filtered_cells": "0",
"filtered_objects": "0",
"layer": null,
"limited_objects": "0",
"max_objects": null,
"truncated": false
},
"result": "equal",
"schema_version": 1,
"scope": {
"cell": null,
"layer": null,
"top": null
},
"status": "complete",
"summary": {
"added_objects": "0",
"changed_cells": "0",
"counts": "exact",
"layer_name_changes": "0",
"library_field_changes": "0",
"removed_objects": "0"
}
}

View file

@ -0,0 +1,64 @@
{
"cell_changes": [],
"comparison_profile": "klamath-object-v2",
"coordinates": {
"bounds": "coordinate_envelope",
"frame": "cell_local",
"unit": "database_unit"
},
"diagnostics": [
{
"byte_offset": null,
"cell": null,
"code": "invalid_input",
"layer": null,
"message": "truncated record",
"severity": "error",
"side": "new",
"target": null
}
],
"exit_code": 2,
"hierarchy": null,
"inputs": {
"new": {
"path": "after.gds",
"path_encoded_hex": null,
"present": null,
"units": null
},
"old": {
"path": "before.gds",
"path_encoded_hex": null,
"present": null,
"units": null
}
},
"kind": "diff",
"layer_legend": [],
"layer_name_changes": [],
"library_changes": [],
"producer": {
"name": "klamath",
"version": "test"
},
"report_selection": {
"cell": null,
"emitted_objects": "0",
"filtered_cells": "0",
"filtered_objects": "0",
"layer": null,
"limited_objects": "0",
"max_objects": null,
"truncated": false
},
"result": "unknown",
"schema_version": 1,
"scope": {
"cell": null,
"layer": null,
"top": null
},
"status": "failed",
"summary": null
}

View file

@ -0,0 +1,360 @@
{
"cell_changes": [
{
"added": [
{
"bounds": [
0,
0,
10,
10
],
"counts": null,
"fields": [
{
"encoding": "uint16",
"name": "layer",
"payload_hex": "0x0001",
"tag": 3330,
"value": [
1
]
},
{
"encoding": "uint16",
"name": "datatype",
"payload_hex": "0x0000",
"tag": 3586,
"value": [
0
]
},
{
"encoding": "xy",
"name": "xy",
"payload_hex": "0x0000000000000000000000000000000a0000000a000000000000000000000000",
"tag": 4099,
"value": [
[
0,
0
],
[
0,
10
],
[
10,
0
],
[
0,
0
]
]
}
],
"id": "c0:new:0",
"kind": "BOUNDARY",
"layer": {
"number": 1,
"purpose": 0
},
"origin": null,
"properties": [],
"source": {
"byte_offset": "382",
"end_offset": "438",
"side": "new"
},
"tag": 2048,
"target": null,
"width": null
}
],
"after": {
"attributes": [],
"byte_offset": "346"
},
"attributes_changed": false,
"before": {
"attributes": [],
"byte_offset": "346"
},
"name": "leaf",
"removed": [
{
"bounds": [
0,
0,
10,
10
],
"counts": null,
"fields": [
{
"encoding": "uint16",
"name": "layer",
"payload_hex": "0x0001",
"tag": 3330,
"value": [
1
]
},
{
"encoding": "uint16",
"name": "datatype",
"payload_hex": "0x0000",
"tag": 3586,
"value": [
0
]
},
{
"encoding": "xy",
"name": "xy",
"payload_hex": "0x0000000000000000000000000000000a0000000a0000000a0000000a000000000000000000000000",
"tag": 4099,
"value": [
[
0,
0
],
[
0,
10
],
[
10,
10
],
[
10,
0
],
[
0,
0
]
]
}
],
"id": "c0:old:0",
"kind": "BOUNDARY",
"layer": {
"number": 1,
"purpose": 0
},
"origin": null,
"properties": [],
"source": {
"byte_offset": "382",
"end_offset": "446",
"side": "old"
},
"tag": 2048,
"target": null,
"width": null
}
],
"replacements": [
{
"added": "c0:new:0",
"explanation": "BOUNDARY modified; coordinate bounds unchanged",
"field_changes": [
{
"after": {
"encoding": "xy",
"name": "xy",
"payload_hex": "0x0000000000000000000000000000000a0000000a000000000000000000000000",
"tag": 4099,
"value": [
[
0,
0
],
[
0,
10
],
[
10,
0
],
[
0,
0
]
]
},
"before": {
"encoding": "xy",
"name": "xy",
"payload_hex": "0x0000000000000000000000000000000a0000000a0000000a0000000a000000000000000000000000",
"tag": 4099,
"value": [
[
0,
0
],
[
0,
10
],
[
10,
10
],
[
10,
0
],
[
0,
0
]
]
},
"tag": 4099
}
],
"match_rule": "unique_kind_layer_bounds",
"properties_changed": false,
"removed": "c0:old:0"
}
]
}
],
"comparison_profile": "klamath-object-v2",
"coordinates": {
"bounds": "coordinate_envelope",
"frame": "cell_local",
"unit": "database_unit"
},
"diagnostics": [],
"exit_code": 1,
"hierarchy": {
"edges": [
{
"after_count": "1",
"before_count": "1",
"parent": "CHIP",
"reference_changed": false,
"target": "left"
},
{
"after_count": "1",
"before_count": "1",
"parent": "CHIP",
"reference_changed": false,
"target": "right"
},
{
"after_count": "2",
"before_count": "2",
"parent": "left",
"reference_changed": false,
"target": "leaf"
},
{
"after_count": "3",
"before_count": "3",
"parent": "right",
"reference_changed": false,
"target": "leaf"
}
],
"nodes": [
{
"after": "included",
"before": "included",
"cell": "CHIP",
"change": "affected"
},
{
"after": "included",
"before": "included",
"cell": "leaf",
"change": "direct"
},
{
"after": "included",
"before": "included",
"cell": "left",
"change": "affected"
},
{
"after": "included",
"before": "included",
"cell": "right",
"change": "affected"
}
]
},
"inputs": {
"new": {
"path": "after.gds",
"path_encoded_hex": null,
"present": true,
"units": {
"encoding": "real8",
"name": "UNITS",
"payload_hex": "0x3f04189374bc6a7f3a044b82fa09b5a5",
"tag": 773,
"value": [
0.001,
9.999999999999999e-10
]
}
},
"old": {
"path": "before.gds",
"path_encoded_hex": null,
"present": true,
"units": {
"encoding": "real8",
"name": "UNITS",
"payload_hex": "0x3f04189374bc6a7f3a044b82fa09b5a5",
"tag": 773,
"value": [
0.001,
9.999999999999999e-10
]
}
}
},
"kind": "diff",
"layer_legend": [],
"layer_name_changes": [],
"library_changes": [],
"producer": {
"name": "klamath",
"version": "test"
},
"report_selection": {
"cell": null,
"emitted_objects": "2",
"filtered_cells": "0",
"filtered_objects": "0",
"layer": null,
"limited_objects": "0",
"max_objects": null,
"truncated": false
},
"result": "different",
"schema_version": 1,
"scope": {
"cell": null,
"layer": null,
"top": null
},
"status": "complete",
"summary": {
"added_objects": "1",
"changed_cells": "1",
"counts": "exact",
"layer_name_changes": "0",
"library_field_changes": "0",
"removed_objects": "1"
}
}

View file

@ -0,0 +1,105 @@
{
"cell_changes": [],
"comparison_profile": "klamath-object-v2",
"coordinates": {
"bounds": "coordinate_envelope",
"frame": "cell_local",
"unit": "database_unit"
},
"diagnostics": [
{
"byte_offset": "158",
"cell": "CHIP",
"code": "unsupported_record",
"layer": {
"number": 1,
"purpose": 0
},
"message": "cell \"CHIP\": at byte 158: unsupported record 0x7f02 in BOUNDARY",
"severity": "error",
"side": "old",
"target": null
},
{
"byte_offset": "158",
"cell": "CHIP",
"code": "unsupported_record",
"layer": {
"number": 1,
"purpose": 0
},
"message": "cell \"CHIP\": at byte 158: unsupported record 0x7f02 in BOUNDARY",
"severity": "error",
"side": "new",
"target": null
}
],
"exit_code": 2,
"hierarchy": null,
"inputs": {
"new": {
"path": "after.gds",
"path_encoded_hex": null,
"present": true,
"units": {
"encoding": "real8",
"name": "UNITS",
"payload_hex": "0x3f04189374bc6a7f3a044b82fa09b5a5",
"tag": 773,
"value": [
0.001,
9.999999999999999e-10
]
}
},
"old": {
"path": "before.gds",
"path_encoded_hex": null,
"present": true,
"units": {
"encoding": "real8",
"name": "UNITS",
"payload_hex": "0x3f04189374bc6a7f3a044b82fa09b5a5",
"tag": 773,
"value": [
0.001,
9.999999999999999e-10
]
}
}
},
"kind": "diff",
"layer_legend": [],
"layer_name_changes": [],
"library_changes": [],
"producer": {
"name": "klamath",
"version": "test"
},
"report_selection": {
"cell": null,
"emitted_objects": "0",
"filtered_cells": "0",
"filtered_objects": "0",
"layer": null,
"limited_objects": "0",
"max_objects": null,
"truncated": false
},
"result": "unknown",
"schema_version": 1,
"scope": {
"cell": null,
"layer": null,
"top": null
},
"status": "incomplete",
"summary": {
"added_objects": "0",
"changed_cells": "0",
"counts": "observed",
"layer_name_changes": "0",
"library_field_changes": "0",
"removed_objects": "0"
}
}

View file

@ -0,0 +1,87 @@
{
"cell_changes": [],
"comparison_profile": "klamath-object-v2",
"coordinates": {
"bounds": "coordinate_envelope",
"frame": "cell_local",
"unit": "database_unit"
},
"diagnostics": [],
"exit_code": 1,
"hierarchy": null,
"inputs": {
"new": {
"path": "after.gds",
"path_encoded_hex": null,
"present": true,
"units": {
"encoding": "real8",
"name": "UNITS",
"payload_hex": "0x3f04189374bc6a7f3a044b82fa09b5a5",
"tag": 773,
"value": [
0.001,
9.999999999999999e-10
]
}
},
"old": {
"path": "before.gds",
"path_encoded_hex": null,
"present": true,
"units": {
"encoding": "real8",
"name": "UNITS",
"payload_hex": "0x3f04189374bc6a7f3a044b82fa09b5a5",
"tag": 773,
"value": [
0.001,
9.999999999999999e-10
]
}
}
},
"kind": "diff",
"layer_legend": [],
"layer_name_changes": [
{
"after": "CORE:WG",
"before": "WG",
"layer": {
"number": 1,
"purpose": 0
}
}
],
"library_changes": [],
"producer": {
"name": "klamath",
"version": "test"
},
"report_selection": {
"cell": null,
"emitted_objects": "0",
"filtered_cells": "0",
"filtered_objects": "0",
"layer": null,
"limited_objects": "0",
"max_objects": null,
"truncated": false
},
"result": "different",
"schema_version": 1,
"scope": {
"cell": null,
"layer": null,
"top": null
},
"status": "complete",
"summary": {
"added_objects": "0",
"changed_cells": "0",
"counts": "exact",
"layer_name_changes": "1",
"library_field_changes": "0",
"removed_objects": "0"
}
}

View file

@ -1,4 +1,6 @@
mod common; mod common;
#[path = "review/reports.rs"]
mod reports;
use common::{library_header, record}; use common::{library_header, record};
use klamath_rs_ext::{ use klamath_rs_ext::{

545
tests/review/reports.rs Normal file
View file

@ -0,0 +1,545 @@
use super::*;
use klamath_rs_ext::review::{
DisplayFilter, Scope,
report::{ReportInputs, ReportOptions, failure_report},
};
use serde_json::{Value, json};
fn inputs() -> ReportInputs {
ReportInputs {
old: Some("before.gds".into()),
new: Some("after.gds".into()),
}
}
fn report(old: &[u8], new: &[u8], options: &ReportOptions) -> Value {
let a = Document::parse(old).unwrap();
let b = Document::parse(new).unwrap();
Comparison::between(&a, &b).json_report(&a, &b, &inputs(), options)
}
fn unknown(geometry: Vec<u8>) -> Vec<u8> {
let mut object = geometry;
object.truncate(object.len() - 4);
record(&mut object, 0x7f02, &[0, 42]);
record(&mut object, RTAG_ENDEL, &[]);
layout(&[("CHIP", vec![object])])
}
#[test]
fn reports_preserve_fixture_results_totals_and_replacement_links() {
for pair in corpus() {
let r = report(&pair.old, &pair.new, &ReportOptions::default());
assert_eq!(r["schema_version"], 1);
assert_eq!(r["comparison_profile"], "klamath-object-v2");
assert_eq!(r["producer"]["version"], env!("CARGO_PKG_VERSION"));
assert_eq!(r["status"], "complete", "{}", pair.name);
assert_eq!(
r["exit_code"],
if pair.changed_cells + pair.metadata == 0 {
0
} else {
1
}
);
assert_eq!(
r["summary"]["changed_cells"],
pair.changed_cells.to_string()
);
assert_eq!(r["summary"]["added_objects"], pair.added.to_string());
assert_eq!(r["summary"]["removed_objects"], pair.removed.to_string());
assert_eq!(
r["summary"]["layer_name_changes"],
pair.metadata.to_string()
);
assert_eq!(r["report_selection"]["truncated"], false);
for cell in r["cell_changes"].as_array().unwrap() {
for replacement in cell["replacements"].as_array().unwrap() {
assert!(
cell["removed"]
.as_array()
.unwrap()
.iter()
.any(|o| o["id"] == replacement["removed"])
);
assert!(
cell["added"]
.as_array()
.unwrap()
.iter()
.any(|o| o["id"] == replacement["added"])
);
}
}
assert_eq!(r, report(&pair.old, &pair.new, &ReportOptions::default()));
}
}
#[test]
fn incomplete_reports_distinguish_known_differences_and_include_structured_locations() {
let a = unknown(square());
let same = report(&a, &a, &ReportOptions::default());
assert_eq!(same["status"], "incomplete");
assert_eq!(same["result"], "unknown");
assert_eq!(same["exit_code"], 2);
assert_eq!(same["summary"]["counts"], "observed");
let diagnostic = &same["diagnostics"][0];
assert_eq!(diagnostic["code"], "unsupported_record");
assert_eq!(diagnostic["side"], "old");
assert_eq!(diagnostic["cell"], "CHIP");
assert_eq!(diagnostic["layer"], json!({"number":1,"purpose":0}));
let offset: usize = diagnostic["byte_offset"].as_str().unwrap().parse().unwrap();
assert_eq!(&a[offset + 2..offset + 4], &0x7f02_u16.to_be_bytes());
let changed = report(&a, &unknown(triangle()), &ReportOptions::default());
assert_eq!(changed["status"], "incomplete");
assert_eq!(changed["result"], "different");
assert_eq!(changed["exit_code"], 2);
assert_eq!(
changed["cell_changes"][0]["removed"][0]["fields"]
.as_array()
.unwrap()
.last()
.unwrap()["payload_hex"],
"0x002a"
);
}
#[test]
fn json_is_unbounded_by_default_and_explicit_filters_do_not_change_totals() {
let a = layout(&[("CHIP", vec![])]);
let b = layout(&[("CHIP", vec![square(); 120])]);
let full = report(&a, &b, &ReportOptions::default());
assert_eq!(
full["cell_changes"][0]["added"].as_array().unwrap().len(),
120
);
let limited = report(
&a,
&b,
&ReportOptions {
max_objects: Some(1),
..Default::default()
},
);
assert_eq!(limited["summary"], full["summary"]);
assert_eq!(limited["exit_code"], 1);
assert_eq!(limited["report_selection"]["truncated"], true);
assert_eq!(limited["report_selection"]["limited_objects"], "119");
assert_eq!(limited["report_selection"]["emitted_objects"], "1");
let filtered = report(
&a,
&b,
&ReportOptions {
filter: DisplayFilter {
cell: Some("absent".into()),
layer: None,
},
..Default::default()
},
);
assert_eq!(filtered["summary"], full["summary"]);
assert_eq!(filtered["cell_changes"], json!([]));
assert_eq!(filtered["report_selection"]["filtered_cells"], "1");
assert_eq!(filtered["report_selection"]["filtered_objects"], "120");
let filtered = report(
&a,
&b,
&ReportOptions {
filter: DisplayFilter {
cell: None,
layer: Some((2, 0)),
},
..Default::default()
},
);
assert_eq!(filtered["summary"], full["summary"]);
assert_eq!(filtered["report_selection"]["filtered_objects"], "120");
assert_eq!(filtered["cell_changes"][0]["added"], json!([]));
}
#[test]
fn typed_evidence_preserves_defaults_properties_bytes_and_real_encodings() {
let mut a = reference("leaf", 0, 1);
a.truncate(a.len() - 4);
record(&mut a, RTAG_MAG, &0x4110000000000000_u64.to_be_bytes());
record(&mut a, RTAG_PROPATTR, &17_u16.to_be_bytes());
record(&mut a, RTAG_PROPVALUE, &[0xff, 0xfe]);
record(&mut a, RTAG_PROPATTR, &17_u16.to_be_bytes());
record(&mut a, RTAG_PROPVALUE, &[0xff, 0xfe]);
record(&mut a, RTAG_ENDEL, &[]);
let mut b = a.clone();
let mag = Document::parse(&layout(&[("CHIP", vec![a.clone()]), ("leaf", vec![])]))
.unwrap()
.records
.into_iter()
.find(|r| r.tag == RTAG_MAG)
.unwrap()
.offset;
// Replace the REAL8 payload within the object, retaining the same decoded value.
let within = a
.windows(8)
.position(|v| v == 0x4110000000000000_u64.to_be_bytes())
.unwrap();
b[within..within + 8].copy_from_slice(&0x4201000000000000_u64.to_be_bytes());
let a = layout(&[("CHIP", vec![a]), ("leaf", vec![])]);
let b = layout(&[("CHIP", vec![b]), ("leaf", vec![])]);
let r = report(&a, &b, &ReportOptions::default());
let replacement = &r["cell_changes"][0]["replacements"][0];
assert_eq!(replacement["match_rule"], "unique_kind_target");
let change = &replacement["field_changes"][0];
assert_eq!(change["tag"], RTAG_MAG);
assert_eq!(change["before"]["value"], change["after"]["value"]);
assert_ne!(
change["before"]["payload_hex"],
change["after"]["payload_hex"]
);
let removed = &r["cell_changes"][0]["removed"][0];
assert_eq!(removed["properties"].as_array().unwrap().len(), 2);
assert_eq!(removed["properties"][0]["attribute"], 17);
assert_eq!(removed["properties"][0]["value"], Value::Null);
assert_eq!(removed["properties"][0]["payload_hex"], "0xfffe");
let offset: usize = removed["source"]["byte_offset"]
.as_str()
.unwrap()
.parse()
.unwrap();
assert!(offset < mag);
let end: usize = removed["source"]["end_offset"]
.as_str()
.unwrap()
.parse()
.unwrap();
assert_eq!(&a[end - 4..end], &[0, 4, 17, 0]);
let mut path = square();
path[2..4].copy_from_slice(&RTAG_PATH.to_be_bytes());
let mut width = path.clone();
width.truncate(width.len() - 4);
record(&mut width, RTAG_WIDTH, &0_i32.to_be_bytes());
record(&mut width, RTAG_ENDEL, &[]);
let r = report(
&layout(&[("CHIP", vec![path])]),
&layout(&[("CHIP", vec![width])]),
&ReportOptions::default(),
);
let change = &r["cell_changes"][0]["replacements"][0]["field_changes"][0];
assert_eq!(change["tag"], RTAG_WIDTH);
assert_eq!(change["before"], Value::Null);
assert_eq!(change["after"]["value"], json!([0]));
}
#[test]
fn hierarchy_reports_shared_ancestors_and_symbolic_arrays() {
let options = ReportOptions {
hierarchy: true,
..Default::default()
};
let r = report(&shared(square()), &shared(triangle()), &options);
let graph = &r["hierarchy"];
assert_eq!(graph["nodes"].as_array().unwrap().len(), 4);
assert_eq!(
graph["nodes"]
.as_array()
.unwrap()
.iter()
.find(|n| n["cell"] == "CHIP")
.unwrap()["change"],
"affected"
);
assert_eq!(
graph["nodes"]
.as_array()
.unwrap()
.iter()
.find(|n| n["cell"] == "leaf")
.unwrap()["change"],
"direct"
);
let edge = graph["edges"]
.as_array()
.unwrap()
.iter()
.find(|e| e["parent"] == "right")
.unwrap();
assert_eq!(edge["before_count"], "3");
assert_eq!(edge["reference_changed"], false);
let bytes = shared(square());
let scope = Scope {
cell: Some("CHIP".into()),
..Default::default()
};
let doc = Document::parse(&bytes)
.unwrap()
.selected(&scope, false)
.unwrap();
let r = Comparison::between(&doc, &doc).json_report(&doc, &doc, &inputs(), &options);
assert_eq!(r["scope"]["cell"], "CHIP");
assert_eq!(
r["hierarchy"]["nodes"]
.as_array()
.unwrap()
.iter()
.find(|n| n["cell"] == "left")
.unwrap()["after"],
"outside_scope"
);
let dangling = layout(&[("CHIP", vec![reference("missing", 0, 1)])]);
let r = report(&dangling, &dangling, &options);
assert_eq!(r["diagnostics"][0]["code"], "unresolved_reference");
assert_eq!(r["diagnostics"][0]["target"], "missing");
assert_eq!(r["hierarchy"]["nodes"][1]["after"], "unresolved");
let cycle = layout(&[("CHIP", vec![reference("CHIP", 0, 1)])]);
assert_eq!(
report(&cycle, &cycle, &options)["diagnostics"][0]["code"],
"hierarchy_cycle"
);
}
#[test]
fn library_attributes_empty_cells_units_and_absence_are_explicit() {
let a = layout(&[]);
let b = layout(&[("empty", vec![])]);
let r = report(&a, &b, &ReportOptions::default());
assert_eq!(r["cell_changes"][0]["before"], Value::Null);
assert_eq!(r["cell_changes"][0]["after"]["attributes"], json!([]));
let mut b = b;
let end = Document::parse(&b).unwrap().cells["empty"].end_offset;
let mut attribute = Vec::new();
record(&mut attribute, RTAG_STRCLASS, &[0, 1]);
b.splice(end..end, attribute);
let r = report(&layout(&[("empty", vec![])]), &b, &ReportOptions::default());
assert_eq!(
r["cell_changes"][0]["after"]["attributes"][0]["value"],
json!([1])
);
assert_eq!(r["inputs"]["old"]["units"]["encoding"], "real8");
let doc = Document::parse(&a).unwrap();
let absent = doc.empty_like();
let r = Comparison::between(&absent, &doc).json_report(
&absent,
&doc,
&inputs(),
&ReportOptions::default(),
);
assert_eq!(r["inputs"]["old"]["present"], false);
assert_eq!(r["inputs"]["old"]["units"], Value::Null);
assert_eq!(
r["library_changes"],
json!([{"field":"presence","tag":null,"before":false,"after":true}])
);
let mut b = a.clone();
let units = doc
.records
.iter()
.find(|r| r.tag == RTAG_UNITS)
.unwrap()
.offset;
b[units + 12..units + 20].copy_from_slice(
&klamath_rs_ext::basic::encode_real8(2e-9)
.unwrap()
.to_be_bytes(),
);
let r = report(&a, &b, &ReportOptions::default());
assert_eq!(r["library_changes"][0]["tag"], RTAG_UNITS);
assert_ne!(r["inputs"]["old"]["units"], r["inputs"]["new"]["units"]);
}
#[test]
fn reports_keep_extreme_coordinates_unsigned_layers_and_timestamp_equality() {
let a = layout(&[("quoted\"\\\n日本", vec![])]);
let mut shape = polygon(&[
[i32::MIN, i32::MIN],
[i32::MAX, i32::MIN],
[i32::MAX, i32::MAX],
[i32::MIN, i32::MAX],
[i32::MIN, i32::MIN],
]);
shape[8..10].copy_from_slice(&u16::MAX.to_be_bytes());
let b = layout(&[("quoted\"\\\n日本", vec![shape])]);
let r = report(&a, &b, &ReportOptions::default());
let object = &r["cell_changes"][0]["added"][0];
assert_eq!(object["layer"]["number"], u16::MAX);
assert_eq!(
object["bounds"],
json!([i32::MIN, i32::MIN, i32::MAX, i32::MAX])
);
let encoded = serde_json::to_string(&r).unwrap();
assert_eq!(serde_json::from_str::<Value>(&encoded).unwrap(), r);
let mut times = b.clone();
let doc = Document::parse(&b).unwrap();
for record in doc
.records
.iter()
.filter(|r| matches!(r.tag, RTAG_BGNLIB | RTAG_BGNSTR))
{
times[record.offset + 4..record.offset + 28].fill(1);
}
let r = report(&b, &times, &ReportOptions::default());
assert_eq!(r["result"], "equal");
assert_eq!(r["exit_code"], 0);
}
#[cfg(unix)]
#[test]
fn cli_preserves_non_utf8_path_bytes_and_literal_option_names() {
use std::os::unix::ffi::OsStringExt;
let directory = std::env::temp_dir().join(format!("klamath json paths {}", std::process::id()));
fs::create_dir_all(&directory).unwrap();
struct Cleanup(PathBuf);
impl Drop for Cleanup {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.0);
}
}
let _cleanup = Cleanup(directory.clone());
let path = directory.join(std::ffi::OsString::from_vec(b"file\xff.gds".to_vec()));
fs::write(&path, layout(&[])).unwrap();
let output = Command::new(env!("CARGO_BIN_EXE_klamath"))
.arg("diff")
.args(["--format", "json", "--"])
.arg(&path)
.arg(&path)
.output()
.unwrap();
assert_eq!(output.status.code(), Some(0));
let r: Value = serde_json::from_slice(&output.stdout).unwrap();
assert_eq!(r["inputs"]["old"]["path"], Value::Null);
let expected = "0x".to_string()
+ &path
.as_os_str()
.as_encoded_bytes()
.iter()
.map(|b| format!("{b:02x}"))
.collect::<String>();
assert_eq!(r["inputs"]["old"]["path_encoded_hex"], expected);
for name in ["--format", "json"] {
fs::write(directory.join(name), layout(&[])).unwrap();
}
let output = Command::new(env!("CARGO_BIN_EXE_klamath"))
.current_dir(&directory)
.args(["diff", "--", "--format", "json"])
.output()
.unwrap();
assert_eq!(output.status.code(), Some(0));
assert!(
String::from_utf8(output.stdout)
.unwrap()
.starts_with("profile ")
);
}
#[test]
fn machine_reports_match_versioned_goldens() {
let options = ReportOptions {
hierarchy: true,
..Default::default()
};
let equal = layout(&[("CHIP", vec![square()])]);
let metadata = corpus()
.into_iter()
.find(|p| p.name == "layer name only")
.unwrap();
let samples = [
("equal", report(&equal, &equal, &ReportOptions::default())),
(
"geometry",
report(&shared(square()), &shared(triangle()), &options),
),
(
"metadata",
report(&metadata.old, &metadata.new, &ReportOptions::default()),
),
(
"incomplete",
report(
&unknown(square()),
&unknown(square()),
&ReportOptions::default(),
),
),
(
"failed",
failure_report(
&inputs(),
&Scope::default(),
&ReportOptions::default(),
"invalid_input",
"truncated record",
Some("new"),
),
),
];
for (name, mut actual) in samples {
actual["producer"]["version"] = json!("test");
let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.join(format!("tests/golden/report-{name}.json"));
if std::env::var_os("KLAMATH_UPDATE_REPORT_GOLDENS").is_some() {
fs::write(&path, serde_json::to_string_pretty(&actual).unwrap() + "\n").unwrap();
}
let expected: Value = serde_json::from_slice(&fs::read(&path).unwrap()).unwrap();
assert_eq!(actual, expected, "{name}");
}
}
#[test]
fn cli_emits_json_for_success_input_errors_scope_errors_and_argument_errors() {
let directory = std::env::temp_dir().join(format!("klamath json {}", std::process::id()));
fs::create_dir_all(&directory).unwrap();
struct Cleanup(PathBuf);
impl Drop for Cleanup {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.0);
}
}
let _cleanup = Cleanup(directory.clone());
let a = directory.join("before file.gds");
let b = directory.join("after file.gds");
fs::write(&a, shared(square())).unwrap();
fs::write(&b, shared(triangle())).unwrap();
let command = |extra: &[&str]| {
let output = Command::new(env!("CARGO_BIN_EXE_klamath"))
.arg("diff")
.arg(&a)
.arg(&b)
.args(["--format", "json"])
.args(extra)
.output()
.unwrap();
assert!(output.stderr.is_empty(), "{:?}", output.stderr);
let report: Value = serde_json::from_slice(&output.stdout).unwrap();
assert_eq!(
output.status.code().unwrap(),
report["exit_code"].as_i64().unwrap() as i32
);
report
};
let full = command(&["--hierarchy", "graph"]);
assert_eq!(full["result"], "different");
assert!(full["hierarchy"].is_object());
let limited = command(&["--max-changes", "0"]);
assert_eq!(limited["summary"], full["summary"]);
assert_eq!(limited["report_selection"]["emitted_objects"], "0");
for extra in [
&["--top", "missing"][..],
&["--unknown"],
&["--max-changes", "x"],
&["--hierarchy", "mermaid"],
&["--depth", "3"],
] {
let failure = command(extra);
assert_eq!(failure["status"], "failed");
assert_eq!(failure["result"], "unknown");
assert_eq!(failure["summary"], Value::Null);
}
fs::write(&b, b"invalid").unwrap();
let invalid = command(&[]);
assert_eq!(invalid["diagnostics"][0]["code"], "invalid_input");
assert_eq!(invalid["diagnostics"][0]["side"], "new");
assert_eq!(invalid["inputs"]["new"]["path"], b.to_str().unwrap());
fs::remove_file(&b).unwrap();
assert_eq!(command(&[])["diagnostics"][0]["code"], "io_error");
fs::write(&b, fs::read(&a).unwrap()).unwrap();
assert_eq!(command(&[])["result"], "equal");
fs::write(&b, unknown(square())).unwrap();
assert_eq!(command(&[])["status"], "incomplete");
}