@tsplc/debug 0.0.0-stage → 0.2.16

package/src/ui/tree.ts

@@ -0,0 +1,156 @@
+import type { DebugConstant, DebugManifest, SourceRange } from "../manifest.ts";
+import { joinPath, pathSegments, typeOf } from "../paths.ts";
+
+/** One row of the instance tree: a root, a record field, an array element or a folded constant. */
+export interface TreeNode {
+  path: string;
+  /** The last segment: a field name, `[3]`, or the whole path for a top-level node. */
+  name: string;
+  type: string;
+  declaration?: SourceRange;
+  /** Whether the target adapter can read it at runtime. */
+  readable: boolean;
+  generated: boolean;
+  constant?: DebugConstant;
+}
+
+export interface TreeRow {
+  node: TreeNode;
+  depth: number;
+}
+
+export const parentPath = (path: string) =>
+  path.slice(0, Math.max(path.lastIndexOf("."), path.lastIndexOf("[")));
+
+/** Every proper prefix of `path` at a `.` or `[` boundary, shortest first. */
+export const ancestorPaths = (path: string) =>
+  [...path.matchAll(/[.[]/g)].map((match) => path.slice(0, match.index));
+
+/** The manifest's instances as a lazily expanded tree, addressed by TypeScript path. */
+export class ManifestTree {
+  readonly top: TreeNode[];
+  private readonly constantsByParent = new Map<string, DebugConstant[]>();
+  private readonly children = new Map<string, TreeNode[]>();
+
+  constructor(readonly manifest: DebugManifest) {
+    const roots = manifest.roots.map((root) => ({
+      path: root.path,
+      name: root.path,
+      type: root.type,
+      declaration: root.declaration,
+      readable: root.readable,
+      generated: root.generated === true,
+    }));
+    for (const constant of manifest.constants) {
+      const parent = parentPath(constant.path);
+      this.constantsByParent.set(parent, [...(this.constantsByParent.get(parent) ?? []), constant]);
+    }
+    const orphans = manifest.constants.filter(
+      (constant) => !this.resolveVariable(roots, parentPath(constant.path)),
+    );
+    this.top = [...roots, ...orphans.map((constant) => this.constantNode(constant, constant.path))];
+  }
+
+  expandable(node: TreeNode) {
+    if (node.constant) return false;
+    const kind = typeOf(this.manifest, node.type).kind;
+    return kind === "record" || kind === "array";
+  }
+
+  childrenOf(node: TreeNode): TreeNode[] {
+    const cached = this.children.get(node.path);
+    if (cached) return cached;
+    const type = typeOf(this.manifest, node.type);
+    const variables: TreeNode[] =
+      type.kind === "record"
+        ? type.fields.map((field) => ({
+            path: `${node.path}.${field.name}`,
+            name: field.name,
+            type: field.type,
+            declaration: field.declaration,
+            readable: node.readable,
+            generated: node.generated || field.generated === true,
+          }))
+        : type.kind === "array"
+          ? Array.from({ length: type.length }, (_, offset) => ({
+              path: `${node.path}[${type.lower + offset}]`,
+              name: `[${type.lower + offset}]`,
+              type: type.element,
+              declaration: node.declaration,
+              readable: node.readable,
+              generated: node.generated,
+            }))
+          : [];
+    const constants = (this.constantsByParent.get(node.path) ?? []).map((constant) =>
+      this.constantNode(constant, constant.path.slice(node.path.length + 1)),
+    );
+    const children = [...variables, ...constants];
+    this.children.set(node.path, children);
+    return children;
+  }
+
+  /** The rows shown for an expansion state, depth first. */
+  rows(expanded: ReadonlySet<string>, showGenerated: boolean): TreeRow[] {
+    const rows: TreeRow[] = [];
+    const visit = (nodes: TreeNode[], depth: number) => {
+      for (const node of nodes) {
+        if (node.generated && !showGenerated) continue;
+        rows.push({ node, depth });
+        if (expanded.has(node.path) && this.expandable(node))
+          visit(this.childrenOf(node), depth + 1);
+      }
+    };
+    visit(this.top, 0);
+    return rows;
+  }
+
+  /** Nodes whose path contains `query` (case-insensitive), in tree order, at most `limit`. */
+  search(query: string, showGenerated: boolean, limit: number) {
+    const needle = query.toLowerCase();
+    const found: TreeNode[] = [];
+    let total = 0;
+    const visit = (nodes: TreeNode[]) => {
+      for (const node of nodes) {
+        if (node.generated && !showGenerated) continue;
+        if (node.path.toLowerCase().includes(needle) && total++ < limit) found.push(node);
+        if (this.expandable(node)) visit(this.childrenOf(node));
+      }
+    };
+    visit(this.top);
+    return { nodes: found, total };
+  }
+
+  resolve(path: string): TreeNode | undefined {
+    const constant = this.manifest.constants.find((entry) => entry.path === path);
+    if (constant) return this.constantNode(constant, path);
+    return this.resolveVariable(this.top, path);
+  }
+
+  private resolveVariable(top: TreeNode[], path: string): TreeNode | undefined {
+    let node = top.find(
+      (root) =>
+        path === root.path ||
+        (path.startsWith(root.path) && /^[.[]/.test(path.slice(root.path.length))),
+    );
+    while (node && node.path !== path) {
+      const rest = path.slice(node.path.length);
+      const [segment] = pathSegments(rest);
+      if (!segment) return undefined;
+      const childPath = joinPath(node.path, segment);
+      node = this.childrenOf(node).find((child) => child.path === childPath);
+    }
+    return node;
+  }
+
+  private constantNode(constant: DebugConstant, name: string): TreeNode {
+    return {
+      path: constant.path,
+      name,
+      type: constant.type,
+      declaration: constant.declaration,
+      readable: false,
+      generated: false,
+      constant,
+    };
+  }
+}

package/src/ui/variables.ts

@@ -0,0 +1,469 @@
+import { LiveValue, type View, empty, fill, h, pathLink, sourceLink, wrappingPath } from "./dom.ts";
+import { typeLabel } from "./format.ts";
+import type { Store, Topic } from "./store.ts";
+import { typeOf } from "../paths.ts";
+import { type TreeNode, type TreeRow, ancestorPaths, parentPath } from "./tree.ts";
+
+const ROW_HEIGHT = 26;
+const OVERSCAN = 10;
+const SEARCH_LIMIT = 5000;
+const LIVE_TOPICS: Topic[] = ["samples", "clock", "session", "stream"];
+
+// Kept across visits, so leaving the page and coming back keeps the tree as it was.
+const expanded = new Set<string>();
+let showGenerated = false;
+let query = "";
+let activeGroup: string | undefined;
+
+const highlight = (path: string, needle: string) => {
+  const at = path.toLowerCase().indexOf(needle.toLowerCase());
+  return h(
+    "span",
+    {},
+    path.slice(0, at),
+    h("mark", {}, path.slice(at, at + needle.length)),
+    path.slice(at + needle.length),
+  );
+};
+
+export const variablesView = (store: Store, params: URLSearchParams): View => {
+  const { tree, manifest, paths } = store;
+  let selected = params.get("path") ?? undefined;
+  let rows: TreeRow[] = [];
+  let windowStart = -1;
+  let windowEnd = -1;
+  let rowValues: LiveValue[] = [];
+  let groupValues: LiveValue[] = [];
+  let detailValue: LiveValue | undefined;
+  let searchTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const search = h("input", {
+    type: "search",
+    class: "search",
+    placeholder: "Search TypeScript paths, e.g. binTrackers[3].bin",
+    value: query,
+    spellcheck: "false",
+  });
+  const generatedToggle = h("input", { type: "checkbox", checked: showGenerated });
+  const count = h("span", { class: "count" });
+  const windowElement = h("div", { class: "vwindow" });
+  const spacer = h("div", { class: "vspacer" }, windowElement);
+  const list = h("div", { class: "vlist", tabindex: 0, role: "tree" }, spacer);
+  const detail = h("section", { class: "panel detail" });
+  const groups = h("section", { class: "panel groups" });
+  const element = h(
+    "div",
+    { class: "page variables" },
+    h(
+      "div",
+      { class: "toolbar" },
+      search,
+      h("label", { class: "check" }, generatedToggle, "show generated"),
+      count,
+    ),
+    h(
+      "div",
+      { class: "split" },
+      h(
+        "div",
+        { class: "listwrap" },
+        h(
+          "div",
+          { class: "row head" },
+          h("span", {}, "Path"),
+          h("span", {}, "Value"),
+          h("span", {}, "Quality · read"),
+          h("span", {}, "Type"),
+          h("span", { title: "In the active watch group" }, "Watch"),
+          h("span", {}, "Declared"),
+        ),
+        list,
+      ),
+      h("aside", { class: "side" }, detail, groups),
+    ),
+  );
+
+  const watched = (path: string) =>
+    Object.values(store.watch.groups).some((paths) => paths.includes(path));
+  const inActiveGroup = (path: string) =>
+    activeGroup !== undefined && (store.watch.groups[activeGroup] ?? []).includes(path);
+
+  const subscribe = () =>
+    store.show({
+      watch: [...rowValues, ...groupValues, ...(detailValue ? [detailValue] : [])]
+        .filter((value) => value.subscribed)
+        .map((value) => value.node.path),
+    });
+
+  const toggleWatch = (path: string) => {
+    const group = activeGroup ?? "Watch";
+    activeGroup = group;
+    const members = store.watch.groups[group] ?? [];
+    void store.saveWatch({
+      ...store.watch.groups,
+      [group]: members.includes(path)
+        ? members.filter((member) => member !== path)
+        : [...members, path],
+    });
+  };
+
+  const renderRow = ({ node, depth }: TreeRow, index: number) => {
+    const expandable = tree.expandable(node);
+    const value = expandable ? undefined : new LiveValue(store, node);
+    if (value) rowValues.push(value);
+    const type = typeOf(manifest, node.type);
+    const open = expanded.has(node.path);
+    const inGroup = inActiveGroup(node.path);
+    return h(
+      "div",
+      {
+        class: `row${node.path === selected ? " selected" : ""}${node.generated ? " generated" : ""}`,
+        "data-index": index,
+        role: "treeitem",
+        "aria-level": depth + 1,
+        "aria-expanded": expandable && !query ? String(open) : undefined,
+      },
+      h(
+        "span",
+        { class: "name", style: `padding-left:${depth * 16 + 4}px`, title: node.path },
+        expandable && !query
+          ? h(
+              "button",
+              { class: "twisty", "data-action": "toggle", tabindex: -1 },
+              open ? "▾" : "▸",
+            )
+          : h("span", { class: "twisty" }),
+        query ? highlight(node.path, query) : node.name,
+        node.generated ? h("span", { class: "tag" }, "generated") : undefined,
+      ),
+      value?.value ??
+        h("span", { class: "value s-group" }, type.kind === "array" ? `[${type.length}]` : "{…}"),
+      value?.meta ?? h("span"),
+      h("span", { class: "type" }, typeLabel(manifest, node.type)),
+      value?.subscribed
+        ? h(
+            "button",
+            {
+              class: `rec${inGroup ? " on" : watched(node.path) ? " elsewhere" : ""}`,
+              "data-action": "watch",
+              tabindex: -1,
+              title: inGroup
+                ? `Watched in “${activeGroup}”: click to remove`
+                : `Watch: add to “${activeGroup ?? "Watch"}”`,
+            },
+            "●",
+          )
+        : h("span"),
+      node.declaration ? sourceLink(store, node.declaration) : h("span"),
+    );
+  };
+
+  const renderWindow = (force: boolean) => {
+    const start = Math.max(0, Math.floor(list.scrollTop / ROW_HEIGHT) - OVERSCAN);
+    const end = Math.min(
+      rows.length,
+      Math.ceil((list.scrollTop + list.clientHeight) / ROW_HEIGHT) + OVERSCAN,
+    );
+    if (!force && start === windowStart && end === windowEnd) return;
+    windowStart = start;
+    windowEnd = end;
+    rowValues = [];
+    windowElement.style.transform = `translateY(${start * ROW_HEIGHT}px)`;
+    windowElement.replaceChildren(
+      ...rows.slice(start, end).map((row, offset) => renderRow(row, start + offset)),
+    );
+    subscribe();
+  };
+
+  const recompute = () => {
+    if (query) {
+      const result = tree.search(query, showGenerated, SEARCH_LIMIT);
+      rows = result.nodes.map((node) => ({ node, depth: 0 }));
+      count.textContent =
+        result.total > rows.length
+          ? `first ${rows.length} of ${result.total} matches`
+          : `${result.total} matches`;
+    } else {
+      rows = tree.rows(expanded, showGenerated);
+      count.textContent = `${rows.length} rows`;
+    }
+    spacer.style.height = `${rows.length * ROW_HEIGHT}px`;
+    renderWindow(true);
+  };
+
+  const scrollToIndex = (index: number) => {
+    const top = index * ROW_HEIGHT;
+    if (top < list.scrollTop) list.scrollTop = top;
+    else if (top + ROW_HEIGHT > list.scrollTop + list.clientHeight)
+      list.scrollTop = top + ROW_HEIGHT - list.clientHeight;
+  };
+
+  const reveal = (path: string) => {
+    for (const ancestor of ancestorPaths(path)) expanded.add(ancestor);
+    recompute();
+    const index = rows.findIndex((row) => row.node.path === path);
+    if (index >= 0) list.scrollTop = Math.max(0, index * ROW_HEIGHT - list.clientHeight / 2);
+  };
+
+  const renderDetail = () => {
+    detailValue = undefined;
+    if (!selected)
+      return detail.replaceChildren(
+        h("h2", {}, "Selection"),
+        empty("Select a row for its declaration and value."),
+      );
+    const node = tree.resolve(selected);
+    if (!node)
+      return detail.replaceChildren(
+        h("h2", {}, "Selection"),
+        empty(`${selected} is not in this build's manifest.`),
+      );
+    const leaf = !tree.expandable(node);
+    if (leaf) detailValue = new LiveValue(store, node);
+    const io = manifest.io.filter((entry) => entry.path === node.path);
+    const sites = manifest.events.filter((site) => site.path === node.path);
+    fill(
+      detail,
+      h("h2", {}, "Selection"),
+      h("div", { class: "detail-path mono" }, node.path),
+      detailValue && h("div", { class: "detail-value" }, detailValue.value, detailValue.meta),
+      h(
+        "dl",
+        {},
+        h("dt", {}, "Type"),
+        h("dd", { class: "mono" }, typeLabel(manifest, node.type)),
+        h("dt", {}, "Declared"),
+        h("dd", {}, node.declaration ? sourceLink(store, node.declaration) : "not known"),
+        h("dt", {}, "Runtime"),
+        h(
+          "dd",
+          {},
+          node.constant
+            ? "folded by the compiler: no storage"
+            : node.readable
+              ? "read live"
+              : "not readable in this build",
+        ),
+        ...io.flatMap((entry) => [
+          h("dt", {}, entry.direction === "input" ? "Input" : "Output"),
+          h(
+            "dd",
+            {},
+            entry.device
+              ? h("a", { href: `#/hardware/${encodeURIComponent(entry.device)}` }, entry.device)
+              : "no device",
+            entry.channel ? ` · ${entry.channel}` : "",
+            entry.address ? ` · ${entry.address}` : "",
+            entry.inverted ? " · inverted" : "",
+          ),
+        ]),
+      ),
+      sites.length > 0 &&
+        h(
+          "div",
+          { class: "sites" },
+          h("h3", {}, "Traced writes"),
+          ...sites.map((site) =>
+            h(
+              "div",
+              { class: "site" },
+              h("code", {}, site.text),
+              " ",
+              sourceLink(store, site.range),
+            ),
+          ),
+        ),
+      query &&
+        h(
+          "button",
+          {
+            onclick: () => {
+              query = "";
+              search.value = "";
+              reveal(node.path);
+            },
+          },
+          "Show in tree",
+        ),
+    );
+  };
+
+  const renderGroups = () => {
+    groupValues = [];
+    const names = Object.keys(store.watch.groups);
+    if (activeGroup === undefined || !names.includes(activeGroup)) activeGroup = names[0];
+    const nameInput = h("input", { placeholder: "New group", size: 12 });
+    const members = activeGroup === undefined ? [] : (store.watch.groups[activeGroup] ?? []);
+    groups.replaceChildren(
+      h("h2", {}, "Watch groups"),
+      h(
+        "p",
+        { class: "hint" },
+        "Paths in a group are read live while this page shows them; nothing is recorded.",
+      ),
+      h(
+        "div",
+        { class: "tabs" },
+        ...Object.entries(store.watch.groups).map(([name, paths]) =>
+          h(
+            "button",
+            {
+              class: `tab${name === activeGroup ? " on" : ""}`,
+              onclick: () => {
+                activeGroup = name;
+                renderGroups();
+                renderWindow(true);
+              },
+            },
+            name,
+            h("span", { class: "n" }, String(paths.length)),
+          ),
+        ),
+        h(
+          "form",
+          {
+            onsubmit: (event: Event) => {
+              event.preventDefault();
+              const name = nameInput.value.trim();
+              if (!name || name in store.watch.groups) return;
+              activeGroup = name;
+              void store.saveWatch({ ...store.watch.groups, [name]: [] });
+            },
+          },
+          nameInput,
+        ),
+      ),
+      ...(members.length
+        ? members.flatMap((member) => {
+            const remove = h(
+              "button",
+              { class: "remove", title: "Remove from group", onclick: () => toggleWatch(member) },
+              "×",
+            );
+            const row = (path: string, removable: boolean) => {
+              const node = tree.resolve(path);
+              const value = node && new LiveValue(store, node);
+              if (value) groupValues.push(value);
+              return h(
+                "div",
+                { class: "member" },
+                pathLink(path, wrappingPath(path)),
+                value
+                  ? value.value
+                  : h("span", { class: "value s-unavailable" }, "not in this build"),
+                value?.meta,
+                removable ? remove : "",
+              );
+            };
+            if (!member.includes("*")) return [row(member, true)];
+            // A pattern from the config or a saved group: one row per path it matches.
+            const matched = paths.expand([member]);
+            return [
+              h(
+                "div",
+                { class: "member" },
+                h("span", { class: "mono" }, wrappingPath(member)),
+                h("span", { class: "dim" }, `${matched.length} paths`),
+                remove,
+              ),
+              ...matched.map((path) => row(path, false)),
+            ];
+          })
+        : [empty(activeGroup ? "Empty: use ● on a row to add it." : "No groups yet.")]),
+    );
+    subscribe();
+  };
+
+  const select = (path: string) => {
+    selected = path;
+    history.replaceState(null, "", `#/variables?path=${encodeURIComponent(path)}`);
+    renderWindow(true);
+    renderDetail();
+    subscribe();
+  };
+
+  const move = (index: number) => {
+    const row = rows[index];
+    if (!row) return;
+    select(row.node.path);
+    scrollToIndex(index);
+  };
+
+  const toggle = (node: TreeNode) => {
+    if (expanded.has(node.path)) expanded.delete(node.path);
+    else expanded.add(node.path);
+    recompute();
+  };
+
+  list.addEventListener("click", (event) => {
+    if (!(event.target instanceof Element) || event.target.closest("a")) return;
+    const rowElement = event.target.closest<HTMLElement>(".row");
+    const row = rows[Number(rowElement?.dataset.index)];
+    if (!row) return;
+    const action = event.target.closest<HTMLElement>("[data-action]")?.dataset.action;
+    if (action === "toggle") toggle(row.node);
+    else if (action === "watch") toggleWatch(row.node.path);
+    else select(row.node.path);
+  });
+  list.addEventListener("keydown", (event) => {
+    const index = rows.findIndex((row) => row.node.path === selected);
+    const node = rows[index]?.node;
+    switch (event.key) {
+      case "ArrowDown":
+        move(index + 1);
+        break;
+      case "ArrowUp":
+        move(Math.max(0, index - 1));
+        break;
+      case "ArrowRight":
+        if (node && !query && tree.expandable(node) && !expanded.has(node.path)) toggle(node);
+        break;
+      case "ArrowLeft":
+        if (node && !query && expanded.has(node.path)) toggle(node);
+        else if (node) move(rows.findIndex((row) => row.node.path === parentPath(node.path)));
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+  });
+  list.addEventListener("scroll", () => renderWindow(false), { passive: true });
+  const resize = new ResizeObserver(() => renderWindow(false));
+  resize.observe(list);
+
+  search.addEventListener("input", () => {
+    clearTimeout(searchTimer);
+    searchTimer = setTimeout(() => {
+      query = search.value.trim();
+      list.scrollTop = 0;
+      recompute();
+      renderDetail();
+    }, 150);
+  });
+  generatedToggle.addEventListener("change", () => {
+    showGenerated = generatedToggle.checked;
+    recompute();
+  });
+
+  renderGroups();
+  renderDetail();
+  requestAnimationFrame(() => (selected && !query ? reveal(selected) : recompute()));
+
+  return {
+    element,
+    update(topics) {
+      if (topics.has("watch")) {
+        renderGroups();
+        renderWindow(true);
+        renderDetail();
+      }
+      if (LIVE_TOPICS.some((topic) => topics.has(topic)))
+        for (const value of [...rowValues, ...groupValues, ...(detailValue ? [detailValue] : [])])
+          value.update();
+    },
+    dispose() {
+      resize.disconnect();
+      clearTimeout(searchTimer);
+    },
+  };
+};

package/src/watch.ts

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import type { WatchGroups } from "./api.ts";
+
+export const watchGroupsSchema = z.strictObject({
+  groups: z.record(z.string().min(1), z.array(z.string().min(1))),
+});
+
+/**
+ * Watch groups: the config's `debug.watch`, then groups saved in `file`. Saving keeps only the
+ * groups that differ from the config, so the config stays their source.
+ */
+export const loadWatchGroups = async (file: string, configured: Record<string, string[]>) => {
+  let saved = existsSync(file)
+    ? watchGroupsSchema.parse(JSON.parse(await readFile(file, "utf8"))).groups
+    : {};
+  const groups = (): WatchGroups => ({ groups: { ...configured, ...saved } });
+  return {
+    groups,
+    save: async ({ groups: next }: WatchGroups) => {
+      saved = Object.fromEntries(
+        Object.entries(next).filter(([name, paths]) => !isDeepStrictEqual(configured[name], paths)),
+      );
+      await mkdir(dirname(file), { recursive: true });
+      await writeFile(file, JSON.stringify({ groups: saved }, null, 2));
+      return groups();
+    },
+  };
+};

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.