wit-parser 0.0.1-preview.1

A WIT (WebAssembly Interface Types) parser, resolver and component encoder

Readme Files Dependencies Versions

wit-parser#

A WebAssembly Interface Types (WIT) parser, semantic resolver, .wit.json serializer, and component type encoder for Zena.

Installation#

zena pkg add zena-lang:wit-parser

Example#

import { parse } from 'zena-lang:wit-parser';
import { AstItemTag } from 'zena-lang:wit-parser/parser';

let source = `
package example:greeter@1.0.0;

interface greet {
  record greeting { text: string, formal: bool }
  hello: func(name: string) -> greeting;
}

interface farewell {
  use greet.{greeting};
  goodbye: func(name: string) -> greeting;
}

world greeter {
  export greet;
  export farewell;
}
`;

// Parses syntax and resolves names and cross-interface `use` references.
// Throws `ParseError` or `ResolveError` if the document is invalid.
let doc = parse(source);

var interfaces = 0;
var worlds = 0;
for (let item in doc.items) {
  if (item.tag == AstItemTag.Interface) {
    interfaces += 1;
  } else if (item.tag == AstItemTag.World) {
    worlds += 1;
  }
}

Libraries#

zena-lang:wit-parser#

The primary entry point for parsing, resolving, and serializing WIT source text.

Function Description
parse(source) Parses and resolves source into a validated Ast. Throws ParseError or ResolveError.
parseSyntax(source) Parses source without resolving names, for single-file syntax tooling such as formatters.
resolve(ast) Resolves names and validates an Ast in place.
toJson(ast, packageOrder?) Serializes a resolved Ast to the .wit.json format emitted by wasm-tools component wit --json.

zena-lang:wit-parser also re-exports Ast, ParseError, and ResolveError. Both error types carry a Span with byte offsets into the source text.

zena-lang:wit-parser/parser#

The AST node declarations (Ast, AstItem, AstItemTag, InterfaceDef, WorldDef, TypeDef, Type, NamedFunc, ResourceFunc, Use, Include, Docs, Attribute, PackageName, NestedPackage, and related types) and Parser.

zena-lang:wit-parser/document#

Utilities for assembling multi-file WIT directories into a single source document while tracking file boundaries for error reporting:

  • WitFile(name, source) and joinWitDocument(files): concatenates .wit files in canonical name order and records where each file starts.
  • WitDocument.locate(offset): maps a byte offset back to a WitLocation (file, 1-based line, 1-based column).
  • witDiagnostic(doc, error): formats a LexError, ParseError, or ResolveError with its filename, line, column, source line, and caret underline.
  • findInterface(ast, namespace, interfacePath): looks up an interface (pkg/iface) in a parsed document.

zena-lang:wit-parser/component-encoder#

Encodes a resolved WIT world into WebAssembly Component Model binary type and import sections:

  • encodeTypesOnlyComponent(ast, worldName): encodes the named world as a standalone types-only component binary.
  • ComponentTypeEncoder: emits component type, alias, import, and export sections and canonical ABI metadata (WitFuncMeta, WitFlatMeta).
  • expandedWorldItems(ast, world) and worldNames(ast): expands world includes and transitive use dependencies.

zena-lang:wit-parser/lexer and zena-lang:wit-parser/token#

Low-level tokenization: Lexer, LexError, Token, TokenType, and Span.

zena-lang:wit-parser/resolver#

Semantic validation and name resolution: Resolver and ResolveError.

7.5 KiB Raw
import {PackageName, Id} from './parser.zena';
import {StringReader} from 'zena:core';

/** Normalize an identifier - strip '%' prefix if present (explicit escaping). */
export function normalizeId(name: String): String {
  if (name.length > 0 && name.getByteAt(0) == 37) { // '%'
    return name.sliceBytes(1, name.length);
  } else {
    return name;
  }
}

export function compareStrings(s1: String, s2: String): i32 {
  let len1 = s1.length;
  let len2 = s2.length;
  let minLen = if (len1 < len2) len1 else len2;
  
  for (var i = 0; i < minLen; i += 1) {
    let b1 = s1.getByteAt(i);
    let b2 = s2.getByteAt(i);
    if (b1 < b2) {
      return -1;
    }
    if (b1 > b2) {
      return 1;
    }
  }
  
  if (len1 < len2) {
    return -1;
  }
  if (len1 > len2) {
    return 1;
  }
  return 0;
}

