@tsplc/debug 0.0.0-stage → 0.2.17

package/src/ui/fixture.ts

@@ -0,0 +1,548 @@
+import type { Quality } from "../api.ts";
+import type { DebugEventSite, DebugManifest, DebugType, SourceRange } from "../manifest.ts";
+
+/** A conveyor line's debug manifest for `dev.ts`: diverters, scanners, an inbound conveyor and ~5000 paths. */
+
+const at = (file: number, line: number, column = 5, length = 24): SourceRange => ({
+  file,
+  line,
+  column,
+  endLine: line,
+  endColumn: column + length,
+});
+
+const record = (
+  name: string,
+  file: number,
+  fields: [string, string, number, true?][],
+): DebugType => ({
+  kind: "record",
+  name,
+  declaration: at(file, Math.min(...fields.map(([, , line]) => line)) - 1, 1),
+  fields: fields.map(([field, type, line, generated]) => ({
+    name: field,
+    target: field,
+    type,
+    declaration: at(file, line),
+    ...(generated ? { generated } : {}),
+  })),
+});
+
+const array = (element: string, length: number): DebugType => ({
+  kind: "array",
+  element,
+  length,
+  lower: 0,
+});
+
+const binSites: DebugEventSite[] = Array.from({ length: 16 }, (_, index) => [
+  {
+    id: 100 + index,
+    kind: "state" as const,
+    path: `program.diverters.binTrackers[${index}].bin`,
+    function: 1,
+    type: "Bin",
+    range: at(1, 41, 7, 24),
+    text: "this.bin = Bin.Present;",
+    task: "MainTask",
+    operands: [
+      {
+        text: "exit",
+        range: at(1, 39, 11, 4),
+        type: "BOOL",
+        path: `line.conveyors.inbound.cards[${index % 10}].input.sensor`,
+        stable: true,
+      },
+      {
+        text: "this.count",
+        range: at(1, 39, 19, 10),
+        type: "DINT",
+        path: `program.diverters.binTrackers[${index}].count`,
+        stable: false,
+      },
+    ],
+  },
+  {
+    id: 200 + index,
+    kind: "state" as const,
+    path: `program.diverters.binTrackers[${index}].bin`,
+    function: 1,
+    type: "Bin",
+    range: at(1, 33, 7, 25),
+    text: "this.bin = Bin.Arriving;",
+    task: "MainTask",
+    operands: [
+      { text: "entry", range: at(1, 31, 11, 5), type: "BOOL", stable: true },
+      { text: "this.bin === Bin.None", range: at(1, 31, 20, 21), type: "BOOL", stable: true },
+    ],
+  },
+]).flat();
+
+const routeSites: DebugEventSite[] = Array.from({ length: 4 }, (_, index) => ({
+  id: 300 + index,
+  kind: "decision",
+  path: `program.scanners.routeLookups[${index}].lane`,
+  function: 2,
+  type: "INT",
+  range: at(2, 31, 7, 18),
+  text: "return route.lane;",
+  task: "ServiceTask",
+  operands: [{ text: "route.ok", range: at(2, 29, 9, 8), type: "BOOL", stable: true }],
+}));
+
+const resolveSteps = [
+  { step: 0, kind: "statement" as const, range: at(2, 22), text: "this.pending = true;" },
+  {
+    step: 1,
+    kind: "await" as const,
+    range: at(2, 24, 18, 46),
+    text: "await services.routing.resolve({ code: this.code })",
+  },
+  { step: 2, kind: "statement" as const, range: at(2, 27), text: "this.lane = route.lane;" },
+  { step: 3, kind: "return" as const, range: at(2, 31), text: "return route.lane;" },
+];
+
+export const fixtureManifest: DebugManifest = {
+  kind: "tsplc-debug",
+  version: 1,
+  build: { id: "c41f7e2a9b0d", target: "GVL_TsplcDebug.build", compiler: "0.2.13" },
+  sources: [
+    "src/program.ts",
+    "src/diverters/bin-tracker.ts",
+    "src/scanners/route-lookup.ts",
+    "src/line/inbound.ts",
+    "src/tracking.ts",
+    "src/settings.ts",
+  ],
+  types: {
+    BOOL: { kind: "scalar", iec: "BOOL" },
+    INT: { kind: "scalar", iec: "INT" },
+    DINT: { kind: "scalar", iec: "DINT" },
+    REAL: { kind: "scalar", iec: "REAL" },
+    STRING: { kind: "scalar", iec: "STRING" },
+    Bin: { kind: "enum", name: "Bin", members: { None: 0, Arriving: 1, Present: 2 } },
+    Mode: { kind: "enum", name: "Mode", members: { Stopped: 0, Running: 1, Faulted: 2 } },
+    ParcelState: {
+      kind: "enum",
+      name: "ParcelState",
+      members: { Inducted: 0, Scanned: 1, Routed: 2, Diverted: 3, Lost: 4 },
+    },
+    BinTracker: record("BinTracker", 1, [
+      ["bin", "Bin", 8],
+      ["count", "DINT", 9],
+      ["exitClear", "BOOL", 10],
+      ["lastCode", "STRING", 11],
+      ["releaseStep", "DINT", 12, true],
+    ]),
+    "BinTracker[16]": array("BinTracker", 16),
+    RouteLookup: record("RouteLookup", 2, [
+      ["code", "STRING", 8],
+      ["lane", "INT", 9],
+      ["pending", "BOOL", 10],
+      ["attempts", "INT", 11],
+      ["step", "DINT", 12, true],
+      ["busy", "BOOL", 13, true],
+    ]),
+    "RouteLookup[4]": array("RouteLookup", 4),
+    CardInput: record("CardInput", 3, [
+      ["sensor", "BOOL", 6],
+      ["jam", "BOOL", 7],
+    ]),
+    CardOutput: record("CardOutput", 3, [
+      ["motor", "BOOL", 11],
+      ["speed", "REAL", 12],
+    ]),
+    Card: record("Card", 3, [
+      ["input", "CardInput", 16],
+      ["output", "CardOutput", 17],
+    ]),
+    "Card[10]": array("Card", 10),
+    Parcel: record("Parcel", 4, [
+      ["code", "STRING", 5],
+      ["lane", "INT", 6],
+      ["zone", "INT", 7],
+      ["state", "ParcelState", 8],
+      ["weightKg", "REAL", 9],
+      ["diverted", "BOOL", 10],
+    ]),
+    "Parcel[768]": array("Parcel", 768),
+    Settings: record("Settings", 5, [
+      ["speed", "REAL", 4],
+      ["accumulation", "BOOL", 5],
+    ]),
+    Scratch: record("Scratch", 0, [["buffer", "DINT", 40]]),
+  },
+  roots: [
+    {
+      path: "program.mode",
+      target: "plc_Program.mode",
+      type: "Mode",
+      declaration: at(0, 12),
+      readable: true,
+    },
+    {
+      path: "program.diverters.binTrackers",
+      target: "plc_Program.diverters.binTrackers",
+      type: "BinTracker[16]",
+      declaration: at(0, 14),
+      readable: true,
+    },
+    {
+      path: "program.scanners.routeLookups",
+      target: "plc_Program.scanners.routeLookups",
+      type: "RouteLookup[4]",
+      declaration: at(0, 17),
+      readable: true,
+    },
+    {
+      path: "line.conveyors.inbound.cards",
+      target: "GVL_Line.inbound_cards",
+      type: "Card[10]",
+      declaration: at(3, 22),
+      readable: true,
+    },
+    {
+      path: "program.tracking.parcels",
+      target: "plc_Program.tracking.parcels",
+      type: "Parcel[768]",
+      declaration: at(4, 14),
+      readable: true,
+    },
+    {
+      path: "program.settings",
+      target: "plc_Program.settings",
+      type: "Settings",
+      declaration: at(0, 20),
+      readable: true,
+    },
+    {
+      path: "program.diagnostics.scratch",
+      target: "plc_Program.diagnostics.scratch",
+      type: "Scratch",
+      declaration: at(0, 38),
+      readable: false,
+    },
+  ],
+  constants: [
+    { path: "program.settings.lanes", type: "INT", value: 4, declaration: at(5, 6) },
+    {
+      path: "program.settings.lineName",
+      type: "STRING",
+      value: "Inbound A",
+      declaration: at(5, 7),
+    },
+    { path: "program.diverters.maxBins", type: "DINT", value: 16, declaration: at(1, 3) },
+    { path: "program.scanners.timeoutMs", type: "DINT", value: 1500, declaration: at(2, 3) },
+  ],
+  io: [
+    ...Array.from({ length: 10 }, (_, index) => ({
+      path: `line.conveyors.inbound.cards[${index}].input.sensor`,
+      target: `GVL_Io.inbound_di${index}`,
+      direction: "input" as const,
+      type: "BOOL",
+      device: "io-inbound-1",
+      channel: `di${index}`,
+      address: `%IX${index >> 3}.${index & 7}`,
+    })),
+    ...Array.from({ length: 10 }, (_, index) => ({
+      path: `line.conveyors.inbound.cards[${index}].output.motor`,
+      target: `GVL_Io.inbound_do${index}`,
+      direction: "output" as const,
+      type: "BOOL",
+      device: "io-inbound-1",
+      channel: `do${index}`,
+      address: `%QX${index >> 3}.${index & 7}`,
+    })),
+    {
+      path: "line.conveyors.inbound.cards[0].input.jam",
+      target: "GVL_Io.inbound_jam",
+      direction: "input",
+      type: "BOOL",
+      device: "io-inbound-1",
+      channel: "di12",
+      address: "%IX1.4",
+      inverted: true,
+    },
+    {
+      path: "line.conveyors.inbound.cards[0].output.speed",
+      target: "GVL_Io.vfd_setpoint",
+      direction: "output",
+      type: "REAL",
+      device: "vfd-inbound",
+      channel: "setpoint",
+      address: "%QW12",
+    },
+  ],
+  devices: [
+    {
+      id: "io-inbound-1",
+      vendor: "Turck",
+      product: "FEN20-16DXP",
+      productCode: "6814023",
+      network: { address: "192.168.10.21", rpiMs: 10 },
+      connection: "Exclusive owner",
+      assemblies: [
+        { direction: "input", bytes: 4, address: "%IB0", raw: "GVL_TsplcDebug.io_inbound_1_in" },
+        { direction: "output", bytes: 2, address: "%QB0", raw: "GVL_TsplcDebug.io_inbound_1_out" },
+      ],
+      health: {
+        state: "GVL_TsplcDebug.io_inbound_1_state",
+        diagnostic: "GVL_TsplcDebug.io_inbound_1_diag",
+      },
+      status: {
+        "Module power": "GVL_Io.inbound_power_ok",
+        "Bus fault": "GVL_Io.inbound_bus_fault",
+      },
+      channels: [
+        ...Array.from({ length: 10 }, (_, index) => ({
+          id: `di${index}`,
+          name: `Zone ${index + 1} photo eye`,
+          direction: "input" as const,
+          type: "BOOL",
+          offsetBits: index,
+          bits: 1,
+          address: `%IX${index >> 3}.${index & 7}`,
+        })),
+        {
+          id: "di12",
+          name: "Jam switch",
+          direction: "input",
+          type: "BOOL",
+          offsetBits: 12,
+          bits: 1,
+          address: "%IX1.4",
+          description: "Normally closed",
+        },
+        {
+          id: "diag",
+          name: "Module diagnostics",
+          direction: "input",
+          type: "WORD",
+          offsetBits: 16,
+          bits: 16,
+          address: "%IW1",
+        },
+        ...Array.from({ length: 10 }, (_, index) => ({
+          id: `do${index}`,
+          name: `Zone ${index + 1} motor`,
+          direction: "output" as const,
+          type: "BOOL",
+          offsetBits: index,
+          bits: 1,
+          address: `%QX${index >> 3}.${index & 7}`,
+        })),
+      ],
+    },
+    {
+      id: "scanner-1",
+      vendor: "Cognex",
+      product: "DataMan 370",
+      productCode: "DMR-370S",
+      network: { address: "192.168.10.31", rpiMs: 20 },
+      connection: "Exclusive owner",
+      assemblies: [
+        { direction: "input", bytes: 8, address: "%IB20", raw: "GVL_TsplcDebug.scanner_1_in" },
+        { direction: "output", bytes: 2, address: "%QB20" },
+      ],
+      channels: [
+        {
+          id: "ready",
+          name: "Trigger ready",
+          direction: "input",
+          type: "BOOL",
+          offsetBits: 0,
+          bits: 1,
+        },
+        {
+          id: "ack",
+          name: "Trigger acknowledge",
+          direction: "input",
+          type: "BOOL",
+          offsetBits: 1,
+          bits: 1,
+        },
+        {
+          id: "complete",
+          name: "Read complete",
+          direction: "input",
+          type: "BOOL",
+          offsetBits: 2,
+          bits: 1,
+        },
+        {
+          id: "resultId",
+          name: "Result id",
+          direction: "input",
+          type: "UINT",
+          offsetBits: 16,
+          bits: 16,
+        },
+        {
+          id: "length",
+          name: "Result length",
+          direction: "input",
+          type: "UINT",
+          offsetBits: 32,
+          bits: 16,
+          unit: "bytes",
+        },
+        {
+          id: "trigger",
+          name: "Trigger",
+          direction: "output",
+          type: "BOOL",
+          offsetBits: 0,
+          bits: 1,
+        },
+      ],
+    },
+    {
+      id: "vfd-inbound",
+      vendor: "SEW-Eurodrive",
+      product: "MOVIDRIVE B",
+      network: { address: "192.168.10.41", rpiMs: 10 },
+      connection: "Exclusive owner",
+      assemblies: [
+        { direction: "input", bytes: 4, address: "%IB40", raw: "GVL_TsplcDebug.vfd_inbound_in" },
+        { direction: "output", bytes: 4, address: "%QB40", raw: "GVL_TsplcDebug.vfd_inbound_out" },
+      ],
+      health: {
+        state: "GVL_TsplcDebug.vfd_inbound_state",
+        message: "GVL_TsplcDebug.vfd_inbound_message",
+      },
+      channels: [
+        {
+          id: "status",
+          name: "Status word",
+          direction: "input",
+          type: "WORD",
+          offsetBits: 0,
+          bits: 16,
+        },
+        {
+          id: "actual",
+          name: "Actual speed",
+          direction: "input",
+          type: "INT",
+          offsetBits: 16,
+          bits: 16,
+          unit: "rpm",
+        },
+        {
+          id: "control",
+          name: "Control word",
+          direction: "output",
+          type: "WORD",
+          offsetBits: 0,
+          bits: 16,
+        },
+        {
+          id: "setpoint",
+          name: "Speed setpoint",
+          direction: "output",
+          type: "INT",
+          offsetBits: 16,
+          bits: 16,
+          unit: "rpm",
+        },
+      ],
+    },
+  ],
+  functions: [
+    {
+      id: 1,
+      name: "BinTracker.update",
+      declaration: at(1, 28),
+      task: "MainTask",
+      target: "BinTracker.update",
+      reads: [],
+    },
+    {
+      id: 2,
+      name: "RouteLookup.resolve",
+      declaration: at(2, 20),
+      task: "ServiceTask",
+      target: "RouteLookup.resolve",
+      reads: [],
+    },
+  ],
+  jobs: [
+    ...Array.from({ length: 4 }, (_, index) => ({
+      id: index + 1,
+      name: "RouteLookup.resolve",
+      declaration: at(2, 20),
+      instance: `program.scanners.routeLookups[${index}]`,
+      target: `plc_Program.scanners.routeLookups[${index}].job`,
+      steps: resolveSteps,
+      requests: [{ service: "routing.resolve", target: "x", sequence: "y" }],
+    })),
+    {
+      id: 5,
+      name: "BinTracker.release",
+      declaration: at(1, 52),
+      instance: "program.diverters.binTrackers[3]",
+      target: "plc_Program.diverters.binTrackers[3].release",
+      steps: [
+        {
+          step: 1,
+          kind: "await",
+          range: at(1, 55, 7, 40),
+          text: "await services.bins.release({ bin: 3 })",
+        },
+      ],
+      requests: [{ service: "bins.release", target: "x", sequence: "y" }],
+    },
+  ],
+  events: [
+    ...binSites,
+    ...routeSites,
+    {
+      id: 400,
+      kind: "state",
+      path: "program.mode",
+      type: "Mode",
+      range: at(0, 61, 7, 26),
+      text: "this.mode = Mode.Faulted;",
+      task: "MainTask",
+      operands: [{ text: "drive.fault", range: at(0, 60, 9, 11), type: "BOOL", stable: true }],
+    },
+  ],
+  writers: [],
+  tasks: [
+    {
+      name: "MainTask",
+      intervalMs: 10,
+      priority: 1,
+    },
+    {
+      name: "ServiceTask",
+      intervalMs: 50,
+      priority: 5,
+    },
+  ],
+  errors: { "1": "Cancelled", "2": "Timeout", "3": "ServiceError" },
+};
+
+const hash = (text: string) =>
+  [...text].reduce((sum, char) => (sum * 31 + char.charCodeAt(0)) >>> 0, 7) % 997;
+
+/** A deterministic value for `path` at time `ms`, so samples and raw bytes agree. */
+export const fixtureValue = (path: string, type: string, ms: number): unknown => {
+  const seed = hash(path);
+  const tick = (period: number) => Math.floor(ms / period + seed);
+  if (path === "program.mode") return 1;
+  if (type === "Bin") return tick(3100) % 3;
+  if (type === "ParcelState") return tick(4300) % 5;
+  if (type === "BOOL") return tick(700 + (seed % 900)) % 2 === 0;
+  if (type === "REAL") return Math.round((40 + 10 * Math.sin(ms / 3000 + seed)) * 100) / 100;
+  if (type === "STRING") return `P${String(tick(5000) % 100000).padStart(5, "0")}`;
+  if (path.endsWith(".lane")) return tick(4000) % 4;
+  return tick(2000) % 32767;
+};
+
+export const fixtureQuality = (path: string): { quality: Quality; status: string } => {
+  if (path.includes("routeLookups[3]")) return { quality: "bad", status: "BadCommunicationError" };
+  if (path.includes("binTrackers[7]"))
+    return { quality: "uncertain", status: "UncertainLastUsableValue" };
+  return { quality: "good", status: "Good" };
+};

