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.

8.6 KiB Raw
/**
 * Assembling and querying WIT documents, for the parser's consumers.
 *
 * The parser takes a source string; these are the steps just before
 * and after it that every consumer repeats — joining a package
 * directory's files into one document in a canonical way, finding an
 * interface in the parsed result, and naming the file and line a
 * failure happened at. They live here rather than in each consumer
 * because their behavior is contract: the compiler's `--wit` flag and
 * its WIT-backed packages must agree on what "a directory of WIT"
 * means, whether the host reads it from disk or holds it in memory.
 *
 * Nothing here does I/O. The caller reads the files.
 */

import { StringBuilder } from 'zena:core';
import { Span } from './token.zena';
import { LexError } from './lexer.zena';
import {
  Ast, AstItem, AstItemTag, InterfaceDef, PackageName, ParseError
} from './parser.zena';
import { ResolveError } from './resolver.zena';

/** Byte-wise string order, for a listing that reads the same everywhere. */
function byteCompare(a: String, b: String) {
  var minLen = a.length;
  if (b.length < minLen) {
    minLen = b.length;
  }
  for (var i = 0; i < minLen; i += 1) {
    let d = a.getByteAt(i) - b.getByteAt(i);
    if (d != 0) {
      return d;
    }
  }
  return a.length - b.length;
}

/** One file of a WIT package directory: its name and its text. */
export final class WitFile {
  name: String;
  source: String;
  new(this.name, this.source);
}

/** Where one of a joined document's files begins in it. */
export final class WitFileStart {
  name: String;
  start: i32;
  new(this.name, this.start);
}

/** Where a byte offset in a document falls, for a reader to go look. */
export final class WitLocation {
  /** The file the offset came from, named as the document's files were. */
  file: String;
  /** 1-based line within that file. */
  line: i32;
  /** 1-based column, in bytes. */
  column: i32;
  new(this.file, this.line, this.column);
}

/**
 * A joined document and where each of its files begins in it.
 *
 * A directory of WIT is parsed as one document, so a `Span` from the
 * parser is an offset into the concatenation while a reader needs a
 * file and a line in it. The starts are recorded as the document is
 * joined, which keeps `locate` the only code that knows how it was put
 * together.
 */
export final class WitDocument {
  /** The joined source, as the parser sees it. */
  source: String;
  /** Each `.wit` file in document order. Empty for an empty document. */
  files: Array<WitFileStart>;

  new(this.source, this.files);

  /** Which file `offset` is in, and where in it. */
  locate(offset: i32): WitLocation {
    var at = offset;
    if (at < 0) { at = 0; }
    if (at > this.source.length) { at = this.source.length; }
    var file = "";
    var fileStart = 0;
    for (let f in this.files) {
      if (f.start <= at) {
        file = f.name;
        fileStart = f.start;
      }
    }
    // Lines count from the file's own start, not the document's, so the
    // number is the one an editor shows.
    var line = 1;
    var lineStart = fileStart;
    for (var i = fileStart; i < at; i += 1) {
      if (this.source.getByteAt(i) == 10) { // '\n'
        line += 1;
        lineStart = i + 1;
      }
    }
    return new WitLocation(file, line, at - lineStart + 1);
  }

  /** The text of the line `offset` is on, without its newline. */
  lineTextAt(offset: i32): String {
    var at = offset;
    if (at < 0) { at = 0; }
    if (at > this.source.length) { at = this.source.length; }
    var start = at;
    while (start > 0 && this.source.getByteAt(start - 1) != 10) {
      start -= 1;
    }
    var end = at;
    while (end < this.source.length && this.source.getByteAt(end) != 10) {
      end += 1;
    }
    return this.source.sliceBytes(start, end);
  }
}

/**
 * The document a directory of WIT makes: its `.wit` files concatenated
 * in byte order of their names, each followed by a newline, and where
 * each of them begins in the result. Files with other extensions are
 * left out, and with no `.wit` files the document is empty.
 */
export function joinWitDocument(files: Array<WitFile>): WitDocument {
  let wit = new GrowableArray<WitFile>();
  for (let file in files) {
    if (file.name.endsWith(".wit")) {
      wit.push(file);
    }
  }
  // Name order, so the document is the same however the host lists.
  for (var a = 0; a < wit.length; a += 1) {
    for (var b = a + 1; b < wit.length; b += 1) {
      if (byteCompare(wit[b].name, wit[a].name) < 0) {
        let t = wit[a];
        wit[a] = wit[b];
        wit[b] = t;
      }
    }
  }
  let starts = new Array<WitFileStart>();
  var source = "";
  for (let file in wit) {
    starts.push(new WitFileStart(file.name, source.length));
    source = `${source}${file.source}\n`;
  }
  return new WitDocument(source, starts);
}

