adding error infrastructure

interop/src/debug.ts

@@ -1,3 +1,4 @@
+import { errors } from "./errors"
 import {
     DebugInfo,
     FunctionDebugInfo,
@@ -20,6 +21,13 @@ export interface StackFrame {
     fn: FunctionDebugInfo
 }
 
+const errorsRx = new RegExp(
+    Object.keys(errors)
+        .map(k => k.replace(/-/g, " "))
+        .join("|"),
+    "gi"
+)
+
 export function parseStackFrame(dbgInfo: DebugInfo, line: string) {
     const resolver = dbgInfo ? SrcMapResolver.from(dbgInfo) : undefined
     const frames: StackFrame[] = []
@@ -54,6 +62,11 @@ export function parseStackFrame(dbgInfo: DebugInfo, line: string) {
         .replace(/at\s+(\w*)_F(\d+)\s+\(pc:(\d+)\)/g, (_, fnName, fnIdx, pc) =>
             expand(pc, fnName, fnIdx)
         )
+        .replace(errorsRx, name => {
+            const id = name.replace(/ /g, "-").toLowerCase()
+            const text = errors[id]
+            return `${text} (https://microsoft.github.io/devicescript/developer/errors/#${id})`
+        })
     return { markedLine, frames }
 }
 

interop/src/errors.ts

@@ -0,0 +1,4 @@
+// generated file, run scripts/builderrors.mjs to update
+export const errors: Record<string, string> = {
+  "loopback-rx-ovf": "Loopback buffer overflow"
+};

package.json

@@ -7,8 +7,9 @@
         "build:jacdac-ts": "cd jacdac-ts && yarn build",
         "build:vscodeicons": "cd vscode && yarn buildicons",
         "build:slow": "node ./build.js",
-        "build": "yarn build:jacdac-ts && yarn build:vscodeicons && yarn build:slow",
+        "build": "yarn build:jacdac-ts && yarn build:vscodeicons && yarn build:errors && yarn build:slow",
         "build:jacdac-ts-fast": "cd jacdac-ts && node ./build.js --fast",
+        "build:errors": "node scripts/builderrors.mjs",
         "build-fast": "yarn build:jacdac-ts-fast && node ./build.js --fast",
         "package": "cd vscode && yarn package",
         "watch": "node ./build.js --watch",

packages/sampleprj/src/main.ts

@@ -1,5 +1,6 @@
 import { subscribeMessage, publishMessage } from "@devicescript/cloud"
 
+console.log("loopback rx ovf")
 setInterval(async () => {
     const data = {
         temp: 20 + Math.random() / 10,

scripts/builderrors.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env zx
+
+import "zx/globals"
+
+const md = await fs.readFile("./website/docs/developer/errors.mdx", {
+    encoding: "utf-8",
+})
+const ts =
+    (await fs.exists("./interop/src/errors.ts")) &&
+    (await fs.readFile("./interop/src/errors.ts", { encoding: "utf-8" }))
+const rx = /^##\s+(?<name>.+)\s+\{#(?<id>[^}]+)\}/gim
+const errors = {}
+md.replace(rx, _ => {
+    const m = rx.exec(_)
+    const { name, id } = m.groups
+    errors[id.toLowerCase()] = name
+    return ""
+})
+
+const fn = "./interop/src/errors.ts"
+const newTs = `// generated file, run scripts/builderrors.mjs to update
+export const errors: Record<string, string> = ${JSON.stringify(
+    errors,
+    null,
+    2
+)};
+`
+if (ts !== newTs) {
+    console.log(`writing ${fn}`)
+    await fs.writeFile(fn, newTs, { encoding: "utf-8" })
+}

website/docs/developer/errors.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 10000
+title: Errors
+description: Troubleshooting DeviceScript errors
+---
+
+# Errors
+
+## Loopback buffer overflow {#loopback-rx-ovf}
+
+The program is issuing requests to service client faster than the system can handle.