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

package/README.md

@@ -25,9 +25,13 @@ Functions:
 ### CBOR Decoder & CDDL Validation
 
 - `cbor_to_json(cbor_hex)` - Converts raw CBOR to JSON with positional information, supporting indefinite arrays/maps and all CBOR types. Each node carries an optional `oddities` array flagging deviations from RFC 8949 deterministic encoding (overlong integers/floats, indefinite length, unsorted/duplicate map keys, non-canonical bignums). Never throws on malformed input — returns a `{ok, value}` / `{ok: false, error, partial?}` union where `error` is a structured `CborDecodeError` (kind / byte offset / byte span / semantic `path`) and `partial` is the sub-tree decoded before the failure, with every unfinished container flagged `incomplete: true`.
-- `validate_cddl(cddl)` - Parses a CDDL schema; reports parse errors and unresolved rule references (e.g. `thing = [unknown_rule, int]` → `kind: "unresolved_references"`).
-- `validate_cbor_against_cddl(cbor_hex, cddl, rule_name)` - Validates a CBOR payload against a named rule. Errors carry `kind`, `expected`, semantic `path`, byte/anchor spans, and an `additional` array when multiple violations fire.
+- `validate_cddl(cddl)` - Parses a CDDL schema; reports parse errors (with a `byte_span` for editor squiggles) and unresolved rule references (e.g. `thing = [unknown_rule, int]` → `kind: "unresolved_references"`).
+- `validate_cbor_against_cddl(cbor_hex, cddl, rule_name)` - Validates a CBOR payload against a named rule. Errors carry `kind`, `expected`, semantic `path`, byte/anchor spans, a `cddl_byte_span` pointing at the failing CDDL type, and an `additional` array when multiple violations fire.
 - `decode_cbor_against_cddl(cbor_hex, cddl, rule_name)` - Maps decoded CBOR onto a CDDL schema and returns labelled JSON (e.g. Cardano `[body, witness_set, bool, aux]` becomes `{transaction_body, transaction_witness_set, ...}`). Handles generics (`set<a>`), tagged sets, type rules used as field labels, and a few well-known tags (bignum → string number, datetime → ISO string). Sub-structures the schema doesn't cover surface under `@extra` / `@positional` so partial matches don't lose data.
+- `cddl_outline(cddl)` - Returns one `{name, kind, span, name_span}` entry per top-level rule. Editor outline view, breadcrumbs, fuzzy "go to rule".
+- `cddl_references(cddl, name)` - Returns `{definition, uses[]}` byte ranges for a rule name. Powers find-references and same-name highlighting on cursor.
+- `cddl_symbol_at(cddl, offset)` - Returns the symbol under the cursor (or `null`), with `role: "definition" | "use"` and a `definition_span` pointing at its rule. Powers hover and Cmd-click go-to-definition.
+- `cddl_format(cddl)` - Pretty-prints CDDL by round-tripping through the AST. Useful for format-on-save.
 
 ### Plutus Script Decoder
 
@@ -366,11 +370,14 @@ validate_cbor_against_cddl("01", "thing = tstr", "thing");
 //     expected: "tstr",
 //     path: "$",
 //     byte_spans: [{ offset: 0, length: 1 }],
