@tsplc/debug 0.0.0-stage → 0.2.17

package/src/manifest.ts

@@ -0,0 +1,271 @@
+import { z } from "zod";
+
+/**
+ * What a build tells the debugger: every TypeScript identity it can show, and the target symbol each one reads.
+ * TypeScript paths (`program.diverters.binTrackers[10].bin`) are the identity; `target` strings are opaque to
+ * everything except the target's adapter (for CODESYS, IEC symbol paths such as `plc_Program.diverters…`).
+ * Written by the compiler to `.tsplc/artifacts/st/debug.json` and shipped with each release.
+ */
+
+/** A location in the project's own sources: `file` indexes `sources`; lines and columns are 1-based. */
+export const sourceRange = z.object({
+  file: z.number().int(),
+  line: z.number().int(),
+  column: z.number().int(),
+  endLine: z.number().int(),
+  endColumn: z.number().int(),
+});
+
+const json: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(json),
+    z.record(z.string(), json),
+  ]),
+);
+
+export const debugField = z.object({
+  name: z.string(),
+  target: z.string(),
+  type: z.string(),
+  declaration: sourceRange.optional(),
+  /** Compiler-made storage, such as an async job's `step`; hidden unless asked for. */
+  generated: z.literal(true).optional(),
+});
+
+/** Keys of `types` are opaque ids; scalars use their IEC name, such as `BOOL`. */
+export const debugType = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("scalar"), iec: z.string() }),
+  z.object({
+    kind: z.literal("enum"),
+    name: z.string(),
+    members: z.record(z.string(), z.number().int()),
+  }),
+  z.object({
+    kind: z.literal("record"),
+    name: z.string(),
+    declaration: sourceRange.optional(),
+    fields: z.array(debugField),
+  }),
+  z.object({
+    kind: z.literal("array"),
+    element: z.string(),
+    length: z.number().int(),
+    /** The first index; TypeScript paths use the target's own indexes, `lower` to `lower + length - 1`. */
+    lower: z.number().int(),
+  }),
+]);
+
+export const debugRoot = z.object({
+  path: z.string(),
+  target: z.string(),
+  type: z.string(),
+  declaration: sourceRange.optional(),
+  /** Readable at runtime through the target's adapter; for CODESYS, all stored state is. */
+  readable: z.boolean(),
+  generated: z.literal(true).optional(),
+});
+
+/** A field the compiler folded away: it has no runtime storage, but its value is known. */
+export const debugConstant = z.object({
+  path: z.string(),
+  type: z.string(),
+  value: json,
+  declaration: sourceRange.optional(),
+});
+
+export const debugIo = z.object({
+  path: z.string(),
+  target: z.string(),
+  direction: z.enum(["input", "output"]),
+  type: z.string(),
+  device: z.string().optional(),
+  channel: z.string().optional(),
+  address: z.string().optional(),
+  inverted: z.literal(true).optional(),
+  shared: z.literal(true).optional(),
+});
+
+export const debugChannel = z.object({
+  id: z.string(),
+  name: z.string(),
+  direction: z.enum(["input", "output"]),
+  type: z.string(),
+  offsetBits: z.number().int(),
+  bits: z.number().int(),
+  address: z.string().optional(),
+  unit: z.string().optional(),
+  description: z.string().optional(),
+});
+
+export const debugDevice = z.object({
+  id: z.string(),
+  product: z.string().optional(),
+  vendor: z.string().optional(),
+  productCode: z.string().optional(),
+  network: z.object({ address: z.string(), rpiMs: z.number().optional() }).optional(),
+  connection: z.string().optional(),
+  assemblies: z.array(
+    z.object({
+      direction: z.enum(["input", "output"]),
+      bytes: z.number().int(),
+      address: z.string().optional(),
+      /** A byte array over the whole assembly, mapped or not. */
+      raw: z.string().optional(),
+    }),
+  ),
+  /**
+   * Target paths of the driver's own state, such as a generated adapter's `eState`; absent means
+   * the device's health is unknown.
+   */
+  health: z
+    .object({
+      state: z.string().optional(),
+      states: z.record(z.string(), z.number().int()).optional(),
+      diagnostic: z.string().optional(),
+      message: z.string().optional(),
+    })
+    .optional(),
+  /** Status symbols by label: hand-configured ones, and a generated Modbus server's error. */
+  status: z.record(z.string(), z.string()).optional(),
+  channels: z.array(debugChannel),
+});
+
+/** A specialized function: one per method per instance, so `reads` resolve to concrete paths. */
+export const debugFunction = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  declaration: sourceRange,
+  /** The TypeScript path of `this`, for a method specialized to one instance. */
+  instance: z.string().optional(),
+  task: z.string().optional(),
+  target: z.string(),
+  /** Member reads in the body whose runtime path is static in this specialization. */
+  reads: z.array(z.object({ range: sourceRange, path: z.string() })),
+});
+
+export const debugJob = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  declaration: sourceRange,
+  instance: z.string().optional(),
+  /** The job's state, with fields `step`, `busy`, `done`, `error` and `cancelling`. */
+  target: z.string(),
+  steps: z.array(
+    z.object({
+      step: z.number().int(),
+      kind: z.enum(["await", "return", "throw", "statement"]),
+      range: sourceRange,
+      text: z.string(),
+    }),
+  ),
+  /**
+   * The PLC clock in milliseconds when the job last started: the clock of telemetry records'
+   * `time` and a batch's `now`.
+   */
+  startedAt: z.string().optional(),
+  /**
+   * Service calls the job awaits, its nested jobs' included; `sequence` is the request counter sent
+   * as `x-tsplc-request`, with `job`'s id when a nested job makes the call.
+   */
+  requests: z.array(
+    z.object({
+      service: z.string(),
+      target: z.string(),
+      sequence: z.string(),
+      job: z.number().int().optional(),
+    }),
+  ),
+  /** Made by the compiler, such as a service call's own job; hidden unless asked for. */
+  generated: z.literal(true).optional(),
+});
+
+/**
+ * Where `debug.trace` records: an enum state field changing, a decision function returning a
+ * different value, or a job starting or finishing. Trace records name their site by `id`.
+ */
+export const debugEventSite = z.object({
+  id: z.number().int(),
+  kind: z.enum(["state", "decision", "job"]),
+  /** For `kind: "job"`: the job, and whether it starts or finishes at this site. */
+  job: z.number().int().optional(),
+  phase: z.enum(["started", "finished"]).optional(),
+  /** The TypeScript path written, or of the job. */
+  path: z.string(),
+  function: z.number().int().optional(),
+  type: z.string(),
+  range: sourceRange,
+  text: z.string(),
+  task: z.string(),
+  /**
+   * Guard values captured in the same scan, at the write: each `if` condition leaf enclosing it.
+   * `stable` is false when the body between the guard and the write can change the leaf.
+   */
+  operands: z.array(
+    z.object({
+      text: z.string(),
+      range: sourceRange,
+      type: z.string(),
+      path: z.string().optional(),
+      stable: z.boolean(),
+    }),
+  ),
+});
+
+/** The statement that last wrote each output, per scan. */
+export const debugWriter = z.object({
+  output: z.string(),
+  target: z.string(),
+  sites: z.array(
+    z.object({ id: z.number().int(), range: sourceRange, function: z.number().int() }),
+  ),
+});
+
+export const debugTask = z.object({
+  name: z.string(),
+  intervalMs: z.number(),
+  priority: z.number().int(),
+});
+
+export const debugManifest = z.object({
+  kind: z.literal("tsplc-debug"),
+  version: z.literal(1),
+  build: z.object({
+    id: z.string(),
+    /** A variable holding `id`, to tell which build the controller runs. */
+    target: z.string(),
+    compiler: z.string(),
+  }),
+  /** Project-relative paths. */
+  sources: z.array(z.string()),
+  types: z.record(z.string(), debugType),
+  roots: z.array(debugRoot),
+  constants: z.array(debugConstant),
+  io: z.array(debugIo),
+  devices: z.array(debugDevice),
+  functions: z.array(debugFunction),
+  jobs: z.array(debugJob),
+  events: z.array(debugEventSite),
+  writers: z.array(debugWriter),
+  tasks: z.array(debugTask),
+  /** Job error codes by number: 1 cancelled, 2 timeout… */
+  errors: z.record(z.string(), z.string()),
+});
+
+export type SourceRange = z.infer<typeof sourceRange>;
+export type DebugType = z.infer<typeof debugType>;
+export type DebugField = z.infer<typeof debugField>;
+export type DebugRoot = z.infer<typeof debugRoot>;
+export type DebugConstant = z.infer<typeof debugConstant>;
+export type DebugIo = z.infer<typeof debugIo>;
+export type DebugDevice = z.infer<typeof debugDevice>;
+export type DebugChannel = z.infer<typeof debugChannel>;
+export type DebugFunction = z.infer<typeof debugFunction>;
+export type DebugJob = z.infer<typeof debugJob>;
+export type DebugEventSite = z.infer<typeof debugEventSite>;
+export type DebugWriter = z.infer<typeof debugWriter>;
+export type DebugTask = z.infer<typeof debugTask>;
+export type DebugManifest = z.infer<typeof debugManifest>;

