@cardananium/cquisitor-lib 0.1.0-beta.51 → 0.1.0-beta.53

package/README.md

@@ -353,9 +353,15 @@ validate_cddl("thing = {n: uint}");
 validate_cddl("thing = [unknown_rule, int]");
 // { valid: false, error: { kind: "unresolved_references",
 //                           message: "missing definition for rule unknown_rule" } }
+
+validate_cddl("; only a comment\n");
+// { valid: false, error: { kind: "no_rules",
+//                           message: "CDDL document defines no rules" } }
 ```
 
-`error.kind` values: `"parse_error"`, `"unresolved_references"`.
+Parser errors include a `byte_span: {offset, length, line}` so editors can squiggle the exact position pest tripped on.
+
+`error.kind` values: `"parse_error"`, `"unresolved_references"`, `"no_rules"`.
 
 #### `validate_cbor_against_cddl(cbor_hex: string, cddl: string, rule_name: string): { valid: boolean, error?: object }`
 
@@ -378,7 +384,9 @@ validate_cbor_against_cddl("01", "thing = tstr", "thing");
 
 `error.cddl_byte_span` carries the byte range in the **CDDL source** pointing at the type the validator tried (and failed) to apply — useful for highlighting the offending rule in an editor. It's synthesised by walking the AST in parallel with `path`, so it's available for any error that has a meaningful `path`. When the `rule_name` you passed isn't the first rule of the document, the offsets are still expressed in *your* CDDL coordinates (the wrapper we use internally is invisible to callers).
 
-`error.kind` values: `"parse_error"`, `"unresolved_references"`, `"missing_rule"`, `"input_parse"`, `"mismatch"`, `"map_cut"`, `"generic"`. When multiple violations fire, the headline goes in the top-level fields and the rest land in `error.additional`.
+`error.kind` values: `"parse_error"`, `"unresolved_references"`, `"no_rules"`, `"missing_rule"`, `"input_parse"`, `"mismatch"`, `"map_cut"`, `"generic"`. When multiple violations fire, the headline goes in the top-level fields and the rest land in `error.additional`.
+
+`anchor_spans` is always populated — for container values (Map / Array / Tag / indefinite strings) it covers the whole structure; for scalars it falls back to `position_info` so a UI's halo highlight always has something to draw.
 
 #### `decode_cbor_against_cddl(cbor_hex: string, cddl: string, rule_name: string): unknown`
 
@@ -431,9 +439,10 @@ cddl_symbol_at("coin = uint\nfee = coin", /* offset = */ 18);
 //  definition_span: {offset: 0, length: 4, line: 1},
 //  rule_span: {offset: 0, length: 11, line: 1}}
 
-// Re-format — round-trip via Display.
-cddl_format("alpha   =   uint");
-// "alpha = uint"
+// Re-format — round-trip via Display. Comments survive
+// (both standalone `; …` and trailing `; …`).
+cddl_format("; header\nalpha   =   uint ; trailing");
+// "; header\nalpha = uint ; trailing\n"
 ```
 
 `validate_cddl` itself returns a `byte_span` on parser errors so editor-side squiggles can underline the offending position directly:

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[];
 }
 
 /**
@@ -232,6 +256,59 @@ export function cddl_symbol_at(cddl: string, offset: number): CddlSymbolAtResult
  */
 export function cddl_format(cddl: string): string;
 
