wesl 0.6.0-pre10

package/src/WeslDevice.ts

@@ -0,0 +1,209 @@
+import { ExtendedGPUValidationError } from "./LinkedWesl";
+import { encodeVlq } from "./vlq/vlq";
+
+/**
+ * We want the WebGPU compilation errors to point at WESL code.
+ * The native facilities are `device.pushErrorScope`, `device.popErrorScope`
+ * and `device.addEventListener("uncapturederror", (ev) => {})`
+ *
+ * So we track the error scopes.
+ * Then, when creating a shader module from WESL code, we forcibly capture the errors.
+ * And then re-emit them to the nearest validation error scope.
+ * If there isn't one, we throw it as an uncapturederror
+ */
+type ErrorScope = {
+  filter: GPUErrorFilter;
+  errors: Promise<GPUError | null>[];
+};
+
+/**
+ * A {@link GPUDevice} with extensions for WESL. Created with {@link makeWeslDevice}.
+ * Used to make error reporting point at the orignal WESL sources.
+ */
+export interface WeslDevice extends GPUDevice {
+  /**
+   * Attaches an error to the current error scope (created by {@link GPUDevice.pushErrorScope}).
+   * If there is no error scope, it reports the error as a `'uncapturederror'`
+   */
+  injectError(type: GPUErrorFilter, error: Promise<GPUError | null>): void;
+}
+
+/**
+ * Mutates a {@link GPUDevice} for usage with WESL. Does not impact your existing code, wherever a {@link GPUDevice} can be used, a {@link WeslDevice} is also valid.
+ *
+ * WESL uses this to display errors pointing at the WESL source instead of pointing at generated code.
+ */
+export function makeWeslDevice(device: GPUDevice): WeslDevice {
+  const errorScopeStack: ErrorScope[] = [];
+
+  (device as WeslDevice).injectError = (type, error) => {
+    const errorScope = errorScopeStack.findLast(v => v.filter === type);
+    if (errorScope !== undefined) {
+      errorScope.errors.push(error);
+    } else {
+      error.then(e => {
+        if (e !== null) {
+          dispatchError(e);
+        }
+      });
+    }
+  };
+
+  function dispatchError(e: GPUError) {
+    // If there's no scope, we throw an error through the WebGPU facilities
+    // Only dispatching an error doesn't result in a browser log message, so we implement that ourselves
+    // We also make sure to first go through the normal "uncapturederror" process. Since this is the last `addEventListener`, it will get called at the very end.
+    device.addEventListener(
+      "uncapturederror",
+      ev => {
+        if (!ev.defaultPrevented) {
+          if ("compilationInfo" in ev.error) {
+            const error = ev.error as ExtendedGPUValidationError;
+            // A custom mode with clickable sources. Uses https://stackoverflow.com/a/79467192/3492994
+            if (error.compilationInfo) {
+              for (const message of error.compilationInfo.messages) {
+                throwClickableError({
+                  url: message.module.url,
+                  text: message.module.text ?? null,
+                  lineNumber: message.lineNum,
+                  lineColumn: message.linePos,
+                  length: message.length,
+                  error: new Error(message.type + ": " + message.message),
+                });
+              }
+            } else {
+              console.error(ev.error.message);
+            }
+          } else {
+            console.error(ev.error.message);
+          }
+        }
+      },
+      {
+        // This event listener should only happen for this event!
+        once: true,
+      },
+    );
+    device.dispatchEvent(
+      new GPUUncapturedErrorEvent("uncapturederror", { error: e }),
+    );
+  }
+
+  // Keep track of the error scopes so that we can inject our errors into them
+  // Based on https://jsgist.org/?src=e3fb4659a668e00c69b03c82ec8f0ad1 from @greggman
+  device.pushErrorScope = ((
+    baseFn: GPUDevice["pushErrorScope"],
+  ): GPUDevice["pushErrorScope"] => {
+    return function (this: GPUDevice, filter: GPUErrorFilter) {
+      errorScopeStack.push({
+        filter,
+        errors: [],
+      });
+      return baseFn.call(this, filter);
+    };
+  })(device.pushErrorScope);
+
+  device.popErrorScope = ((
+    baseFn: GPUDevice["popErrorScope"],
+  ): GPUDevice["popErrorScope"] => {
+    return function (this: GPUDevice) {
+      // Get our custom error scope stack
+      const errorScope = errorScopeStack.pop();
+      if (errorScope === undefined) {
+        // This can also happen when makeWeslDevice was called after a `pushErrorScope`
+        throw new DOMException(
+          "popErrorScope called on empty error scope stack",
+          "OperationError",
+        );
+      }
+      // Add the real error reporter
+      errorScope.errors.push(baseFn.call(this));
+      // And get the first error (not null)
+      // LATER consider reporting *all* errors, and not just the first
+      const errorPromise = Promise.all(errorScope.errors).then(
+        values => values.find(v => v !== null) ?? null,
+      );
+      return errorPromise;
+    };
+  })(device.popErrorScope);
+
+  return device as WeslDevice;
+}
+
+// Based on https://stackoverflow.com/questions/65274147/sourceurl-for-css
+export function throwClickableError({
+  url,
+  text,
+  lineNumber,
+  lineColumn,
+  length,
+  error,
+}: {
+  url: string;
+  text: string | null;
+  lineNumber: number;
+  lineColumn: number;
+  length: number;
+  error: Error;
+}) {
+  // We remap an error directly to where we need it to be
+  // The fields are
+  // 1. Generated column (aka 0)
+  // 2. Index into sources list (aka 0)
+  // 3. Original line number (zero based)
+  // 4. Original column number (zero based)
+
+  // So we need 2 mappings. One to map to the correct spot,
+  // and another one to be the "length" (terminate the first mapping)
+  let mappings =
+    encodeVlq([
+      0,
+      0,
+      Math.max(0, lineNumber - 1),
+      Math.max(0, lineColumn - 1),
+    ]) +
+    "," +
+    // Sadly no browser makes use of this info to map the error properly
+    encodeVlq([
+      18, // Arbitrary number that is high enough
+      0,
+      Math.max(0, lineNumber - 1),
+      Math.max(0, lineColumn - 1) + length,
+    ]);
+
+  // And this is what our source map looks like
+  const sourceMap = {
+    version: 3,
+    file: null,
+    sources: [url],
+    sourcesContent: [text ?? null],
+    names: [],
+    mappings,
+  };
+
+  let generatedCode = `throw new Error(${JSON.stringify(error.message + "")})`;
+  // And redirect it to WESL
+  generatedCode +=
+    "\n//# sourceMappingURL=data:application/json;base64," +
+    btoa(unescape(encodeURIComponent(JSON.stringify(sourceMap))));
+  generatedCode += "\n//# sourceURL=" + sourceMap.sources[0];
+
+  let oldLimit = 0;
+  // Supported on Chrome https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stackTraceLimit
+  if ("stackTraceLimit" in Error) {
+    oldLimit = Error.stackTraceLimit;
+    Error.stackTraceLimit = 1;
+  }
+
+  // Run the error-throwing file
+  try {
+    (0, eval)(generatedCode);
+  } catch (e: any) {
+    if ("stackTraceLimit" in Error) {
+      Error.stackTraceLimit = oldLimit;
+    }
+    error.message = "";
+    e.cause = error;
+    throw e;
+  }
+}