+//     cddl_byte_span: { offset: 8, length: 4, line: 1 },  // points at `tstr`
 //     message: "expected type tstr, got Integer(Integer(1))"
 //   }
 // }
 ```
 
+`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`.
 
 #### `decode_cbor_against_cddl(cbor_hex: string, cddl: string, rule_name: string): unknown`
@@ -395,6 +402,48 @@ decode_cbor_against_cddl(txHex, conwayCddl, "transaction");
 
 Recognised features: type choices (first match wins), generics (`set<a>`), tagged data (well-known tags 0/2/3 specialised to ISO date / bignum string), rule references, optionals/repetitions, prelude scalars. Sub-structures the schema doesn't cover or that don't match any choice fall back to a raw form under `@extra` (maps) or `@positional` (arrays) so data is never silently dropped.
 
+#### CDDL editor primitives
+
+For embedding a CDDL editor / inspector. All four functions parse the document with the same checked parser as `validate_cddl` and throw on parse errors.
+
+```typescript
+// Document outline — list every rule with its byte range.
+cddl_outline("alpha = uint\nbeta = (a: int)");
+// [
+//   {name: "alpha", kind: "type",  span: {offset: 0,  length: 12, line: 1},
+//                                  name_span: {offset: 0, length: 5, line: 1}},
+//   {name: "beta",  kind: "group", span: {offset: 13, length: 14, line: 2},
+//                                  name_span: {offset: 13, length: 4, line: 2}}
+// ]
+
+// Find every use of a rule — the IDE "Find references" affordance.
+cddl_references("coin = uint\noutput = [bstr, coin]\nfee = coin", "coin");
+// {definition: {offset: 0, length: 4, line: 1},
+//  uses: [
+//    {offset: 26, length: 4, line: 2},
+//    {offset: 38, length: 4, line: 3}
+//  ]}
+
+// Symbol at cursor — hover info and Cmd-click target.
+cddl_symbol_at("coin = uint\nfee = coin", /* offset = */ 18);
+// {name: "coin", kind: "rule_reference", role: "use",
+//  span: {offset: 18, length: 4, line: 2},
+//  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"
+```
+
+`validate_cddl` itself returns a `byte_span` on parser errors so editor-side squiggles can underline the offending position directly:
+
+```typescript
+validate_cddl("alpha = ");
+// {valid: false,
+//  error: {kind: "parse_error", message: "...", byte_span: {offset: 8, length: 0, line: 1}}}
+```
+
 ### Plutus Script Decoder
 
 #### `decode_plutus_program_uplc_json(hex: string): ProgramJson`

package/browser/cquisitor_lib.d.ts

@@ -171,6 +171,67 @@ export function validate_cbor_against_cddl(
     rule_name: string
 ): CborValidationResult;
 
+/** Outline entry — one rule from `cddl_outline`. */
+export interface CddlOutlineEntry {
+    /** Rule name (`transaction_body`, `set`, …). */
+    name: string;
+    /** `"type"` for `=`, `"group"` for `( … )`. */
+    kind: "type" | "group";
+    /** Byte range covering the whole `name = …` rule definition. */
+    span: { offset: number; length: number; line: number };
+    /** Byte range of just the rule's name identifier. */
+    name_span: { offset: number; length: number; line: number };
+}
+
+/** Result of `cddl_symbol_at`. `null` when the cursor isn't on an identifier. */
+export type CddlSymbolAtResult =
+    | null
+    | {
+          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;
+      };
+
+/** Result of `cddl_references`. */
+export interface CddlReferencesResult {
+    definition: { offset: number; length: number; line: number } | null;
+    uses: { offset: number; length: number; line: number }[];
+}
+
+/**
+ * Returns one entry per top-level rule (`{name, kind, span, name_span}`).
+ * Used for editor outline view, breadcrumbs, fuzzy "go to rule".
+ * @param cddl
+ */
+export function cddl_outline(cddl: string): CddlOutlineEntry[];
+
+/**
+ * Returns `{definition, uses[]}` byte ranges for the rule named `name`.
+ * Powers find-references and rename-aware highlighting.
+ * @param cddl
+ * @param name
+ */
+export function cddl_references(cddl: string, name: string): CddlReferencesResult;
+
+/**
+ * Returns the symbol under `offset` (or `null` if none). For uses,
+ * `definition_span` points at the rule's name — the "go to definition"
+ * target.
+ * @param cddl
+ * @param offset
+ */
+export function cddl_symbol_at(cddl: string, offset: number): CddlSymbolAtResult;
+
+/**
+ * Pretty-prints the CDDL by parsing it and serialising via `Display`.
+ * Useful for "format on save". Throws on invalid input.
+ * @param cddl
+ */
+export function cddl_format(cddl: string): string;
+
 /**
  * Maps decoded CBOR onto a CDDL schema and returns labelled JSON. Where
  * `cbor_to_json` returns positional CBOR (numeric map keys, raw arrays),
@@ -408,6 +469,11 @@ export type CddlValidationResult =
 export interface CddlErrorInfo {
     kind: string;
     message: string;
+    /**
+     * 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 };
 }
 
 export type CborValidationResult =
@@ -418,6 +484,7 @@ export type CborValidationResult =
  * `kind` categorises the failure:
  *  - "parse_error" — the CDDL itself failed to parse
  *  - "unresolved_references" — the CDDL references a rule name that isn't defined
+ *  - "no_rules" — the CDDL parsed but defined no rules (empty / comment-only document)
  *  - "missing_rule" — the rule name passed to `validate_cbor_against_cddl` is not in the CDDL
  *  - "input_parse" — the CBOR bytes themselves are malformed
  *  - "mismatch" / "map_cut" — a data mismatch; inspect `expected`, `path`,
@@ -428,9 +495,21 @@ export interface CborValidationErrorInfo {
     kind: string;
     message: string;
     expected?: string;
+    /** Semantic path into the CBOR (e.g. `$.b[0]`). */
     path?: string;
+    /** Byte range in the CBOR input that triggered the error. */
     byte_spans?: CborPosition[];
+    /** Byte range covering the whole containing CBOR structure. */
     anchor_spans?: CborPosition[];
+    /**
+     * Byte range in the CDDL **source** pointing at the type the
+     * validator tried to apply when it failed (synthesised by walking
+     * the AST in parallel with `path`). Useful for highlighting the
+     * offending CDDL rule in editors.
+     */
+    cddl_byte_span?: { offset: number; length: number; line: number };
+    /** Other validation errors reported in the same run. */
+    additional?: CborValidationErrorInfo[];
 }
 
 export interface DecodingParams {

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_from_str, 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, 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

@@ -28456,6 +28456,34 @@ export function cbor_to_json(cbor_hex) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Re-format the CDDL document by parsing and serialising via `Display`.
+ * Useful for "format on save". Returns the parse error message on
+ * invalid input.
+ * @param {string} cddl
+ * @returns {string}
+ */
+export function cddl_format(cddl) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(cddl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.cddl_format(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Returns a `ast::CDDL` wrapped in `JsValue` from a `&str`
  *
@@ -28488,6 +28516,61 @@ export function cddl_from_str(input) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Returns `[{name, kind, span, name_span}]` for every top-level rule
+ * in the CDDL document. Use it for editor outline / breadcrumbs /
+ * fuzzy-pick-rule navigation.
+ * @param {string} cddl
+ * @returns {any}
+ */
+export function cddl_outline(cddl) {
+    const ptr0 = passStringToWasm0(cddl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.cddl_outline(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Returns `{definition: span | null, uses: span[]}` for the rule
+ * `name`. Powers find-references and rename-aware highlighting.
+ * @param {string} cddl
+ * @param {string} name
+ * @returns {any}
+ */
+export function cddl_references(cddl, name) {
+    const ptr0 = passStringToWasm0(cddl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.cddl_references(ptr0, len0, ptr1, len1);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Returns the symbol under `offset` (`null` if the cursor isn't on an
+ * identifier), with `role: "definition" | "use"`, `kind`, `span`, and
+ * `definition_span` (the rule's name span — the go-to-definition
+ * target).
+ * @param {string} cddl
+ * @param {number} offset
+ * @returns {any}
+ */
+export function cddl_symbol_at(cddl, offset) {
+    const ptr0 = passStringToWasm0(cddl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.cddl_symbol_at(ptr0, len0, offset);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * @param {string} hex_str
  * @returns {any}
@@ -29389,6 +29472,17 @@ export function __wbg_entries_e0b73aa8571ddb56(arg0) {
     const ret = Object.entries(arg0);
     return ret;
 }
+export function __wbg_error_a6fa202b58aa1cd3(arg0, arg1) {
+    let deferred0_0;
+    let deferred0_1;
+    try {
+        deferred0_0 = arg0;
+        deferred0_1 = arg1;
+        console.error(getStringFromWasm0(arg0, arg1));
+    } finally {
+        wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
+    }
+}
 export function __wbg_getRandomValues_112147a6595454ff(arg0) {
     const ret = arg0.getRandomValues;
     return ret;
@@ -29463,6 +29557,10 @@ export function __wbg_new_0c7403db6e782f19(arg0) {
     const ret = new Uint8Array(arg0);
     return ret;
 }
+export function __wbg_new_227d7c05414eb861() {
+    const ret = new Error();
+    return ret;
+}
 export function __wbg_new_34d45cc8e36aaead() {
     const ret = new Map();
     return ret;
@@ -29533,6 +29631,13 @@ export function __wbg_set_fde2cec06c23692b(arg0, arg1, arg2) {
     const ret = arg0.set(arg1, arg2);
     return ret;
 }
+export function __wbg_stack_3b0d974bbf31e44f(arg0, arg1) {
+    const ret = arg1.stack;
+    const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}
 export function __wbg_static_accessor_GLOBAL_8cfadc87a297ca02() {
     const ret = typeof global === 'undefined' ? null : global;
     return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);

package/browser/cquisitor_lib_bg.wasm.d.ts

@@ -4,13 +4,17 @@ 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 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 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 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 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 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];
@@ -2446,7 +2450,7 @@ export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) =>
 export const __wbindgen_exn_store: (a: number) => void;
 export const __externref_table_alloc: () => number;
 export const __wbindgen_externrefs: WebAssembly.Table;
-export const __externref_table_dealloc: (a: number) => void;
 export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __externref_table_dealloc: (a: number) => void;
 export const __externref_drop_slice: (a: number, b: number) => void;
 export const __wbindgen_start: () => void;

package/node/cquisitor_lib.d.ts

@@ -171,6 +171,67 @@ export function validate_cbor_against_cddl(
     rule_name: string
 ): CborValidationResult;
 
+/** Outline entry — one rule from `cddl_outline`. */
+export interface CddlOutlineEntry {
+    /** Rule name (`transaction_body`, `set`, …). */
+    name: string;
+    /** `"type"` for `=`, `"group"` for `( … )`. */
+    kind: "type" | "group";
+    /** Byte range covering the whole `name = …` rule definition. */
+    span: { offset: number; length: number; line: number };
+    /** Byte range of just the rule's name identifier. */
+    name_span: { offset: number; length: number; line: number };
+}
+
+/** Result of `cddl_symbol_at`. `null` when the cursor isn't on an identifier. */
+export type CddlSymbolAtResult =
+    | null
+    | {
+          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;
+      };
+
+/** Result of `cddl_references`. */
+export interface CddlReferencesResult {
+    definition: { offset: number; length: number; line: number } | null;
+    uses: { offset: number; length: number; line: number }[];
+}
+
+/**
+ * Returns one entry per top-level rule (`{name, kind, span, name_span}`).
+ * Used for editor outline view, breadcrumbs, fuzzy "go to rule".
+ * @param cddl
+ */
+export function cddl_outline(cddl: string): CddlOutlineEntry[];
+
+/**
+ * Returns `{definition, uses[]}` byte ranges for the rule named `name`.
+ * Powers find-references and rename-aware highlighting.
+ * @param cddl
+ * @param name
+ */
+export function cddl_references(cddl: string, name: string): CddlReferencesResult;
+
+/**
+ * Returns the symbol under `offset` (or `null` if none). For uses,
+ * `definition_span` points at the rule's name — the "go to definition"
+ * target.
+ * @param cddl
+ * @param offset
+ */
+export function cddl_symbol_at(cddl: string, offset: number): CddlSymbolAtResult;
+
+/**
+ * Pretty-prints the CDDL by parsing it and serialising via `Display`.
+ * Useful for "format on save". Throws on invalid input.
+ * @param cddl
+ */
+export function cddl_format(cddl: string): string;
+
 /**
  * Maps decoded CBOR onto a CDDL schema and returns labelled JSON. Where
  * `cbor_to_json` returns positional CBOR (numeric map keys, raw arrays),
@@ -408,6 +469,11 @@ export type CddlValidationResult =
 export interface CddlErrorInfo {
     kind: string;
     message: string;
+    /**
+     * 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 };
 }
 
 export type CborValidationResult =
@@ -418,6 +484,7 @@ export type CborValidationResult =
  * `kind` categorises the failure:
  *  - "parse_error" — the CDDL itself failed to parse
  *  - "unresolved_references" — the CDDL references a rule name that isn't defined
+ *  - "no_rules" — the CDDL parsed but defined no rules (empty / comment-only document)
  *  - "missing_rule" — the rule name passed to `validate_cbor_against_cddl` is not in the CDDL
  *  - "input_parse" — the CBOR bytes themselves are malformed
  *  - "mismatch" / "map_cut" — a data mismatch; inspect `expected`, `path`,
@@ -428,9 +495,21 @@ export interface CborValidationErrorInfo {
     kind: string;
     message: string;
     expected?: string;
+    /** Semantic path into the CBOR (e.g. `$.b[0]`). */
     path?: string;
+    /** Byte range in the CBOR input that triggered the error. */
     byte_spans?: CborPosition[];
+    /** Byte range covering the whole containing CBOR structure. */
     anchor_spans?: CborPosition[];
+    /**
+     * Byte range in the CDDL **source** pointing at the type the
+     * validator tried to apply when it failed (synthesised by walking
+     * the AST in parallel with `path`). Useful for highlighting the
+     * offending CDDL rule in editors.
+     */
+    cddl_byte_span?: { offset: number; length: number; line: number };
+    /** Other validation errors reported in the same run. */
+    additional?: CborValidationErrorInfo[];
 }
 
 export interface DecodingParams {

package/node/cquisitor_lib.js

@@ -28683,6 +28683,35 @@ function cbor_to_json(cbor_hex) {
 }
 exports.cbor_to_json = cbor_to_json;
 
+/**
+ * Re-format the CDDL document by parsing and serialising via `Display`.
+ * Useful for "format on save". Returns the parse error message on
+ * invalid input.
+ * @param {string} cddl
+ * @returns {string}
+ */
+function cddl_format(cddl) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(cddl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.cddl_format(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+exports.cddl_format = cddl_format;
+
 /**
  * Returns a `ast::CDDL` wrapped in `JsValue` from a `&str`
  *
@@ -28716,6 +28745,64 @@ function cddl_from_str(input) {
 }
 exports.cddl_from_str = cddl_from_str;
 
+/**
+ * Returns `[{name, kind, span, name_span}]` for every top-level rule
+ * in the CDDL document. Use it for editor outline / breadcrumbs /
+ * fuzzy-pick-rule navigation.
+ * @param {string} cddl
+ * @returns {any}
+ */
+function cddl_outline(cddl) {
+    const ptr0 = passStringToWasm0(cddl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.cddl_outline(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.cddl_outline = cddl_outline;
+
+/**
+ * Returns `{definition: span | null, uses: span[]}` for the rule
+ * `name`. Powers find-references and rename-aware highlighting.
+ * @param {string} cddl
+ * @param {string} name
+ * @returns {any}
+ */
+function cddl_references(cddl, name) {
+    const ptr0 = passStringToWasm0(cddl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.cddl_references(ptr0, len0, ptr1, len1);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.cddl_references = cddl_references;
+
+/**
+ * Returns the symbol under `offset` (`null` if the cursor isn't on an
+ * identifier), with `role: "definition" | "use"`, `kind`, `span`, and
+ * `definition_span` (the rule's name span — the go-to-definition
+ * target).
+ * @param {string} cddl
+ * @param {number} offset
+ * @returns {any}
+ */
+function cddl_symbol_at(cddl, offset) {
+    const ptr0 = passStringToWasm0(cddl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.cddl_symbol_at(ptr0, len0, offset);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.cddl_symbol_at = cddl_symbol_at;
+
 /**
  * @param {string} hex_str
  * @returns {any}
@@ -29661,6 +29748,17 @@ function __wbg_get_imports() {
             const ret = Object.entries(arg0);
             return ret;
         },
+        __wbg_error_a6fa202b58aa1cd3: function(arg0, arg1) {
+            let deferred0_0;
+            let deferred0_1;
+            try {
+                deferred0_0 = arg0;
+                deferred0_1 = arg1;
+                console.error(getStringFromWasm0(arg0, arg1));
+            } finally {
+                wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
+            }
+        },
         __wbg_getRandomValues_112147a6595454ff: function(arg0) {
             const ret = arg0.getRandomValues;
             return ret;
@@ -29735,6 +29833,10 @@ function __wbg_get_imports() {
             const ret = new Uint8Array(arg0);
             return ret;
         },
+        __wbg_new_227d7c05414eb861: function() {
+            const ret = new Error();
+            return ret;
+        },
         __wbg_new_34d45cc8e36aaead: function() {
             const ret = new Map();
             return ret;
@@ -29805,6 +29907,13 @@ function __wbg_get_imports() {
             const ret = arg0.set(arg1, arg2);
             return ret;
         },
+        __wbg_stack_3b0d974bbf31e44f: function(arg0, arg1) {
+            const ret = arg1.stack;
+            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
         __wbg_static_accessor_GLOBAL_8cfadc87a297ca02: function() {
             const ret = typeof global === 'undefined' ? null : global;
             return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);

package/node/cquisitor_lib_bg.wasm.d.ts

@@ -4,13 +4,17 @@ 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 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 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 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 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 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];
@@ -2446,7 +2450,7 @@ export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) =>
 export const __wbindgen_exn_store: (a: number) => void;
 export const __externref_table_alloc: () => number;
 export const __wbindgen_externrefs: WebAssembly.Table;
-export const __externref_table_dealloc: (a: number) => void;
 export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __externref_table_dealloc: (a: number) => void;
 export const __externref_drop_slice: (a: number, b: number) => void;
 export const __wbindgen_start: () => void;

package/package.json

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