+/** One entry from `map_cbor_to_cddl`: a single position of a CBOR
+ *  node, the type that matched it, and the path it ends up at in the
+ *  output of `decode_cbor_against_cddl`. */
+export interface CborCddlMapEntry {
+    /** Path into the *raw* CBOR tree (numeric map keys are bracketed). */
+    cbor_path: string;
+    /** Path into the labelled JSON returned by `decode_cbor_against_cddl`.
+     *  Numeric map keys come back as bracket-quoted strings (`["0"]`)
+     *  because decoded JSON has only string keys; identifier-safe keys
+     *  use dot notation (`.name`). For unspecialised tags (anything
+     *  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: 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`, …). */
+    cbor_type?: string;
+}
+
+/**
+ * Returns a flat list of mapping entries pairing each visited CBOR node
+ * with the CDDL position that describes it. Use it to wire
+ * bidirectional highlight between a CBOR panel and a CDDL panel without
+ * needing a validation error to trigger it.
+ *
+ * Order is depth-first pre-order, so a parent's entry precedes its
+ * children's. Tags in the CBOR are transparent to the path grammar
+ * (anweiss-style): `Tag(258, [...])` is walked as if the tag wrapper
+ * weren't there when matching against `[* a]`-shaped schemas.
+ *
+ * @param cbor_hex
+ * @param cddl
+ * @param rule_name
+ */
+export function map_cbor_to_cddl(
+    cbor_hex: string,
+    cddl: string,
+    rule_name: string
+): CborCddlMapEntry[];
+
 /**
  * Maps decoded CBOR onto a CDDL schema and returns labelled JSON. Where
  * `cbor_to_json` returns positional CBOR (numeric map keys, raw arrays),
@@ -473,7 +550,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 =
@@ -507,7 +584,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.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./cquisitor_lib_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    Address, AddressKind, Anchor, AnchorDataHash, AssetName, AssetNames, Assets, AuxiliaryData, AuxiliaryDataHash, AuxiliaryDataSet, BaseAddress, BigInt, BigNum, Bip32PrivateKey, Bip32PublicKey, Block, BlockEra, BlockHash, BootstrapWitness, BootstrapWitnesses, ByronAddress, ByronAddressType, CborContainerType, CborSetType, Certificate, CertificateKind, Certificates, CertificatesBuilder, ChangeConfig, CoinSelectionStrategyCIP2, Committee, CommitteeColdResign, CommitteeHotAuth, Constitution, ConstrPlutusData, CostModel, Costmdls, CredKind, Credential, Credentials, DNSRecordAorAAAA, DNSRecordSRV, DRep, DRepDeregistration, DRepKind, DRepRegistration, DRepUpdate, DRepVotingThresholds, DataCost, DataHash, DatumSource, Ed25519KeyHash, Ed25519KeyHashes, Ed25519Signature, EnterpriseAddress, ExUnitPrices, ExUnits, FixedBlock, FixedTransaction, FixedTransactionBodies, FixedTransactionBody, FixedTxWitnessesSet, FixedVersionedBlock, GeneralTransactionMetadata, GenesisDelegateHash, GenesisHash, GenesisHashes, GenesisKeyDelegation, GovernanceAction, GovernanceActionId, GovernanceActionIds, GovernanceActionKind, HardForkInitiationAction, Header, HeaderBody, InfoAction, Int, Ipv4, Ipv6, KESSignature, KESVKey, Language, LanguageKind, Languages, LegacyDaedalusPrivateKey, LinearFee, MIRKind, MIRPot, MIRToStakeCredentials, MalformedAddress, MetadataJsonSchema, MetadataList, MetadataMap, Mint, MintAssets, MintBuilder, MintWitness, MintsAssets, MoveInstantaneousReward, MoveInstantaneousRewardsCert, MultiAsset, MultiHostName, NativeScript, NativeScriptKind, NativeScriptSource, NativeScripts, NetworkId, NetworkIdKind, NetworkInfo, NewConstitutionAction, NoConfidenceAction, Nonce, OperationalCert, OutputDatum, ParameterChangeAction, PlutusData, PlutusDataKind, PlutusDatumSchema, PlutusList, PlutusMap, PlutusMapValues, PlutusScript, PlutusScriptSource, PlutusScripts, PlutusWitness, PlutusWitnesses, Pointer, PointerAddress, PoolMetadata, PoolMetadataHash, PoolParams, PoolRegistration, PoolRetirement, PoolVotingThresholds, PrivateKey, ProposedProtocolParameterUpdates, ProtocolParamUpdate, ProtocolVersion, PublicKey, PublicKeys, Redeemer, RedeemerTag, RedeemerTagKind, Redeemers, Relay, RelayKind, Relays, RewardAddress, RewardAddresses, ScriptAll, ScriptAny, ScriptDataHash, ScriptHash, ScriptHashNamespace, ScriptHashes, ScriptNOfK, ScriptPubkey, ScriptRef, ScriptSchema, SingleHostAddr, SingleHostName, StakeAndVoteDelegation, StakeDelegation, StakeDeregistration, StakeRegistration, StakeRegistrationAndDelegation, StakeVoteRegistrationAndDelegation, Strings, TimelockExpiry, TimelockStart, Transaction, TransactionBatch, TransactionBatchList, TransactionBodies, TransactionBody, TransactionBuilder, TransactionBuilderConfig, TransactionBuilderConfigBuilder, TransactionHash, TransactionInput, TransactionInputs, TransactionMetadatum, TransactionMetadatumKind, TransactionMetadatumLabels, TransactionOutput, TransactionOutputAmountBuilder, TransactionOutputBuilder, TransactionOutputs, TransactionSetsState, TransactionUnspentOutput, TransactionUnspentOutputs, TransactionWitnessSet, TransactionWitnessSets, TreasuryWithdrawals, TreasuryWithdrawalsAction, TxInputsBuilder, URL, UnitInterval, Update, UpdateCommitteeAction, VRFCert, VRFKeyHash, VRFVKey, Value, VersionedBlock, Vkey, Vkeys, Vkeywitness, Vkeywitnesses, VoteDelegation, VoteKind, VoteRegistrationAndDelegation, Voter, VoterKind, Voters, VotingBuilder, VotingProcedure, VotingProcedures, VotingProposal, VotingProposalBuilder, VotingProposals, Withdrawals, WithdrawalsBuilder, calculate_ex_units_ceil_cost, cbor_to_json, cddl_format, cddl_from_str, cddl_outline, cddl_references, cddl_symbol_at, check_block_or_tx_signatures, create_send_all, decode_arbitrary_bytes_from_metadatum, decode_cbor_against_cddl, decode_metadatum_to_json_str, decode_plutus_datum_to_json_str, decode_plutus_program_pretty_uplc, decode_plutus_program_uplc_json, decode_specific_type, decrypt_with_password, encode_arbitrary_bytes_as_metadatum, encode_json_str_to_metadatum, encode_json_str_to_native_script, encode_json_str_to_plutus_datum, encrypt_with_password, execute_tx_scripts, extract_hashes_from_transaction_js, get_decodable_types, get_deposit, get_implicit_input, get_necessary_data_list_js, get_possible_types_for_input, get_ref_script_bytes, get_utxo_list_from_tx, has_transaction_set_tag, hash_auxiliary_data, hash_plutus_data, hash_script_data, make_daedalus_bootstrap_witness, make_icarus_bootstrap_witness, make_vkey_witness, min_ada_for_output, min_fee, min_ref_script_fee, min_script_fee, validate_cbor_against_cddl, validate_cbor_from_slice, validate_cddl, validate_cddl_from_str, validate_json_from_str, validate_transaction_js
+    Address, AddressKind, Anchor, AnchorDataHash, AssetName, AssetNames, Assets, AuxiliaryData, AuxiliaryDataHash, AuxiliaryDataSet, BaseAddress, BigInt, BigNum, Bip32PrivateKey, Bip32PublicKey, Block, BlockEra, BlockHash, BootstrapWitness, BootstrapWitnesses, ByronAddress, ByronAddressType, CborContainerType, CborSetType, Certificate, CertificateKind, Certificates, CertificatesBuilder, ChangeConfig, CoinSelectionStrategyCIP2, Committee, CommitteeColdResign, CommitteeHotAuth, Constitution, ConstrPlutusData, CostModel, Costmdls, CredKind, Credential, Credentials, DNSRecordAorAAAA, DNSRecordSRV, DRep, DRepDeregistration, DRepKind, DRepRegistration, DRepUpdate, DRepVotingThresholds, DataCost, DataHash, DatumSource, Ed25519KeyHash, Ed25519KeyHashes, Ed25519Signature, EnterpriseAddress, ExUnitPrices, ExUnits, FixedBlock, FixedTransaction, FixedTransactionBodies, FixedTransactionBody, FixedTxWitnessesSet, FixedVersionedBlock, GeneralTransactionMetadata, GenesisDelegateHash, GenesisHash, GenesisHashes, GenesisKeyDelegation, GovernanceAction, GovernanceActionId, GovernanceActionIds, GovernanceActionKind, HardForkInitiationAction, Header, HeaderBody, InfoAction, Int, Ipv4, Ipv6, KESSignature, KESVKey, Language, LanguageKind, Languages, LegacyDaedalusPrivateKey, LinearFee, MIRKind, MIRPot, MIRToStakeCredentials, MalformedAddress, MetadataJsonSchema, MetadataList, MetadataMap, Mint, MintAssets, MintBuilder, MintWitness, MintsAssets, MoveInstantaneousReward, MoveInstantaneousRewardsCert, MultiAsset, MultiHostName, NativeScript, NativeScriptKind, NativeScriptSource, NativeScripts, NetworkId, NetworkIdKind, NetworkInfo, NewConstitutionAction, NoConfidenceAction, Nonce, OperationalCert, OutputDatum, ParameterChangeAction, PlutusData, PlutusDataKind, PlutusDatumSchema, PlutusList, PlutusMap, PlutusMapValues, PlutusScript, PlutusScriptSource, PlutusScripts, PlutusWitness, PlutusWitnesses, Pointer, PointerAddress, PoolMetadata, PoolMetadataHash, PoolParams, PoolRegistration, PoolRetirement, PoolVotingThresholds, PrivateKey, ProposedProtocolParameterUpdates, ProtocolParamUpdate, ProtocolVersion, PublicKey, PublicKeys, Redeemer, RedeemerTag, RedeemerTagKind, Redeemers, Relay, RelayKind, Relays, RewardAddress, RewardAddresses, ScriptAll, ScriptAny, ScriptDataHash, ScriptHash, ScriptHashNamespace, ScriptHashes, ScriptNOfK, ScriptPubkey, ScriptRef, ScriptSchema, SingleHostAddr, SingleHostName, StakeAndVoteDelegation, StakeDelegation, StakeDeregistration, StakeRegistration, StakeRegistrationAndDelegation, StakeVoteRegistrationAndDelegation, Strings, TimelockExpiry, TimelockStart, Transaction, TransactionBatch, TransactionBatchList, TransactionBodies, TransactionBody, TransactionBuilder, TransactionBuilderConfig, TransactionBuilderConfigBuilder, TransactionHash, TransactionInput, TransactionInputs, TransactionMetadatum, TransactionMetadatumKind, TransactionMetadatumLabels, TransactionOutput, TransactionOutputAmountBuilder, TransactionOutputBuilder, TransactionOutputs, TransactionSetsState, TransactionUnspentOutput, TransactionUnspentOutputs, TransactionWitnessSet, TransactionWitnessSets, TreasuryWithdrawals, TreasuryWithdrawalsAction, TxInputsBuilder, URL, UnitInterval, Update, UpdateCommitteeAction, VRFCert, VRFKeyHash, VRFVKey, Value, VersionedBlock, Vkey, Vkeys, Vkeywitness, Vkeywitnesses, VoteDelegation, VoteKind, VoteRegistrationAndDelegation, Voter, VoterKind, Voters, VotingBuilder, VotingProcedure, VotingProcedures, VotingProposal, VotingProposalBuilder, VotingProposals, Withdrawals, WithdrawalsBuilder, calculate_ex_units_ceil_cost, cbor_to_json, cddl_format, cddl_from_str, cddl_outline, cddl_references, cddl_symbol_at, check_block_or_tx_signatures, create_send_all, decode_arbitrary_bytes_from_metadatum, decode_cbor_against_cddl, decode_metadatum_to_json_str, decode_plutus_datum_to_json_str, decode_plutus_program_pretty_uplc, decode_plutus_program_uplc_json, decode_specific_type, decrypt_with_password, encode_arbitrary_bytes_as_metadatum, encode_json_str_to_metadatum, encode_json_str_to_native_script, encode_json_str_to_plutus_datum, encrypt_with_password, execute_tx_scripts, extract_hashes_from_transaction_js, get_decodable_types, get_deposit, get_implicit_input, get_necessary_data_list_js, get_possible_types_for_input, get_ref_script_bytes, get_utxo_list_from_tx, has_transaction_set_tag, hash_auxiliary_data, hash_plutus_data, hash_script_data, make_daedalus_bootstrap_witness, make_icarus_bootstrap_witness, make_vkey_witness, map_cbor_to_cddl, min_ada_for_output, min_fee, min_ref_script_fee, min_script_fee, validate_cbor_against_cddl, validate_cbor_from_slice, validate_cddl, validate_cddl_from_str, validate_json_from_str, validate_transaction_js
 } from "./cquisitor_lib_bg.js";

package/browser/cquisitor_lib_bg.js

@@ -29149,6 +29149,31 @@ export function make_vkey_witness(tx_body_hash, sk) {
     return Vkeywitness.__wrap(ret);
 }
 
+/**
+ * Returns a flat list of `{cbor_path, cbor_byte_span, cbor_anchor_span,
+ * cddl_byte_span, rule_name?}` entries — one per node visited during a
+ * parallel CBOR ↔ CDDL traversal. Use it to wire bidirectional
+ * highlight between a CBOR panel and a CDDL panel without needing a
+ * validation error to trigger it.
+ * @param {string} cbor_hex
+ * @param {string} cddl
+ * @param {string} rule_name
+ * @returns {any}
+ */
+export function map_cbor_to_cddl(cbor_hex, cddl, rule_name) {
+    const ptr0 = passStringToWasm0(cbor_hex, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(cddl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ptr2 = passStringToWasm0(rule_name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len2 = WASM_VECTOR_LEN;
+    const ret = wasm.map_cbor_to_cddl(ptr0, len0, ptr1, len1, ptr2, len2);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * returns minimal amount of ada for the output for case when the amount is included to the output
  * @param {TransactionOutput} output

package/browser/cquisitor_lib_bg.wasm.d.ts

@@ -7,20 +7,21 @@ export const get_possible_types_for_input: (a: number, b: number) => [number, nu
 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];
+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];
 export const cddl_references: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const cddl_symbol_at: (a: number, b: number, c: number) => [number, number, number];
 export const decode_cbor_against_cddl: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+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 validate_cbor_from_slice: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_json_from_str: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const cddl_from_str: (a: number, b: 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[];
 }
 
 /**
@@ -232,6 +256,59 @@ export function cddl_symbol_at(cddl: string, offset: number): CddlSymbolAtResult
  */
 export function cddl_format(cddl: string): string;
 
+/** One entry from `map_cbor_to_cddl`: a single position of a CBOR
+ *  node, the type that matched it, and the path it ends up at in the
+ *  output of `decode_cbor_against_cddl`. */
+export interface CborCddlMapEntry {
+    /** Path into the *raw* CBOR tree (numeric map keys are bracketed). */
+    cbor_path: string;
+    /** Path into the labelled JSON returned by `decode_cbor_against_cddl`.
+     *  Numeric map keys come back as bracket-quoted strings (`["0"]`)
+     *  because decoded JSON has only string keys; identifier-safe keys
+     *  use dot notation (`.name`). For unspecialised tags (anything
+     *  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: 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`, …). */
+    cbor_type?: string;
+}
+
+/**
+ * Returns a flat list of mapping entries pairing each visited CBOR node
+ * with the CDDL position that describes it. Use it to wire
+ * bidirectional highlight between a CBOR panel and a CDDL panel without
+ * needing a validation error to trigger it.
+ *
+ * Order is depth-first pre-order, so a parent's entry precedes its
+ * children's. Tags in the CBOR are transparent to the path grammar
+ * (anweiss-style): `Tag(258, [...])` is walked as if the tag wrapper
+ * weren't there when matching against `[* a]`-shaped schemas.
+ *
+ * @param cbor_hex
+ * @param cddl
+ * @param rule_name
+ */
+export function map_cbor_to_cddl(
+    cbor_hex: string,
+    cddl: string,
+    rule_name: string
+): CborCddlMapEntry[];
+
 /**
  * Maps decoded CBOR onto a CDDL schema and returns labelled JSON. Where
  * `cbor_to_json` returns positional CBOR (numeric map keys, raw arrays),
@@ -473,7 +550,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 =
@@ -507,7 +584,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.js

@@ -29412,6 +29412,32 @@ function make_vkey_witness(tx_body_hash, sk) {
 }
 exports.make_vkey_witness = make_vkey_witness;
 
+/**
+ * Returns a flat list of `{cbor_path, cbor_byte_span, cbor_anchor_span,
+ * cddl_byte_span, rule_name?}` entries — one per node visited during a
+ * parallel CBOR ↔ CDDL traversal. Use it to wire bidirectional
+ * highlight between a CBOR panel and a CDDL panel without needing a
+ * validation error to trigger it.
+ * @param {string} cbor_hex
+ * @param {string} cddl
+ * @param {string} rule_name
+ * @returns {any}
+ */
+function map_cbor_to_cddl(cbor_hex, cddl, rule_name) {
+    const ptr0 = passStringToWasm0(cbor_hex, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(cddl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ptr2 = passStringToWasm0(rule_name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len2 = WASM_VECTOR_LEN;
+    const ret = wasm.map_cbor_to_cddl(ptr0, len0, ptr1, len1, ptr2, len2);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.map_cbor_to_cddl = map_cbor_to_cddl;
+
 /**
  * returns minimal amount of ada for the output for case when the amount is included to the output
  * @param {TransactionOutput} output

package/node/cquisitor_lib_bg.wasm.d.ts

@@ -7,20 +7,21 @@ export const get_possible_types_for_input: (a: number, b: number) => [number, nu
 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];
+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];
 export const cddl_references: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const cddl_symbol_at: (a: number, b: number, c: number) => [number, number, number];
 export const decode_cbor_against_cddl: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+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 validate_cbor_from_slice: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const validate_json_from_str: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
 export const cddl_from_str: (a: number, b: 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.51",
+  "version": "0.1.0-beta.53",
   "license": "Apache-2.0",
   "files": [
     "node/cquisitor_lib_bg.wasm",