package/src/debug/ASTtoString.ts

@@ -0,0 +1,290 @@
+import { assertUnreachable } from "../../../mini-parse/src/Assertions.ts";
+import {
+  AbstractElem,
+  Attribute,
+  AttributeElem,
+  DirectiveElem,
+  FnElem,
+  StuffElem,
+  TypedDeclElem,
+  TypeRefElem,
+  TypeTemplateParameter,
+  UnknownExpressionElem,
+} from "../AbstractElems.ts";
+import {
+  diagnosticControlToString,
+  expressionToString,
+} from "../LowerAndEmit.ts";
+import { importToString } from "./ImportToString.ts";
+import { LineWrapper } from "./LineWrapper.ts";
+
+const maxLineLength = 150;
+
+export function astToString(elem: AbstractElem, indent = 0): string {
+  const { kind } = elem;
+  const str = new LineWrapper(indent, maxLineLength);
+  str.add(kind);
+  addElemFields(elem, str);
+  let childStrings: string[] = [];
+  if ("contents" in elem) {
+    childStrings = elem.contents.map(e => astToString(e, indent + 2));
+  }
+  if (childStrings.length) {
+    str.nl();
+    str.addBlock(childStrings.join("\n"), false);
+  }
+
+  return str.result;
+}
+
+// LATER rewrite to be shorter and easier to read
+function addElemFields(elem: AbstractElem, str: LineWrapper): void {
+  const { kind } = elem;
+  if (kind === "text") {
+    const { srcModule, start, end } = elem;
+    str.add(` '${srcModule.src.slice(start, end)}'`);
+  } else if (
+    kind === "var" ||
+    kind === "let" ||
+    kind === "gvar" ||
+    kind === "const" ||
+    kind === "override"
+  ) {
+    addTypedDeclIdent(elem.name, str);
+    listAttributeElems(elem.attributes, str);
+  } else if (kind === "struct") {
+    str.add(" " + elem.name.ident.originalName);
+  } else if (kind === "member") {
+    const { name, typeRef, attributes } = elem;
+    listAttributeElems(attributes, str);
+    str.add(" " + name.name);
+    str.add(": " + typeRefElemToString(typeRef));
+  } else if (kind === "name") {
+    str.add(" " + elem.name);
+  } else if (kind === "memberRef") {
+    const { extraComponents } = elem;
+    const extraText =
+      extraComponents ? debugContentsToString(extraComponents) : "";
+    str.add(` ${elem.name.ident.originalName}.${elem.member.name}${extraText}`);
+  } else if (kind === "fn") {
+    addFnFields(elem, str);
+  } else if (kind === "alias") {
+    const { name, typeRef } = elem;
+    const prefix = name.ident.kind === "decl" ? "%" : "";
+    str.add(" " + prefix + name.ident.originalName);
+    str.add("=" + typeRefElemToString(typeRef));
+  } else if (kind === "attribute") {
+    addAttributeFields(elem.attribute, str);
+  } else if (kind === "expression") {
+    const contents = elem.contents
+      .map(e => {
+        if (e.kind === "text") {
+          return "'" + e.srcModule.src.slice(e.start, e.end) + "'";
+        } else {
+          return astToString(e);
+        }
+      })
+      .join(" ");
+    str.add(" " + contents);
+  } else if (kind === "type") {
+    const { name } = elem;
+    const nameStr = typeof name === "string" ? name : name.originalName;
+    str.add(" " + nameStr);
+
+    if (elem.templateParams !== undefined) {
+      const paramStrs = elem.templateParams
+        .map(templateParamToString)
+        .join(", ");
+      str.add("<" + paramStrs + ">");
+    }
+  } else if (kind === "synthetic") {
+    str.add(` '${elem.text}'`);
+  } else if (kind === "import") {
+    str.add(" " + importToString(elem.imports));
+  } else if (kind === "ref") {
+    str.add(" " + elem.ident.originalName);
+  } else if (kind === "typeDecl") {
+    addTypedDeclIdent(elem, str);
+  } else if (kind === "decl") {
+    const { ident } = elem;
+    str.add(" %" + ident.originalName);
+  } else if (kind === "assert") {
+    // Nothing to do for now
+  } else if (kind === "module") {
+    // Ignore this kind of elem
+  } else if (kind === "param") {
+    // LATER This branch shouldn't exist
+  } else if (kind === "stuff") {
+    // Ignore
+  } else if (kind === "directive") {
+    addDirective(elem, str);
+  } else if (kind === "statement") {
+    listAttributeElems(elem.attributes, str);
+  } else if (kind === "switch-clause") {
+    // Nothing to do for now
+  } else {
+    assertUnreachable(kind);
+  }
+}
+
+function addAttributeFields(attr: Attribute, str: LineWrapper) {
+  const { kind } = attr;
+  if (kind === "@attribute") {
+    const { name, params } = attr;
+    str.add(" @" + name);
+    if (params && params.length > 0) {
+      str.add("(");
+      str.add(params.map(unknownExpressionToString).join(", "));
+      str.add(")");
+    }
+  } else if (kind === "@builtin") {
+    str.add(` @builtin(${attr.param.name})`);
+  } else if (kind === "@diagnostic") {
+    str.add(
+      ` @diagnostic${diagnosticControlToString(attr.severity, attr.rule)}`,
+    );
+  } else if (kind === "@if") {
+    str.add(" @if");
+    str.add("(");
+    str.add(expressionToString(attr.param.expression));
+    str.add(")");
+  } else if (kind === "@interpolate") {
+    str.add(` @interpolate(${attr.params.map(v => v.name).join(", ")})`);
+  } else {
+    assertUnreachable(kind);
+  }
+}
+
+/** @return string representation of an attribute (for test/debug) */
+export function attributeToString(attr: Attribute): string {
+  const str = new LineWrapper(0, maxLineLength);
+  addAttributeFields(attr, str);
+  return str.result;
+}
+
+function addTypedDeclIdent(elem: TypedDeclElem, str: LineWrapper) {
+  const { decl, typeRef } = elem;
+  str.add(" %" + decl.ident.originalName);
+  if (typeRef) {
+    str.add(" : " + typeRefElemToString(typeRef));
+  }
+}
+
+function addFnFields(elem: FnElem, str: LineWrapper) {
+  const { name, params, returnType, attributes } = elem;
+
+  str.add(" " + name.ident.originalName);
+
+  str.add("(");
+  const paramStrs = params
+    .map(
+      (
+        p, // LATER DRY
+      ) => {
+        const { name } = p;
+        const { originalName } = name.decl.ident;
+        const typeRef = typeRefElemToString(name.typeRef!);
+        return originalName + ": " + typeRef;
+      },
+    )
+    .join(", ");
+  str.add(paramStrs);
+  str.add(")");
+
+  listAttributeElems(attributes, str);
+
+  if (returnType) {
+    str.add(" -> " + typeRefElemToString(returnType));
+  }
+}
+
+/** show attribute names in short form to verify collection */
+function listAttributeElems(
+  attributes: AttributeElem[] | undefined,
+  str: LineWrapper,
+) {
+  attributes?.forEach(a => str.add(" " + attributeName(a.attribute)));
+}
+
+function attributeName(attr: Attribute): string {
+  const { kind } = attr;
+  if (kind === "@attribute") {
+    return "@" + attr.name;
+  } else {
+    return kind;
+  }
+}
+
+function addDirective(elem: DirectiveElem, str: LineWrapper) {
+  const { directive, attributes } = elem;
+  const { kind } = directive;
+  if (kind === "diagnostic") {
+    const { severity, rule } = directive;
+    const control = diagnosticControlToString(severity, rule);
+    str.add(` diagnostic${control}`);
+  } else if (kind === "enable" || kind === "requires") {
+    str.add(` ${kind} ${directive.extensions.map(v => v.name).join(", ")}`);
+  } else {
+    assertUnreachable(kind);
+  }
+  listAttributeElems(attributes, str);
+}
+
+function unknownExpressionToString(elem: UnknownExpressionElem): string {
+  // LATER Temp hack while I clean up the expression parsing
+  if ("contents" in elem) {
+    // @ts-ignore
+    const contents = elem.contents
+      // @ts-ignore
+      .map(e => {
+        if (e.kind === "text") {
+          return "'" + e.srcModule.src.slice(e.start, e.end) + "'";
+        } else {
+          return astToString(e);
+        }
+      })
+      .join(" ");
+    return contents;
+  }
+  return astToString(elem);
+}
+
+function templateParamToString(p: TypeTemplateParameter): string {
+  if (typeof p === "string") {
+    return p;
+  } else if (p.kind === "type") {
+    return typeRefElemToString(p);
+  } else if (p.kind === "expression") {
+    return unknownExpressionToString(p);
+  } else {
+    console.log("unknown template parameter type", p);
+    return "??";
+  }
+}
+
+function typeRefElemToString(elem: TypeRefElem): string {
+  if (!elem) return "?type?";
+  const { name } = elem;
+  const nameStr = typeof name === "string" ? name : name.originalName;
+
+  let params = "";
+  if (elem.templateParams !== undefined) {
+    const paramStrs = elem.templateParams.map(templateParamToString).join(", ");
+    params = "<" + paramStrs + ">";
+  }
+  return nameStr + params;
+}
+
+export function debugContentsToString(elem: StuffElem): string {
+  const parts = elem.contents.map(c => {
+    const { kind } = c;
+    if (kind === "text") {
+      return c.srcModule.src.slice(c.start, c.end);
+    } else if (kind === "ref") {
+      return c.ident.originalName; // not using the mapped to decl name, so this can be used for debug..
+    } else {
+      return `?${c.kind}?`;
+    }
+  });
+  return parts.join(" ");
+}

