@tsplc/compiler 0.0.0-stage → 0.1.0

package/src/frontend/services.ts

@@ -0,0 +1,435 @@
+import { runtimeSources } from "./module-graph.ts";
+import ts from "typescript";
+import { dirname, join, relative } from "node:path";
+import { error, type Diagnostic } from "@tsplc/compiler/ir";
+import {
+  isIntegerType,
+  serviceContract,
+  servicePath,
+  wireLayout,
+  wireRecord,
+  type ServiceContract,
+  type WireField,
+  type WireScalar,
+} from "@tsplc/server";
+
+/** The server section's transport; each client's type argument names its router. */
+export interface ServiceOptions {
+  transport: "http" | "opcua";
+  baseUrlEnv?: string;
+}
+
+/** A procedure record read from its type, with the PLC enum each enum field names. */
+interface RecordLayout {
+  fields: Record<string, WireField>;
+  enums: Record<string, ts.EnumDeclaration>;
+}
+
+const property = (checker: ts.TypeChecker, type: ts.Type, name: string) => {
+  const symbol = type.getProperty(name);
+  return symbol && checker.getTypeOfSymbol(symbol);
+};
+
+/** An `iec.*` schema's layout, which its type carries as an optional phantom property. */
+const layoutNumber = (checker: ts.TypeChecker, type: ts.Type, name: string, label: string) => {
+  const brand = property(checker, type, wireLayout);
+  const value = brand && property(checker, checker.getNonNullableType(brand), name);
+  if (!value) return undefined;
+  if (!value.isNumberLiteral()) throw new Error(`${label}: ${name} must be a literal number.`);
+  return value.value;
+};
+
+const scalarLayout = (
+  checker: ts.TypeChecker,
+  type: ts.Type,
+  label: string,
+): { field: WireScalar; enumeration?: ts.EnumDeclaration } => {
+  if (type.flags & ts.TypeFlags.Boolean) return { field: { kind: "boolean" } };
+  // An enum type is the union of its member literals.
+  const first = type.isUnion() ? type.types[0] : type;
+  const member = first?.symbol?.valueDeclaration;
+  if (first && first.flags & ts.TypeFlags.EnumLiteral && member && ts.isEnumMember(member)) {
+    const members: Record<string, number> = {};
+    for (const item of member.parent.members) {
+      const value = checker.getConstantValue(item);
+      if (typeof value !== "number")
+        throw new Error(`${label}: PLC enums require numeric members.`);
+      members[item.name.getText()] = value;
+    }
+    return { field: { kind: "enum", members }, enumeration: member.parent };
+  }
+  const capacity = layoutNumber(checker, type, "capacity", label);
+  if (capacity !== undefined) return { field: { kind: "string", capacity } };
+  const brand = property(checker, type, wireLayout);
+  const iec = brand && property(checker, checker.getNonNullableType(brand), "iec");
+  if (iec?.isStringLiteral() && isIntegerType(iec.value)) {
+    const minimum = layoutNumber(checker, type, "minimum", label);
+    const maximum = layoutNumber(checker, type, "maximum", label);
+    if (minimum !== undefined && maximum !== undefined)
+      return { field: { kind: "integer", iec: iec.value, minimum, maximum } };
+  }
+  throw new Error(
+    `${label}: use z.boolean(), z.enum() of a numeric enum, iec.STRING(), or an integer such as iec.INT().`,
+  );
+};
+
+const recordLayout = (
+  checker: ts.TypeChecker,
+  type: ts.Type,
+  label: string,
+  output: boolean,
+): RecordLayout => {
+  const fields: Record<string, WireField> = {};
+  const enums: Record<string, ts.EnumDeclaration> = {};
+  // A procedure without `.input()` takes `void`.
+  if (!(type.flags & ts.TypeFlags.Void)) {
+    if (
+      !(type.flags & ts.TypeFlags.Object) ||
+      type.getStringIndexType() ||
+      type.getNumberIndexType() ||
+      type.getCallSignatures().length
+    )
+      throw new Error(`${label}: PLC procedures exchange one closed z.strictObject() record.`);
+    for (const field of type.getProperties()) {
+      const key = `${label}.${field.name}`;
+      if (field.flags & ts.SymbolFlags.Optional)
+        throw new Error(`${key}: optional wire fields are unsupported.`);
+      const value = checker.getTypeOfSymbol(field);
+      const length = layoutNumber(checker, value, "length", key);
+      const element = length === undefined ? undefined : value.getNumberIndexType();
+      const scalar = scalarLayout(checker, element ?? value, key);
+      fields[field.name] =
+        length === undefined ? scalar.field : { kind: "array", length, element: scalar.field };
+      if (scalar.enumeration) enums[field.name] = scalar.enumeration;
+    }
+  }
+  return { fields: wireRecord(fields, label, output).fields, enums };
+};
+
+/** Identifies a record by layout, so every name for it lowers to one PLC struct. */
+const recordKey = (layout: RecordLayout) =>
+  JSON.stringify([
+    layout.fields,
+    Object.entries(layout.enums)
+      .map(([field, value]) => [field, value.getSourceFile().fileName, value.name.text])
+      .sort(),
+  ]);
+
+const procedureAt = (checker: ts.TypeChecker, router: ts.Type, path: readonly string[]) => {
+  let type = property(checker, router, "_def");
+  type = type && property(checker, type, "record");
+  for (const part of path) type = type && property(checker, type, part);
+  const definition = type && property(checker, type, "_def");
+  if (!definition || !property(checker, definition, "procedure")) return undefined;
+  const kind = property(checker, definition, "type");
+  const types = property(checker, definition, "$types");
+  const input = types && property(checker, types, "input");
+  const output = types && property(checker, types, "output");
+  if (!kind?.isStringLiteral() || !input || !output) return undefined;
+  return { kind: kind.value, input, output };
+};
+
+const pascal = (path: string) =>
+  path
+    .split(".")
+    .map((part) => part[0]!.toUpperCase() + part.slice(1))
+    .join("");
+
+/**
+ * Replaces each `createServiceClient<Router>()` call with an in-memory module of the called
+ * procedures, read from the router's type: the server never runs and no file is written.
+ */
+export const lowerServices = (
+  program: ts.Program,
+  sdk: string,
+  options: ServiceOptions | undefined,
+) => {
+  const sources = new Map<string, string>();
+  const diagnostics: Diagnostic[] = [];
+  const records = new Map<string, { name: string; layout: RecordLayout }>();
+  const calls = new Map<string, { contract: ServiceContract; input: string; output: string }>();
+  const checker = program.getTypeChecker();
+  const symbol = (node: ts.Node) => {
+    let value = checker.getSymbolAtLocation(node);
+    while (value && value.flags & ts.SymbolFlags.Alias) value = checker.getAliasedSymbol(value);
+    return value;
+  };
+  const fail = (node: ts.Node, code: string, message: string) => {
+    const source = node.getSourceFile(),
+      start = node.getStart(source),
+      position = source.getLineAndCharacterOfPosition(start);
+    diagnostics.push(
+      error(code, message, {
+        file: source.fileName,
+        start,
+        end: node.end,
+        line: position.line + 1,
+        column: position.character + 1,
+      }),
+    );
+  };
+  const record = (layout: RecordLayout, name: string) => {
+    const key = recordKey(layout);
+    const existing = records.get(key);
+    if (existing) return existing.name;
+    records.set(key, { name, layout });
+    return name;
+  };
+
+  const clients = new Map<ts.Symbol, ts.Type>();
+  let file: string | undefined;
+  const sourceFiles = runtimeSources(program).filter((source) => !source.isDeclarationFile);
+  for (const source of sourceFiles)
+    for (const statement of source.statements) {
+      if (!ts.isVariableStatement(statement)) continue;
+      for (const declaration of statement.declarationList.declarations) {
+        const call = declaration.initializer;
+        if (
+          !call ||
+          !ts.isCallExpression(call) ||
+          symbol(call.expression)?.name !== "createServiceClient" ||
+          !symbol(call.expression)?.declarations?.some((value) =>
+            value.getSourceFile().fileName.startsWith(dirname(sdk) + "/"),
+          )
+        )
+          continue;
+        const router = call.typeArguments?.[0];
+        const client = symbol(declaration.name);
+        if (!router || !client || !(statement.declarationList.flags & ts.NodeFlags.Const))
+          fail(
+            declaration,
+            "PLC1013",
+            "Create a service client as a module constant: const services = createServiceClient<AppRouter>().",
+          );
+        else if (!options)
+          fail(call, "PLC1013", "Configure server in tsplc.config.ts to call the server.");
+        else if (options.transport === "http" && !options.baseUrlEnv)
+          fail(call, "PLC1013", "HTTP service transport requires server.baseUrlEnv.");
+        else {
+          clients.set(client, checker.getTypeFromTypeNode(router));
+          file ??= join(dirname(source.fileName), ".tsplc-services.ts");
+        }
+      }
+    }
+
+  for (const source of sourceFiles) {
+    const edits: { start: number; end: number; text: string }[] = [];
+    const imports = new Map<string, string>();
+    const visit = (node: ts.Node): void => {
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+        const clause = node.importClause;
+        const bindings = clause?.namedBindings;
+        const typeOnly =
+          clause?.isTypeOnly ||
+          (!clause?.name &&
+            bindings &&
+            ts.isNamedImports(bindings) &&
+            bindings.elements.every((element) => element.isTypeOnly));
+        if (!typeOnly && clause && bindings && ts.isNamedImports(bindings)) {
+          const elements = bindings.elements.filter((element) => {
+            const imported = symbol(element.name);
+            return !imported || !clients.has(imported);
+          });
+          if (elements.length !== bindings.elements.length)
+            edits.push({
+              start: node.getStart(source),
+              end: node.end,
+              text:
+                elements.length || clause.name
+                  ? ts
+                      .createPrinter()
+                      .printNode(
+                        ts.EmitHint.Unspecified,
+                        ts.factory.updateImportDeclaration(
+                          node,
+                          node.modifiers,
+                          ts.factory.updateImportClause(
+                            clause,
+                            clause.isTypeOnly,
+                            clause.name,
+                            ts.factory.updateNamedImports(bindings, elements),
+                          ),
+                          node.moduleSpecifier,
+                          node.attributes,
+                        ),
+                        source,
+                      )
+                  : "",
+            });
+        }
+        if (
+          !typeOnly &&
+          (node.moduleSpecifier.text.startsWith("node:") ||
+            ["@tsplc/server", "@trpc/server", "zod", "fs", "http", "https", "net", "tls"].includes(
+              node.moduleSpecifier.text,
+            ))
+        )
+          fail(
+            node,
+            "PLC1013",
+            `Server runtime import ${node.moduleSpecifier.text} cannot execute in PLC code. Expose a PLC procedure on the server router and call it through createServiceClient instead.`,
+          );
+      }
+      if (ts.isVariableStatement(node)) {
+        const clientStatement = node.declarationList.declarations.some((declaration) => {
+          const declared = symbol(declaration.name);
+          return declared && clients.has(declared);
+        });
+        if (clientStatement) {
+          edits.push({ start: node.getStart(source), end: node.end, text: "" });
+          return;
+        }
+      }
+      if (clients.size && ts.isPropertyAccessExpression(node)) {
+        const parts: string[] = [];
+        let root: ts.Expression = node;
+        while (ts.isPropertyAccessExpression(root)) {
+          parts.unshift(root.name.text);
+          root = root.expression;
+        }
+        const client = symbol(root);
+        const router = client && clients.get(client);
+        const procedure = router && procedureAt(checker, router, parts);
+        if (router) {
+          const path = parts.join(".");
+          if (!procedure) {
+            fail(node, "PLC1013", `${path} is not a procedure of the client's router.`);
+            return;
+          }
+          let call = calls.get(path);
+          if (!call) {
+            try {
+              if (procedure.kind !== "query" && procedure.kind !== "mutation")
+                throw new Error(
+                  `${path}: subscriptions use a different transport; expose a query or mutation to the PLC.`,
+                );
+              const input = recordLayout(checker, procedure.input, `${path}.input`, false);
+              const output = recordLayout(checker, procedure.output, `${path}.output`, true);
+              call = {
+                contract: serviceContract(
+                  path,
+                  procedure.kind,
+                  { fields: input.fields },
+                  { fields: output.fields },
+                ),
+                input: record(input, `${pascal(path)}Input`),
+                output: record(output, `${pascal(path)}Output`),
+              };
+              calls.set(path, call);
+            } catch (cause) {
+              fail(node, "PLC2001", cause instanceof Error ? cause.message : String(cause));
+              return;
+            }
+          }
+          const name = `tsplcService_${path.replaceAll(".", "_")}`;
+          const local = imports.get(name) ?? `tsplcRemote${imports.size}`;
+          imports.set(name, local);
+          edits.push({ start: node.getStart(source), end: node.end, text: local });
+          return;
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(source);
+    if (!edits.length) continue;
+    let text = source.text;
+    for (const edit of edits.sort((a, b) => b.start - a.start))
+      text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+    if (imports.size && file) {
+      const path = relative(dirname(source.fileName), file).replaceAll("\\", "/");
+      text += `\nimport {${[...imports].map(([name, local]) => `${name} as ${local}`).join(",")}} from ${JSON.stringify(path.startsWith("../") ? path : `./${path}`)};\n`;
+    }
+    sources.set(source.fileName, text);
+  }
+  if (file && options) sources.set(file, serviceModule(records, calls, options));
+  return {
+    sources,
+    diagnostics,
+    file,
+    records: new Map([...records].map(([key, { name }]) => [key, name])),
+  };
+};
+
+const serviceModule = (
+  records: ReadonlyMap<string, { name: string; layout: RecordLayout }>,
+  calls: ReadonlyMap<string, { contract: ServiceContract; input: string; output: string }>,
+  options: ServiceOptions,
+) => {
+  const enums = new Map<ts.EnumDeclaration, string>();
+  const enumName = (declaration: ts.EnumDeclaration) => {
+    const name = enums.get(declaration) ?? `tsplcEnum${enums.size}`;
+    enums.set(declaration, name);
+    return name;
+  };
+  const scalar = (field: WireScalar, enumeration: ts.EnumDeclaration | undefined) => {
+    switch (field.kind) {
+      case "boolean":
+        return "BOOL";
+      case "integer":
+        return field.iec;
+      case "string":
+        return `STRING<${field.capacity}>`;
+      case "enum":
+        return enumName(enumeration!);
+    }
+  };
+  const interfaces = [...records.values()].map(({ name, layout }) => {
+    const fields = Object.entries(layout.fields).map(([key, field]) => {
+      const enumeration = layout.enums[key];
+      const type =
+        field.kind === "array"
+          ? `FixedArray<${scalar(field.element, enumeration)},${field.length}>`
+          : scalar(field, enumeration);
+      return `${key}:${type}`;
+    });
+    return `export interface ${name}{${fields.join(";")}}`;
+  });
+  const functions = [...calls.values()]
+    .sort((left, right) => left.contract.path.localeCompare(right.contract.path))
+    .map(({ contract, input, output }) => {
+      const hasInput = Object.keys(contract.input.fields).length > 0;
+      const request = hasInput ? "input" : `defaultValue<${input}>()`;
+      const operation =
+        options.transport === "http"
+          ? `tsplcServiceFetch<${output}>(\`\${tsplcServiceBaseUrl}${servicePath(contract)}\`,{method:"POST",json:${request}})`
+          : `tsplcServiceCall<${output},${input}>(${JSON.stringify(servicePath(contract))},${request})`;
+      return `export const tsplcService_${contract.path.replaceAll(".", "_")}=async(${hasInput ? `input:${input}` : ""}):Promise<${output}>=>{return await ${operation};};`;
+    });
+  const transport =
+    options.transport === "http"
+      ? `import {fetch as tsplcServiceFetch} from "@tsplc/compiler/async";\nimport {env as tsplcServiceEnv} from "@tsplc/compiler/config";`
+      : `import {opcuaCall as tsplcServiceCall} from "@tsplc/compiler/async";`;
+  const enumImports = [...enums].map(
+    ([declaration, name]) =>
+      `import type {${declaration.name.text} as ${name}} from ${JSON.stringify(declaration.getSourceFile().fileName)};`,
+  );
+  const baseUrl =
+    options.transport === "http"
+      ? `const tsplcServiceBaseUrl:STRING<512>=tsplcServiceEnv<STRING<512>>(${JSON.stringify(options.baseUrlEnv)});`
+      : "";
+  return [transport, ...enumImports, baseUrl, ...interfaces, ...functions].join("\n") + "\n";
+};
+
+/** Lowers a type that names a called procedure's record, such as `inferRouterOutputs<AppRouter>["a"]["b"]`. */
+export const serviceRecords = (
+  program: ts.Program,
+  lowering: { file: string | undefined; records: ReadonlyMap<string, string> },
+) => {
+  const source = lowering.file && program.getSourceFile(lowering.file);
+  if (!source) return undefined;
+  const checker = program.getTypeChecker();
+  const declarations = new Map(
+    source.statements.filter(ts.isInterfaceDeclaration).map((value) => [value.name.text, value]),
+  );
+  return (type: ts.Type): ts.Symbol | undefined => {
+    let key: string;
+    try {
+      key = recordKey(recordLayout(checker, type, "record", false));
+    } catch {
+      return undefined;
+    }
+    const name = lowering.records.get(key);
+    const declaration = name === undefined ? undefined : declarations.get(name);
+    return declaration && checker.getSymbolAtLocation(declaration.name);
+  };
+};