package/src/opcua.ts

@@ -0,0 +1,69 @@
+import { resolve } from "node:path";
+import { createMonitor, type MonitorOptions, type Reading } from "@tsplc/opcua";
+import type { ResolvedTsplcConfig } from "@tsplc/config";
+import type { TargetAdapter, TargetRead, TargetSample } from "./adapter.ts";
+
+type MonitorConfig = NonNullable<ResolvedTsplcConfig["monitor"]>;
+
+/**
+ * The connection the config's `monitor` section describes. Its certificate directory is relative
+ * to `root`, and the password comes from `passwordEnv` in `env`.
+ */
+export const opcUaConnection = (
+  monitor: MonitorConfig,
+  options: { root: string; env: Record<string, string | undefined> },
+): MonitorOptions => {
+  const password = monitor.passwordEnv && options.env[monitor.passwordEnv];
+  if (monitor.username && !password)
+    throw new Error(
+      monitor.passwordEnv
+        ? `Set ${monitor.passwordEnv} to the OPC UA password of ${monitor.username}.`
+        : "Configure monitor.passwordEnv for the OPC UA user.",
+    );
+  return {
+    endpoint: monitor.endpoint,
+    namespaceUri: monitor.namespaceUri,
+    certificateDirectory: resolve(options.root, monitor.certificateDirectory),
+    security: monitor.securityPolicy,
+    securityMode: monitor.securityMode === "Sign" ? "Sign" : "SignAndEncrypt",
+    ...(monitor.username && password && { credentials: { username: monitor.username, password } }),
+  };
+};
+
+/**
+ * Reads a CODESYS controller over OPC UA, where targets are IEC symbol paths. It reads only
+ * what the build publishes, so it suits a local virtual PLC; samples arrive on change.
+ */
+export const createOpcUaAdapter = (options: MonitorOptions): TargetAdapter => {
+  const monitor = createMonitor(options);
+  const controller = new AbortController();
+  const running = monitor.run(controller.signal);
+  const sample = ({ value, quality, status }: Reading): TargetSample => ({
+    value,
+    quality,
+    status,
+    receivedAt: new Date().toISOString(),
+  });
+  const names = (targets: readonly TargetRead[]) => targets.map(({ target }) => target);
+
+  return {
+    method: "OPC UA",
+    endpoint: options.endpoint,
+    samplingMs: monitor.samplingMs,
+    connection: monitor.status,
+    onConnection: monitor.onStatus,
+    read: async (targets) =>
+      new Map(
+        Object.entries(await monitor.read(names(targets))).map(([target, reading]) => [
+          target,
+          sample(reading),
+        ]),
+      ),
+    subscribe: (targets, listener) =>
+      monitor.watch(names(targets), (target, reading) => listener(target, sample(reading))),
+    close: async () => {
+      controller.abort();
+      await running;
+    },
+  };
+};

