@tsplc/debug 0.2.16 → 0.2.18

package/src/manifest.ts

@@ -9,178 +9,180 @@ import { z } from "zod";
 
 /** 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(),
+	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),
-  ]),
+	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(),
+	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(),
-  }),
+	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(),
+	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(),
+	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(),
+	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(),
+	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),
+	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() })),
+	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(),
+	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(),
 });
 
 /**
@@ -188,71 +190,75 @@ export const debugJob = z.object({
  * 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(),
-    }),
-  ),
+	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() }),
-  ),
+	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(),
+	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()),
+	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>;

package/src/opcua.ts

@@ -1,33 +1,31 @@
-import { resolve } from "node:path";
-import { createMonitor, type MonitorOptions, type Reading } from "@tsplc/opcua";
+import {
+	createMonitor,
+	monitorConnection,
+	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`.
- */
+/** The config's `monitor` connection, with the user's password from `passwordEnv` in `env`. */
 export const opcUaConnection = (
-  monitor: MonitorConfig,
-  options: { root: string; env: Record<string, string | undefined> },
+	monitor: NonNullable<ResolvedTsplcConfig["monitor"]>,
+	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 } }),
-  };
+	const password = monitor.passwordEnv
+		? options.env[monitor.passwordEnv]
+		: undefined;
+	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 monitorConnection(monitor, {
+		root: options.root,
+		password: password ?? null,
+	});
 };
 
 /**
@@ -35,35 +33,37 @@ export const opcUaConnection = (
  * 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);
+	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;
-    },
-  };
+	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;
+		},
+	};
 };