@cardananium/cquisitor-lib 0.1.0-beta.52 → 0.1.0-beta.54

package/browser/cquisitor_lib.d.ts

@@ -171,6 +171,30 @@ export function validate_cbor_against_cddl(
     rule_name: string
 ): CborValidationResult;
 
+/**
+ * **CDDL spans carry both byte and char offsets.** `offset`/`length`
+ * count UTF-8 bytes (what `pest` reports); `char_offset`/`char_length`
+ * count UTF-16 code units — the unit JS strings, `string.slice`,
+ * editor APIs, and the LSP protocol use. For ASCII-only sources the
+ * two pairs are identical.
+ *
+ * **CBOR spans are byte offsets only** — into the decoded CBOR buffer.
+ * If you have a hex string, multiply by 2 to slice the hex view:
+ * `hex.slice(off*2, (off+len)*2)`.
+ */
+export interface SourceSpan {
+    /** UTF-8 byte offset in the source. */
+    offset: number;
+    /** UTF-8 byte length. */
+    length: number;
+    /** UTF-16 code unit offset (= `string.slice`-friendly). */
+    char_offset: number;
+    /** UTF-16 code unit length. */
+    char_length: number;
+    /** 1-indexed line. */
+    line: number;
+}
+
 /** Outline entry — one rule from `cddl_outline`. */
 export interface CddlOutlineEntry {
     /** Rule name (`transaction_body`, `set`, …). */
@@ -178,9 +202,9 @@ export interface CddlOutlineEntry {
     /** `"type"` for `=`, `"group"` for `( … )`. */
     kind: "type" | "group";
     /** Byte range covering the whole `name = …` rule definition. */
-    span: { offset: number; length: number; line: number };
+    span: SourceSpan;
     /** Byte range of just the rule's name identifier. */
-    name_span: { offset: number; length: number; line: number };
+    name_span: SourceSpan;
 }
 
 /** Result of `cddl_symbol_at`. `null` when the cursor isn't on an identifier. */
@@ -190,15 +214,15 @@ export type CddlSymbolAtResult =
           name: string;
           kind: "type" | "group" | "rule_reference" | "prelude_or_unknown";
           role: "definition" | "use";
-          span: { offset: number; length: number; line: number };
-          definition_span: { offset: number; length: number; line: number } | null;
-          rule_span: { offset: number; length: number; line: number } | null;
+          span: SourceSpan;
+          definition_span: SourceSpan | null;
+          rule_span: SourceSpan | null;
       };
 
 /** Result of `cddl_references`. */
 export interface CddlReferencesResult {
-    definition: { offset: number; length: number; line: number } | null;
-    uses: { offset: number; length: number; line: number }[];
+    definition: SourceSpan | null;
+    uses: SourceSpan[];
 }
 
 /**
@@ -245,12 +269,19 @@ export interface CborCddlMapEntry {
      *  except 0 / 2 / 3) the inner gets an extra `["@value"]` segment
      *  to match the `{@tag, @value}` wrapper the decoder emits. */
     decoded_path: string;
+    /** Whether this entry describes the value at `cbor_path`, or the
+     *  *key* of a map entry at that path. Map entries with named keys
+     *  produce both a `"key"` entry (CBOR span = key bytes, CDDL span
+     *  = `name:` / `<value>:` declaration) and a `"value"` entry; both
+     *  carry the same `cbor_path` / `decoded_path`. Array slots, tag
+     *  payloads, and root nodes are always `"value"`. */
+    entry_role: "key" | "value";
     /** Header byte range of the CBOR node. */
     cbor_byte_span: { offset: number; length: number };
     /** Whole-structure byte range (= `cbor_byte_span` for scalars). */
     cbor_anchor_span: { offset: number; length: number };
     /** Byte range in the CDDL source describing this position. */
-    cddl_byte_span: { offset: number; length: number; line: number };
+    cddl_byte_span: SourceSpan;
     /** Name of the CDDL rule that matched, if a rule boundary was crossed. */
     rule_name?: string;
     /** CBOR node's wire type (`U8`, `Bytes`, `Map`, `Array`, `Tag`, …). */