package/src/paths.ts

@@ -0,0 +1,185 @@
+import type { DebugManifest, DebugType, SourceRange } from "./manifest.ts";
+
+/**
+ * TypeScript paths over a manifest: `program.diverters.binTrackers[10].bin` names a root
+ * (`program.diverters`), then record fields and array indexes. Pure, so the browser UI can use it.
+ */
+
+/** A path that reads a target, or a constant the compiler folded. */
+export type ResolvedPath =
+  | {
+      kind: "target";
+      path: string;
+      target: string;
+      type: string;
+      readable: boolean;
+      generated?: true;
+      declaration?: SourceRange;
+    }
+  | { kind: "constant"; path: string; type: string; value: unknown; declaration?: SourceRange };
+
+/** Roots or constants that share a prefix, such as `program` above `program.diverters`. */
+interface GroupPath {
+  kind: "group";
+  path: string;
+}
+
+/** A child in the instance tree. */
+export type PathNode = { name: string } & (ResolvedPath | GroupPath);
+
+const segmentPattern = /[^.[\]]+|\[(?:-?\d+|\*)\]/g;
+
+export const pathSegments = (path: string) => path.match(segmentPattern) ?? [];
+
+export const joinPath = (prefix: string, segment: string) =>
+  segment.startsWith("[") || !prefix ? `${prefix}${segment}` : `${prefix}.${segment}`;
+
+/** Scalar type ids are their IEC names, and may have no entry in `types`. */
+export const typeOf = (manifest: DebugManifest, id: string): DebugType =>
+  manifest.types[id] ?? { kind: "scalar", iec: id };
+
+export const createPaths = (manifest: DebugManifest) => {
+  const typeOfId = (id: string) => typeOf(manifest, id);
+  // I/O bindings are readable symbols with TypeScript paths of their own.
+  const bases = new Map<string, Extract<ResolvedPath, { kind: "target" }>>([
+    ...manifest.roots.map(
+      ({ path, ...root }) => [path, { kind: "target" as const, path, ...root }] as const,
+    ),
+    ...manifest.io.map(
+      ({ path, target, type }) =>
+        [path, { kind: "target" as const, path, target, type, readable: true }] as const,
+    ),
+  ]);
+  const constants = new Map(
+    manifest.constants.map(({ path, ...constant }) => [
+      path,
+      { kind: "constant" as const, path, ...constant },
+    ]),
+  );
+  /** Children of the prefixes of every root and constant path, which are groups unless they resolve. */
+  const groups = new Map<string, Set<string>>();
+  for (const path of [...bases.keys(), ...constants.keys()]) {
+    let prefix = "";
+    for (const segment of pathSegments(path)) {
+      let children = groups.get(prefix);
+      if (!children) groups.set(prefix, (children = new Set()));
+      children.add(segment);
+      prefix = joinPath(prefix, segment);
+    }
+  }
+
+  const resolve = (path: string): ResolvedPath | undefined => {
+    const constant = constants.get(path);
+    if (constant) return constant;
+    const segments = pathSegments(path);
+    for (let length = segments.length; length > 0; length--) {
+      const base = bases.get(segments.slice(0, length).reduce(joinPath, ""));
+      if (!base) continue;
+      let resolved: ResolvedPath = base;
+      for (const segment of segments.slice(length)) {
+        const type = typeOfId(resolved.type);
+        if (type.kind === "record") {
+          const field = type.fields.find(({ name }) => name === segment);
+          if (!field) return;
+          resolved = {
+            kind: "target",
+            path: joinPath(resolved.path, segment),
+            target: `${resolved.target}.${field.target}`,
+            type: field.type,
+            readable: resolved.readable,
+            ...(field.generated && { generated: true }),
+            ...(field.declaration && { declaration: field.declaration }),
+          };
+        } else if (type.kind === "array") {
+          const index = /^\[(-?\d+)\]$/.exec(segment)?.[1];
+          if (
+            index === undefined ||
+            Number(index) < type.lower ||
+            Number(index) >= type.lower + type.length
+          )
+            return;
+          resolved = {
+            kind: "target",
+            path: joinPath(resolved.path, segment),
+            target: `${resolved.target}[${index}]`,
+            type: type.element,
+            readable: resolved.readable,
+          };
+        } else return;
+      }
+      return resolved;
+    }
+  };
+
+  const typedChildren = (resolved: ResolvedPath | undefined) => {
+    const type = resolved?.kind === "target" ? typeOfId(resolved.type) : undefined;
+    if (type?.kind === "record") return type.fields.map(({ name }) => name);
+    if (type?.kind === "array")
+      return Array.from({ length: type.length }, (_, index) => `[${type.lower + index}]`);
+    return [];
+  };
+
+  /** A path's fields or indexes, and the roots and constants below it. */
+  const children = (path: string): PathNode[] => {
+    const names = [...typedChildren(resolve(path)), ...(groups.get(path) ?? [])];
+    return [...new Set(names)].map((name) => {
+      const child = joinPath(path, name);
+      return { name, ...(resolve(child) ?? { kind: "group", path: child }) };
+    });
+  };
+
+  const isLeaf = (node: ResolvedPath | GroupPath) =>
+    node.kind === "constant" ||
+    (node.kind === "target" && ["scalar", "enum"].includes(typeOfId(node.type).kind));
+
+  /**
+   * Leaf paths matching `patterns`, where `*` stands for one segment. A pattern naming a record,
+   * array or group stands for all its leaves; wildcards and expansion skip compiler-made fields.
+   * Paths that don't resolve are kept, so callers can report them.
+   */
+  const expand = (patterns: readonly string[], limit = 2000) => {
+    const leaves = new Set<string>();
+    const add = (path: string) => {
+      leaves.add(path);
+      if (leaves.size > limit) throw new RangeError(`More than ${limit} values match`);
+    };
+    const below = (node: ResolvedPath | GroupPath) => {
+      if (isLeaf(node)) return add(node.path);
+      for (const child of children(node.path))
+        if (!(child.kind === "target" && child.generated)) below(child);
+    };
+    const match = (prefix: string, rest: readonly string[], wildcard: boolean) => {
+      const [head, ...tail] = rest;
+      if (head === undefined) {
+        const node: ResolvedPath | GroupPath | undefined =
+          resolve(prefix) ?? (groups.has(prefix) ? { kind: "group", path: prefix } : undefined);
+        if (node) below(node);
+        else if (!wildcard) add(prefix);
+        return;
+      }
+      if (head === "*" || head === "[*]") {
+        for (const child of children(prefix))
+          if (
+            !(child.kind === "target" && child.generated) &&
+            (head === "*" || child.name.startsWith("["))
+          )
+            match(child.path, tail, true);
+      } else match(joinPath(prefix, head), tail, wildcard);
+    };
+    for (const pattern of patterns) match("", pathSegments(pattern), false);
+    return [...leaves];
+  };
+
+  /** A value as TypeScript shows it: enum members by name, BOOL as a boolean. */
+  const decode = (typeId: string, raw: unknown) => {
+    const type = typeOfId(typeId);
+    if (type.kind === "enum")
+      return Object.entries(type.members).find(([, value]) => value === raw)?.[0] ?? raw;
+    if (type.kind === "scalar" && type.iec === "BOOL" && typeof raw === "number") return raw !== 0;
+    return raw;
+  };
+
+  return { typeOf: typeOfId, resolve, children, isLeaf, expand, decode };
+};
+
+export type Paths = ReturnType<typeof createPaths>;

