monochromatic_jsonc_edit/lib.rs
1//! What:
2//! `monochromatic-jsonc-edit` parses JSONC into a comment-bearing document model,
3//! edits it
4//! immutably,
5//! and emits canonical JSONC.
6//! A Rust crate is closest to a TypeScript package module:
7//! it holds private implementation
8//! files and one public API surface,
9//! and the public items are re-exported here so callers
10//! write `monochromatic_jsonc_edit::parse_jsonc` instead of reaching into modules.
11//! Why:
12//! The maintained TypeScript package `@monochromatic-dev/jsonc-edit-core-ts` treats comments
13//! as queryable data rather than discarded trivia,
14//! compares numbers by exact mathematical
15//! value while retaining unedited spelling,
16//! and keeps escaped unpaired UTF-16 surrogates.
17//! This crate carries the same supported behavior into native Rust with no dependencies and
18//! no `unsafe` block,
19//! as recorded in `doc/decision/jsonc-edit-rust-foundation.md`.
20//!
21//! In TS you'd write (pseudocode):
22//! ```ts
23//! import { parseJsonc, jsoncStringify } from '@monochromatic-dev/jsonc-edit-core-ts';
24//! ```
25
26/// What:
27/// The crate's public failure types.
28/// Why:
29/// Parse,
30/// number,
31/// address and shape failures answer different caller questions,
32/// so each has
33/// its own type.
34///
35/// In TS you'd write (pseudocode):
36/// ```ts
37/// export * from './errors';
38/// ```
39pub mod error;
40
41/// What:
42/// Decimal digit-string arithmetic for unbounded number exponents.
43/// Why:
44/// A JSON exponent may carry more digits than any machine integer holds,
45/// and this crate
46/// refuses to bound or materialize it.
47///
48/// In TS you'd write (pseudocode):
49/// ```ts
50/// // private module: decimal string addition and subtraction.
51/// ```
52mod number_scale;
53
54/// What:
55/// The exact mathematical identity of a JSON number literal.
56/// Why:
57/// `1`,
58/// `1.0` and `1e0` must compare equal while adjacent large integers stay distinct.
59///
60/// In TS you'd write (pseudocode):
61/// ```ts
62/// export { JsoncNumberIdentity } from './number';
63/// ```
64pub mod number;
65
66/// What:
67/// Document addresses used by the read and edit surface.
68/// Why:
69/// A key and an array index are different questions,
70/// and the type keeps them apart.
71///
72/// In TS you'd write (pseudocode):
73/// ```ts
74/// export type { JsoncPath } from './path';
75/// ```
76pub mod path;
77
78/// What:
79/// The parsed document model:
80/// values,
81/// members,
82/// keys,
83/// numbers and attached comments.
84/// Why:
85/// Every key and every value carries its own optional comment,
86/// which is what makes the
87/// comment surface queryable instead of merely preserved.
88///
89/// In TS you'd write (pseudocode):
90/// ```ts
91/// export type { JsoncValue } from './value';
92/// ```
93pub mod value;
94
95/// What:
96/// The byte scanner for JSONC tokens,
97/// strings,
98/// numbers and comment trivia.
99/// Why:
100/// Scanning is linear over borrowed source,
101/// with no regular expression and no recursion,
102/// so
103/// malformed input produces a positioned error instead of a stack or backtracking cost.
104///
105/// In TS you'd write (pseudocode):
106/// ```ts
107/// // private module: the scanner the parser drives.
108/// ```
109mod scan;
110
111/// What:
112/// Quoted-string conversion between JSON tokens and UTF-16 code units.
113/// Why:
114/// Escaped unpaired surrogates must survive parsing,
115/// and replacement values must be written
116/// back as legal JSON text.
117///
118/// In TS you'd write (pseudocode):
119/// ```ts
120/// export { decodeQuoted, encodeQuoted, unitsToString } from './textUnits';
121/// ```
122pub mod text_units;
123
124/// What:
125/// Comment attachment,
126/// merging and canonical rendering helpers.
127/// Why:
128/// Stacked comments merge into one normalized comment per key or value,
129/// and emission needs
130/// the same style rules the parser recorded.
131///
132/// In TS you'd write (pseudocode):
133/// ```ts
134/// export { mergeComments } from './mergeComments';
135/// ```
136mod comment_merge;
137
138/// What:
139/// The iterative,
140/// depth-bounded JSONC parser.
141/// Why:
142/// Valid 512-container documents must parse without exhausting the call stack,
143/// and a 513th
144/// opener must be rejected before deeper state exists.
145///
146/// In TS you'd write (pseudocode):
147/// ```ts
148/// export { parseJsonc } from './parse';
149/// ```
150mod parse;
151
152/// What:
153/// The canonical JSONC emitter.
154/// Why:
155/// Output is normalized rather than byte-preserving,
156/// so comments stay attached to the same
157/// key or value across an emit-and-reparse cycle.
158///
159/// In TS you'd write (pseudocode):
160/// ```ts
161/// export { emitJsoncValue } from './stringify';
162/// ```
163mod emit;
164
165/// What:
166/// Re-export the failure types at the crate root.
167/// Why:
168/// Callers name `monochromatic_jsonc_edit::JsoncParseError` in signatures without importing
169/// a module path.
170///
171/// In TS you'd write (pseudocode):
172/// ```ts
173/// export { JsoncParseError, JsoncPathNotFoundError, JsoncTypeError } from './errors';
174/// ```
175pub use error::{JsoncEditError, JsoncNumberError, JsoncParseError, JsoncPathNotFoundError, JsoncTypeError};
176/// What:
177/// Re-export the exact-number identity.
178/// Why:
179/// It appears inside the public value model,
180/// so it is part of the API surface.
181///
182/// In TS you'd write (pseudocode):
183/// ```ts
184/// export { JsoncNumberIdentity } from './number';
185/// ```
186pub use number::JsoncNumberIdentity;
187/// What:
188/// Re-export the address type and its key-path helper.
189/// Why:
190/// Read and edit calls take addresses,
191/// so callers need the type at the crate root.
192///
193/// In TS you'd write (pseudocode):
194/// ```ts
195/// export { jsoncKeyPath, type JsoncPathSegment } from './path';
196/// ```
197pub use path::{jsonc_key_path, JsoncPathSegment};
198/// What:
199/// Re-export the document model.
200/// Why:
201/// These are the types every caller holds,
202/// inspects and edits.
203///
204/// In TS you'd write (pseudocode):
205/// ```ts
206/// export type { JsoncValue, JsoncKind, JsoncEntry, JsoncKey, JsoncComment } from './value';
207/// ```
208pub use value::{JsoncComment, JsoncCommentKind, JsoncEntry, JsoncKey, JsoncKind, JsoncValue};
209
210/// What:
211/// Re-export comment merging and the parse and emit entry points.
212/// Why:
213/// These three functions are the whole document lifecycle a caller needs before the edit
214/// surface is added.
215///
216/// In TS you'd write (pseudocode):
217/// ```ts
218/// export { mergeComments, parseJsonc, emitJsoncValue } from './index';
219/// ```
220pub use comment_merge::attach as merge_comments;
221/// What:
222/// Re-export the canonical emitter.
223/// Why:
224/// Writing a document is half of the lifecycle,
225/// and callers should not name a private module.
226///
227/// In TS you'd write (pseudocode):
228/// ```ts
229/// export { emitJsoncValue } from './stringify';
230/// ```
231pub use emit::emit_jsonc_value;
232/// What:
233/// Re-export the JSONC parser entry point.
234/// Why:
235/// Parsing is the other half of the lifecycle and the only way to obtain a document value.
236///
237/// In TS you'd write (pseudocode):
238/// ```ts
239/// export { parseJsonc } from './parse';
240/// ```
241pub use parse::parse_jsonc;
242/// What:
243/// Re-export the quoted-string conversions.
244/// Why:
245/// Callers that hold a raw token or stored code units need the same decoding and encoding
246/// rules the parser and emitter use.
247///
248/// In TS you'd write (pseudocode):
249/// ```ts
250/// export { decodeQuoted, encodeQuoted, unitsToString } from './textUnits';
251/// ```
252pub use text_units::{decode_quoted, encode_quoted, units_to_string};
253
254/// What:
255/// Source positions (byte offset,
256/// line,
257/// column) for parsed values and object keys.
258/// Why:
259/// Callers that decode a document into their own types need `file:line:col` for a value they reject,
260/// and the document tree itself stays position-free so existing constructors and comparisons keep working.
261///
262/// In TS you'd write (pseudocode):
263/// ```ts
264/// export * from './span';
265/// ```
266mod span;
267/// What:
268/// Re-export the span types and the span-reporting parser entry point.
269/// Why:
270/// Positions are a parsing feature,
271/// so callers reach them from the crate root beside `parse_jsonc`.
272///
273/// In TS you'd write (pseudocode):
274/// ```ts
275/// export { parseJsoncWithSpans, jsoncPositionAt } from './span';
276/// export type { JsoncPosition, JsoncSpan, JsoncSpans, JsoncSpanned } from './span';
277/// ```
278pub use span::{JsoncPosition, JsoncSpan, JsoncSpanned, JsoncSpans, jsonc_position_at, parse_jsonc_with_spans};
279
280/// What:
281/// Parser and emitter conformance tests over the public crate interface.
282/// Why:
283/// Comment ownership,
284/// depth limits,
285/// UTF-16 escapes and exact numbers must survive a parse,
286/// emit and reparse cycle,
287/// which compilation alone cannot show.
288///
289/// In TS you'd write (pseudocode):
290/// ```ts
291/// import './parse.test';
292/// ```
293#[cfg(test)]
294mod parse_tests;
295
296/// What:
297/// Tests for the span-reporting parse entry point and the position rule.
298/// Why:
299/// Positions are only trustworthy if slicing the text between a span's offsets returns the node's own token,
300/// which compilation cannot show.
301///
302/// In TS you'd write (pseudocode):
303/// ```ts
304/// import './span.test';
305/// ```
306#[cfg(test)]
307mod span_tests;
308
309/// What:
310/// Exact-number identity tests,
311/// including an independent rational oracle.
312/// Why:
313/// Equality across spellings and rejection of malformed tokens are the crate's numeric
314/// contract,
315/// and an oracle cross-checks the normalizer rather than itself.
316///
317/// In TS you'd write (pseudocode):
318/// ```ts
319/// import './number.test';
320/// ```
321#[cfg(test)]
322mod number_tests;
323
324/// What:
325/// Quoted-string conversion tests.
326/// Why:
327/// Lone surrogates,
328/// control characters and escape spellings must survive decode,
329/// convert and
330/// re-encode without changing the code units.
331///
332/// In TS you'd write (pseudocode):
333/// ```ts
334/// import './textUnits.test';
335/// ```
336#[cfg(test)]
337mod text_units_tests;
338
339/// What:
340/// The immutable edit state plus its parse and serialize entry points.
341/// Why:
342/// A caller holds a state,
343/// derives new states from edits,
344/// and writes any of them out.
345///
346/// In TS you'd write (pseudocode):
347/// ```ts
348/// export { parseJsoncEdit, jsoncStringify, type JsoncEditState } from './editState';
349/// ```
350mod edit_state;
351
352/// What:
353/// Address resolution for reads,
354/// existence checks and key listing.
355/// Why:
356/// Every surface walks addresses with the same last-duplicate and bounds rules.
357///
358/// In TS you'd write (pseudocode):
359/// ```ts
360/// export { jsoncGetValue, jsoncHas, jsoncKeys } from './editNavigate';
361/// ```
362mod navigate;
363
364/// What:
365/// The iterative spine walk shared by every immutable edit.
366/// Why:
367/// A recursive rebuild overflows a debug test thread's stack at the accepted 512-container depth,
368/// so descent and rebuild keep their own explicit level stack.
369///
370/// In TS you'd write (pseudocode):
371/// ```ts
372/// // private module: descend(root, path) then rebuild(levels, value).
373/// ```
374mod edit_spine;
375
376/// What:
377/// Immutable value replacement,
378/// insertion and deletion.
379/// Why:
380/// Structural edits return a new document and leave the input state usable.
381///
382/// In TS you'd write (pseudocode):
383/// ```ts
384/// export { jsoncSet, jsoncDelete } from './editSet';
385/// ```
386mod edit_apply;
387
388/// What:
389/// The comment-as-data query and edit surface.
390/// Why:
391/// A value's comment and its key's comment are separate data,
392/// and both are editable.
393///
394/// In TS you'd write (pseudocode):
395/// ```ts
396/// export { jsoncGetComment, jsoncSetComment, jsoncGetKeyComment, jsoncSetKeyComment } from './editComment';
397/// ```
398mod edit_comment;
399
400/// What:
401/// Re-export the edit state and its lifecycle functions.
402/// Why:
403/// These are the entry points a consumer needs to hold and serialize a document.
404///
405/// In TS you'd write (pseudocode):
406/// ```ts
407/// export { parseJsoncEdit, jsoncStringify, type JsoncEditState } from './index';
408/// ```
409pub use edit_state::{jsonc_state_from_value, jsonc_stringify, parse_jsonc_edit, JsoncEditState};
410
411/// What:
412/// Re-export the read surface.
413/// Why:
414/// Reads answer what a document holds without deriving a new one.
415///
416/// In TS you'd write (pseudocode):
417/// ```ts
418/// export { jsoncGetValue, jsoncHas, jsoncKeys } from './index';
419/// ```
420pub use navigate::{jsonc_has, jsonc_keys, jsonc_lookup};
421
422/// What:
423/// Re-export the structural edit surface.
424/// Why:
425/// Setting and deleting are the two operations that change document shape.
426///
427/// In TS you'd write (pseudocode):
428/// ```ts
429/// export { jsoncSet, jsoncDelete } from './index';
430/// ```
431pub use edit_apply::{jsonc_delete, jsonc_set};
432
433/// What:
434/// Re-export the comment surface.
435/// Why:
436/// Comments are queryable and editable data,
437/// not output decoration.
438///
439/// In TS you'd write (pseudocode):
440/// ```ts
441/// export { jsoncGetComment, jsoncSetComment, jsoncGetKeyComment, jsoncSetKeyComment } from './index';
442/// ```
443pub use edit_comment::{jsonc_comment, jsonc_key_comment, jsonc_set_comment, jsonc_set_key_comment};
444
445/// What:
446/// Read and structural edit tests.
447/// Why:
448/// Immutability,
449/// insertion limits and the two failure kinds are the edit contract.
450///
451/// In TS you'd write (pseudocode):
452/// ```ts
453/// import './edit.test';
454/// ```
455#[cfg(test)]
456mod edit_tests;
457
458/// What:
459/// Comment query and edit tests.
460/// Why:
461/// Key and value comments are separate data and must keep their owner across emission.
462///
463/// In TS you'd write (pseudocode):
464/// ```ts
465/// import './editComment.test';
466/// ```
467#[cfg(test)]
468mod edit_comment_tests;
469
470/// What:
471/// Public-surface tests for address helpers,
472/// identity accessors,
473/// comment merging and errors.
474/// Why:
475/// Every exported item needs coverage before the crate can be called complete.
476///
477/// In TS you'd write (pseudocode):
478/// ```ts
479/// import './api.test';
480/// ```
481#[cfg(test)]
482mod api_tests;
483
484/// What:
485/// Shared-fixture tests read from the same corpus the TypeScript conformance suite uses.
486/// Why:
487/// One language-neutral contract keeps both maintained implementations from drifting.
488///
489/// In TS you'd write (pseudocode):
490/// ```ts
491/// import './fixtures.test';
492/// ```
493#[cfg(test)]
494mod fixture_tests;