package/src/ui/format.ts

@@ -0,0 +1,125 @@
+import type { Quality } from "../api.ts";
+import type { DebugManifest, SourceRange } from "../manifest.ts";
+import { typeOf } from "../paths.ts";
+
+/** How a value is shown: each state has its own styling and label, so none passes for live. */
+export type ValueState = "live" | "uncertain" | "bad" | "stale" | "unavailable" | "constant";
+
+export const valueStateLabels: Record<ValueState, string> = {
+  live: "good",
+  uncertain: "uncertain",
+  bad: "bad",
+  stale: "stale",
+  unavailable: "unavailable",
+  constant: "constant",
+};
+
+/** A sample is stale when the controller connection is down or the sample is older than three sample intervals. */
+export const valueState = (
+  quality: Quality,
+  ageMs: number,
+  context: { connected: boolean; intervalMs: number },
+): ValueState => {
+  if (quality === "unavailable") return "unavailable";
+  if (!context.connected || ageMs > 3 * context.intervalMs) return "stale";
+  if (quality === "bad") return "bad";
+  if (quality === "uncertain") return "uncertain";
+  return "live";
+};
+
+export const formatAge = (ms: number) => {
+  if (ms < 1000) return "now";
+  if (ms < 60_000) return `${Math.floor(ms / 1000)} s ago`;
+  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)} min ago`;
+  return `${Math.floor(ms / 3_600_000)} h ago`;
+};
+
+export const formatDuration = (ms: number) => {
+  if (ms < 1000) return `${Math.round(ms)} ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)} s`;
+  return `${Math.floor(ms / 60_000)} min ${Math.floor((ms % 60_000) / 1000)} s`;
+};
+
+/** How often values are read: `250 ms`, `1 s`, `1.5 s`. */
+export const formatInterval = (ms: number) => (ms < 1000 ? `${ms} ms` : `${ms / 1000} s`);
+
+/** Local time of day with milliseconds, for ordering events by eye. */
+export const formatClock = (iso: string) => {
+  const date = new Date(iso);
+  const pad = (value: number, width = 2) => String(value).padStart(width, "0");
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
+};
+
+/** When a value was read, to the second: `read 14:03:27`. */
+export const formatReadAt = (iso: string) => `read ${formatClock(iso).slice(0, 8)}`;
+
+/** A value of unknown type: booleans as IEC literals, strings quoted. */
+export const formatScalar = (value: unknown): string => {
+  if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+  if (typeof value === "number")
+    return Number.isInteger(value) ? String(value) : String(Number(value.toPrecision(6)));
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === null || value === undefined) return "—";
+  return JSON.stringify(value);
+};
+
+/** A value in the program's terms: enum members by name, whether the host decoded them already or not. */
+export const formatValue = (manifest: DebugManifest, typeId: string, value: unknown): string => {
+  const type = typeOf(manifest, typeId);
+  if (type.kind !== "enum") return formatScalar(value);
+  if (typeof value === "string" && Object.hasOwn(type.members, value)) return value;
+  if (typeof value !== "number") return formatScalar(value);
+  const member = Object.entries(type.members).find(([, number]) => number === value)?.[0];
+  return member ?? `${value} (not a ${type.name})`;
+};
+
+export const typeLabel = (manifest: DebugManifest, typeId: string): string => {
+  const type = typeOf(manifest, typeId);
+  switch (type.kind) {
+    case "scalar":
+      return type.iec;
+    case "enum":
+    case "record":
+      return type.name;
+    case "array":
+      return `${typeLabel(manifest, type.element)}[${type.length}]`;
+  }
+};
+
+const PROPERTY_TEXT = 16;
+
+/** A record's properties as `barcode=CON-MD3-884… scanner=3`, long strings cut short. */
+export const formatProperties = (properties: Record<string, unknown>) =>
+  Object.entries(properties)
+    .map(([key, value]) => {
+      const text = typeof value === "string" ? value : formatScalar(value);
+      return `${key}=${text.length > PROPERTY_TEXT ? `${text.slice(0, PROPERTY_TEXT)}…` : text}`;
+    })
+    .join(" ");
+
+/** A VS Code link to a project file, when the project root on the debugger host is known. */
+const fileHref = (projectRoot: string | undefined, file: string, line: number, column: number) => {
+  if (projectRoot === undefined) return undefined;
+  const root = projectRoot.replaceAll("\\", "/").replace(/\/$/, "");
+  const absolute = `${root}/${file}`.replace(/^\/?/, "/");
+  return `vscode://file${absolute}:${line}:${column}`;
+};
+
+/** `file:line`, and a VS Code link when the project root on the debugger host is known. */
+export const sourceLocation = (
+  manifest: DebugManifest,
+  projectRoot: string | undefined,
+  range: SourceRange,
+) => {
+  const file = manifest.sources[range.file] ?? `source ${range.file}`;
+  const href = fileHref(projectRoot, file, range.line, range.column);
+  return { label: `${file}:${range.line}`, ...(href && { href }) };
+};
+
+/** A record's project-relative `file:line` as `basename:line`, with the same VS Code link. */
+export const recordLocation = (projectRoot: string | undefined, source: string) => {
+  const [, file = source, line] = /^(.*):(\d+)$/.exec(source) ?? [];
+  const label = `${file.slice(file.lastIndexOf("/") + 1)}${line ? `:${line}` : ""}`;
+  const href = line === undefined ? undefined : fileHref(projectRoot, file, Number(line), 1);
+  return { label, ...(href && { href }) };
+};