package/src/debug/ImportToString.ts

@@ -0,0 +1,29 @@
+import { assertUnreachable } from "../../../mini-parse/src/Assertions";
+import {
+  ImportCollection,
+  ImportItem,
+  ImportStatement,
+} from "../AbstractElems";
+
+export function importToString(tree: ImportStatement): string {
+  return importToStringImpl(tree) + ";";
+}
+
+function importToStringImpl(tree: ImportStatement): string {
+  return [
+    ...tree.segments.map(s => s.name),
+    segmentToString(tree.finalSegment),
+  ].join("::");
+}
+
+function segmentToString(segment: ImportCollection | ImportItem): string {
+  if (segment.kind === "import-item") {
+    const { name, as } = segment;
+    const asMsg = as ? ` as ${as}` : "";
+    return `${name}${asMsg}`;
+  } else if (segment.kind === "import-collection") {
+    return `{${segment.subtrees.map(s => importToStringImpl(s)).join(", ")}}`;
+  } else {
+    assertUnreachable(segment);
+  }
+}

package/src/debug/LineWrapper.ts

@@ -0,0 +1,70 @@
+/** debug utility for constructing strings that wrap at a fixed column width
+ * text beyond the column width is wrapped to start on the next line
+ */
+export class LineWrapper {
+  #fragments: string[] = [];
+  #column = 0;
+  #spc: string;
+  #oneLine = true;
+  #isHanging = false;
+  #hangingSpc: string;
+
+  constructor(
+    readonly indent = 0,
+    readonly maxWidth = 60,
+    readonly hangingIndent = 2,
+  ) {
+    this.#spc = " ".repeat(indent);
+    this.#hangingSpc = " ".repeat(hangingIndent);
+  }
+
+  /** add a new line to the constructed string */
+  nl() {
+    this.#fragments.push("\n");
+    this.#column = 0;
+    this.#oneLine = false;
+    this.#isHanging = false;
+  }
+
+  /** add a string, wrapping to the next line if necessary */
+  add(s: string) {
+    if (this.#column + firstLineLength(s) > this.maxWidth) {
+      this.hangingNl();
+    }
+    if (this.#column === 0) {
+      this.#fragments.push(this.#spc);
+      if (this.#isHanging) {
+        this.#fragments.push(this.#hangingSpc);
+      }
+      this.#column = this.indent;
+    }
+    this.#fragments.push(s);
+    this.#column += s.length;
+  }
+
+  /** add a raw block of text with no wrapping */
+  addBlock(s: string, andNewLine = true) {
+    this.#fragments.push(s);
+    if (andNewLine) this.nl();
+  }
+
+  /** @return the constructed string */
+  get result(): string {
+    return this.#fragments.join("");
+  }
+
+  /** true if the result contains no newlines */
+  get oneLine(): boolean {
+    return this.#oneLine;
+  }
+
+  private hangingNl() {
+    this.nl();
+    this.#isHanging = true;
+  }
+}
+
+function firstLineLength(s: string): number {
+  const i = s.indexOf("\n");
+  return i === -1 ? s.length : i;
+}