@@ -289,6 +320,29 @@ export function map_cbor_to_cddl(
  * Sub-structures the schema doesn't cover fall back to a raw
  * representation (under `@extra` for maps / `@positional` for arrays),
  * so partial matches still yield useful output.
+ *
+ * **Map output shape**: by default we emit JSON objects (`{a: 1, b: 2}`)
+ * for the convenient case. We switch to a wire-order-preserving array
+ * form `{ "@entries": [{ key, value, match: { via, label } }, ...] }`
+ * when the JSON object form would lose information:
+ *
+ *  * any cbor key is a complex value (Array / Map / Tag / non-standard
+ *    Simple) — JSON objects can only have string keys.
+ *  * the cbor map has duplicate keys (RFC 8949 §5.6 — non-canonical
+ *    but legal). Collapsing into a value-array would drop the
+ *    interleaving order with surrounding entries.
+ *
+ * In `@entries` form, each pair carries a `match` field describing how
+ * the cbor key was matched against the schema:
+ *  * `match.via: "literal"` — bareword / literal value match;
+ *    `match.label` is the literal text.
+ *  * `match.via: "type"` — `<type1> => …` schema, the key conforms
+ *    to a type (e.g. `policy_id => …`); `match.label` is `null`.
+ *  * `match.via: "unmatched"` — no schema entry accepted this key,
+ *    `key` and `value` are raw decoded forms; `match.label` is `null`.
+ *
+ * Almost all Cardano maps (txbody, multiasset, witness_set) use object
+ * form; the `@entries` form only kicks in for the unusual cases above.
  * @param {string} cbor_hex
  * @param {string} cddl
  * @param {string} rule_name
@@ -519,7 +573,7 @@ export interface CddlErrorInfo {
      * Byte range in the CDDL source the parser tripped over, when the
      * error has positional info. Useful for IDE squiggly underlines.
      */
-    byte_span?: { offset: number; length: number; line: number };
+    byte_span?: SourceSpan;
 }
 
 export type CborValidationResult =
@@ -553,7 +607,7 @@ export interface CborValidationErrorInfo {
      * the AST in parallel with `path`). Useful for highlighting the
      * offending CDDL rule in editors.
      */
-    cddl_byte_span?: { offset: number; length: number; line: number };
+    cddl_byte_span?: SourceSpan;
     /** Other validation errors reported in the same run. */
     additional?: CborValidationErrorInfo[];
 }

package/browser/cquisitor_lib_bg.wasm.d.ts

@@ -4,7 +4,11 @@ export const memory: WebAssembly.Memory;
 export const decode_specific_type: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
 export const get_decodable_types: () => [number, number];
 export const get_possible_types_for_input: (a: number, b: number) => [number, number];
-export const extract_hashes_from_transaction_js: (a: number, b: number) => [number, number, number, number];
+export const decode_plutus_program_pretty_uplc: (a: number, b: number) => [number, number, number, number];
+export const decode_plutus_program_uplc_json: (a: number, b: number) => [number, number, number];
+export const execute_tx_scripts: (a: number, b: number, c: any, d: any) => [number, number, number];
+export const get_ref_script_bytes: (a: number, b: number, c: number) => [number, number, number, number];
+export const get_utxo_list_from_tx: (a: number, b: number) => [number, number, number, number];
 export const cbor_to_json: (a: number, b: number) => [number, number, number];
 export const cddl_format: (a: number, b: number) => [number, number, number, number];
 export const cddl_outline: (a: number, b: number) => [number, number, number];