/**
 * `joinWitDocument`'s source alone, for a caller with nothing to
 * report against it.
 */
export function joinWitFiles(files: Array<WitFile>): String {
  return joinWitDocument(files).source;
}

/**
 * The span `e` happened at, when `e` is one of the three failures the
 * parser raises against a document: `LexError`, `ParseError`,
 * `ResolveError`. Anything else is a fault in the parser itself and
 * carries no position.
 */
export function witErrorSpan(e: Error): Span | null {
  if (e is LexError) {
    return e.span;
  }
  if (e is ParseError) {
    return e.span;
  }
  if (e is ResolveError) {
    return e.span;
  }
  return null;
}

/**
 * `e` rendered against `doc` as a terminal diagnostic: the file, line
 * and column it happened at, then the offending line and an underline.
 * The header is `file:line:column - Error: `, which is what the Zena
 * compiler's own syntax errors carry.
 *
 * Null when `e` carries no span, and null when its span is past the end
 * of `doc`: the compiler splices a program's WIT-backed packages onto a
 * document before parsing it, and a failure in that spliced text has no
 * file this document can name. The caller reports the message plainly.
 */
export function witDiagnostic(doc: WitDocument, e: Error): String | null {
  let span = witErrorSpan(e);
  if (span == null) {
    return null;
  }
  let at = span;
  if (at.start > doc.source.length) {
    return null;
  }
  let loc = doc.locate(at.start);
  let sb = new StringBuilder();
  sb.append(`${loc.file}:${loc.line}:${loc.column} - Error: ${e.message}\n`);
  sb.append(`${doc.lineTextAt(at.start)}\n`);
  for (var i = 1; i < loc.column; i += 1) {
    sb.append(" ");
  }
  // A zero-width span — the end of the document — still gets one caret
  // to point with.
  var width = at.end - at.start;
  if (width < 1) { width = 1; }
  for (var i = 0; i < width; i += 1) {
    sb.append("^");
  }
  return sb.toString();
}

/** One interface of a parsed document, with its package's name. */
export final class FoundInterface {
  def: InterfaceDef;
  packageName: PackageName;
  new(this.def, this.packageName);
}

/**
 * The interface `namespace:interfacePath` (`pkg/iface`) in `ast`, from
 * the main package or a nested one.
 *
 * Versions are the WIT's own business — callers resolve by unversioned
 * name — so matching ignores them, and two versions of one interface
 * in the same document is an error rather than a guess.
 */
export function findInterface(
  ast: Ast,
  namespace: String,
  interfacePath: String
): FoundInterface {
  let found = findInterfaceOrNull(ast, namespace, interfacePath);
  if (found == null) {
    throw new Error("WIT interface '" + namespace + ":" + interfacePath +
        "' is not declared by the package's WIT.");
  }
  return found;
}

/** `findInterface`, but an absent interface is null rather than a
 * throw — for callers with their own way of saying no, like a `use`
 * hop reported as a per-member skip. A duplicate still throws. */
export function findInterfaceOrNull(
  ast: Ast,
  namespace: String,
  interfacePath: String
): FoundInterface | null {
  var found: FoundInterface | null = null;
  var matches = 0;
  let consider = (pkg: PackageName | null, items: Array<AstItem>) => {
    if (pkg == null) {
      return;
    }
    let p = pkg;
    for (let item in items) {
      if (item.tag != AstItemTag.Interface) {
        continue;
      }
      let def = item.interfaceDef as InterfaceDef;
      let path = `${p.name.name}/${def.name.name}`;
      if (p.namespace.name == namespace && path == interfacePath) {
        found = new FoundInterface(def, p);
        matches += 1;
      }
    }
  };
  consider(ast.packageName, ast.items);
  for (let nested in ast.nestedPackages) {
    consider(nested.name, nested.items);
  }
  if (matches > 1) {
    throw new Error("WIT interface '" + namespace + ":" + interfacePath +
        "' is declared more than once (differing versions?) — pin one.");
  }
  return found;
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none