package/src/debug/ScopeToString.ts

@@ -0,0 +1,79 @@
+import { childScope, Ident, Scope } from "../Scope.ts";
+import { attributeToString } from "./ASTtoString.ts";
+import { LineWrapper } from "./LineWrapper.ts";
+
+/** A debugging print of the scope tree with identifiers in nested brackets */
+export function scopeToString(
+  scope: Scope,
+  indent = 0,
+  shortIdents = true,
+): string {
+  const { contents, kind, ifAttribute } = scope;
+
+  const str = new LineWrapper(indent);
+  const attrStrings = ifAttribute && attributeToString(ifAttribute);
+  if (attrStrings) str.add(attrStrings + " ");
+  if (kind === "partial") str.add("-");
+  str.add("{ ");
+
+  const last = contents.length - 1;
+  let lastWasScope = false;
+  let hasBlock = false;
+  contents.forEach((elem, i) => {
+    if (childScope(elem)) {
+      const childScope: Scope = elem;
+      const childBlock = scopeToString(childScope, indent + 2, shortIdents);
+      !lastWasScope && str.nl();
+      str.addBlock(childBlock);
+      lastWasScope = true;
+      hasBlock = true;
+    } else {
+      lastWasScope && str.add("  ");
+      lastWasScope = false;
+      const ident: Ident = elem;
+      if (shortIdents) {
+        str.add(identShortString(ident));
+      } else {
+        str.add(identToString(ident));
+      }
+      if (i < last) str.add(" ");
+    }
+  });
+
+  if (!hasBlock && str.oneLine) {
+    str.add(" }");
+  } else {
+    if (hasBlock && !lastWasScope) str.nl();
+    str.add("}");
+  }
+
+  str.add(` #${scope.id}`);
+
+  return str.result;
+}
+
+/** A debug print of the scope tree with identifiers in long form in nested brackets */
+export function scopeToStringLong(scope: Scope): string {
+  return scopeToString(scope, 0, false);
+}
+
+/** name of an identifier, with decls prefixed with '%' */
+function identShortString(ident: Ident): string {
+  const { kind, originalName } = ident;
+  const prefix = kind === "decl" ? "%" : "";
+  return `${prefix}${originalName}`;
+}
+
+export function identToString(ident?: Ident): string {
+  if (!ident) return JSON.stringify(ident);
+  const { kind, originalName } = ident;
+  const idStr = ident.id ? `#${ident.id}` : "";
+  if (kind === "ref") {
+    const ref = identToString(ident.refersTo!);
+    return `${originalName} ${idStr} -> ${ref}`;
+  } else {
+    const { mangledName } = ident;
+    const mangled = mangledName ? `(${mangledName})` : "";
+    return `%${originalName}${mangled} ${idStr} `;
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./debug/ASTtoString.js";
+export * from "./debug/ScopeToString.js";
+export * from "./LinkedWesl.js";
+export * from "./Linker.js";
+export { WeslStream } from "./parse/WeslStream.js";
+export * from "./ParsedRegistry.js";
+export * from "./ParseWESL.js";
+export * from "./PathUtil.js";
+export * from "./TransformBindingStructs.js";
+export * from "./WeslBundle.js";
+export * from "./WeslDevice.js";