Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
1 changed files with 798 additions and 681 deletions
|
|
@ -1,4 +1,9 @@
|
|||
# Machine-readable diff reports
|
||||
# JSON diff reports
|
||||
|
||||
Use JSON reports to automate layout review while retaining the evidence behind
|
||||
a result. The [comparison rules](comparison.md) define equality; the
|
||||
[version 1 JSON Schema](diff-report-v1.schema.json) defines every field.
|
||||
A [complete example](../tests/golden/report-geometry.json) shows geometry changes.
|
||||
|
||||
```sh
|
||||
pheon diff before.gds after.gds --format json > report.json
|
||||
|
|
@ -6,184 +11,116 @@ pheon diff before.gds after.gds --format json --hierarchy graph
|
|||
pheon 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.
|
||||
`diff` writes one UTF-8 JSON document and a newline to stdout, including comparison
|
||||
diagnostics. Output write failures go to stderr and return 2; interrupted output
|
||||
is invalid. Other CLI commands retain text output.
|
||||
|
||||
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.
|
||||
## Check the result first
|
||||
|
||||
## Versions and determinism
|
||||
|
||||
Pheon emits schema version 1 with producer name `pheon`. This schema has not
|
||||
had a public release. The comparison profile remains `klamath-object-v2`, and
|
||||
the `KLAMATH_LAYER_NAMES_V1` GDS marker retains its existing meaning.
|
||||
|
||||
`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 |
|
||||
| `status` | `result` | Exit code | Meaning |
|
||||
| --- | --- | --- | --- |
|
||||
| `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` | `different` | 2 | Definite differences, with comparison limitations. |
|
||||
| `incomplete` | `unknown` | 2 | Equality cannot be established. |
|
||||
| `failed` | `unknown` | 2 | No comparison result is available. |
|
||||
| `failed` | `unknown` | 2 | No comparison result. |
|
||||
|
||||
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.
|
||||
A code of 1 is an expected result, including when saving a report. Unsupported
|
||||
records, future metadata, unresolved references, and cycles make a comparison
|
||||
incomplete. Malformed input, I/O errors, invalid scopes, and command errors fail.
|
||||
|
||||
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` covers the whole scoped comparison before display filters. Counts are
|
||||
`exact` for complete results and `observed` for incomplete ones. Failed reports
|
||||
have a null summary and empty change arrays. Replacement suggestions and affected
|
||||
ancestors do not add to change counts.
|
||||
|
||||
`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 and evidence selection
|
||||
|
||||
## Scope, selection, and numbers
|
||||
`scope` records `top`, `cell`, and numeric `layer` selectors; null means
|
||||
unrestricted. The full input is parsed before scope selection.
|
||||
|
||||
`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 filters and `max_objects`.
|
||||
JSON is unbounded by default. Explicit `--max-changes N` limits total emitted
|
||||
removals plus additions, with removals first within each cell. Selection counters
|
||||
`filtered_cells`, `filtered_objects`, `limited_objects`, and `emitted_objects`
|
||||
explain omissions. `truncated` is true when filtering or limits omit evidence.
|
||||
Library changes, layer-name changes, diagnostics, summaries, and the optional
|
||||
graph remain. Replacement links appear only if both objects are emitted.
|
||||
|
||||
`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.
|
||||
## Read values safely
|
||||
|
||||
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.
|
||||
Aggregate counts, limits, and byte offsets are unsigned decimal **strings** to
|
||||
avoid JSON number precision loss. Coordinates, numeric tags, layer/type pairs,
|
||||
widths, and array dimensions are bounded JSON numbers. Null means absent or
|
||||
unavailable; zero and empty arrays remain meaningful values.
|
||||
|
||||
`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.
|
||||
`inputs.old` and `inputs.new` record paths, presence, and UNITS. An absent revision
|
||||
is distinct from an empty library. The Rust API supports absent Git revisions
|
||||
with `Document::empty_like`. Failed reports may lack presence, units, or argument
|
||||
context. Non-UTF-8 paths use null `path` and `path_encoded_hex`: `0x`-prefixed
|
||||
platform-native Rust path bytes, not a portable filename encoding.
|
||||
|
||||
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.
|
||||
## Interpret changes
|
||||
|
||||
## Change evidence
|
||||
| Section | Evidence |
|
||||
| --- | --- |
|
||||
| `library_changes` | Typed before/after header fields, including unscaled UNITS. Presence changes use a null tag and boolean values. |
|
||||
| `layer_name_changes` | Before/after names for numeric pairs `{ "number": 1, "purpose": 0 }`. |
|
||||
| `layer_legend` | Unchanged names available in scope. Annotation labels do not also appear as object changes. |
|
||||
| `cell_changes` | Name, nullable before/after cell records, attributes, removed/added objects, and replacement suggestions. A null side means absent; an existing empty cell still has a byte offset. |
|
||||
|
||||
`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.
|
||||
Objects retain kind, numeric tag, layer, target, bounds, source side and half-open
|
||||
byte range, typed fields, and a sorted property multiset including duplicates.
|
||||
Convenience fields include origin, width, and reference dimensions. SREF counts
|
||||
are `[1, 1]`; kind and retained fields still distinguish a one-element AREF.
|
||||
|
||||
`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.
|
||||
Coordinates are cell-local database units. Bounds are stored-coordinate
|
||||
envelopes, excluding stroke width, rendered text, and recursive target geometry.
|
||||
Consider UNITS before deriving physical dimensions.
|
||||
|
||||
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.
|
||||
Fields contain `tag`, display `name`, `encoding`, decoded `value`, and
|
||||
`payload_hex`. Numeric tags are authoritative. XY values are lists of points;
|
||||
other numeric values are arrays. Unsupported encodings have null values and
|
||||
preserved bytes. Invalid UTF-8 strings/properties have null decoded values;
|
||||
hex preserves their bytes.
|
||||
|
||||
Each object retains:
|
||||
Evidence follows the comparison profile: boundary/box rings are canonicalized,
|
||||
string padding is removed, and fields/properties are sorted. REAL8 encodings and
|
||||
explicit defaults remain significant. Source offsets locate original records.
|
||||
|
||||
- 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.
|
||||
Replacements link report-local removed/added IDs with `match_rule`,
|
||||
`field_changes`, and `properties_changed`. Rules are `unique_kind_layer_bounds`,
|
||||
`unique_kind_layer`, or `unique_kind_target`. IDs are not persistent identities;
|
||||
ambiguous candidates stay separate. Explanation text is for display only.
|
||||
|
||||
## 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.
|
||||
Diagnostics provide `code`, `severity`, `message`, input side, byte offset, cell,
|
||||
layer, and target; unknown context is null. Use codes and context for automation.
|
||||
Fatal parser locations currently appear only in the human message, with null
|
||||
structured offsets. Do not parse 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`.
|
||||
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`.
|
||||
|
||||
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.
|
||||
`--hierarchy graph` includes the full scoped union graph; otherwise `hierarchy`
|
||||
is null. Nodes are keyed by name, with per-side states `included`, `outside_scope`,
|
||||
`unresolved`, or `absent`, and change states `direct`, `affected`, or `unchanged`.
|
||||
Edges record parent, target, before/after direct placement counts, and changed
|
||||
reference records. Array multiplicities are symbolic, not expanded or recursively
|
||||
accumulated. Shared cells occur once and removed edges remain. Display filters,
|
||||
object limits, and text depth do not trim the graph.
|
||||
|
||||
## Development
|
||||
## Versions
|
||||
|
||||
`cargo test --test review` checks report semantics, CLI behavior, and versioned
|
||||
goldens. To intentionally regenerate report goldens after reviewing a contract
|
||||
change, run:
|
||||
`schema_version` is 1, `comparison_profile` is `klamath-object-v2`, and
|
||||
`producer.name` is `pheon`. Structure, equality rules, and producer version evolve
|
||||
independently. Understand the profile before interpreting equality. Consumers
|
||||
should tolerate additional optional fields and unknown codes/rules without
|
||||
assuming equality. Removed fields or changed meanings require a schema change.
|
||||
|
||||
```sh
|
||||
PHEON_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.
|
||||
Serialization is deterministic for identical inputs, paths, options, and producer
|
||||
version. Sorted evidence retains duplicates. Reports have no generation timestamp
|
||||
or required content fingerprint. See [development](development.md) for contract
|
||||
tests and golden updates.
|
||||
|
|
|
|||
Loading…
Reference in a new issue