@@ -14,11 +18,7 @@ export const decode_cbor_against_cddl: (a: number, b: number, c: number, d: numb
 export const map_cbor_to_cddl: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_cbor_against_cddl: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_cddl: (a: number, b: number) => [number, number, number];
-export const decode_plutus_program_pretty_uplc: (a: number, b: number) => [number, number, number, number];
-export const decode_plutus_program_uplc_json: (a: number, b: number) => [number, number, number];
-export const execute_tx_scripts: (a: number, b: number, c: any, d: any) => [number, number, number];
-export const get_ref_script_bytes: (a: number, b: number, c: number) => [number, number, number, number];
-export const get_utxo_list_from_tx: (a: number, b: number) => [number, number, number, number];
+export const extract_hashes_from_transaction_js: (a: number, b: number) => [number, number, number, number];
 export const check_block_or_tx_signatures: (a: number, b: number) => [number, number, number];
 export const get_necessary_data_list_js: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const validate_transaction_js: (a: number, b: number, c: number, d: number) => [number, number, number, number];

package/node/cquisitor_lib.d.ts

@@ -171,6 +171,30 @@ export function validate_cbor_against_cddl(
     rule_name: string
 ): CborValidationResult;
 
+/**
+ * **CDDL spans carry both byte and char offsets.** `offset`/`length`
+ * count UTF-8 bytes (what `pest` reports); `char_offset`/`char_length`
+ * count UTF-16 code units — the unit JS strings, `string.slice`,
+ * editor APIs, and the LSP protocol use. For ASCII-only sources the
+ * two pairs are identical.
+ *
+ * **CBOR spans are byte offsets only** — into the decoded CBOR buffer.
+ * If you have a hex string, multiply by 2 to slice the hex view:
+ * `hex.slice(off*2, (off+len)*2)`.
+ */
+export interface SourceSpan {
+    /** UTF-8 byte offset in the source. */
+    offset: number;
+    /** UTF-8 byte length. */
+    length: number;
+    /** UTF-16 code unit offset (= `string.slice`-friendly). */
+    char_offset: number;
+    /** UTF-16 code unit length. */
+    char_length: number;
+    /** 1-indexed line. */
+    line: number;
+}
+
 /** Outline entry — one rule from `cddl_outline`. */
 export interface CddlOutlineEntry {
     /** Rule name (`transaction_body`, `set`, …). */
@@ -178,9 +202,9 @@ export interface CddlOutlineEntry {
     /** `"type"` for `=`, `"group"` for `( … )`. */
     kind: "type" | "group";
     /** Byte range covering the whole `name = …` rule definition. */
-    span: { offset: number; length: number; line: number };
+    span: SourceSpan;
     /** Byte range of just the rule's name identifier. */
-    name_span: { offset: number; length: number; line: number };
+    name_span: SourceSpan;
 }
 
 /** Result of `cddl_symbol_at`. `null` when the cursor isn't on an identifier. */
@@ -190,15 +214,15 @@ export type CddlSymbolAtResult =
           name: string;
           kind: "type" | "group" | "rule_reference" | "prelude_or_unknown";
           role: "definition" | "use";
-          span: { offset: number; length: number; line: number };
-          definition_span: { offset: number; length: number; line: number } | null;
-          rule_span: { offset: number; length: number; line: number } | null;
+          span: SourceSpan;
+          definition_span: SourceSpan | null;
+          rule_span: SourceSpan | null;
       };
 
 /** Result of `cddl_references`. */
 export interface CddlReferencesResult {
-    definition: { offset: number; length: number; line: number } | null;
-    uses: { offset: number; length: number; line: number }[];
+    definition: SourceSpan | null;
+    uses: SourceSpan[];
 }
 
 /**
@@ -245,12 +269,19 @@ export interface CborCddlMapEntry {
      *  except 0 / 2 / 3) the inner gets an extra `["@value"]` segment
      *  to match the `{@tag, @value}` wrapper the decoder emits. */
     decoded_path: string;
+    /** Whether this entry describes the value at `cbor_path`, or the
+     *  *key* of a map entry at that path. Map entries with named keys
+     *  produce both a `"key"` entry (CBOR span = key bytes, CDDL span
+     *  = `name:` / `<value>:` declaration) and a `"value"` entry; both
+     *  carry the same `cbor_path` / `decoded_path`. Array slots, tag
+     *  payloads, and root nodes are always `"value"`. */
+    entry_role: "key" | "value";
     /** Header byte range of the CBOR node. */
     cbor_byte_span: { offset: number; length: number };
     /** Whole-structure byte range (= `cbor_byte_span` for scalars). */
     cbor_anchor_span: { offset: number; length: number };
     /** Byte range in the CDDL source describing this position. */
-    cddl_byte_span: { offset: number; length: number; line: number };
+    cddl_byte_span: SourceSpan;
     /** Name of the CDDL rule that matched, if a rule boundary was crossed. */
     rule_name?: string;
     /** CBOR node's wire type (`U8`, `Bytes`, `Map`, `Array`, `Tag`, …). */
@@ -289,6 +320,29 @@ export function map_cbor_to_cddl(
  * Sub-structures the schema doesn't cover fall back to a raw
  * representation (under `@extra` for maps / `@positional` for arrays),
  * so partial matches still yield useful output.
+ *
+ * **Map output shape**: by default we emit JSON objects (`{a: 1, b: 2}`)
+ * for the convenient case. We switch to a wire-order-preserving array
+ * form `{ "@entries": [{ key, value, match: { via, label } }, ...] }`
+ * when the JSON object form would lose information:
+ *
+ *  * any cbor key is a complex value (Array / Map / Tag / non-standard
+ *    Simple) — JSON objects can only have string keys.
+ *  * the cbor map has duplicate keys (RFC 8949 §5.6 — non-canonical
+ *    but legal). Collapsing into a value-array would drop the
+ *    interleaving order with surrounding entries.
+ *
+ * In `@entries` form, each pair carries a `match` field describing how
+ * the cbor key was matched against the schema:
+ *  * `match.via: "literal"` — bareword / literal value match;
+ *    `match.label` is the literal text.
+ *  * `match.via: "type"` — `<type1> => …` schema, the key conforms
+ *    to a type (e.g. `policy_id => …`); `match.label` is `null`.
+ *  * `match.via: "unmatched"` — no schema entry accepted this key,
+ *    `key` and `value` are raw decoded forms; `match.label` is `null`.
+ *
+ * Almost all Cardano maps (txbody, multiasset, witness_set) use object
+ * form; the `@entries` form only kicks in for the unusual cases above.
  * @param {string} cbor_hex
  * @param {string} cddl
  * @param {string} rule_name
@@ -519,7 +573,7 @@ export interface CddlErrorInfo {
      * Byte range in the CDDL source the parser tripped over, when the
      * error has positional info. Useful for IDE squiggly underlines.
      */
-    byte_span?: { offset: number; length: number; line: number };
+    byte_span?: SourceSpan;
 }
 
 export type CborValidationResult =
@@ -553,7 +607,7 @@ export interface CborValidationErrorInfo {
      * the AST in parallel with `path`). Useful for highlighting the
      * offending CDDL rule in editors.
      */
-    cddl_byte_span?: { offset: number; length: number; line: number };
+    cddl_byte_span?: SourceSpan;
     /** Other validation errors reported in the same run. */
     additional?: CborValidationErrorInfo[];
 }

package/node/cquisitor_lib_bg.wasm.d.ts

@@ -4,7 +4,11 @@ export const memory: WebAssembly.Memory;
 export const decode_specific_type: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
 export const get_decodable_types: () => [number, number];
 export const get_possible_types_for_input: (a: number, b: number) => [number, number];
-export const extract_hashes_from_transaction_js: (a: number, b: number) => [number, number, number, number];
+export const decode_plutus_program_pretty_uplc: (a: number, b: number) => [number, number, number, number];
+export const decode_plutus_program_uplc_json: (a: number, b: number) => [number, number, number];
+export const execute_tx_scripts: (a: number, b: number, c: any, d: any) => [number, number, number];
+export const get_ref_script_bytes: (a: number, b: number, c: number) => [number, number, number, number];
+export const get_utxo_list_from_tx: (a: number, b: number) => [number, number, number, number];
 export const cbor_to_json: (a: number, b: number) => [number, number, number];
 export const cddl_format: (a: number, b: number) => [number, number, number, number];
 export const cddl_outline: (a: number, b: number) => [number, number, number];
@@ -14,11 +18,7 @@ export const decode_cbor_against_cddl: (a: number, b: number, c: number, d: numb
 export const map_cbor_to_cddl: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_cbor_against_cddl: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_cddl: (a: number, b: number) => [number, number, number];
-export const decode_plutus_program_pretty_uplc: (a: number, b: number) => [number, number, number, number];
-export const decode_plutus_program_uplc_json: (a: number, b: number) => [number, number, number];
-export const execute_tx_scripts: (a: number, b: number, c: any, d: any) => [number, number, number];
-export const get_ref_script_bytes: (a: number, b: number, c: number) => [number, number, number, number];
-export const get_utxo_list_from_tx: (a: number, b: number) => [number, number, number, number];
+export const extract_hashes_from_transaction_js: (a: number, b: number) => [number, number, number, number];
 export const check_block_or_tx_signatures: (a: number, b: number) => [number, number, number];
 export const get_necessary_data_list_js: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const validate_transaction_js: (a: number, b: number, c: number, d: number) => [number, number, number, number];

package/package.json

@@ -4,7 +4,7 @@
     "Evgenii Lisitskii <evgeniilisitskii@gmail.com>"
   ],
   "description": "Cardano transaction validation library",
-  "version": "0.1.0-beta.52",
+  "version": "0.1.0-beta.54",
   "license": "Apache-2.0",
   "files": [
     "node/cquisitor_lib_bg.wasm",