1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
//! Wire-AST codec: lex-core internal AST ↔ `lex_extension::WireNode`.
//!
//! This module bridges lex-core's typed AST (`Document`, `ContentItem` and
//! friends) to the wire-format types defined in the public `lex-extension`
//! crate. The codec is what lets the registry-driven resolve pass round-trip
//! handler-returned wire ASTs back into typed lex-core nodes for splicing.
//!
//! # Direction
//!
//! - [`to_wire_node`] — forward: total over the AST shapes a parsed lex
//! document can produce. Output is a [`lex_extension::WireNode`] tree.
//! - [`from_wire_node`] — reverse: fallible. Recognised `WireNode`
//! variants become lex-core [`crate::lex::ast::ContentItem`]s; unknown
//! shapes return [`FromWireError::UnsupportedKind`].
//!
//! # Lossy in places, by design
//!
//! The forward codec preserves *block structure* but drops several
//! representation-only details that the wire format does not have
//! slots for:
//!
//! - `Range::span` (byte offsets) — the wire format encodes only
//! `(line, column)`. Reverse codec reconstructs `span = 0..0` since
//! spliced content's byte offsets are advisory.
//! - **Inline-attached annotations** on inline nodes — wire
//! `WireInline` doesn't carry annotation slots.
//! - **Block-level annotations** on `Paragraph`, `Session`, `List`,
//! `Table`, etc. — none of the wire `WireNode` variants carry an
//! `annotations` field, so attached annotations are dropped in the
//! forward direction. (Standalone `ContentItem::Annotation` nodes
//! *are* round-tripped fully via `WireNode::Annotation`.) The
//! `LexIncludeHandler` mitigates this for include splicing by
//! promoting `Document.annotations` to leading root children
//! *before* the codec runs, matching the legacy
//! `prepare_splice_list` behaviour.
//! - **Document-level metadata** — `Document.title` and
//! `Document.annotations` are dropped by the codec itself. The
//! `LexIncludeHandler` re-applies the legacy `prepare_splice_list`
//! transformation in front of the codec so these surface as
//! leading children of the wire `Document`.
//! - **Marker structure** on sessions and lists — the wire format
//! stringifies the marker (`"1.1."`, `"(a)"`); the parser
//! reconstructs the typed marker on the next parse.
//! - **List-item per-item markers** — list-item markers are derived
//! from the parent list's `marker_style` plus item index in the
//! reverse direction; the original raw marker text on each item is
//! not preserved.
//! - **Verbatim multi-group bodies** — a multi-group verbatim block
//! collapses to its first group in the forward direction; the
//! additional groups are dropped. `lex.include` never returns
//! multi-group verbatims, so this loss is invisible to the current
//! codec consumer.
//! - **Table per-cell alignment** — wire tables carry one alignment
//! string for the whole table; lex-core tracks alignment per cell.
//! Forward picks the first non-`None` *body* cell's alignment
//! (header-row alignment is skipped because it is often a styling
//! artefact); reverse applies that alignment to every cell.
//! - **Tables with block-content cells** — `WireTableCell` only
//! carries inline content; lex-core's `TableCell.children` (block
//! content inside a cell, e.g. nested lists) has no slot in the
//! wire form. Rather than silently drop that content, the forward
//! codec emits a `lex.internal.unsupported.table_block_cells`
//! placeholder; the reverse codec rejects it with
//! `FromWireError::UnsupportedKind`. Future codec work that
//! introduces an escape-hatch encoding for these tables (e.g.,
//! `body_text` carrying the raw source) can lift this restriction.
//! - **`TextContent`** uses the parsed-inline path
//! ([`TextContent::inline_nodes`]) when available, producing
//! matching `WireInline` variants; otherwise emits the raw source
//! as a single `WireInline::Text`. Reverse codec re-serialises
//! through a `.lex` source-form string that the parser
//! re-interprets identically.
//!
//! Verbatim `subject` and `mode` (`Inflow` / `Fullwidth`) **are**
//! preserved end-to-end: `WireNode::Verbatim` carries dedicated
//! `subject` and `mode` fields that the forward codec populates and
//! the reverse codec applies during reconstruction.
//!
//! For the consumer that matters today (`LexIncludeHandler`), the
//! remaining losses do not change observable include output: the
//! handler's `prepare_splice_list`-equivalent normalisation covers
//! the document-level losses, table-with-block-cells surfaces as a
//! visible `UnsupportedKind` rather than silent drop, and the
//! representation-only losses (spans, marker structure, per-cell
//! alignment) re-derive identically when the spliced content is
//! re-formatted to `.lex` source.
//!
//! # Versioning
//!
//! This codec speaks `lex_extension::WIRE_VERSION = 1`. Wire-format
//! changes that bump that constant require codec updates here.
pub use FromWireError;
pub use ;
pub use ;