package/src/telemetry.ts

@@ -0,0 +1,110 @@
+import type { TelemetryBatch, TelemetryRecord, TelemetryReply } from "@tsplc/server/telemetry";
+import { recordedAt } from "@tsplc/server/telemetry-log";
+import type { Session } from "./api.ts";
+import type { DebugManifest } from "./manifest.ts";
+
+/** Clock estimates are kept this long, on the server's clock. */
+const clockWindowMs = 60_000;
+
+/** A record with the batch it came in, numbered in its task's sequence, at its time on the server's clock. */
+export interface ReceivedRecord {
+  build: string;
+  task: string;
+  sequence: number;
+  at: string;
+  record: TelemetryRecord;
+}
+
+/**
+ * Follows the app server's telemetry ring (`GET /tsplc/telemetry`): it hands out each new record
+ * once, keeps the tasks' scan rates, and estimates the PLC's clock against the server's.
+ */
+export const createTelemetryFollower = (manifest: DebugManifest) => {
+  const intervals = new Map(manifest.tasks.map(({ name, intervalMs }) => [name, intervalMs]));
+  const tasks = new Map<string, Session["tasks"][number]>(
+    manifest.tasks.map(({ name }) => [
+      name,
+      { name, scan: null, scansPerSecond: null, dropped: 0 },
+    ]),
+  );
+  const rates = new Map<string, { scan: number; now: number }>();
+  let estimates: { offsetMs: number; intervalMs: number; at: number }[] = [];
+  let newest = 0;
+  let build: string | null = null;
+
+  /**
+   * A batch's `now` was read before it was sent, so `now − receivedAt` falls short of the true
+   * offset by its transit time: the largest recent estimate is the closest, and their spread,
+   * plus a scan, bounds how far off it may be.
+   */
+  const clock = (): Session["clock"] => {
+    if (!estimates.length) return null;
+    const offsets = estimates.map(({ offsetMs }) => offsetMs);
+    const best = estimates.reduce((best, estimate) =>
+      estimate.offsetMs > best.offsetMs ? estimate : best,
+    );
+    return {
+      offsetMs: best.offsetMs,
+      uncertaintyMs: best.offsetMs - Math.min(...offsets) + best.intervalMs,
+    };
+  };
+
+  const observe = (batch: TelemetryBatch, receivedAt: number) => {
+    const rate = rates.get(batch.task);
+    // A restarted PLC counts scans and time from zero again.
+    const restarted = rate !== undefined && batch.now < rate.now;
+    if (restarted) estimates = [];
+    estimates = estimates.filter(({ at }) => receivedAt - at < clockWindowMs);
+    estimates.push({
+      offsetMs: batch.now - receivedAt,
+      intervalMs: intervals.get(batch.task) ?? 0,
+      at: receivedAt,
+    });
+    const stats = {
+      name: batch.task,
+      scansPerSecond: tasks.get(batch.task)?.scansPerSecond ?? null,
+      scan: batch.scan,
+      dropped: batch.dropped,
+    };
+    if (!rate || restarted) rates.set(batch.task, { scan: batch.scan, now: batch.now });
+    else if (batch.now - rate.now >= 1000) {
+      stats.scansPerSecond = ((batch.scan - rate.scan) * 1000) / (batch.now - rate.now);
+      rates.set(batch.task, { scan: batch.scan, now: batch.now });
+    }
+    tasks.set(batch.task, stats);
+  };
+
+  return {
+    /** Where the next pull starts. */
+    since: () => newest,
+    /** Takes a reply to `GET /tsplc/telemetry?since=<since()>`; a restarted server starts over. */
+    accept: (reply: TelemetryReply): ReceivedRecord[] => {
+      if (reply.latest < newest) {
+        newest = 0;
+        return [];
+      }
+      const received: ReceivedRecord[] = [];
+      for (const batch of reply.batches) {
+        if (batch.seq <= newest) continue;
+        newest = batch.seq;
+        build = batch.build;
+        const receivedAt = new Date(batch.receivedAt);
+        observe(batch, receivedAt.getTime());
+        batch.records.forEach((record, index) =>
+          received.push({
+            build: batch.build,
+            task: batch.task,
+            sequence: batch.first + index,
+            at: recordedAt(batch, record, receivedAt).toISOString(),
+            record,
+          }),
+        );
+      }
+      return received;
+    },
+    /** The build the newest batch came from. */
+    build: () => build,
+    clock,
+    tasks: () => [...tasks.values()].map((task) => ({ ...task })),
+  };
+};