export function isPurelyNumeric(s: String): boolean {
  if (s.length == 0) return false;
  for (var i = 0; i < s.length; i += 1) {
    let b = s.getByteAt(i);
    if (b < 48 || b > 57) {
      return false;
    }
  }
  return true;
}

export function stringToInt(s: String): i32 {
  var val = 0;
  for (var i = 0; i < s.length; i += 1) {
    let b = s.getByteAt(i);
    val = val * 10 + (b - 48);
  }
  return val;
}

function readInt(r: StringReader) {
  var val = 0;
  while (!r.isAtEnd) {
    let b = r.peekByte();
    if (b >= 48 && b <= 57) {
      val = val * 10 + (b - 48);
      r.advanceByte();
    } else {
      break;
    }
  }
  return val;
}

export function getPreIdentifiers(s: String, start: i32, end: i32): Array<String> {
  let arr = new GrowableArray<String>();
  if (start < 0 || start >= end) return arr;
  
  var curStart = start;
  for (var i = start; i < end; i += 1) {
    if (s.getByteAt(i) == 46) { // '.'
      arr.push(s.sliceBytes(curStart, i));
      curStart = i + 1;
    }
  }
  if (curStart < end) {
    arr.push(s.sliceBytes(curStart, end));
  }
  return arr;
}

export function compareVersions(v1: String, v2: String): i32 {
  let r1 = new StringReader(v1);
  let r2 = new StringReader(v2);
  
  let maj1 = readInt(r1);
  if (r1.peekByte() == 46) { r1.advanceByte(); } // '.'
  let min1 = readInt(r1);
  if (r1.peekByte() == 46) { r1.advanceByte(); } // '.'
  let pat1 = readInt(r1);
  
  let maj2 = readInt(r2);
  if (r2.peekByte() == 46) { r2.advanceByte(); } // '.'
  let min2 = readInt(r2);
  if (r2.peekByte() == 46) { r2.advanceByte(); } // '.'
  let pat2 = readInt(r2);
  
  if (maj1 < maj2) return -1;
  if (maj1 > maj2) return 1;
  if (min1 < min2) return -1;
  if (min1 > min2) return 1;
  if (pat1 < pat2) return -1;
  if (pat1 > pat2) return 1;
  
  var hasPre1 = false;
  var preStart1 = -1;
  var buildStart1 = -1;
  if (r1.peekByte() == 45) { // '-'
    hasPre1 = true;
    r1.advanceByte();
    preStart1 = r1.position;
  }
  while (!r1.isAtEnd) {
    if (r1.peekByte() == 43) { // '+'
      buildStart1 = r1.position;
      break;
    }
    r1.advanceByte();
  }
  let preEnd1 = if (buildStart1 >= 0) buildStart1 else r1.position;
  
  var hasPre2 = false;
  var preStart2 = -1;
  var buildStart2 = -1;
  if (r2.peekByte() == 45) { // '-'
    hasPre2 = true;
    r2.advanceByte();
    preStart2 = r2.position;
  }
  while (!r2.isAtEnd) {
    if (r2.peekByte() == 43) { // '+'
      buildStart2 = r2.position;
      break;
    }
    r2.advanceByte();
  }
  let preEnd2 = if (buildStart2 >= 0) buildStart2 else r2.position;
  
  if (hasPre1 && !hasPre2) return -1;
  if (!hasPre1 && hasPre2) return 1;
  if (!hasPre1 && !hasPre2) {
    return compareStrings(v1, v2);
  }
  
  let arr1 = getPreIdentifiers(v1, preStart1, preEnd1);
  let arr2 = getPreIdentifiers(v2, preStart2, preEnd2);
  
  let len1 = arr1.length;
  let len2 = arr2.length;
  let minLen = if (len1 < len2) len1 else len2;
  
  for (var idx = 0; idx < minLen; idx += 1) {
    let id1 = arr1[idx];
    let id2 = arr2[idx];
    
    let isNum1 = isPurelyNumeric(id1);
    let isNum2 = isPurelyNumeric(id2);
    
    if (isNum1 && isNum2) {
      let n1 = stringToInt(id1);
      let n2 = stringToInt(id2);
      if (n1 < n2) return -1;
      if (n1 > n2) return 1;
    } else if (isNum1) {
      return -1;
    } else if (isNum2) {
      return 1;
    } else {
      let comp = compareStrings(id1, id2);
      if (comp != 0) return comp;
    }
  }
  
  if (len1 < len2) return -1;
  if (len1 > len2) return 1;
  return compareStrings(v1, v2);
}

