@cbortech/cbor 0.26.5 → 0.26.7

package/dist/ast/CborByteString.d.ts

@@ -1,11 +1,14 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
 import { CborItem } from './CborItem';
 import { CborWriter, EncodingWidth } from '../cbor/encode';
+import { ByteCommentSyntax } from '../cdn/serialize-utils';
 /** One part of a byte string parsed from a CDN `+` concatenation chain. */
 export interface CborByteStringPart {
     bytes: Uint8Array;
     /** Original literal source text, when the part came from a byte string token. */
     source?: string;
+    /** Which comment syntax `source` recognizes, if any — see `ednCommentSyntax`. */
+    commentSyntax?: ByteCommentSyntax;
 }
 /** CBOR Major Type 2 — definite-length byte string. */
 export declare class CborByteString extends CborItem {
@@ -15,12 +18,23 @@ export declare class CborByteString extends CborItem {
     readonly ednEncoding: 'hex' | 'base64' | 'base64url' | 'base32' | 'base32hex';
     encodingWidth: EncodingWidth | undefined;
     readonly ednSource: string | undefined;
+    /**
+     * Which comment syntax `ednSource` recognizes, if any — set once at parse
+     * time by whoever actually knows the literal's real origin (see
+     * `ByteCommentSyntax`), never re-derived later from its prefix string:
+     * a user extension can register under any prefix, including one a
+     * built-in (`b32`/`h32`) also uses, so the prefix string alone can't say
+     * which comment rules (if any) actually apply. `undefined` when
+     * `ednSource` has no comment syntax, or its extension's isn't known.
+     */
+    readonly ednCommentSyntax: ByteCommentSyntax | undefined;
     /** Part boundaries of the original `+` concatenation chain, if any. */
     readonly ednParts: readonly CborByteStringPart[] | undefined;
     constructor(value: Uint8Array, options?: {
         ednEncoding?: 'hex' | 'base64' | 'base64url' | 'base32' | 'base32hex';
         encodingWidth?: EncodingWidth;
         ednSource?: string;
+        ednCommentSyntax?: ByteCommentSyntax;
         ednParts?: readonly CborByteStringPart[];
     });
     _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;

package/dist/ast/CborEllipsis.d.ts

@@ -3,9 +3,101 @@ import { CborTag } from './CborTag';
 import { CborItem } from './CborItem';
 export declare const CPA888_TAG = 888n;
 export declare class CborEllipsis extends CborTag {
+    /**
+     * For the array (string/bytes elision) form: `realBoundary[i]` is `true`
+     * when a genuine `+` from the source precedes `items[i]` — as opposed to
+     * `items[i]` sitting *inside* a single `h'xx...yy'` literal's own `...`
+     * notation (index 0's value is never consulted — there is nothing before
+     * the first item). `preserveConcatenation` uses this to show only the
+     * real boundaries and fuse everything else, exactly as each source
+     * literal was spelled.
+     *
+     * `undefined` means no boundary information is available at all (e.g.
+     * reconstructed from raw CBOR bytes, which carry no notion of "was there
+     * a `+` here" to begin with) — `preserveConcatenation` then has no effect,
+     * the same as for a value that didn't originate from CDN source.
+     */
+    readonly realBoundary: readonly boolean[] | undefined;
+    /**
+     * For a subtree-elision placeholder (`888(null)`, i.e. `content
+     * instanceof CborSimple`) that sits *inside* another `CborEllipsis`'s
+     * items: `true` when it came from a `h'xx...yy'`-family literal's own
+     * `...` notation — even a fully-elided `h'...'` with no hex digits at all
+     * — as opposed to a bare standalone `...` token. Only consulted when this
+     * placeholder ends up isolated as its own preserved fragment (nothing to
+     * fuse it with on either side), to pick the right spelling: `h'...'` vs
+     * plain `...`.
+     */
+    readonly fromByteLiteral: boolean;
+    /**
+     * When `fromByteLiteral` is `true`: that `h'xx...yy'`-family literal's own
+     * raw source text (e.g. `h'AB...CD'` verbatim — case, interior whitespace,
+     * and any `/ ... /`/`# ...` comments included), for `preserveByteString`
+     * to round-trip instead of re-emitting a freshly lower-cased, comment-free
+     * `h'...'` literal. `undefined` when `fromByteLiteral` is `false`.
+     */
+    readonly literalSource: string | undefined;
     /** Subtree elision: 888(null) */
-    constructor();
+    constructor(fromByteLiteral?: boolean, literalSource?: string);
     /** String/bytes elision: 888([items...]) */
-    constructor(items: CborItem[]);
+    constructor(items: CborItem[], realBoundary?: readonly boolean[]);
     _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    /**
+     * `true` when this bytes elision has at least one real `+` boundary
+     * somewhere — as opposed to being a single `h'xx...yy'` literal's own
+     * `...` notation, which is not "produced by + concatenation" (see
+     * `preserveByteString`'s own docs) and so has its spelling preserved by
+     * `preserveByteString` alone, the same as a non-elided `h'...'` literal.
+     *
+     * A real boundary can hide two ways: as `realBoundary[i]` (`i > 0`) on the
+     * items array itself, or *inside* a merged `CborByteString` whose
+     * `ednParts.length > 1` — two `+`-joined literals that sat next to each
+     * other with no ellipsis between them (e.g. `h'AB' + h'CD...EF'`) merge
+     * into one item during parsing, so their boundary doesn't show up in
+     * `realBoundary` at that item's own index.
+     */
+    private _hasRealConcatenation;
+    /**
+     * Render one elision fragment as it should appear under
+     * `preserveConcatenation`: a merged multi-part `CborTextString` (see the
+     * parser's `currentParts` consolidation) is expanded back into its
+     * original `+`-joined literals, single-line, honoring `preserveRawString`
+     * per part. Anything else (a single-part fragment, or a nested
+     * `CborEllipsis`) renders normally.
+     *
+     * Only reached for text elision (or anything not shaped like a pure bytes
+     * elision, or a bytes elision with no `realBoundary` information) —
+     * `_renderPreservedBytesElision` handles the bytes case that has that
+     * information, since it needs to see all the fragments together to know
+     * which `...`s are real `+`-joined ellipses and which are internal to one
+     * `h'...'` literal.
+     */
+    private _renderFragment;
+    /**
+     * Re-emit a `888([...])` bytes elision as a single `h'xx...yy'` literal
+     * when every item is either a plain `CborByteString` fragment or a
+     * subtree-elision placeholder (`888(null)`) — i.e. exactly what
+     * `h'xx...yy'` parses into. Returns `undefined` when the items don't
+     * match that shape (e.g. text-string elision, or a fragment that isn't a
+     * plain byte string), so the caller falls back to the `frag + ... + frag`
+     * form.
+     */
+    private _compactHexElided;
+    /**
+     * `preserveConcatenation` rendering for a bytes elision. Groups the
+     * fragments at every *real* boundary (`realBoundary[i]`) and renders each
+     * group as one unit — fusing together whatever sits between real
+     * boundaries, including any `h'xx...yy'` literal's own internal `...`
+     * (wherever it's positioned — leading, trailing, or in the middle) and
+     * the fragments on either side of it, exactly as that literal was
+     * written. Within a group, a `CborByteString` that itself merged several
+     * `+`-joined literals (`ednParts.length > 1`, always a real boundary
+     * internally — see the parser) is further split at each of those parts.
+     *
+     * Returns `undefined` when there's no `realBoundary` to work from, or an
+     * item isn't a plain `CborByteString` or subtree-elision placeholder
+     * (e.g. text elision), so the caller falls back to the compact literal or
+     * the simpler per-fragment `frag + ... + frag` rendering.
+     */
+    private _renderPreservedBytesElision;
 }

package/dist/ast/CborFloat.d.ts

@@ -25,6 +25,15 @@ export declare class CborFloat extends CborItem {
      * to round-trip the literal when `appStrings` is not false.
      */
     ednSource?: string;
+    /**
+     * Original CDN literal source text (e.g. `1.50`, `1.5_1`, `0x1.8p+0_1`),
+     * set by the parser when this float came from a plain CDN float literal
+     * (as opposed to a `float'...'` app-string, which uses `ednSource`
+     * above). Used by `_toCDN()` to round-trip the literal's exact spelling,
+     * including its encoding-indicator suffix, when `preserveNumberFormat`
+     * is set.
+     */
+    literalSource?: string;
     /**
      * Original encoded payload bytes (big-endian, without the initial byte),
      * set by the decoder when the value is NaN so that NaN payloads survive a
@@ -36,6 +45,7 @@ export declare class CborFloat extends CborItem {
     constructor(value: number, options?: {
         precision?: FloatPrecision;
         rawBits?: Uint8Array;
+        literalSource?: string;
     });
     _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, _depth: number): string;

package/dist/ast/CborItem.d.ts

@@ -1,4 +1,4 @@
-import { CBOROptions, ToCDNOptions, ToJSOptions, ToHexDumpOptions, ToCBOROptions, CborComments, DecodeWarning, ParseWarning } from '../types';
+import { CBOROptions, ToCDNOptions, ToJSOptions, ToHexDumpOptions, ToCBOROptions, CborComment, CborComments, DecodeWarning, ParseWarning } from '../types';
 import { CborWriter } from '../cbor/encode';
 /** @internal One line of an annotated hex dump. */
 export interface AnnotatedLine {
@@ -6,6 +6,27 @@ export interface AnnotatedLine {
     hex: string;
     comment: string;
 }
+export interface AppSeqEncodingEdit {
+    /** Start/end offsets within appSeqSource of an existing indicator. */
+    start: number;
+    end: number;
+    /** Replacement used by encodingIndicators: 'always'. */
+    always: string;
+    /** Replacement used by encodingIndicators: 'never'. */
+    never: string;
+}
+/**
+ * Original literal features used by the sole item inside a preserved
+ * `prefix<<item>>` source. They let serialization honour an explicitly
+ * disabled sibling `preserve*` option instead of replaying that literal
+ * verbatim through `preserveAppSequence`.
+ */
+export interface AppSeqSourceFeatures {
+    byteString?: boolean;
+    textString?: boolean;
+    rawString?: boolean;
+    concatenation?: boolean;
+}
 /**
  * Abstract base class for all CBOR AST nodes.
  *
@@ -31,6 +52,71 @@ export declare abstract class CborItem {
      * They do not affect CBOR bytes or JS conversion.
      */
     comments?: CborComments;
+    /**
+     * `true` when this node is an array/map entry (or indefinite-length
+     * string chunk) immediately preceded by a blank line in the parsed CDN
+     * source — set unconditionally by the parser, regardless of any
+     * `preserve*` option, mirroring `start`/`end`. Only consulted by
+     * `toCDN()` when `ToCDNOptions.preserveBlankLines` is set; otherwise
+     * ignored. Left `undefined` for nodes not parsed as a container entry, or
+     * with no blank line before them.
+     */
+    blankLineBefore?: boolean;
+    /**
+     * Original application-string/-sequence source text — `prefix'...'`,
+     * `` prefix`...` ``, or `prefix<<...>>` — set by the parser when the
+     * resolving extension declares `preserveAppSeqSource: 'optional'`. A
+     * subclass's own `_toCDN()` override may check this (gated behind
+     * `ToCDNOptions.preserveAppSequence`) to round-trip the exact original
+     * spelling instead of always regenerating `prefix'...'` notation from the
+     * resolved value. Left `undefined` for nodes not parsed from one of these
+     * forms.
+     */
+    appSeqSource?: string;
+    /**
+     * Comments contained within `appSeqSource`, with `start`/`end` offsets
+     * relative to that string. These spans allow comment markers to be
+     * converted (or comments to be removed) without regenerating and thereby
+     * losing the original application-string/-sequence notation.
+     */
+    appSeqComments?: CborComment[];
+    /**
+     * Source edits for encoding indicators contained in a raw-tag
+     * `appSeqSource`. Includes zero-width edits where an indicator was absent
+     * so `encodingIndicators: 'always'` can insert one without regenerating
+     * the surrounding source.
+     */
+    appSeqEncodingEdits?: AppSeqEncodingEdit[];
+    /**
+     * `false` when `appSeqEncodingEdits` does not cover every encoding
+     * indicator nested inside a raw-tag `appSeqSource` — i.e. its content
+     * contains a node type `collectContentEncodingEdits` doesn't know how to
+     * edit (e.g. a `CborMap`, `CborTag`, or indefinite-length string inside an
+     * `ip` array). Left `undefined` (treated as complete) when coverage is
+     * exhaustive, which holds for every tag content type `dt` accepts and for
+     * most content `ip` accepts. When `false`, `decideTaggedAppSeqRendering`
+     * must not choose the `'source'` decision under `encodingIndicators !==
+     * 'auto'`, since surgical span edits would silently leave the uncovered
+     * node's indicator unchanged; it falls back to `'structural'` instead.
+     */
+    appSeqEncodingEditsComplete?: boolean;
+    /**
+     * For an `appSeqSource` parsed from `prefix<<item>>` notation: the offset
+     * within `appSeqSource`, relative to its own start, where the sole inner
+     * item's own consumption ends — i.e. right after its own encoding
+     * indicator, if it had one. Lets `adjustAppSeqIndicator` locate and strip
+     * that inner indicator exactly, regardless of what (whitespace, a
+     * trailing comma, a comment) separates it from the closing `>>`, rather
+     * than pattern-matching text near `>>`. `undefined` when `appSeqSource`
+     * isn't `<<...>>` notation, or wasn't captured with a single inner item.
+     */
+    appSeqInnerEnd?: number;
+    /**
+     * Literal-preservation features present in the sole item of a captured
+     * `prefix<<item>>` source. Used to resolve explicitly disabled
+     * `preserve*` options without treating unrelated options as conflicts.
+     */
+    appSeqSourceFeatures?: AppSeqSourceFeatures;
     /**
      * Validity violations detected while decoding or parsing this node.
      * Populated when `strict: false` is set in `FromCBOROptions` or
@@ -46,9 +132,12 @@ export declare abstract class CborItem {
     /**
      * @internal
      * True when this node is, or contains through wrapper nodes (tags,
-     * embedded CBOR, app-sequence results), an array or map.
-     * `inlineLeafContainers` never inlines a container whose entries contain
-     * another container, even one that renders on a single line.
+     * app-sequence results), an array or map. `inlineLeafContainers` never
+     * inlines a container whose entries contain another container, even one
+     * that renders on a single line. `CborEmbeddedCBOR` (`<<...>>`) is the one
+     * exception: it inlines its own entries based purely on whether they
+     * render without a line break, regardless of this flag — see its
+     * `_toCDN()`, which omits `entryIsLeaf` for that reason.
      */
     get _containsCdnContainer(): boolean;
     /** Serialize this node to CBOR binary. */

package/dist/ast/CborNint.d.ts

@@ -16,8 +16,17 @@ export declare class CborNint extends CborItem {
     /** CBOR raw argument n, where actual value = −1 − n. */
     readonly argument: bigint;
     encodingWidth: EncodingWidth | undefined;
+    /**
+     * Original CDN digit spelling (sign + base + digits, without the
+     * encoding-indicator suffix), set by the parser when this value came
+     * from CDN text. Used by `_toCDN()` to round-trip the literal's base
+     * (`-0xff`, `-0o377`, `-0b101`, decimal) when `preserveNumberFormat` is
+     * set.
+     */
+    readonly ednSource?: string;
     constructor(value: number | bigint, options?: {
         encodingWidth?: EncodingWidth;
+        ednSource?: string;
     });
     /** The actual decoded negative value (−1 − argument). */
     get value(): bigint;

package/dist/ast/CborSimple.d.ts

@@ -12,12 +12,21 @@ import { CborWriter } from '../cbor/encode';
  */
 export declare class CborSimple extends CborItem {
     readonly value: number;
-    constructor(value: number);
+    /**
+     * Original CDN digit spelling of the argument to `simple(...)` (base +
+     * digits), set by the parser when this value came from CDN text. Used by
+     * `_toCDN()` to round-trip the argument's base (`0x10`, decimal, …) when
+     * `preserveNumberFormat` is set.
+     */
+    readonly ednSource?: string;
+    constructor(value: number, options?: {
+        ednSource?: string;
+    });
     static readonly FALSE: CborSimple;
     static readonly TRUE: CborSimple;
     static readonly NULL: CborSimple;
     static readonly UNDEFINED: CborSimple;
     _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
-    _toCDN(_options: ToCDNOptions | undefined, _depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborTag.d.ts

@@ -6,8 +6,16 @@ export declare class CborTag extends CborItem {
     readonly tag: bigint;
     readonly content: CborItem;
     encodingWidth: EncodingWidth | undefined;
+    /**
+     * Original CDN digit spelling of the tag number (base + digits, without
+     * the encoding-indicator suffix), set by the parser when this tag came
+     * from CDN text. Used by `_toCDN()` to round-trip the tag number's base
+     * (`0x3e7`, decimal, …) when `preserveNumberFormat` is set.
+     */
+    ednSource?: string;
     constructor(tag: number | bigint, content: CborItem, options?: {
         encodingWidth?: EncodingWidth;
+        ednSource?: string;
     });
     get _containsCdnContainer(): boolean;
     _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;

package/dist/ast/CborTextString.d.ts

@@ -10,16 +10,36 @@ export declare class CborTextString extends CborItem {
     readonly ednParts: readonly string[] | undefined;
     /** Original raw-string source text, when parsed from a single backtick literal. */
     readonly ednSource: string | undefined;
+    /**
+     * Original double-quoted source text (including its escape sequences),
+     * when parsed from a single non-concatenated `"..."` literal. Used by
+     * `_toCDN()` to round-trip the literal's exact spelling when
+     * `preserveTextString` is set.
+     */
+    readonly quotedEdnSource: string | undefined;
     /**
      * Original source text per `ednParts` entry, aligned by index; `undefined`
      * for parts that were not raw backtick literals.
      */
     readonly ednPartSources: readonly (string | undefined)[] | undefined;
+    /**
+     * `true` at index `i`, aligned with `ednParts`, when that part came from a
+     * byte-string literal on the right of a text-leading `+` concatenation
+     * (decoded as UTF-8 and merged in per §5.1) rather than a double-quoted
+     * `"..."` literal. Both cases leave `ednPartSources[i]` `undefined` (byte
+     * strings have no preserved raw source here, same as an unpreserved
+     * double-quoted literal), so this is what lets `appSeqSourceFeatures`
+     * attribute the part to `byteString` instead of the unpreservable
+     * `textString`.
+     */
+    readonly ednPartIsByteString: readonly boolean[] | undefined;
     constructor(value: string, options?: {
         encodingWidth?: EncodingWidth;
         ednParts?: readonly string[];
         ednSource?: string;
+        quotedEdnSource?: string;
         ednPartSources?: readonly (string | undefined)[];
+        ednPartIsByteString?: readonly boolean[];
     });
     _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, depth: number): string;

package/dist/ast/CborUint.d.ts

@@ -5,8 +5,16 @@ import { CborWriter, EncodingWidth } from '../cbor/encode';
 export declare class CborUint extends CborItem {
     readonly value: bigint;
     encodingWidth: EncodingWidth | undefined;
+    /**
+     * Original CDN digit spelling (base + digits, without the encoding-
+     * indicator suffix), set by the parser when this value came from CDN
+     * text. Used by `_toCDN()` to round-trip the literal's base (`0xff`,
+     * `0o377`, `0b101`, decimal) when `preserveNumberFormat` is set.
+     */
+    readonly ednSource?: string;
     constructor(value: number | bigint, options?: {
         encodingWidth?: EncodingWidth;
+        ednSource?: string;
     });
     _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
     _toCDN(options: ToCDNOptions | undefined, _depth: number): string;

package/dist/ast/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../mapEntries-6hy7UgeN.cjs");exports.CborArray=e.C,exports.CborBigNint=e.v,exports.CborBigUint=e.y,exports.CborByteString=e.E,exports.CborEmbeddedCBOR=e.b,exports.CborFloat=e.O,exports.CborIndefiniteByteString=e.T,exports.CborIndefiniteTextString=e.w,exports.CborItem=e.j,exports.CborMap=e.S,exports.CborNint=e.k,exports.CborSimple=e.x,exports.CborTag=e.D,exports.CborTextString=e.g,exports.CborUint=e.A;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../mapEntries-D2NyeCX3.cjs");exports.CborArray=e.D,exports.CborBigNint=e._,exports.CborBigUint=e.v,exports.CborByteString=e.A,exports.CborEmbeddedCBOR=e.w,exports.CborFloat=e.M,exports.CborIndefiniteByteString=e.k,exports.CborIndefiniteTextString=e.O,exports.CborItem=e.I,exports.CborMap=e.E,exports.CborNint=e.P,exports.CborSimple=e.T,exports.CborTag=e.j,exports.CborTextString=e.h,exports.CborUint=e.F;

package/dist/ast/index.js

@@ -1,2 +1,2 @@
-import { A as e, C as t, D as n, E as r, O as i, S as a, T as o, b as s, g as c, j as l, k as u, v as d, w as f, x as p, y as m } from "../mapEntries-Clr-oNtQ.js";
-export { t as CborArray, d as CborBigNint, m as CborBigUint, r as CborByteString, s as CborEmbeddedCBOR, i as CborFloat, o as CborIndefiniteByteString, f as CborIndefiniteTextString, l as CborItem, a as CborMap, u as CborNint, p as CborSimple, n as CborTag, c as CborTextString, e as CborUint };
+import { A as e, D as t, E as n, F as r, I as i, M as a, O as o, P as s, T as c, _ as l, h as u, j as d, k as f, v as p, w as m } from "../mapEntries-DxrDre2P.js";
+export { t as CborArray, l as CborBigNint, p as CborBigUint, e as CborByteString, m as CborEmbeddedCBOR, a as CborFloat, f as CborIndefiniteByteString, o as CborIndefiniteTextString, i as CborItem, n as CborMap, s as CborNint, c as CborSimple, d as CborTag, u as CborTextString, r as CborUint };

package/dist/cbor.d.ts

@@ -177,6 +177,14 @@ export declare class CBOR {
      * @example
      * // CDN text input
      * CBOR.validate('{"a": 1}', { type: 'cdn' });
+     *
+     * @example
+     * // Schema validation with a compiled CDDL schema
+     * import { CDDL } from '@cbortech/cbor/cddl';
+     * const schema = CDDL.compile('person = { name: tstr, ? age: uint }');
+     * const result = CBOR.validate('{"name": "kudo"}', { type: 'cdn', cddl: schema });
+     * result.valid;      // true
+     * result.cddlErrors; // []
      */
     static validate(input: ArrayBufferView | ArrayBufferLike | string, options?: ValidateOptions): ValidateResult;
     /**

package/dist/cddl/ast.d.ts

@@ -0,0 +1,196 @@
+/**
+ * CDDL AST node definitions.
+ *
+ * Unlike the CBOR side (class-based CborItem nodes), the CDDL AST is a plain
+ * discriminated-union structure: nodes are produced by the parser, consumed
+ * by the compiler/writer (and, in a later phase, the validator), and never
+ * carry behavior of their own.
+ *
+ * All nodes carry `start`/`end` character offsets into the parsed source so
+ * diagnostics and editor tooling can point at exact ranges.
+ */
+export interface CddlNodeBase {
+    /** Character offset of the first character of this node in the source. */
+    start: number;
+    /** Character offset just past the last character of this node. */
+    end: number;
+}
+/**
+ * rule = typename [genericparm] S assignt S type
+ *      / groupname [genericparm] S assigng S grpent
+ *
+ * Both forms are parsed into the same shape: `body` is a group entry, which
+ * subsumes a plain type (an entry with no occurrence and no member key).
+ * Whether a rule is used as a type or as a group is resolved semantically at
+ * validation time, not at parse time.
+ */
+export interface CddlRule extends CddlNodeBase {
+    kind: 'rule';
+    name: string;
+    /** Generic parameter names from `name<A, B> = …`, if any. */
+    generics?: string[];
+    /** '=' defines; '/=' extends a type choice; '//=' extends a group choice. */
+    assign: '=' | '/=' | '//=';
+    body: CddlGroupEntry;
+}
+/** type = type1 *(S "/" S type1) — always wrapped, even for one alternative. */
+export interface CddlType extends CddlNodeBase {
+    kind: 'type';
+    alternatives: CddlType1[];
+}
+/** type1 = type2 [S (rangeop / ctlop) S type2] */
+export interface CddlType1 extends CddlNodeBase {
+    kind: 'type1';
+    target: CddlType2;
+    /** Present when a range or control operator follows the target. */
+    op?: {
+        kind: 'range';
+        inclusive: boolean;
+    } | {
+        kind: 'ctl';
+        name: string;
+    };
+    /** The right-hand operand; present exactly when `op` is present. */
+    controller?: CddlType2;
+}
+export type CddlType2 = CddlValue | CddlRef | CddlParenType | CddlMapType | CddlArrayType | CddlUnwrap | CddlEnum | CddlTagged | CddlMajor | CddlAny;
+/** A literal value: number, text string, or byte string. */
+export type CddlValue = CddlNodeBase & {
+    kind: 'value';
+    raw: string;
+} & ({
+    type: 'int';
+    value: number | bigint;
+} | {
+    type: 'float';
+    value: number;
+} | {
+    type: 'text';
+    value: string;
+} | {
+    type: 'bytes';
+    value: Uint8Array;
+    qualifier: '' | 'h' | 'b64';
+});
+/** typename [genericarg] — also used for groupname references. */
+export interface CddlRef extends CddlNodeBase {
+    kind: 'ref';
+    name: string;
+    genericArgs?: CddlType1[];
+}
+/** "(" S type S ")" */
+export interface CddlParenType extends CddlNodeBase {
+    kind: 'paren';
+    type: CddlType;
+}
+/** "{" S group S "}" */
+export interface CddlMapType extends CddlNodeBase {
+    kind: 'map';
+    group: CddlGroup;
+}
+/** "[" S group S "]" */
+export interface CddlArrayType extends CddlNodeBase {
+    kind: 'array';
+    group: CddlGroup;
+}
+/** "~" S typename [genericarg] */
+export interface CddlUnwrap extends CddlNodeBase {
+    kind: 'unwrap';
+    ref: CddlRef;
+}
+/** "&" S "(" S group S ")" / "&" S groupname [genericarg] */
+export interface CddlEnum extends CddlNodeBase {
+    kind: 'enum';
+    group: CddlGroup | CddlRef;
+}
+/**
+ * "#" "6" ["." head-number] "(" S type S ")" — a tagged item.
+ * `tag` is a literal tag number, a `<type>` head-number expression
+ * (RFC 9682 §3.2), or absent for `#6(…)` (any tag number).
+ */
+export interface CddlTagged extends CddlNodeBase {
+    kind: 'tagged';
+    tag?: bigint | CddlType;
+    item: CddlType;
+    /**
+     * Source text of the '#6[.head]' part (e.g. '#6.0x10') when the tag number
+     * is literal or absent; lets the formatter preserve the number base.
+     */
+    raw?: string;
+}
+/**
+ * "#" DIGIT ["." uint] and "#" "7" ["." head-number] — a major type,
+ * optionally constrained by additional information (or, for major 7, the
+ * simple value / float head-number, which may be a `<type>` expression).
+ */
+export interface CddlMajor extends CddlNodeBase {
+    kind: 'major';
+    major: number;
+    ai?: bigint | CddlType;
+    /**
+     * Source text of the '#N[.ai]' expression (e.g. '#7.0b11001') when the
+     * head-number is literal or absent; lets the formatter preserve the
+     * number base.
+     */
+    raw?: string;
+}
+/** "#" — any data item. */
+export interface CddlAny extends CddlNodeBase {
+    kind: 'any';
+}
+/** group = grpchoice *(S "//" S grpchoice); each choice is an entry list. */
+export interface CddlGroup extends CddlNodeBase {
+    kind: 'group';
+    choices: CddlGroupEntry[][];
+    /**
+     * True when the final entry is followed by a comma (optcom). Commas
+     * between entries are cosmetic and not recorded, but the trailing comma is
+     * syntactically significant: `(int,)` is a group, never a parenthesized
+     * type, so e.g. it cannot be the root of a data model.
+     */
+    trailingComma?: boolean;
+}
+export type CddlGroupEntry = CddlEntryValue | CddlEntryGroup;
+/** grpent = [occur S] [memberkey S] type — also covers bare group references. */
+export interface CddlEntryValue extends CddlNodeBase {
+    kind: 'entry';
+    occur?: CddlOccur;
+    memberKey?: CddlMemberKey;
+    value: CddlType;
+}
+/** grpent = [occur S] "(" S group S ")" — an inline parenthesized group. */
+export interface CddlEntryGroup extends CddlNodeBase {
+    kind: 'entry-group';
+    occur?: CddlOccur;
+    group: CddlGroup;
+}
+/**
+ * occur = [uint] "*" [uint] / "+" / "?"
+ * marker '*' covers `*`, `n*`, `*m`, and `n*m` via min/max.
+ */
+export interface CddlOccur extends CddlNodeBase {
+    kind: 'occur';
+    marker: '?' | '+' | '*';
+    min?: number;
+    max?: number;
+}
+/**
+ * memberkey = type1 S ["^" S] "=>"
+ *           / bareword S ":"
+ *           / value S ":"
+ *
+ * `cut` is true for the ':' forms (implicit cut, RFC 8610 §3.5.4) and for
+ * the explicit `^ =>` form.
+ */
+export type CddlMemberKey = CddlNodeBase & {
+    cut: boolean;
+} & ({
+    kind: 'type1';
+    key: CddlType1;
+} | {
+    kind: 'bareword';
+    key: string;
+} | {
+    kind: 'value';
+    key: CddlValue;
+});

package/dist/cddl/controls.d.ts

@@ -0,0 +1,28 @@
+import { CborItem } from '../ast/CborItem';
+import { CddlNodeBase, CddlType2, CddlValue } from './ast';
+type Path = readonly (string | number)[];
+/** Matching primitives provided by the validator (closed over env/ctx). */
+export interface ControlDeps {
+    matchType2(item: CborItem, t2: CddlType2, path: Path): boolean;
+    /** Like matchType2, but suppresses instance offsets in recorded errors —
+     *  the item was decoded out of an embedded byte string, so its offsets
+     *  are relative to the embedded bytes, not the outer document. */
+    matchEmbedded(item: CborItem, t2: CddlType2, path: Path): boolean;
+    resolveValue(t2: CddlType2): CddlValue | undefined;
+    /** Whether some integer ≥ min matches the type; undefined = unanalyzable. */
+    existsIntGE(t2: CddlType2, min: bigint): boolean | undefined;
+    matchesLiteral(item: CborItem, v: CddlValue): boolean;
+    fail(path: Path, item: CborItem | undefined, node: CddlNodeBase | undefined, message: string): false;
+    warnOnce(message: string, node?: CddlNodeBase): void;
+    features: ReadonlySet<string>;
+    uint(n: number | bigint): CborItem;
+}
+export type ControlHandler = (deps: ControlDeps, item: CborItem, target: CddlType2, controller: CddlType2, path: Path, node: CddlNodeBase) => boolean;
+/**
+ * The .feature controller is a feature name, or an array whose first
+ * element is the feature name and whose rest is detail (RFC 9165 §5) —
+ * either form may be parenthesized, e.g. `.feature (["x", "detail"])`.
+ */
+export declare const featureName: (deps: ControlDeps, controller: CddlType2) => string | undefined;
+export declare function getControl(name: string): ControlHandler | undefined;
+export {};