From 248f6bcff74893500dd666be6d34ca5d81c68691 Mon Sep 17 00:00:00 2001 From: Jan Petykiewicz Date: Sun, 15 Nov 2026 10:38:48 -0800 Subject: [PATCH] feat(review): add versioned JSON comparison reports --- Cargo.toml | 1 + README.md | 14 +- docs/diff-report-v1.schema.json | 206 +++++++++++ docs/diff-reports.md | 185 ++++++++++ src/bin/klamath.rs | 146 +++++++- src/review.rs | 144 +++++++- src/review/changes.rs | 9 + src/review/report.rs | 385 ++++++++++++++++++++ src/review/selection.rs | 24 +- tests/golden/report-equal.json | 78 ++++ tests/golden/report-failed.json | 64 ++++ tests/golden/report-geometry.json | 360 ++++++++++++++++++ tests/golden/report-incomplete.json | 105 ++++++ tests/golden/report-metadata.json | 87 +++++ tests/review.rs | 2 + tests/review/reports.rs | 545 ++++++++++++++++++++++++++++ 16 files changed, 2312 insertions(+), 43 deletions(-) create mode 100644 docs/diff-report-v1.schema.json create mode 100644 docs/diff-reports.md create mode 100644 src/review/report.rs create mode 100644 tests/golden/report-equal.json create mode 100644 tests/golden/report-failed.json create mode 100644 tests/golden/report-geometry.json create mode 100644 tests/golden/report-incomplete.json create mode 100644 tests/golden/report-metadata.json create mode 100644 tests/review/reports.rs diff --git a/Cargo.toml b/Cargo.toml index e201109..b08e0a5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -13,6 +13,7 @@ crate-type = ["cdylib", "rlib"] [dependencies] byteorder = "^1" arrow = {version = "^54", features = ["ffi"]} +serde_json = "1" [profile.release] diff --git a/README.md b/README.md index 2eb673a..937b41c 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ schema, offset definitions, and ID assignment. ## Layout review CLI -The review CLI uses the existing Rust dependencies: +The review CLI is a standalone Rust executable: ```sh 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 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 --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 ``` @@ -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 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 type/layer/bounding box, then by type/layer among the remaining objects. References additionally match by target. Ambiguous groups stay additions and diff --git a/docs/diff-report-v1.schema.json b/docs/diff-report-v1.schema.json new file mode 100644 index 0000000..c47d031 --- /dev/null +++ b/docs/diff-report-v1.schema.json @@ -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"}} + }} + } + } + } +} diff --git a/docs/diff-reports.md b/docs/diff-reports.md new file mode 100644 index 0000000..1557109 --- /dev/null +++ b/docs/diff-reports.md @@ -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. diff --git a/src/bin/klamath.rs b/src/bin/klamath.rs index 5dc0c21..37e0a02 100644 --- a/src/bin/klamath.rs +++ b/src/bin/klamath.rs @@ -1,3 +1,4 @@ +use klamath_rs_ext::review::report::{ReportInputs, ReportOptions, failure_report}; use klamath_rs_ext::review::{ Comparison, DisplayFilter, Document, Scope, dump_records, hierarchy, parse_layer, parse_layer_name, write_layer_names, @@ -7,12 +8,13 @@ use std::{ ffi::OsString, fs, io::{self, Write}, + path::PathBuf, process::ExitCode, }; const HELP: &str = "Usage: 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 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()) } -fn run() -> Result { - let args: Vec<_> = std::env::args_os().skip(1).collect(); +fn json_stdout(report: &serde_json::Value) -> Result<(), String> { + 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 { + 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 { if args.is_empty() || args[0] == "--help" || args[0] == "-h" { stdout(HELP)?; return Ok(0); @@ -111,7 +162,10 @@ fn run() -> Result { "ascii".to_string() }; let mut max_changes = 100; + let mut explicit_max = None; + let mut output_format = "text".to_string(); let mut depth = 8; + let mut explicit_depth = false; let mut paths = Vec::new(); let mut literal = false; let mut i = 1; @@ -128,22 +182,25 @@ fn run() -> Result { return Ok(0); } Some("--records") if command == "dump" => raw = true, - Some("--top") => scope.top = 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("--show-cell") if compare => show.cell = Some(value(&args, &mut i)?), + Some("--top") => scope.top = 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("--show-cell") if compare => show.cell = Some(value(args, &mut i)?), 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("--format") if command == "hierarchy" => 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 == "diff" => output_format = value(args, &mut i)?, Some("--max-changes") if compare => { - max_changes = value(&args, &mut i)? + max_changes = value(args, &mut i)? .parse() - .map_err(|_| "invalid change limit")? + .map_err(|_| "invalid change limit")?; + explicit_max = Some(max_changes); } 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:?}")), _ => paths.push(args[i].clone()), @@ -153,6 +210,25 @@ fn run() -> Result { if paths.len() != expected && !(command == "git-diff" && paths.len() == 9) { 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") || (command == "hierarchy" && format == "none") { @@ -248,11 +324,51 @@ fn run() -> Result { }) } +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 { - 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), 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) } } diff --git a/src/review.rs b/src/review.rs index 4ee01fd..05763b2 100644 --- a/src/review.rs +++ b/src/review.rs @@ -14,6 +14,31 @@ mod selection; pub use selection::{DisplayFilter, Scope}; mod changes; 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, + pub cell: Option, + pub layer: Option, + pub target: Option, +} + +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 LAYER_SENTINEL: &str = "KLAMATH_LAYER_NAMES_V1"; @@ -45,7 +70,7 @@ pub struct Object<'a> { pub multiplicity: u64, key: Key<'a>, metadata: bool, - issues: Vec, + issues: Vec, } impl Object<'_> { @@ -76,7 +101,7 @@ pub struct Cell<'a> { pub end_offset: usize, pub objects: Vec>, attributes: Vec<(u16, &'a [u8])>, - issues: Vec, + issues: Vec, } #[derive(Debug)] @@ -86,8 +111,9 @@ pub struct Document<'a> { pub layer_names: BTreeMap, /// Unsupported features or invalid reference graphs prevent an equality claim. pub issues: Vec, + pub diagnostics: Vec, header: Vec<(u16, &'a [u8])>, - global_issues: Vec, + global_issues: Vec, known_cells: BTreeSet, pub scope: Scope, present: bool, @@ -246,7 +272,7 @@ fn allowed_field(kind: u16, tag: u16) -> bool { } } -fn object<'a>(records: &[Record<'a>], issues: &mut Vec) -> Result, String> { +fn object<'a>(records: &[Record<'a>], issues: &mut Vec) -> Result, String> { let first = &records[0]; let mut fields = Vec::new(); let mut properties = Vec::new(); @@ -264,7 +290,8 @@ fn object<'a>(records: &[Record<'a>], issues: &mut Vec) -> Result Document<'a> { cells: BTreeMap::new(), layer_names: BTreeMap::new(), issues: Vec::new(), + diagnostics: Vec::new(), header: Vec::new(), global_issues: Vec::new(), known_cells: BTreeSet::new(), @@ -461,7 +489,8 @@ impl<'a> Document<'a> { | RTAG_SRFNAME | RTAG_LIBSECUR ) { - doc.global_issues.push(error( + doc.global_issues.push(Diagnostic::at( + "unsupported_record", record.offset, format!("unsupported library record 0x{:04x}", record.tag), )); @@ -534,7 +563,8 @@ impl<'a> Document<'a> { return Err(error(record.offset, "missing ENDSTR")); } if record.tag != RTAG_STRCLASS { - cell.issues.push(error( + cell.issues.push(Diagnostic::at( + "unsupported_record", record.offset, 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) { let text = object.field(RTAG_STRING).unwrap(); 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, - "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) { - let edges = self.edges(); - for (parent, target) in edges.keys() { - if !self.known_cells.contains(target) { - self.issues - .push(format!("cell {parent:?}: unresolved reference {target:?}")); + let mut unresolved = BTreeMap::new(); + for (parent, cell) in &self.cells { + for object in &cell.objects { + if let Some(target) = &object.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(); for root in self.cells.keys() { let mut stack = vec![(root.as_str(), false)]; @@ -631,8 +675,14 @@ impl<'a> Document<'a> { match state.get(name) { Some(2) => continue, Some(1) => { - self.issues - .push(format!("cyclic hierarchy involving {name:?}")); + self.diagnostics.push(Diagnostic { + 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; } _ => (), @@ -723,9 +773,28 @@ fn format_records(records: &[Record<'_>]) -> String { 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, +} + +fn owned_fields<'a>(fields: impl IntoIterator) -> Vec { + fields + .into_iter() + .map(|(tag, data)| FieldValue { + tag, + data: data.to_vec(), + }) + .collect() +} + #[derive(Debug)] pub struct ObjectChange { pub offset: usize, + pub end_offset: usize, pub kind: u16, pub layer: Option, pub bounds: Option, @@ -734,12 +803,15 @@ pub struct ObjectChange { pub width: Option, pub counts: Option<[u16; 2]>, pub description: String, + pub fields: Vec, + pub properties: Vec<(u16, Vec)>, } impl From<&Object<'_>> for ObjectChange { fn from(object: &Object<'_>) -> Self { Self { offset: object.offset, + end_offset: object.end_offset, kind: object.kind, layer: object.layer, bounds: object.bounds, @@ -754,12 +826,27 @@ impl From<&Object<'_>> for ObjectChange { .field(RTAG_WIDTH) .map(|data| i32::from_be_bytes(data.try_into().unwrap())), counts: object.target.as_ref().map(|_| { - object - .field(RTAG_COLROW) - .map(|data| [integer(&data[..2]), integer(&data[2..])]) - .unwrap_or([1, 1]) + if object.kind == RTAG_AREF { + let data = object.field(RTAG_COLROW).unwrap(); + [integer(&data[..2]), integer(&data[2..])] + } else { + [1, 1] + } }), 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, pub new_offset: Option, pub attributes_changed: bool, + pub old_attributes: Vec, + pub new_attributes: Vec, pub removed: Vec, pub added: Vec, pub replacements: Vec, @@ -785,6 +874,9 @@ pub struct LayerNameChange { #[derive(Debug)] pub struct LibraryFieldChange { pub field: String, + pub tag: Option, + pub old_fields: Vec, + pub new_fields: Vec, pub old: Vec, pub new: Vec, } @@ -821,6 +913,9 @@ impl Comparison { if old.present != new.present { result.library_fields.push(LibraryFieldChange { field: "presence".to_string(), + tag: None, + old_fields: Vec::new(), + new_fields: Vec::new(), old: vec![if old.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 { result.library_fields.push(LibraryFieldChange { 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(), new: b.iter().map(|data| format_data(tag, data)).collect(), }); @@ -881,6 +979,12 @@ impl Comparison { old_offset: a.map(|c| c.offset), new_offset: b.map(|c| c.offset), 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(), added: Vec::new(), replacements: Vec::new(), diff --git a/src/review/changes.rs b/src/review/changes.rs index c962766..22e202a 100644 --- a/src/review/changes.rs +++ b/src/review/changes.rs @@ -5,6 +5,8 @@ pub struct Replacement { pub removed: usize, pub added: usize, pub explanation: String, + /// Explanation matching is never object identity or geometric equivalence. + pub match_rule: &'static str, } type Group = (u16, Option, Option, Option); @@ -54,6 +56,13 @@ pub(super) fn replacements(old: &[ObjectChange], new: &[ObjectChange]) -> Vec, + pub new: Option, +} + +/// Limits affect evidence only. The default includes every changed object. +#[derive(Clone, Debug, Default)] +pub struct ReportOptions { + pub filter: DisplayFilter, + pub max_objects: Option, + 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::>()), + ) + } 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::>()), + ), + 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::>() + ), + ), + 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::>() + ), + ), + 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::>() + ), + ), + 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 { + 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::>() + }) +} + +fn field_changes(old: &ObjectChange, new: &ObjectChange) -> Vec { + 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::>() + .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::().to_string(), + "added_objects": self.cells.iter().map(|c| c.added.len()).sum::().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::>() + ); + report["layer_name_changes"] = json!( + self.layer_names + .iter() + .map(|c| json!({ + "layer": layer(c.layer), "before": c.old, "after": c.new + })) + .collect::>() + ); + 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::>()); + 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::>(), + "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::>() + }) +} diff --git a/src/review/selection.rs b/src/review/selection.rs index 42e09f2..bab79a1 100644 --- a/src/review/selection.rs +++ b/src/review/selection.rs @@ -63,6 +63,7 @@ impl<'a> Document<'a> { cells: BTreeMap::new(), layer_names: BTreeMap::new(), issues: Vec::new(), + diagnostics: Vec::new(), header: self.header.clone(), global_issues: Vec::new(), known_cells: BTreeSet::new(), @@ -84,17 +85,26 @@ impl<'a> Document<'a> { } 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 issue in cell - .issues - .iter() - .chain(cell.objects.iter().flat_map(|o| &o.issues)) - { - self.issues.push(format!("cell {name:?}: {issue}")); + for issue in &cell.issues { + let mut issue = issue.clone(); + issue.cell = Some(name.clone()); + issue.message = format!("cell {name:?}: {}", issue.message); + self.diagnostics.push(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.issues = self.diagnostics.iter().map(|d| d.message.clone()).collect(); } /// Project a parsed document. Missing selectors are allowed only for one diff --git a/tests/golden/report-equal.json b/tests/golden/report-equal.json new file mode 100644 index 0000000..cc02059 --- /dev/null +++ b/tests/golden/report-equal.json @@ -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" + } +} diff --git a/tests/golden/report-failed.json b/tests/golden/report-failed.json new file mode 100644 index 0000000..3b08309 --- /dev/null +++ b/tests/golden/report-failed.json @@ -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 +} diff --git a/tests/golden/report-geometry.json b/tests/golden/report-geometry.json new file mode 100644 index 0000000..9e03987 --- /dev/null +++ b/tests/golden/report-geometry.json @@ -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" + } +} diff --git a/tests/golden/report-incomplete.json b/tests/golden/report-incomplete.json new file mode 100644 index 0000000..8f0346b --- /dev/null +++ b/tests/golden/report-incomplete.json @@ -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" + } +} diff --git a/tests/golden/report-metadata.json b/tests/golden/report-metadata.json new file mode 100644 index 0000000..2c51187 --- /dev/null +++ b/tests/golden/report-metadata.json @@ -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" + } +} diff --git a/tests/review.rs b/tests/review.rs index 829eeb5..cebe600 100644 --- a/tests/review.rs +++ b/tests/review.rs @@ -1,4 +1,6 @@ mod common; +#[path = "review/reports.rs"] +mod reports; use common::{library_header, record}; use klamath_rs_ext::{ diff --git a/tests/review/reports.rs b/tests/review/reports.rs new file mode 100644 index 0000000..af19169 --- /dev/null +++ b/tests/review/reports.rs @@ -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) -> Vec { + 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::(&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, ×, &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::(); + 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"); +}