export function formatPackageName(name: PackageName | null): String {
  if (name == null) { return ""; }
  let n = name;
  var result = `${normalizeId(n.namespace.name)}:${normalizeId(n.name.name)}`;
  if (n.version != null) {
    result = `${result}@${n.version as String}`;
  }
  return result;
}

export function comparePackageNames(pn1: PackageName | null, pn2: PackageName | null): i32 {
  if (pn1 == null && pn2 == null) return 0;
  if (pn1 == null) return -1;
  if (pn2 == null) return 1;
  
  let p1 = pn1;
  let p2 = pn2;
  
  let ns1 = normalizeId(p1.namespace.name);
  let ns2 = normalizeId(p2.namespace.name);
  let nsComp = compareStrings(ns1, ns2);
  if (nsComp != 0) return nsComp;
  
  let n1 = normalizeId(p1.name.name);
  let n2 = normalizeId(p2.name.name);
  let nComp = compareStrings(n1, n2);
  if (nComp != 0) return nComp;
  
  if (p1.version == null && p2.version == null) return 0;
  if (p1.version == null) return -1;
  if (p2.version == null) return 1;
  
  return compareVersions(p1.version as String, p2.version as String);
}

export function comparePackageNameStrings(pkgOrder: Array<String>, k1: String, k2: String): i32 {
  if (k1 == k2) return 0;

  // Sort according to pkgOrder if both are present in the list
  var idx1 = -1;
  var idx2 = -1;
  for (var pIdx = 0; pIdx < pkgOrder.length; pIdx += 1) {
    if (pkgOrder[pIdx] == k1) { idx1 = pIdx; }
    if (pkgOrder[pIdx] == k2) { idx2 = pIdx; }
  }
  if (idx1 >= 0 && idx2 >= 0) {
    if (idx1 < idx2) return -1;
    return 1;
  }
  
  let p1 = parsePackageParts(k1);
  let p2 = parsePackageParts(k2);
  
  let nsComp = compareStrings(p1.namespace, p2.namespace);
  if (nsComp != 0) return nsComp;
  
  let nComp = compareStrings(p1.name, p2.name);
  if (nComp != 0) return nComp;
  
  let hasVer1 = p1.version != null;
  let hasVer2 = p2.version != null;
  
  if (!hasVer1 && !hasVer2) return 0;
  if (!hasVer1 && hasVer2) return -1;
  if (hasVer1 && !hasVer2) return 1;
  
  return compareVersions(p1.version as String, p2.version as String);
}

class PackageParts {
  namespace: String;
  name: String;
  version: String | null;
  new(this.namespace, this.name, this.version);
}

function parsePackageParts(name: String): PackageParts {
  let colonParts = name.split(":");
  var namespace = "";
  var rest = name;
  if (colonParts.length == 2) {
    namespace = colonParts[0];
    rest = colonParts[1];
  }
  
  let atParts = rest.split("@");
  if (atParts.length == 2) {
    return new PackageParts(namespace, atParts[0], atParts[1]);
  }
  return new PackageParts(namespace, rest, null);
}

export class PackageNameRef {
  packageName: String;
  version: String | null;
  new(this.packageName, this.version);
}

export function parsePackageName(name: String): PackageNameRef {
  let atParts = name.split("@");
  if (atParts.length == 2) {
    return new PackageNameRef(atParts[0], atParts[1]);
  }
  return new PackageNameRef(name, null);
}

export class InterfaceNameRef {
  packageName: String;
  version: String | null;
  interfaceName: String;
  new(this.packageName, this.version, this.interfaceName);
}

export function parseInterfaceName(name: String): InterfaceNameRef | null {
  let slashParts = name.split("/");
  if (slashParts.length != 2) {
    return null;
  }
  let pkgRef = parsePackageName(slashParts[0]);
  return new InterfaceNameRef(pkgRef.packageName, pkgRef.version, slashParts[1]);
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none