@k67/kaitai-struct-ts 0.9.0 → 0.10.0

package/dist/index.mjs

@@ -1,29 +1,67 @@
 // src/utils/errors.ts
 var KaitaiError = class _KaitaiError extends Error {
-  constructor(message, position) {
-    super(message);
+  constructor(message, position, context) {
+    super(_KaitaiError.formatMessage(message, position, context));
     this.position = position;
+    this.context = context;
     this.name = "KaitaiError";
     Object.setPrototypeOf(this, _KaitaiError.prototype);
   }
+  /**
+   * Format error message with position and context.
+   * @private
+   */
+  static formatMessage(message, position, context) {
+    let formatted = message;
+    if (position !== void 0) {
+      formatted += ` (at byte offset 0x${position.toString(16).toUpperCase()})`;
+    }
+    if (context && context.length > 0) {
+      const hexContext = _KaitaiError.formatHexContext(context, position);
+      formatted += `
+${hexContext}`;
+    }
+    return formatted;
+  }
+  /**
+   * Format hex dump context around error position.
+   * @private
+   */
+  static formatHexContext(data, position) {
+    const contextSize = 16;
+    const start = Math.max(0, (position ?? 0) - contextSize);
+    const end = Math.min(data.length, (position ?? 0) + contextSize);
+    const chunk = data.slice(start, end);
+    const lines = ["Context:"];
+    let offset = start;
+    for (let i = 0; i < chunk.length; i += 16) {
+      const lineBytes = chunk.slice(i, i + 16);
+      const hex = Array.from(lineBytes).map((b) => b.toString(16).padStart(2, "0")).join(" ");
+      const ascii = Array.from(lineBytes).map((b) => b >= 32 && b <= 126 ? String.fromCharCode(b) : ".").join("");
+      const offsetStr = `  ${(offset + i).toString(16).padStart(8, "0")}`;
+      const marker = position !== void 0 && position >= offset + i && position < offset + i + lineBytes.length ? " <--" : "";
+      lines.push(`${offsetStr}: ${hex.padEnd(48, " ")} | ${ascii}${marker}`);
+    }
+    return lines.join("\n");
+  }
 };
 var ValidationError = class _ValidationError extends KaitaiError {
-  constructor(message, position) {
-    super(message, position);
+  constructor(message, position, context) {
+    super(message, position, context);
     this.name = "ValidationError";
     Object.setPrototypeOf(this, _ValidationError.prototype);
   }
 };
 var ParseError = class _ParseError extends KaitaiError {
-  constructor(message, position) {
-    super(message, position);
+  constructor(message, position, context) {
+    super(message, position, context);
     this.name = "ParseError";
     Object.setPrototypeOf(this, _ParseError.prototype);
   }
 };
 var EOFError = class _EOFError extends KaitaiError {
-  constructor(message = "Unexpected end of stream", position) {
-    super(message, position);
+  constructor(message = "Unexpected end of stream", position, context) {
+    super(message, position, context);
     this.name = "EOFError";
     Object.setPrototypeOf(this, _EOFError.prototype);
   }
@@ -1815,15 +1853,15 @@ var Evaluator = class {
         return !this.equals(leftVal, rightVal);
       // Bitwise
       case "<<":
-        return this.toInt(leftVal) << this.toInt(rightVal);
+        return this.bitwiseOp(leftVal, rightVal, (a, b) => a << b);
       case ">>":
-        return this.toInt(leftVal) >> this.toInt(rightVal);
+        return this.bitwiseOp(leftVal, rightVal, (a, b) => a >> b);
       case "&":
-        return this.toInt(leftVal) & this.toInt(rightVal);
+        return this.bitwiseOp(leftVal, rightVal, (a, b) => a & b);
       case "|":
-        return this.toInt(leftVal) | this.toInt(rightVal);
+        return this.bitwiseOp(leftVal, rightVal, (a, b) => a | b);
       case "^":
-        return this.toInt(leftVal) ^ this.toInt(rightVal);
+        return this.bitwiseOp(leftVal, rightVal, (a, b) => a ^ b);
       // Logical
       case "and":
         return this.toBoolean(leftVal) && this.toBoolean(rightVal);
@@ -1867,6 +1905,16 @@ var Evaluator = class {
         `Cannot access property ${property} of null/undefined`
       );
     }
+    if (property === "to_i") {
+      if (typeof obj === "number") return Math.floor(obj);
+      if (typeof obj === "bigint") return Number(obj);
+      if (typeof obj === "string") return parseInt(obj, 10);
+      if (typeof obj === "boolean") return obj ? 1 : 0;
+      return this.toInt(obj);
+    }
+    if (property === "to_s") {
+      return String(obj);
+    }
     if (typeof obj === "object") {
       return obj[property];
     }
@@ -1893,8 +1941,9 @@ var Evaluator = class {
    * Evaluate method call (object.method()).
    * @private
    */
-  evaluateMethodCall(object, method, _args, context) {
+  evaluateMethodCall(object, method, args, context) {
     const obj = this.evaluate(object, context);
+    const evalArgs = args.map((arg) => this.evaluate(arg, context));
     if (method === "length" || method === "size") {
       if (Array.isArray(obj)) return obj.length;
       if (obj instanceof Uint8Array) return obj.length;
@@ -1902,13 +1951,182 @@ var Evaluator = class {
       throw new ParseError(`Object does not have a ${method} property`);
     }
     if (method === "to_i") {
+      const base = evalArgs.length > 0 ? this.toInt(evalArgs[0]) : 10;
+      if (typeof obj === "string") {
+        return parseInt(obj, base);
+      }
       return this.toInt(obj);
     }
     if (method === "to_s") {
       return String(obj);
     }
+    if (typeof obj === "string") {
+      return this.evaluateStringMethod(obj, method, evalArgs);
+    }
+    if (Array.isArray(obj) || obj instanceof Uint8Array) {
+      return this.evaluateArrayMethod(obj, method, evalArgs);
+    }
     throw new ParseError(`Unknown method: ${method}`);
   }
+  /**
+   * Evaluate string methods.
+   * @private
+   */
+  evaluateStringMethod(str, method, args) {
+    switch (method) {
+      case "substring": {
+        const start = args.length > 0 ? this.toInt(args[0]) : 0;
+        const end = args.length > 1 ? this.toInt(args[1]) : void 0;
+        return str.substring(start, end);
+      }
+      case "substr": {
+        const start = args.length > 0 ? this.toInt(args[0]) : 0;
+        const length = args.length > 1 ? this.toInt(args[1]) : void 0;
+        return str.substr(start, length);
+      }
+      case "reverse":
+        return str.split("").reverse().join("");
+      case "to_i": {
+        const base = args.length > 0 ? this.toInt(args[0]) : 10;
+        return parseInt(str, base);
+      }
+      case "length":
+      case "size":
+        return str.length;
+      // Ruby-style string methods used in Kaitai
+      case "upcase":
+      case "to_upper":
+        return str.toUpperCase();
+      case "downcase":
+      case "to_lower":
+        return str.toLowerCase();
+      case "capitalize":
+        return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+      case "strip":
+      case "trim":
+        return str.trim();
+      case "lstrip":
+      case "trim_start":
+        return str.trimStart();
+      case "rstrip":
+      case "trim_end":
+        return str.trimEnd();
+      case "starts_with":
+      case "startsWith": {
+        if (args.length === 0) {
+          throw new ParseError("starts_with requires 1 argument");
+        }
+        return str.startsWith(String(args[0]));
+      }
+      case "ends_with":
+      case "endsWith": {
+        if (args.length === 0) {
+          throw new ParseError("ends_with requires 1 argument");
+        }
+        return str.endsWith(String(args[0]));
+      }
+      case "includes":
+      case "contains": {
+        if (args.length === 0) {
+          throw new ParseError("includes requires 1 argument");
+        }
+        return str.includes(String(args[0]));
+      }
+      case "index_of":
+      case "indexOf": {
+        if (args.length === 0) {
+          throw new ParseError("index_of requires 1 argument");
+        }
+        return str.indexOf(String(args[0]));
+      }
+      case "split": {
+        if (args.length === 0) {
+          throw new ParseError("split requires 1 argument");
+        }
+        return str.split(String(args[0]));
+      }
+      case "replace": {
+        if (args.length < 2) {
+          throw new ParseError("replace requires 2 arguments");
+        }
+        return str.replace(String(args[0]), String(args[1]));
+      }
+      case "replace_all":
+      case "replaceAll": {
+        if (args.length < 2) {
+          throw new ParseError("replace_all requires 2 arguments");
+        }
+        const search = String(args[0]);
+        const replace = String(args[1]);
+        return str.split(search).join(replace);
+      }
+      case "pad_left":
+      case "padStart": {
+        if (args.length === 0) {
+          throw new ParseError("pad_left requires at least 1 argument");
+        }
+        const length = this.toInt(args[0]);
+        const fillString = args.length > 1 ? String(args[1]) : " ";
+        return str.padStart(length, fillString);
+      }
+      case "pad_right":
+      case "padEnd": {
+        if (args.length === 0) {
+          throw new ParseError("pad_right requires at least 1 argument");
+        }
+        const length = this.toInt(args[0]);
+        const fillString = args.length > 1 ? String(args[1]) : " ";
+        return str.padEnd(length, fillString);
+      }
+      default:
+        throw new ParseError(`Unknown string method: ${method}`);
+    }
+  }
+  /**
+   * Evaluate array methods.
+   * @private
+   */
+  evaluateArrayMethod(arr, method, args) {
+    const array = Array.isArray(arr) ? arr : Array.from(arr);
+    switch (method) {
+      case "length":
+      case "size":
+        return array.length;
+      case "first":
+        return array[0];
+      case "last":
+        return array[array.length - 1];
+      case "min":
+        return Math.min(...array.map((v) => this.toNumber(v)));
+      case "max":
+        return Math.max(...array.map((v) => this.toNumber(v)));
+      case "reverse":
+        return [...array].reverse();
+      case "sort":
+        return [...array].sort((a, b) => this.compare(a, b));
+      case "includes":
+      case "contains": {
+        if (args.length === 0) {
+          throw new ParseError("includes requires 1 argument");
+        }
+        return array.some((item) => this.equals(item, args[0]));
+      }
+      case "index_of":
+      case "indexOf": {
+        if (args.length === 0) {
+          throw new ParseError("index_of requires 1 argument");
+        }
+        return array.findIndex((item) => this.equals(item, args[0]));
+      }
+      case "slice": {
+        const start = args.length > 0 ? this.toInt(args[0]) : 0;
+        const end = args.length > 1 ? this.toInt(args[1]) : void 0;
+        return array.slice(start, end);
+      }
+      default:
+        throw new ParseError(`Unknown array method: ${method}`);
+    }
+  }
   /**
    * Evaluate enum access (EnumName::value).
    * @private
@@ -1938,6 +2156,38 @@ var Evaluator = class {
     const result = a % b;
     return result < 0 ? result + b : result;
   }
+  /**
+   * Helper: Bitwise operation with BigInt support.
+   * JavaScript bitwise operators work on 32-bit integers, but Kaitai
+   * may use 64-bit values. For values that fit in 32 bits, use native ops.
+   * For larger values, convert to BigInt (with limitations).
+   * @private
+   */
+  bitwiseOp(left, right, op) {
+    if (typeof left === "bigint" || typeof right === "bigint") {
+      const leftBig = typeof left === "bigint" ? left : BigInt(left);
+      const rightBig = typeof right === "bigint" ? right : BigInt(right);
+      if (op.toString().includes("<<")) {
+        return leftBig << BigInt(Number(rightBig));
+      }
+      if (op.toString().includes(">>")) {
+        return leftBig >> BigInt(Number(rightBig));
+      }
+      if (op.toString().includes("&")) {
+        return leftBig & rightBig;
+      }
+      if (op.toString().includes("|")) {
+        return leftBig | rightBig;
+      }
+      if (op.toString().includes("^")) {
+        return leftBig ^ rightBig;
+      }
+    }
+    if (left === void 0 || left === null || right === void 0 || right === null) {
+      throw new ParseError("Cannot perform bitwise operation on null/undefined");
+    }
+    return op(this.toInt(left), this.toInt(right));
+  }
   /**
    * Helper: Compare two values.
    * @private
@@ -2025,6 +2275,112 @@ function evaluateExpression(expression, context) {
   return evaluator.evaluate(ast, context);
 }
 
+// src/utils/process.ts
+import { inflate } from "pako";
+function applyProcess(data, process) {
+  const spec = typeof process === "string" ? { algorithm: process } : process;
+  const algorithm = spec.algorithm;
+  if (!algorithm) {
+    throw new ParseError("Process specification missing algorithm");
+  }
+  switch (algorithm) {
+    case "zlib":
+      return processZlib(data);
+    case "xor":
+      return processXor(data, spec.key);
+    case "rol":
+      return processRol(data, spec.amount, spec.group);
+    case "ror":
+      return processRor(data, spec.amount, spec.group);
+    case "bswap2":
+      return processByteswap(data, 2);
+    case "bswap4":
+      return processByteswap(data, 4);
+    case "bswap8":
+      return processByteswap(data, 8);
+    case "bswap16":
+      return processByteswap(data, 16);
+    default:
+      throw new ParseError(
+        `Unknown process algorithm: ${algorithm}. Supported: zlib, xor, rol, ror, bswap2, bswap4, bswap8, bswap16`
+      );
+  }
+}
+function processZlib(data) {
+  try {
+    return inflate(data);
+  } catch (error) {
+    throw new ParseError(
+      `Zlib decompression failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function processXor(data, key) {
+  if (key === void 0) {
+    throw new ParseError("XOR process requires a key parameter");
+  }
+  const result = new Uint8Array(data.length);
+  const keyBytes = Array.isArray(key) ? key : [key];
+  if (keyBytes.length === 0) {
+    throw new ParseError("XOR key cannot be empty");
+  }
+  for (let i = 0; i < data.length; i++) {
+    result[i] = data[i] ^ keyBytes[i % keyBytes.length];
+  }
+  return result;
+}
+function processRol(data, amount, group) {
+  const bits = amount ?? 1;
+  const groupSize = group ?? 1;
+  if (bits < 0 || bits > 7) {
+    throw new ParseError("ROL amount must be between 0 and 7");
+  }
+  if (groupSize !== 1) {
+    throw new ParseError("ROL with group size > 1 not yet supported");
+  }
+  const result = new Uint8Array(data.length);
+  for (let i = 0; i < data.length; i++) {
+    const byte = data[i];
+    result[i] = (byte << bits | byte >> 8 - bits) & 255;
+  }
+  return result;
+}
+function processRor(data, amount, group) {
+  const bits = amount ?? 1;
+  const groupSize = group ?? 1;
+  if (bits < 0 || bits > 7) {
+    throw new ParseError("ROR amount must be between 0 and 7");
+  }
+  if (groupSize !== 1) {
+    throw new ParseError("ROR with group size > 1 not yet supported");
+  }
+  const result = new Uint8Array(data.length);
+  for (let i = 0; i < data.length; i++) {
+    const byte = data[i];
+    result[i] = (byte >> bits | byte << 8 - bits) & 255;
+  }
+  return result;
+}
+function processByteswap(data, groupSize) {
+  if (![2, 4, 8, 16].includes(groupSize)) {
+    throw new ParseError(
+      `Invalid byteswap group size: ${groupSize}. Must be 2, 4, 8, or 16`
+    );
+  }
+  if (data.length % groupSize !== 0) {
+    throw new ParseError(
+      `Data length ${data.length} is not aligned to group size ${groupSize}`
+    );
+  }
+  const result = new Uint8Array(data.length);
+  for (let i = 0; i < data.length; i += groupSize) {
+    for (let j = 0; j < groupSize; j++) {
+      result[i + j] = data[i + groupSize - 1 - j];
+    }
+  }
+  return result;
+}
+
 // src/interpreter/TypeInterpreter.ts
 var TypeInterpreter = class _TypeInterpreter {
   /**
@@ -2061,13 +2417,20 @@ var TypeInterpreter = class _TypeInterpreter {
    * @param stream - Binary stream to parse
    * @param parent - Parent object (for nested types)
    * @param typeArgs - Arguments for parametric types
+   * @param root - Root object of the parse tree (for nested types)
    * @returns Parsed object
    */
-  parse(stream, parent, typeArgs) {
+  parse(stream, parent, typeArgs, root) {
     const result = {};
-    const context = new Context(stream, result, parent, this.schema.enums);
+    const actualRoot = root || result;
+    const context = new Context(stream, actualRoot, parent, this.schema.enums);
     context.current = result;
+    const startPos = stream.pos;
     result["_io"] = stream;
+    if (root) {
+      ;
+      result["_root"] = root;
+    }
     if (typeArgs && this.schema.params) {
       for (let i = 0; i < this.schema.params.length && i < typeArgs.length; i++) {
         const param = this.schema.params[i];
@@ -2076,6 +2439,9 @@ var TypeInterpreter = class _TypeInterpreter {
         context.set(param.id, evaluatedArg);
       }
     }
+    if (this.schema.instances) {
+      this.setupInstances(result, stream, context);
+    }
     if (this.schema.seq) {
       for (const attr of this.schema.seq) {
         const value = this.parseAttribute(attr, context);
@@ -2084,9 +2450,8 @@ var TypeInterpreter = class _TypeInterpreter {
         }
       }
     }
-    if (this.schema.instances) {
-      this.setupInstances(result, stream, context);
-    }
+    const endPos = stream.pos;
+    result["_sizeof"] = endPos - startPos;
     return result;
   }
   /**
@@ -2391,11 +2756,13 @@ var TypeInterpreter = class _TypeInterpreter {
         context
       );
     }
-    if (isBuiltinType(type)) {
-      return this.parseBuiltinType(type, stream, context);
+    const { typeName, args } = this.parseParameterizedType(type, context);
+    const effectiveArgs = args.length > 0 ? args : typeArgs;
+    if (isBuiltinType(typeName)) {
+      return this.parseBuiltinType(typeName, stream, context);
     }
-    if (this.schema.types && type in this.schema.types) {
-      const typeSchema = this.schema.types[type];
+    if (this.schema.types && typeName in this.schema.types) {
+      const typeSchema = this.schema.types[typeName];
       const meta = this.schema.meta || this.parentMeta;
       if (this.schema.enums && !typeSchema.enums) {
         typeSchema.enums = this.schema.enums;
@@ -2404,9 +2771,100 @@ var TypeInterpreter = class _TypeInterpreter {
         typeSchema.types = this.schema.types;
       }
       const interpreter = new _TypeInterpreter(typeSchema, meta);
-      return interpreter.parse(stream, context.current, typeArgs);
+      return interpreter.parse(
+        stream,
+        context.current,
+        effectiveArgs,
+        context.root
+      );
+    }
+    throw new ParseError(`Unknown type: ${typeName}`);
+  }
+  /**
+   * Parse parameterized type syntax and extract type name and arguments.
+   * Supports: type_name(arg1, arg2, ...) or just type_name
+   *
+   * @param typeSpec - Type specification string
+   * @param context - Execution context for evaluating argument expressions
+   * @returns Object with typeName and evaluated args
+   * @private
+   */
+  parseParameterizedType(typeSpec, context) {
+    const match = typeSpec.match(/^([a-z_][a-z0-9_]*)\((.*)\)$/i);
+    if (!match) {
+      return { typeName: typeSpec, args: [] };
+    }
+    const typeName = match[1];
+    const argsString = match[2].trim();
+    if (!argsString) {
+      return { typeName, args: [] };
+    }
+    const args = [];
+    let current = "";
+    let inString = false;
+    let stringChar = "";
+    let parenDepth = 0;
+    for (let i = 0; i < argsString.length; i++) {
+      const char = argsString[i];
+      if (inString) {
+        current += char;
+        if (char === stringChar && argsString[i - 1] !== "\\") {
+          inString = false;
+        }
+      } else if (char === '"' || char === "'") {
+        inString = true;
+        stringChar = char;
+        current += char;
+      } else if (char === "(") {
+        parenDepth++;
+        current += char;
+      } else if (char === ")") {
+        parenDepth--;
+        current += char;
+      } else if (char === "," && parenDepth === 0) {
+        args.push(this.parseArgument(current.trim(), context));
+        current = "";
+      } else {
+        current += char;
+      }
+    }
+    if (current.trim()) {
+      args.push(this.parseArgument(current.trim(), context));
+    }
+    return { typeName, args };
+  }
+  /**
+   * Parse and evaluate a single type argument.
+   *
+   * @param arg - Argument string
+   * @param context - Execution context
+   * @returns Evaluated argument value
+   * @private
+   */
+  parseArgument(arg, context) {
+    if (arg === "true") return true;
+    if (arg === "false") return false;
+    if (arg.startsWith('"') && arg.endsWith('"') || arg.startsWith("'") && arg.endsWith("'")) {
+      return arg.slice(1, -1);
+    }
+    if (/^-?\d+$/.test(arg)) {
+      return parseInt(arg, 10);
+    }
+    if (/^-?\d+\.\d+$/.test(arg)) {
+      return parseFloat(arg);
+    }
+    if (/^0x[0-9a-f]+$/i.test(arg)) {
+      return parseInt(arg, 16);
+    }
+    try {
+      const result = this.evaluateValue(arg, context);
+      if (typeof result === "string" || typeof result === "number" || typeof result === "boolean") {
+        return result;
+      }
+      return Number(result);
+    } catch {
+      return arg;
     }
-    throw new ParseError(`Unknown type: ${type}`);
   }
   /**
    * Parse a switch type (type selection based on expression).
@@ -2449,12 +2907,21 @@ var TypeInterpreter = class _TypeInterpreter {
    * @returns Parsed value
    * @private
    */
-  parseBuiltinType(type, stream, _context) {
+  parseBuiltinType(type, stream, context) {
     const base = getBaseType(type);
     const typeEndian = getTypeEndianness(type);
     const meta = this.schema.meta || this.parentMeta;
     const metaEndian = meta?.endian;
-    const endian = typeEndian || (typeof metaEndian === "string" ? metaEndian : "le");
+    let endian;
+    if (typeEndian) {
+      endian = typeEndian;
+    } else if (typeof metaEndian === "string") {
+      endian = metaEndian;
+    } else if (metaEndian && typeof metaEndian === "object") {
+      endian = this.evaluateEndianExpression(metaEndian, context);
+    } else {
+      endian = "le";
+    }
     if (isIntegerType(type)) {
       return this.readInteger(base, endian, stream);
     }
@@ -2531,7 +2998,7 @@ var TypeInterpreter = class _TypeInterpreter {
   }
   /**
    * Apply processing transformation to data.
-   * Supports basic transformations like zlib decompression.
+   * Delegates to the process utility module.
    *
    * @param data - Data to process
    * @param process - Processing specification
@@ -2539,13 +3006,35 @@ var TypeInterpreter = class _TypeInterpreter {
    * @private
    */
   applyProcessing(data, process) {
-    const processType = typeof process === "string" ? process : process.algorithm;
-    if (processType) {
-      throw new NotImplementedError(
-        `Processing type "${processType}" is not yet implemented. Supported in future versions with zlib, encryption, etc.`
-      );
+    return applyProcess(data, process);
+  }
+  /**
+   * Evaluate expression-based endianness (switch-on).
+   *
+   * @param endianExpr - Endianness expression with switch-on and cases
+   * @param context - Execution context
+   * @returns Resolved endianness ('le' or 'be')
+   * @private
+   */
+  evaluateEndianExpression(endianExpr, context) {
+    const switchOn = endianExpr["switch-on"];
+    const cases = endianExpr.cases;
+    if (!switchOn || typeof switchOn !== "string") {
+      throw new ParseError('Endian expression missing "switch-on" field');
+    }
+    if (!cases || typeof cases !== "object") {
+      throw new ParseError('Endian expression missing "cases" field');
+    }
+    const switchValue = this.evaluateValue(switchOn, context);
+    const key = String(switchValue);
+    if (key in cases) {
+      const endian = cases[key];
+      if (endian !== "le" && endian !== "be") {
+        throw new ParseError(`Invalid endianness value: ${endian}`);
+      }
+      return endian;
     }
-    return data;
+    return "le";
   }
   /**
    * Evaluate a value that can be an expression or literal.
@@ -2687,6 +3176,12 @@ export {
  * @author Fabiano Pinto
  * @license MIT
  */
+/**
+ * @fileoverview Data processing utilities for Kaitai Struct
+ * @module utils/process
+ * @author Fabiano Pinto
+ * @license MIT
+ */
 /**
  * @fileoverview Type interpreter for executing Kaitai Struct schemas
  * @module interpreter/TypeInterpreter