@k67/kaitai-struct-ts 0.2.0

package/dist/index.js

@@ -0,0 +1,1405 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BUILTIN_TYPES: () => BUILTIN_TYPES,
+  Context: () => Context,
+  EOFError: () => EOFError,
+  KaitaiError: () => KaitaiError,
+  KaitaiStream: () => KaitaiStream,
+  KsyParser: () => KsyParser,
+  NotImplementedError: () => NotImplementedError,
+  ParseError: () => ParseError,
+  TypeInterpreter: () => TypeInterpreter,
+  ValidationError: () => ValidationError,
+  getBaseType: () => getBaseType,
+  getTypeEndianness: () => getTypeEndianness,
+  isBuiltinType: () => isBuiltinType,
+  isFloatType: () => isFloatType,
+  isIntegerType: () => isIntegerType,
+  isStringType: () => isStringType,
+  parse: () => parse
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils/errors.ts
+var KaitaiError = class _KaitaiError extends Error {
+  constructor(message, position) {
+    super(message);
+    this.position = position;
+    this.name = "KaitaiError";
+    Object.setPrototypeOf(this, _KaitaiError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends KaitaiError {
+  constructor(message, position) {
+    super(message, position);
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var ParseError = class _ParseError extends KaitaiError {
+  constructor(message, position) {
+    super(message, position);
+    this.name = "ParseError";
+    Object.setPrototypeOf(this, _ParseError.prototype);
+  }
+};
+var EOFError = class _EOFError extends KaitaiError {
+  constructor(message = "Unexpected end of stream", position) {
+    super(message, position);
+    this.name = "EOFError";
+    Object.setPrototypeOf(this, _EOFError.prototype);
+  }
+};
+var NotImplementedError = class _NotImplementedError extends KaitaiError {
+  constructor(feature) {
+    super(`Feature not yet implemented: ${feature}`);
+    this.name = "NotImplementedError";
+    Object.setPrototypeOf(this, _NotImplementedError.prototype);
+  }
+};
+
+// src/utils/encoding.ts
+function decodeString(bytes, encoding) {
+  const normalizedEncoding = encoding.toLowerCase().replace(/[-_]/g, "");
+  switch (normalizedEncoding) {
+    case "utf8":
+    case "utf-8":
+      return decodeUtf8(bytes);
+    case "ascii":
+    case "usascii":
+      return decodeAscii(bytes);
+    case "utf16":
+    case "utf16le":
+    case "utf-16le":
+      return decodeUtf16Le(bytes);
+    case "utf16be":
+    case "utf-16be":
+      return decodeUtf16Be(bytes);
+    case "latin1":
+    case "iso88591":
+    case "iso-8859-1":
+      return decodeLatin1(bytes);
+    default:
+      if (typeof TextDecoder !== "undefined") {
+        try {
+          return new TextDecoder(encoding).decode(bytes);
+        } catch {
+          throw new Error(`Unsupported encoding: ${encoding}`);
+        }
+      }
+      throw new Error(`Unsupported encoding: ${encoding}`);
+  }
+}
+function decodeUtf8(bytes) {
+  if (typeof TextDecoder !== "undefined") {
+    return new TextDecoder("utf-8").decode(bytes);
+  }
+  let result = "";
+  let i = 0;
+  while (i < bytes.length) {
+    const byte1 = bytes[i++];
+    if (byte1 < 128) {
+      result += String.fromCharCode(byte1);
+    } else if (byte1 < 224) {
+      const byte2 = bytes[i++];
+      result += String.fromCharCode((byte1 & 31) << 6 | byte2 & 63);
+    } else if (byte1 < 240) {
+      const byte2 = bytes[i++];
+      const byte3 = bytes[i++];
+      result += String.fromCharCode(
+        (byte1 & 15) << 12 | (byte2 & 63) << 6 | byte3 & 63
+      );
+    } else {
+      const byte2 = bytes[i++];
+      const byte3 = bytes[i++];
+      const byte4 = bytes[i++];
+      let codePoint = (byte1 & 7) << 18 | (byte2 & 63) << 12 | (byte3 & 63) << 6 | byte4 & 63;
+      codePoint -= 65536;
+      result += String.fromCharCode(
+        55296 + (codePoint >> 10),
+        56320 + (codePoint & 1023)
+      );
+    }
+  }
+  return result;
+}
+function decodeAscii(bytes) {
+  let result = "";
+  for (let i = 0; i < bytes.length; i++) {
+    result += String.fromCharCode(bytes[i] & 127);
+  }
+  return result;
+}
+function decodeLatin1(bytes) {
+  let result = "";
+  for (let i = 0; i < bytes.length; i++) {
+    result += String.fromCharCode(bytes[i]);
+  }
+  return result;
+}
+function decodeUtf16Le(bytes) {
+  if (typeof TextDecoder !== "undefined") {
+    return new TextDecoder("utf-16le").decode(bytes);
+  }
+  let result = "";
+  for (let i = 0; i < bytes.length; i += 2) {
+    const charCode = bytes[i] | bytes[i + 1] << 8;
+    result += String.fromCharCode(charCode);
+  }
+  return result;
+}
+function decodeUtf16Be(bytes) {
+  if (typeof TextDecoder !== "undefined") {
+    return new TextDecoder("utf-16be").decode(bytes);
+  }
+  let result = "";
+  for (let i = 0; i < bytes.length; i += 2) {
+    const charCode = bytes[i] << 8 | bytes[i + 1];
+    result += String.fromCharCode(charCode);
+  }
+  return result;
+}
+
+// src/stream/KaitaiStream.ts
+var KaitaiStream = class _KaitaiStream {
+  /**
+   * Create a new KaitaiStream from a buffer
+   * @param buffer - ArrayBuffer or Uint8Array containing the binary data
+   */
+  constructor(buffer) {
+    this._pos = 0;
+    this._bits = 0;
+    this._bitsLeft = 0;
+    if (buffer instanceof ArrayBuffer) {
+      this.buffer = new Uint8Array(buffer);
+      this.view = new DataView(buffer);
+    } else {
+      this.buffer = buffer;
+      this.view = new DataView(
+        buffer.buffer,
+        buffer.byteOffset,
+        buffer.byteLength
+      );
+    }
+  }
+  /**
+   * Current position in the stream
+   */
+  get pos() {
+    return this._pos;
+  }
+  set pos(value) {
+    this._pos = value;
+    this._bitsLeft = 0;
+  }
+  /**
+   * Total size of the stream in bytes
+   */
+  get size() {
+    return this.buffer.length;
+  }
+  /**
+   * Check if we've reached the end of the stream
+   */
+  isEof() {
+    return this._pos >= this.buffer.length;
+  }
+  /**
+   * Seek to a specific position in the stream
+   * @param pos - Position to seek to
+   */
+  seek(pos) {
+    if (pos < 0 || pos > this.buffer.length) {
+      throw new Error(`Invalid seek position: ${pos}`);
+    }
+    this.pos = pos;
+  }
+  /**
+   * Ensure we have enough bytes available
+   * @param count - Number of bytes needed
+   */
+  ensureBytes(count) {
+    if (this._pos + count > this.buffer.length) {
+      throw new EOFError(
+        `Requested ${count} bytes at position ${this._pos}, but only ${this.buffer.length - this._pos} bytes available`,
+        this._pos
+      );
+    }
+  }
+  // ==================== Unsigned Integers ====================
+  /**
+   * Read 1-byte unsigned integer (0 to 255)
+   */
+  readU1() {
+    this.ensureBytes(1);
+    return this.buffer[this._pos++];
+  }
+  /**
+   * Read 2-byte unsigned integer, little-endian
+   */
+  readU2le() {
+    this.ensureBytes(2);
+    const value = this.view.getUint16(this._pos, true);
+    this._pos += 2;
+    return value;
+  }
+  /**
+   * Read 2-byte unsigned integer, big-endian
+   */
+  readU2be() {
+    this.ensureBytes(2);
+    const value = this.view.getUint16(this._pos, false);
+    this._pos += 2;
+    return value;
+  }
+  /**
+   * Read 4-byte unsigned integer, little-endian
+   */
+  readU4le() {
+    this.ensureBytes(4);
+    const value = this.view.getUint32(this._pos, true);
+    this._pos += 4;
+    return value;
+  }
+  /**
+   * Read 4-byte unsigned integer, big-endian
+   */
+  readU4be() {
+    this.ensureBytes(4);
+    const value = this.view.getUint32(this._pos, false);
+    this._pos += 4;
+    return value;
+  }
+  /**
+   * Read 8-byte unsigned integer, little-endian
+   * Returns BigInt for values > Number.MAX_SAFE_INTEGER
+   */
+  readU8le() {
+    this.ensureBytes(8);
+    const value = this.view.getBigUint64(this._pos, true);
+    this._pos += 8;
+    return value;
+  }
+  /**
+   * Read 8-byte unsigned integer, big-endian
+   * Returns BigInt for values > Number.MAX_SAFE_INTEGER
+   */
+  readU8be() {
+    this.ensureBytes(8);
+    const value = this.view.getBigUint64(this._pos, false);
+    this._pos += 8;
+    return value;
+  }
+  // ==================== Signed Integers ====================
+  /**
+   * Read 1-byte signed integer (-128 to 127)
+   */
+  readS1() {
+    this.ensureBytes(1);
+    return this.view.getInt8(this._pos++);
+  }
+  /**
+   * Read 2-byte signed integer, little-endian
+   */
+  readS2le() {
+    this.ensureBytes(2);
+    const value = this.view.getInt16(this._pos, true);
+    this._pos += 2;
+    return value;
+  }
+  /**
+   * Read 2-byte signed integer, big-endian
+   */
+  readS2be() {
+    this.ensureBytes(2);
+    const value = this.view.getInt16(this._pos, false);
+    this._pos += 2;
+    return value;
+  }
+  /**
+   * Read 4-byte signed integer, little-endian
+   */
+  readS4le() {
+    this.ensureBytes(4);
+    const value = this.view.getInt32(this._pos, true);
+    this._pos += 4;
+    return value;
+  }
+  /**
+   * Read 4-byte signed integer, big-endian
+   */
+  readS4be() {
+    this.ensureBytes(4);
+    const value = this.view.getInt32(this._pos, false);
+    this._pos += 4;
+    return value;
+  }
+  /**
+   * Read 8-byte signed integer, little-endian
+   * Returns BigInt for values outside Number.MAX_SAFE_INTEGER range
+   */
+  readS8le() {
+    this.ensureBytes(8);
+    const value = this.view.getBigInt64(this._pos, true);
+    this._pos += 8;
+    return value;
+  }
+  /**
+   * Read 8-byte signed integer, big-endian
+   * Returns BigInt for values outside Number.MAX_SAFE_INTEGER range
+   */
+  readS8be() {
+    this.ensureBytes(8);
+    const value = this.view.getBigInt64(this._pos, false);
+    this._pos += 8;
+    return value;
+  }
+  // ==================== Floating Point ====================
+  /**
+   * Read 4-byte IEEE 754 single-precision float, little-endian
+   */
+  readF4le() {
+    this.ensureBytes(4);
+    const value = this.view.getFloat32(this._pos, true);
+    this._pos += 4;
+    return value;
+  }
+  /**
+   * Read 4-byte IEEE 754 single-precision float, big-endian
+   */
+  readF4be() {
+    this.ensureBytes(4);
+    const value = this.view.getFloat32(this._pos, false);
+    this._pos += 4;
+    return value;
+  }
+  /**
+   * Read 8-byte IEEE 754 double-precision float, little-endian
+   */
+  readF8le() {
+    this.ensureBytes(8);
+    const value = this.view.getFloat64(this._pos, true);
+    this._pos += 8;
+    return value;
+  }
+  /**
+   * Read 8-byte IEEE 754 double-precision float, big-endian
+   */
+  readF8be() {
+    this.ensureBytes(8);
+    const value = this.view.getFloat64(this._pos, false);
+    this._pos += 8;
+    return value;
+  }
+  // ==================== Byte Arrays ====================
+  /**
+   * Read a fixed number of bytes
+   * @param length - Number of bytes to read
+   */
+  readBytes(length) {
+    this.ensureBytes(length);
+    const bytes = this.buffer.slice(this._pos, this._pos + length);
+    this._pos += length;
+    return bytes;
+  }
+  /**
+   * Read all remaining bytes until end of stream
+   */
+  readBytesFull() {
+    const bytes = this.buffer.slice(this._pos);
+    this._pos = this.buffer.length;
+    return bytes;
+  }
+  /**
+   * Read bytes until a terminator byte is found
+   * @param term - Terminator byte value
+   * @param include - Include terminator in result
+   * @param consume - Consume terminator from stream
+   * @param eosError - Throw error if EOS reached before terminator
+   */
+  readBytesterm(term, include = false, consume = true, eosError = true) {
+    const start = this._pos;
+    let end = start;
+    while (end < this.buffer.length && this.buffer[end] !== term) {
+      end++;
+    }
+    const foundTerm = end < this.buffer.length;
+    if (!foundTerm && eosError) {
+      throw new EOFError(
+        `Terminator byte ${term} not found before end of stream`,
+        this._pos
+      );
+    }
+    const includeEnd = include && foundTerm ? end + 1 : end;
+    const bytes = this.buffer.slice(start, includeEnd);
+    if (foundTerm && consume) {
+      this._pos = end + 1;
+    } else {
+      this._pos = end;
+    }
+    return bytes;
+  }
+  // ==================== Strings ====================
+  /**
+   * Read a fixed-length string
+   * @param length - Number of bytes to read
+   * @param encoding - Character encoding (default: UTF-8)
+   */
+  readStr(length, encoding = "UTF-8") {
+    const bytes = this.readBytes(length);
+    return decodeString(bytes, encoding);
+  }
+  /**
+   * Read a null-terminated string
+   * @param encoding - Character encoding (default: UTF-8)
+   * @param term - Terminator byte (default: 0)
+   * @param include - Include terminator in result
+   * @param consume - Consume terminator from stream
+   * @param eosError - Throw error if EOS reached before terminator
+   */
+  readStrz(encoding = "UTF-8", term = 0, include = false, consume = true, eosError = true) {
+    const bytes = this.readBytesterm(term, include, consume, eosError);
+    return decodeString(bytes, encoding);
+  }
+  // ==================== Bit-level Reading ====================
+  /**
+   * Align bit reading to byte boundary
+   */
+  alignToByte() {
+    this._bitsLeft = 0;
+  }
+  /**
+   * Read specified number of bits as unsigned integer (big-endian)
+   * @param n - Number of bits to read (1-64)
+   */
+  readBitsIntBe(n) {
+    if (n < 1 || n > 64) {
+      throw new Error(`Invalid bit count: ${n}. Must be between 1 and 64`);
+    }
+    let result = 0n;
+    for (let bitsNeeded = n; bitsNeeded > 0; ) {
+      if (this._bitsLeft === 0) {
+        this._bits = this.readU1();
+        this._bitsLeft = 8;
+      }
+      const bitsToRead = Math.min(bitsNeeded, this._bitsLeft);
+      const mask = (1 << bitsToRead) - 1;
+      const shift = this._bitsLeft - bitsToRead;
+      result = result << BigInt(bitsToRead) | BigInt(this._bits >> shift & mask);
+      this._bitsLeft -= bitsToRead;
+      bitsNeeded -= bitsToRead;
+    }
+    return result;
+  }
+  /**
+   * Read specified number of bits as unsigned integer (little-endian)
+   * @param n - Number of bits to read (1-64)
+   */
+  readBitsIntLe(n) {
+    if (n < 1 || n > 64) {
+      throw new Error(`Invalid bit count: ${n}. Must be between 1 and 64`);
+    }
+    let result = 0n;
+    let bitPos = 0;
+    for (let bitsNeeded = n; bitsNeeded > 0; ) {
+      if (this._bitsLeft === 0) {
+        this._bits = this.readU1();
+        this._bitsLeft = 8;
+      }
+      const bitsToRead = Math.min(bitsNeeded, this._bitsLeft);
+      const mask = (1 << bitsToRead) - 1;
+      result |= BigInt(this._bits & mask) << BigInt(bitPos);
+      this._bits >>= bitsToRead;
+      this._bitsLeft -= bitsToRead;
+      bitsNeeded -= bitsToRead;
+      bitPos += bitsToRead;
+    }
+    return result;
+  }
+  // ==================== Utility Methods ====================
+  /**
+   * Get the underlying buffer
+   */
+  getBuffer() {
+    return this.buffer;
+  }
+  /**
+   * Create a substream from current position with specified size
+   * @param size - Size of the substream in bytes
+   */
+  substream(size) {
+    this.ensureBytes(size);
+    const subBuffer = this.buffer.slice(this._pos, this._pos + size);
+    this._pos += size;
+    return new _KaitaiStream(subBuffer);
+  }
+};
+
+// src/parser/schema.ts
+var BUILTIN_TYPES = [
+  // Unsigned integers
+  "u1",
+  "u2",
+  "u2le",
+  "u2be",
+  "u4",
+  "u4le",
+  "u4be",
+  "u8",
+  "u8le",
+  "u8be",
+  // Signed integers
+  "s1",
+  "s2",
+  "s2le",
+  "s2be",
+  "s4",
+  "s4le",
+  "s4be",
+  "s8",
+  "s8le",
+  "s8be",
+  // Floating point
+  "f4",
+  "f4le",
+  "f4be",
+  "f8",
+  "f8le",
+  "f8be",
+  // String
+  "str",
+  "strz"
+];
+function isBuiltinType(type) {
+  return BUILTIN_TYPES.includes(type);
+}
+function getTypeEndianness(type) {
+  if (type.endsWith("le")) return "le";
+  if (type.endsWith("be")) return "be";
+  return void 0;
+}
+function getBaseType(type) {
+  if (type.endsWith("le") || type.endsWith("be")) {
+    return type.slice(0, -2);
+  }
+  return type;
+}
+function isIntegerType(type) {
+  const base = getBaseType(type);
+  return /^[us][1248]$/.test(base);
+}
+function isFloatType(type) {
+  const base = getBaseType(type);
+  return /^f[48]$/.test(base);
+}
+function isStringType(type) {
+  return type === "str" || type === "strz";
+}
+
+// src/parser/KsyParser.ts
+var import_yaml = require("yaml");
+var KsyParser = class {
+  /**
+   * Parse a .ksy YAML string into a typed schema object.
+   *
+   * @param yaml - YAML string containing the .ksy definition
+   * @param options - Parsing options
+   * @returns Parsed and validated schema
+   * @throws {ParseError} If YAML parsing fails
+   * @throws {ValidationError} If schema validation fails
+   */
+  parse(yaml, options = {}) {
+    const { validate = true, strict = false } = options;
+    let parsed;
+    try {
+      parsed = (0, import_yaml.parse)(yaml);
+    } catch (error) {
+      throw new ParseError(
+        `Failed to parse YAML: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new ParseError("KSY file must contain an object");
+    }
+    const schema = parsed;
+    if (validate) {
+      const result = this.validate(schema, { strict });
+      if (!result.valid) {
+        const errorMessages = result.errors.map((e) => e.message).join("; ");
+        throw new ValidationError(
+          `Schema validation failed: ${errorMessages}`
+        );
+      }
+      if (result.warnings.length > 0 && !strict) {
+        console.warn(
+          "Schema validation warnings:",
+          result.warnings.map((w) => w.message)
+        );
+      }
+    }
+    return schema;
+  }
+  /**
+   * Validate a schema object.
+   *
+   * @param schema - Schema to validate
+   * @param options - Validation options
+   * @returns Validation result with errors and warnings
+   */
+  validate(schema, options = {}) {
+    const { strict = false, isNested = false } = options;
+    const errors = [];
+    const warnings = [];
+    if (!schema.meta && !isNested) {
+      errors.push({
+        message: 'Missing required "meta" section',
+        path: [],
+        code: "MISSING_META"
+      });
+    } else if (schema.meta) {
+      if (!schema.meta.id) {
+        errors.push({
+          message: 'Missing required "meta.id" field',
+          path: ["meta"],
+          code: "MISSING_META_ID"
+        });
+      } else if (typeof schema.meta.id !== "string") {
+        errors.push({
+          message: '"meta.id" must be a string',
+          path: ["meta", "id"],
+          code: "INVALID_META_ID_TYPE"
+        });
+      } else if (!/^[a-z][a-z0-9_]*$/.test(schema.meta.id)) {
+        warnings.push({
+          message: '"meta.id" should follow snake_case naming convention',
+          path: ["meta", "id"],
+          code: "META_ID_NAMING"
+        });
+      }
+      if (schema.meta.endian) {
+        if (typeof schema.meta.endian === "string" && schema.meta.endian !== "le" && schema.meta.endian !== "be") {
+          errors.push({
+            message: '"meta.endian" must be "le" or "be"',
+            path: ["meta", "endian"],
+            code: "INVALID_ENDIAN"
+          });
+        }
+      }
+    }
+    if (schema.seq) {
+      if (!Array.isArray(schema.seq)) {
+        errors.push({
+          message: '"seq" must be an array',
+          path: ["seq"],
+          code: "INVALID_SEQ_TYPE"
+        });
+      } else {
+        schema.seq.forEach((attr, index) => {
+          this.validateAttribute(
+            attr,
+            ["seq", String(index)],
+            errors,
+            warnings,
+            strict
+          );
+        });
+      }
+    }
+    if (schema.instances) {
+      if (typeof schema.instances !== "object") {
+        errors.push({
+          message: '"instances" must be an object',
+          path: ["instances"],
+          code: "INVALID_INSTANCES_TYPE"
+        });
+      } else {
+        Object.entries(schema.instances).forEach(([key, instance]) => {
+          this.validateAttribute(
+            instance,
+            ["instances", key],
+            errors,
+            warnings,
+            strict
+          );
+        });
+      }
+    }
+    if (schema.types) {
+      if (typeof schema.types !== "object") {
+        errors.push({
+          message: '"types" must be an object',
+          path: ["types"],
+          code: "INVALID_TYPES_TYPE"
+        });
+      } else {
+        Object.entries(schema.types).forEach(([key, type]) => {
+          const typeResult = this.validate(type, { ...options, isNested: true });
+          errors.push(
+            ...typeResult.errors.map((e) => ({
+              ...e,
+              path: ["types", key, ...e.path]
+            }))
+          );
+          warnings.push(
+            ...typeResult.warnings.map((w) => ({
+              ...w,
+              path: ["types", key, ...w.path]
+            }))
+          );
+        });
+      }
+    }
+    if (schema.enums) {
+      if (typeof schema.enums !== "object") {
+        errors.push({
+          message: '"enums" must be an object',
+          path: ["enums"],
+          code: "INVALID_ENUMS_TYPE"
+        });
+      }
+    }
+    return {
+      valid: errors.length === 0 && (strict ? warnings.length === 0 : true),
+      errors,
+      warnings
+    };
+  }
+  /**
+   * Validate an attribute specification.
+   *
+   * @param attr - Attribute to validate
+   * @param path - Path to this attribute in the schema
+   * @param errors - Array to collect errors
+   * @param warnings - Array to collect warnings
+   * @param strict - Whether to be strict about warnings
+   * @private
+   */
+  validateAttribute(attr, path, errors, warnings, _strict) {
+    if (attr.id && typeof attr.id === "string") {
+      if (!/^[a-z][a-z0-9_]*$/.test(attr.id)) {
+        warnings.push({
+          message: `Field "${attr.id}" should follow snake_case naming convention`,
+          path: [...path, "id"],
+          code: "FIELD_ID_NAMING"
+        });
+      }
+    }
+    if (attr.repeat) {
+      if (attr.repeat !== "expr" && attr.repeat !== "eos" && attr.repeat !== "until") {
+        errors.push({
+          message: '"repeat" must be "expr", "eos", or "until"',
+          path: [...path, "repeat"],
+          code: "INVALID_REPEAT"
+        });
+      }
+      if (attr.repeat === "expr" && !attr["repeat-expr"]) {
+        errors.push({
+          message: '"repeat-expr" is required when repeat is "expr"',
+          path: [...path, "repeat-expr"],
+          code: "MISSING_REPEAT_EXPR"
+        });
+      }
+      if (attr.repeat === "until" && !attr["repeat-until"]) {
+        errors.push({
+          message: '"repeat-until" is required when repeat is "until"',
+          path: [...path, "repeat-until"],
+          code: "MISSING_REPEAT_UNTIL"
+        });
+      }
+    }
+    if (attr["size-eos"] && attr.size) {
+      warnings.push({
+        message: '"size-eos" and "size" are mutually exclusive',
+        path: [...path],
+        code: "SIZE_EOS_WITH_SIZE"
+      });
+    }
+    if (attr.contents) {
+      if (!Array.isArray(attr.contents) && typeof attr.contents !== "string") {
+        errors.push({
+          message: '"contents" must be an array or string',
+          path: [...path, "contents"],
+          code: "INVALID_CONTENTS_TYPE"
+        });
+      }
+    }
+  }
+  /**
+   * Parse multiple .ksy files and resolve imports.
+   *
+   * @param mainYaml - Main .ksy file content
+   * @param imports - Map of import names to their YAML content
+   * @param options - Parsing options
+   * @returns Parsed schema with resolved imports
+   */
+  parseWithImports(mainYaml, _imports, options = {}) {
+    const mainSchema = this.parse(mainYaml, options);
+    return mainSchema;
+  }
+};
+
+// src/interpreter/Context.ts
+var Context = class _Context {
+  /**
+   * Create a new execution context.
+   *
+   * @param _io - Binary stream being read
+   * @param _root - Root object of the parse tree
+   * @param _parent - Parent object (optional)
+   */
+  constructor(_io, _root = null, _parent = null) {
+    this._io = _io;
+    this._root = _root;
+    /** Stack of parent objects */
+    this.parentStack = [];
+    /** Current object being parsed */
+    this._current = {};
+    if (_parent !== null) {
+      this.parentStack.push(_parent);
+    }
+  }
+  /**
+   * Get the current I/O stream.
+   * Accessible in expressions as `_io`.
+   *
+   * @returns Current stream
+   */
+  get io() {
+    return this._io;
+  }
+  /**
+   * Get the root object.
+   * Accessible in expressions as `_root`.
+   *
+   * @returns Root object
+   */
+  get root() {
+    return this._root;
+  }
+  /**
+   * Get the parent object.
+   * Accessible in expressions as `_parent`.
+   *
+   * @returns Parent object or null if at root
+   */
+  get parent() {
+    return this.parentStack.length > 0 ? this.parentStack[this.parentStack.length - 1] : null;
+  }
+  /**
+   * Get the current object being parsed.
+   * Used to access fields defined earlier in the sequence.
+   *
+   * @returns Current object
+   */
+  get current() {
+    return this._current;
+  }
+  /**
+   * Set the current object.
+   *
+   * @param obj - Object to set as current
+   */
+  set current(obj) {
+    this._current = obj;
+  }
+  /**
+   * Push a new parent onto the stack.
+   * Used when entering a nested type.
+   *
+   * @param parent - Parent object to push
+   */
+  pushParent(parent) {
+    this.parentStack.push(parent);
+  }
+  /**
+   * Pop the current parent from the stack.
+   * Used when exiting a nested type.
+   *
+   * @returns The popped parent object
+   */
+  popParent() {
+    return this.parentStack.pop();
+  }
+  /**
+   * Get a value from the context by path.
+   * Supports special names: _io, _root, _parent, _index.
+   *
+   * @param name - Name or path to resolve
+   * @returns Resolved value
+   */
+  resolve(name) {
+    switch (name) {
+      case "_io":
+        return this._io;
+      case "_root":
+        return this._root;
+      case "_parent":
+        return this.parent;
+      case "_index":
+        return this._current["_index"];
+      default:
+        if (name in this._current) {
+          return this._current[name];
+        }
+        return void 0;
+    }
+  }
+  /**
+   * Set a value in the current object.
+   *
+   * @param name - Field name
+   * @param value - Value to set
+   */
+  set(name, value) {
+    this._current[name] = value;
+  }
+  /**
+   * Create a child context for nested parsing.
+   * The current object becomes the parent in the child context.
+   *
+   * @param stream - Stream for the child context (defaults to current stream)
+   * @returns New child context
+   */
+  createChild(stream) {
+    const childContext = new _Context(
+      stream || this._io,
+      this._root || this._current,
+      this._current
+    );
+    return childContext;
+  }
+  /**
+   * Clone this context.
+   * Creates a shallow copy with the same stream, root, and parent.
+   *
+   * @returns Cloned context
+   */
+  clone() {
+    const cloned = new _Context(this._io, this._root, this.parent);
+    cloned._current = { ...this._current };
+    cloned.parentStack = [...this.parentStack];
+    return cloned;
+  }
+};
+
+// src/interpreter/TypeInterpreter.ts
+var TypeInterpreter = class _TypeInterpreter {
+  /**
+   * Create a new type interpreter.
+   *
+   * @param schema - Kaitai Struct schema to interpret
+   * @param parentMeta - Parent schema's meta (for nested types)
+   */
+  constructor(schema, parentMeta) {
+    this.schema = schema;
+    this.parentMeta = parentMeta;
+    if (!schema.meta && !parentMeta) {
+      throw new ParseError("Schema must have meta section");
+    }
+    if (schema.meta && !schema.meta.id && !parentMeta) {
+      throw new ParseError("Root schema must have meta.id");
+    }
+  }
+  /**
+   * Parse binary data according to the schema.
+   *
+   * @param stream - Binary stream to parse
+   * @param parent - Parent object (for nested types)
+   * @returns Parsed object
+   */
+  parse(stream, parent) {
+    const result = {};
+    const context = new Context(stream, result, parent);
+    context.current = result;
+    if (this.schema.seq) {
+      for (const attr of this.schema.seq) {
+        const value = this.parseAttribute(attr, context);
+        if (attr.id) {
+          result[attr.id] = value;
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Parse a single attribute according to its specification.
+   *
+   * @param attr - Attribute specification
+   * @param context - Execution context
+   * @returns Parsed value
+   * @private
+   */
+  parseAttribute(attr, context) {
+    const stream = context.io;
+    if (attr.if) {
+      throw new NotImplementedError("Conditional parsing (if)");
+    }
+    if (attr.pos !== void 0) {
+      const pos = typeof attr.pos === "number" ? attr.pos : 0;
+      stream.seek(pos);
+    }
+    if (attr.io) {
+      throw new NotImplementedError("Custom I/O streams");
+    }
+    if (attr.repeat) {
+      return this.parseRepeated(attr, context);
+    }
+    if (attr.contents) {
+      return this.parseContents(attr, context);
+    }
+    return this.parseValue(attr, context);
+  }
+  /**
+   * Parse a repeated attribute.
+   *
+   * @param attr - Attribute specification with repeat
+   * @param context - Execution context
+   * @returns Array of parsed values
+   * @private
+   */
+  parseRepeated(attr, context) {
+    const result = [];
+    const stream = context.io;
+    switch (attr.repeat) {
+      case "expr": {
+        const count = typeof attr["repeat-expr"] === "number" ? attr["repeat-expr"] : 0;
+        for (let i = 0; i < count; i++) {
+          context.set("_index", i);
+          result.push(this.parseValue(attr, context));
+        }
+        break;
+      }
+      case "eos": {
+        while (!stream.isEof()) {
+          context.set("_index", result.length);
+          result.push(this.parseValue(attr, context));
+        }
+        break;
+      }
+      case "until": {
+        if (!attr["repeat-until"]) {
+          throw new ParseError("repeat-until expression is required");
+        }
+        throw new NotImplementedError("repeat-until");
+      }
+      default:
+        throw new ParseError(`Unknown repeat type: ${attr.repeat}`);
+    }
+    return result;
+  }
+  /**
+   * Parse and validate contents.
+   *
+   * @param attr - Attribute specification with contents
+   * @param context - Execution context
+   * @returns The validated contents
+   * @private
+   */
+  parseContents(attr, context) {
+    const stream = context.io;
+    const expected = attr.contents;
+    if (Array.isArray(expected)) {
+      const bytes = stream.readBytes(expected.length);
+      for (let i = 0; i < expected.length; i++) {
+        if (bytes[i] !== expected[i]) {
+          throw new ValidationError(
+            `Contents mismatch at byte ${i}: expected ${expected[i]}, got ${bytes[i]}`,
+            stream.pos - expected.length + i
+          );
+        }
+      }
+      return bytes;
+    } else {
+      const encoding = attr.encoding || this.schema.meta.encoding || "UTF-8";
+      const str = stream.readStr(expected.length, encoding);
+      if (str !== expected) {
+        throw new ValidationError(
+          `Contents mismatch: expected "${expected}", got "${str}"`,
+          stream.pos - expected.length
+        );
+      }
+      return str;
+    }
+  }
+  /**
+   * Parse a single value according to its type.
+   *
+   * @param attr - Attribute specification
+   * @param context - Execution context
+   * @returns Parsed value
+   * @private
+   */
+  parseValue(attr, context) {
+    const stream = context.io;
+    const type = attr.type;
+    if (attr.size !== void 0) {
+      const size = typeof attr.size === "number" ? attr.size : 0;
+      if (type === "str" || !type) {
+        const encoding = attr.encoding || this.schema.meta.encoding || "UTF-8";
+        if (type === "str") {
+          return stream.readStr(size, encoding);
+        } else {
+          return stream.readBytes(size);
+        }
+      } else {
+        const substream = stream.substream(size);
+        return this.parseType(type, substream, context);
+      }
+    }
+    if (attr["size-eos"]) {
+      if (type === "str") {
+        const encoding = attr.encoding || this.schema.meta.encoding || "UTF-8";
+        const bytes = stream.readBytesFull();
+        return new TextDecoder(encoding).decode(bytes);
+      } else {
+        return stream.readBytesFull();
+      }
+    }
+    if (!type) {
+      throw new ParseError("Attribute must have either type, size, or contents");
+    }
+    return this.parseType(type, stream, context);
+  }
+  /**
+   * Parse a value of a specific type.
+   *
+   * @param type - Type name or switch specification
+   * @param stream - Stream to read from
+   * @param context - Execution context
+   * @returns Parsed value
+   * @private
+   */
+  parseType(type, stream, context) {
+    if (typeof type === "object") {
+      throw new NotImplementedError("Switch types");
+    }
+    if (isBuiltinType(type)) {
+      return this.parseBuiltinType(type, stream, context);
+    }
+    if (this.schema.types && type in this.schema.types) {
+      const typeSchema = this.schema.types[type];
+      const meta = this.schema.meta || this.parentMeta;
+      const interpreter = new _TypeInterpreter(typeSchema, meta);
+      return interpreter.parse(stream, context.current);
+    }
+    throw new ParseError(`Unknown type: ${type}`);
+  }
+  /**
+   * Parse a built-in type.
+   *
+   * @param type - Built-in type name
+   * @param stream - Stream to read from
+   * @param context - Execution context
+   * @returns Parsed value
+   * @private
+   */
+  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");
+    if (isIntegerType(type)) {
+      return this.readInteger(base, endian, stream);
+    }
+    if (isFloatType(type)) {
+      return this.readFloat(base, endian, stream);
+    }
+    if (isStringType(type)) {
+      throw new ParseError("String types require size, size-eos, or terminator");
+    }
+    throw new ParseError(`Unknown built-in type: ${type}`);
+  }
+  /**
+   * Read an integer value.
+   *
+   * @param type - Integer type (u1, u2, u4, u8, s1, s2, s4, s8)
+   * @param endian - Endianness
+   * @param stream - Stream to read from
+   * @returns Integer value
+   * @private
+   */
+  readInteger(type, endian, stream) {
+    switch (type) {
+      case "u1":
+        return stream.readU1();
+      case "u2":
+        return endian === "le" ? stream.readU2le() : stream.readU2be();
+      case "u4":
+        return endian === "le" ? stream.readU4le() : stream.readU4be();
+      case "u8":
+        return endian === "le" ? stream.readU8le() : stream.readU8be();
+      case "s1":
+        return stream.readS1();
+      case "s2":
+        return endian === "le" ? stream.readS2le() : stream.readS2be();
+      case "s4":
+        return endian === "le" ? stream.readS4le() : stream.readS4be();
+      case "s8":
+        return endian === "le" ? stream.readS8le() : stream.readS8be();
+      default:
+        throw new ParseError(`Unknown integer type: ${type}`);
+    }
+  }
+  /**
+   * Read a floating point value.
+   *
+   * @param type - Float type (f4, f8)
+   * @param endian - Endianness
+   * @param stream - Stream to read from
+   * @returns Float value
+   * @private
+   */
+  readFloat(type, endian, stream) {
+    switch (type) {
+      case "f4":
+        return endian === "le" ? stream.readF4le() : stream.readF4be();
+      case "f8":
+        return endian === "le" ? stream.readF8le() : stream.readF8be();
+      default:
+        throw new ParseError(`Unknown float type: ${type}`);
+    }
+  }
+};
+
+// src/index.ts
+function parse(ksyYaml, buffer, options = {}) {
+  const { validate = true, strict = false } = options;
+  const parser = new KsyParser();
+  const schema = parser.parse(ksyYaml, { validate, strict });
+  const stream = new KaitaiStream(buffer);
+  const interpreter = new TypeInterpreter(schema);
+  return interpreter.parse(stream);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BUILTIN_TYPES,
+  Context,
+  EOFError,
+  KaitaiError,
+  KaitaiStream,
+  KsyParser,
+  NotImplementedError,
+  ParseError,
+  TypeInterpreter,
+  ValidationError,
+  getBaseType,
+  getTypeEndianness,
+  isBuiltinType,
+  isFloatType,
+  isIntegerType,
+  isStringType,
+  parse
+});
+/**
+ * @fileoverview Custom error classes for Kaitai Struct parsing and validation
+ * @module utils/errors
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * @fileoverview String encoding and decoding utilities for binary data
+ * @module utils/encoding
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * @fileoverview Binary stream reader for Kaitai Struct
+ * @module stream/KaitaiStream
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * @fileoverview Binary stream reading functionality
+ * @module stream
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * @fileoverview Type definitions for Kaitai Struct YAML schema (.ksy files)
+ * @module parser/schema
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * @fileoverview Parser for Kaitai Struct YAML (.ksy) files
+ * @module parser/KsyParser
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * @fileoverview Parser module for Kaitai Struct YAML files
+ * @module parser
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * @fileoverview Execution context for Kaitai Struct parsing
+ * @module interpreter/Context
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * @fileoverview Type interpreter for executing Kaitai Struct schemas
+ * @module interpreter/TypeInterpreter
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * @fileoverview Interpreter module for executing Kaitai Struct schemas
+ * @module interpreter
+ * @author Fabiano Pinto
+ * @license MIT
+ */
+/**
+ * @fileoverview Main entry point for kaitai-struct-ts library
+ * @module kaitai-struct-ts
+ * @author Fabiano Pinto
+ * @license MIT
+ * @version 0.2.0
+ *
+ * @description
+ * A runtime interpreter for Kaitai Struct binary format definitions in TypeScript.
+ * Parse any binary data format by providing a .ksy (Kaitai Struct YAML) definition file.
+ *
+ * @example
+ * ```typescript
+ * import { parse } from 'kaitai-struct-ts'
+ *
+ * const ksyDefinition = `
+ * meta:
+ *   id: my_format
+ *   endian: le
+ * seq:
+ *   - id: magic
+ *     contents: [0x4D, 0x5A]
+ *   - id: version
+ *     type: u2
+ * `
+ *
+ * const buffer = new Uint8Array([0x4D, 0x5A, 0x01, 0x00])
+ * const result = parse(ksyDefinition, buffer)
+ * console.log(result.version) // 1
+ * ```
+ */
+//# sourceMappingURL=index.js.map