@tsplc/compiler 0.0.0-stage → 0.1.0

package/project/cli.ts

@@ -0,0 +1,282 @@
+#!/usr/bin/env bun
+import { buildServer } from "./server.ts";
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+import {
+  buildTargetFor,
+  controllerFor,
+  loadTsplcConfig,
+  rawBuildConfig,
+  simulationConfig,
+} from "@tsplc/config";
+import {
+  buildProject as buildSt,
+  configureDocker,
+  configureRuntime,
+  inspectController,
+  installLibraries,
+  loadSources,
+  resolveConfig,
+  runProject,
+  updateController,
+} from "@tsplc/build";
+import { checkHostConfig } from "@tsplc/compiler";
+import { type Diagnostic, formatDiagnostic, hasErrors } from "@tsplc/compiler/ir";
+import { deviceTree } from "@tsplc/typegen";
+import { loadHardware, resolveIo } from "@tsplc/typegen/hardware";
+import { generateProject } from "@tsplc/typegen";
+import { buildProject, checkProject, cleanProject, projectTargets } from "./project.ts";
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      config: { type: "string" },
+      help: { type: "boolean", short: "h" },
+      "emit-only": { type: "boolean" },
+      format: { type: "string" },
+      read: { type: "string", multiple: true },
+      "initialize-user": { type: "boolean" },
+      "frozen-lockfile": { type: "boolean" },
+      check: { type: "boolean" },
+      plc: { type: "boolean" },
+      server: { type: "boolean" },
+      simulate: { type: "boolean" },
+      runtime: { type: "boolean" },
+    },
+  });
+  const command = positionals[0],
+    file = values.config ?? "tsplc.config.ts";
+  if (!command || values.help) {
+    console.log(
+      "tsplc install|typegen|check|build|run|download|online-change|inspect|clean|configure [--config tsplc.config.ts] [--plc|--server] [--simulate] [--runtime] [--emit-only] [--format json] [--read symbol]",
+    );
+    return 0;
+  }
+  if (positionals.length > 1) throw new Error("Specify one command.");
+  if (
+    ![
+      "install",
+      "typegen",
+      "check",
+      "build",
+      "run",
+      "download",
+      "online-change",
+      "inspect",
+      "clean",
+      "configure",
+    ].includes(command)
+  )
+    throw new Error(`Unknown command ${command}.`);
+  if (values.format && !["json", "text"].includes(values.format))
+    throw new Error("--format must be json or text.");
+  if (values["emit-only"] && command !== "build")
+    throw new Error("--emit-only is supported by build only.");
+  if (values.runtime && command !== "configure")
+    throw new Error("--runtime applies only to configure.");
+  if ((values.plc || values.server) && command !== "build")
+    throw new Error("--plc and --server apply only to build.");
+  if (values.simulate && !["run", "download", "online-change"].includes(command))
+    throw new Error("--simulate applies only to run, download and online-change.");
+  if (values.plc && values.server)
+    throw new Error("Choose --plc or --server, or omit both for a full build.");
+  if (values.server && values["emit-only"])
+    throw new Error("--emit-only applies to PLC emission only.");
+  const log = console.log,
+    previousLogTarget = process.env["TSPLC_LOG_STDERR"];
+  if (values.format === "json") {
+    console.log = console.error;
+    process.env["TSPLC_LOG_STDERR"] = "1";
+  }
+  let result: unknown;
+  try {
+    if (command === "configure") {
+      await (values.runtime ? configureRuntime() : configureDocker());
+      result = { ok: true };
+    } else if (command === "clean") {
+      result = await cleanProject(file);
+    } else {
+      if (["check", "build", "run", "download", "online-change"].includes(command)) {
+        const diagnostics = checkHostConfig(resolve(file));
+        if (hasErrors(diagnostics)) throw new DiagnosticFailure({ diagnostics });
+      }
+      const loaded = await loadTsplcConfig(file);
+      const { config, configFile, root } = loaded;
+      // Generated types keep describing the hardware project; only the download omits fieldbus I/O.
+      const target = values.simulate ? { ...loaded, config: simulationConfig(config) } : loaded;
+      if (command === "install")
+        result = {
+          libraries: await installLibraries(config.dependencies, root, {
+            frozen: values["frozen-lockfile"],
+          }),
+        };
+      else if (command === "typegen") {
+        const targets = await projectTargets(file, { loaded });
+        if (config.compiler && !values.check) {
+          await generateProject(file, { hardwareOnly: true, loaded, targets });
+          const emitted = await buildProject(file, { emitOnly: true, loaded });
+          if (hasErrors(emitted.diagnostics)) throw new DiagnosticFailure(emitted);
+        }
+        result = await generateProject(file, { check: values.check, loaded, targets });
+      } else if (command === "check") {
+        result = config.compiler
+          ? await checkProject(file, { loaded })
+          : {
+              objects: (
+                await loadSources(
+                  resolveConfig(
+                    {
+                      ...rawBuildConfig(config),
+                      io: resolveIo(config, await loadHardware(config, root)),
+                    },
+                    configFile,
+                  ),
+                )
+              ).objects.length,
+            };
+      } else if (command === "build" && values.server) {
+        result = await buildServer(config, root);
+      } else if (command === "build" || command === "run") {
+        if (config.compiler) {
+          const built = await buildProject(file, {
+            emitOnly: values["emit-only"],
+            frozenLockfile: values["frozen-lockfile"],
+            loaded: target,
+            controller: controllerFor(config, command),
+            buildTarget: buildTargetFor(command),
+          });
+          if (hasErrors(built.diagnostics)) throw new DiagnosticFailure(built);
+          await generateProject(file, {
+            loaded,
+            targets: await projectTargets(file, { loaded }),
+          });
+          result = built;
+        } else {
+          if (values["emit-only"]) throw new Error("Raw Structured Text is already emitted.");
+          if (!config.build) throw new Error("Configure build settings.");
+          const build = rawBuildConfig(config);
+          const libraries = await installLibraries(config.dependencies, root, {
+            frozen: values["frozen-lockfile"],
+          });
+          const hardware = await loadHardware(target.config, root);
+          result = await buildSt(
+            resolveConfig(
+              {
+                ...build,
+                libraries,
+                io: resolveIo(target.config, hardware),
+                deviceTree: await deviceTree(target.config, hardware),
+                controller: controllerFor(config, command),
+              },
+              configFile,
+            ),
+          );
+          await generateProject(file, { hardwareOnly: !config.typegen, loaded });
+        }
+        if (command === "build" && !values.plc && !values["emit-only"] && config.server?.runtime) {
+          const backend = await buildServer(config, root);
+          result = { ...(typeof result === "object" && result !== null ? result : {}), ...backend };
+        }
+        if (command === "run") {
+          if (!config.build) throw new Error("Configure build to run this project.");
+          await runProject(
+            resolveConfig(config.compiler ? config.build : rawBuildConfig(config), configFile),
+            config.name,
+          );
+        }
+      } else if (command === "inspect") {
+        if (!config.build) throw new Error("Configure build settings and controller connection.");
+        // Inspection needs only the connection/baseline. It must remain usable
+        // when local sources, descriptors or dependency caches are unavailable.
+        result = await inspectController(
+          resolveConfig(
+            { ...config.build, controller: controllerFor(config, command) },
+            configFile,
+          ),
+          values.read,
+        );
+      } else if (["download", "online-change"].includes(command)) {
+        if (!config.build) throw new Error("Configure build settings and controller connection.");
+        let settings: ReturnType<typeof resolveConfig>;
+        if (config.compiler) {
+          const emitted = await buildProject(file, {
+            emitOnly: true,
+            loaded: target,
+            buildTarget: buildTargetFor(command),
+          });
+          if (hasErrors(emitted.diagnostics)) throw new DiagnosticFailure(emitted);
+          if (!emitted.controllerConfig)
+            throw new Error("Configure build settings for deployment.");
+          // Emission already resolves the generated entry/task paths. Passing
+          // this through the input schema again would reject its configFile.
+          settings = { ...emitted.controllerConfig, io: {} };
+        } else
+          settings = resolveConfig(
+            {
+              ...rawBuildConfig(config),
+              io: resolveIo(target.config, await loadHardware(target.config, root)),
+            },
+            configFile,
+          );
+        const libraries = await installLibraries(config.dependencies, root, {
+          frozen: values["frozen-lockfile"],
+        });
+        result = await updateController(
+          { ...settings, libraries, controller: controllerFor(config, command) },
+          command as "download" | "online-change",
+          {
+            initializeUser: values["initialize-user"],
+            read: values.read,
+          },
+        );
+      } else throw new Error(`Unknown command ${command}.`);
+    }
+  } finally {
+    console.log = log;
+    if (previousLogTarget === undefined) delete process.env["TSPLC_LOG_STDERR"];
+    else process.env["TSPLC_LOG_STDERR"] = previousLogTarget;
+  }
+  return report(result, values.format);
+}
+class DiagnosticFailure extends Error {
+  constructor(readonly result: unknown) {
+    super("PLC validation failed.");
+  }
+}
+function report(result: unknown, format?: string) {
+  const diagnostics =
+    result && typeof result === "object" && "diagnostics" in result
+      ? (result.diagnostics as Diagnostic[])
+      : [];
+  const ok = !hasErrors(diagnostics);
+  if (format === "json")
+    console.log(
+      JSON.stringify({ ok, ...(result && typeof result === "object" ? result : { result }) }),
+    );
+  else {
+    for (const diagnostic of diagnostics) console.error(formatDiagnostic(diagnostic));
+    if (ok) console.log("tsPLC completed.");
+  }
+  return ok ? 0 : 1;
+}
+try {
+  process.exitCode = await main();
+} catch (cause) {
+  // main() may fail before its options parse, so detect JSON output from raw argv.
+  const json = process.argv.includes("json") || process.argv.includes("--format=json");
+  if (cause instanceof DiagnosticFailure) {
+    process.exitCode = report(cause.result, json ? "json" : undefined);
+  } else {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (json)
+      console.log(
+        JSON.stringify({
+          ok: false,
+          diagnostics: [{ origin: "config", code: "PLC5003", severity: "error", message }],
+        }),
+      );
+    else console.error(message);
+    process.exitCode = 1;
+  }
+}

package/project/index.ts

@@ -0,0 +1 @@
+export { checkProject, buildProject, cleanProject, projectTargets } from "./project.ts";

package/project/project.ts

@@ -0,0 +1,298 @@
+import { copyFile, mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import {
+  buildCodesys,
+  codesysBuildConfig,
+  type CodesysPlan,
+  diagnoseCodesys,
+  emitCodesys,
+  ioTargets,
+  publicationSelectors,
+  planCodesys,
+} from "@tsplc/compiler/codesys";
+import { analyze, checkHostConfig } from "@tsplc/compiler";
+import {
+  type Controller,
+  type BuildTarget,
+  type NormalizedConfig,
+  type ResolvedTsplcConfig,
+  compilerConfig,
+  loadTsplcConfig,
+} from "@tsplc/config";
+import { deviceTree, type ProjectTargets, loadHardware, resolveIo } from "@tsplc/typegen";
+import { installLibraries } from "@tsplc/build";
+import { type Diagnostic, hasErrors, normalizeModule } from "@tsplc/compiler/ir";
+import { cleanArtifacts, engineeringDirectory, owned, publishArtifacts } from "./artifacts.ts";
+
+const failure = (origin: Diagnostic["origin"], code: string, cause: unknown): Diagnostic => ({
+  origin,
+  code,
+  severity: "error",
+  message: cause instanceof Error ? cause.message : String(cause),
+});
+
+type LoadedConfig = Awaited<ReturnType<typeof loadTsplcConfig>>;
+
+async function loadProject(
+  file: string,
+  loaded?: LoadedConfig,
+  buildTarget?: BuildTarget,
+): Promise<{
+  config?: NormalizedConfig;
+  configFile: string;
+  shared?: ResolvedTsplcConfig;
+  diagnostics: readonly Diagnostic[];
+}> {
+  let configFile = resolve(file);
+  try {
+    configFile = await realpath(configFile);
+    const diagnostics = checkHostConfig(configFile);
+    if (hasErrors(diagnostics)) return { configFile, diagnostics };
+    const shared = (loaded ?? (await loadTsplcConfig(configFile))).config;
+    const root = dirname(configFile);
+
+    const config = compilerConfig(
+      shared,
+      resolveIo(shared, await loadHardware(shared, root)),
+      buildTarget,
+    );
+    return {
+      configFile,
+      shared,
+      config: { ...config, ...sourceInput(config, root) },
+      diagnostics,
+    };
+  } catch (cause) {
+    return { configFile, diagnostics: [failure("config", "PLC5003", cause)] };
+  }
+}
+
+/** The analyzer's entry points, resolved against the config file's directory. */
+function sourceInput(
+  compiler: { tsconfig: string; programs: Record<string, { module: string; export: string }> },
+  root: string,
+) {
+  return {
+    tsconfig: resolve(root, compiler.tsconfig),
+    programs: Object.fromEntries(
+      Object.entries(compiler.programs).map(([name, entry]) => [
+        name,
+        { ...entry, module: resolve(root, entry.module) },
+      ]),
+    ),
+  };
+}
+
+/**
+ * I/O keys and publication selectors from analyzed PLC source. It ignores the
+ * config's own type errors, so a typo cannot switch off the types that flag it;
+ * it is undefined only while the source itself fails analysis.
+ */
+export async function projectTargets(
+  file = "tsplc.config.ts",
+  options: { loaded?: LoadedConfig } = {},
+): Promise<ProjectTargets | undefined> {
+  const configFile = await realpath(resolve(file));
+  const { config } = options.loaded ?? (await loadTsplcConfig(configFile));
+  if (!config.compiler) return undefined;
+  const source = analyze({
+    ...sourceInput(config.compiler, dirname(configFile)),
+    services: config.server,
+  });
+  const core = source.module && normalizeModule(source.module).core;
+  return core ? { io: ioTargets(core), publication: publicationSelectors(core) } : undefined;
+}
+
+export async function checkProject(
+  file = "tsplc.config.ts",
+  options: { loaded?: LoadedConfig; buildTarget?: BuildTarget } = {},
+): Promise<{
+  configFile: string;
+  config?: NormalizedConfig;
+  shared?: ResolvedTsplcConfig;
+  plan?: CodesysPlan;
+  diagnostics: readonly Diagnostic[];
+}> {
+  const loaded = await loadProject(file, options.loaded, options.buildTarget);
+  if (!loaded.config) {
+    return loaded;
+  }
+
+  const config = loaded.config;
+  if (config.target.kind !== "codesys") {
+    return {
+      ...loaded,
+      diagnostics: [failure("backend", "PLC7001", `Unsupported target: ${config.target.kind}`)],
+    };
+  }
+
+  const source = analyze({
+    tsconfig: config.tsconfig,
+    programs: config.programs,
+    services: loaded.shared?.server,
+  });
+  if (!source.module) {
+    return { ...loaded, diagnostics: source.diagnostics };
+  }
+  const normalized = normalizeModule(source.module);
+  if (!normalized.core) {
+    return { ...loaded, diagnostics: normalized.diagnostics };
+  }
+
+  const tasks = config.tasks.map((task) => ({
+    name: task.name,
+    intervalNanoseconds: task.schedule.interval.nanoseconds,
+    priority: task.priority,
+    programs: task.programs,
+  }));
+  const planned = planCodesys(normalized.core, { tasks }, config.target.options);
+  return {
+    ...loaded,
+    ...planned,
+    diagnostics: [
+      ...loaded.diagnostics,
+      ...source.diagnostics,
+      ...normalized.diagnostics,
+      ...planned.diagnostics,
+    ],
+  };
+}
+
+export async function buildProject(
+  file = "tsplc.config.ts",
+  options: {
+    emitOnly?: boolean;
+    frozenLockfile?: boolean;
+    loaded?: LoadedConfig;
+    controller?: Controller;
+    buildTarget?: BuildTarget;
+  } = {},
+): Promise<{
+  directory?: string;
+  status?: "emitted" | "vendor-compiled";
+  controllerConfig?: ReturnType<typeof codesysBuildConfig>;
+  diagnostics: readonly Diagnostic[];
+}> {
+  let staging: string | undefined;
+  try {
+    const configFile = await realpath(resolve(file));
+    // Withdraw the previous success receipt before checking the new source.
+    // Old artifacts remain owned and intact until publication succeeds.
+    const previous = await owned(configFile, true);
+    if (previous.unknown.length) {
+      throw new Error(`Output contains unrelated files: ${previous.unknown.join(", ")}`);
+    }
+
+    const checked = await checkProject(configFile, {
+      loaded: options.loaded,
+      buildTarget: options.buildTarget,
+    });
+    if (!checked.plan || !checked.config) {
+      return { diagnostics: checked.diagnostics };
+    }
+    const bundle = emitCodesys(checked.plan);
+    if (hasErrors(bundle.diagnostics)) {
+      return { diagnostics: bundle.diagnostics };
+    }
+    const controllerConfig = checked.shared?.build
+      ? codesysBuildConfig(checked.plan, bundle, {
+          configFile,
+          sourceDir: join(previous.output, "st"),
+          outDir: resolve(dirname(configFile), checked.shared.build.outDir),
+          controller: options.controller,
+        })
+      : undefined;
+
+    await mkdir(previous.root, { recursive: true });
+    staging = await mkdtemp(join(previous.root, "stage-"));
+    const artifacts = [
+      ...bundle.artifacts,
+      { path: "mappings.json", content: `${JSON.stringify(bundle.mappings, null, 2)}\n` },
+      { path: "io-symbols.json", content: `${JSON.stringify(bundle.ioSymbols, null, 2)}\n` },
+      { path: "publication.json", content: `${JSON.stringify(bundle.publication, null, 2)}\n` },
+      { path: "config.json", content: `${JSON.stringify(checked.config, null, 2)}\n` },
+    ];
+    for (const artifact of artifacts) {
+      const path = join(staging, "st", artifact.path);
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, artifact.content);
+    }
+
+    let vendor: Awaited<ReturnType<typeof buildCodesys>> | undefined;
+    if (!options.emitOnly) {
+      // The engineering cache has its own ownership marker and survives clean.
+      const engineering = checked.shared?.build
+        ? resolve(dirname(configFile), checked.shared.build.outDir ?? "build")
+        : join(previous.root, "engineering");
+      const libraries = checked.shared
+        ? await installLibraries(checked.shared.dependencies, dirname(configFile), {
+            frozen: options.frozenLockfile,
+          })
+        : undefined;
+      await engineeringDirectory(engineering, configFile);
+      const tree =
+        checked.shared &&
+        (await deviceTree(checked.shared, await loadHardware(checked.shared, dirname(configFile))));
+      try {
+        vendor = await buildCodesys(checked.plan, bundle, {
+          configFile,
+          sourceDir: join(staging, "st"),
+          outDir: engineering,
+          libraries,
+          controller: options.controller,
+          // The emitted names locate mapped IO; the tree maps their channels.
+          deviceTree: tree && {
+            ...tree,
+            mappings: bundle.ioMappings.map(({ address, variable }) => ({ address, variable })),
+          },
+        });
+      } catch (cause) {
+        return { diagnostics: diagnoseCodesys(cause, bundle) };
+      }
+
+      const vendorArtifacts = [
+        ["Application.project", vendor.project],
+        ["Application.app", vendor.output],
+        ["Application.crc", vendor.checksum],
+      ] as const;
+      for (const [name, path] of vendorArtifacts) {
+        if (!path) continue;
+        const destination = join(staging, "vendor", name);
+        await mkdir(dirname(destination), { recursive: true });
+        await copyFile(path, destination);
+      }
+    }
+
+    const status = vendor ? "vendor-compiled" : "emitted";
+    await publishArtifacts(staging, previous, {
+      configFile,
+      status,
+      ...(vendor && { vendor: { application: vendor.application, tasks: vendor.tasks } }),
+    });
+    // Publication moved this directory into place; it is no longer staging.
+    staging = undefined;
+    return {
+      directory: previous.output,
+      status,
+      ...(controllerConfig && { controllerConfig }),
+      diagnostics: [...checked.diagnostics, ...bundle.diagnostics],
+    };
+  } catch (cause) {
+    return { diagnostics: [failure("config", "PLC5004", cause)] };
+  } finally {
+    if (staging) {
+      await rm(staging, { recursive: true, force: true });
+    }
+  }
+}
+
+export async function cleanProject(file = "tsplc.config.ts"): Promise<{
+  diagnostics: readonly Diagnostic[];
+}> {
+  try {
+    await cleanArtifacts(await realpath(resolve(file)));
+    return { diagnostics: [] };
+  } catch (cause) {
+    return { diagnostics: [failure("config", "PLC5004", cause)] };
+  }
+}

package/project/server.ts

@@ -0,0 +1,83 @@
+import { existsSync } from "node:fs";
+import { mkdtemp, mkdir, rm, rename } from "node:fs/promises";
+import { dirname, resolve, join } from "node:path";
+import { createRequire } from "node:module";
+import ts from "typescript";
+import type { ResolvedTsplcConfig } from "@tsplc/config";
+import { typeCheckOnly } from "@tsplc/compiler";
+
+export const resolveServerModule = (root: string, name: string) =>
+  name.startsWith(".") || name.startsWith("/") || existsSync(resolve(root, name))
+    ? resolve(root, name)
+    : createRequire(join(root, "package.json")).resolve(name);
+
+const kebabCase = (name: string) =>
+  name
+    .replace(/([a-z0-9])([A-Z])|([A-Z])([A-Z][a-z])/g, "$1$3-$2$4")
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+
+/** Compiles the host entry, which starts its own listener, into `build/server/<name>-services`. */
+export const buildServer = async (config: ResolvedTsplcConfig, root: string) => {
+  const settings = config.server;
+  if (!settings?.runtime) throw new Error("Configure server.runtime to build an executable.");
+  const runtime = settings.runtime;
+  const entry = resolveServerModule(root, runtime.entry);
+  const windows = runtime.target
+    ? runtime.target.includes("windows")
+    : process.platform === "win32";
+  const outFile = resolve(
+    root,
+    "build/server",
+    `${kebabCase(config.name)}-services${windows ? ".exe" : ""}`,
+  );
+  const tsconfig = ts.findConfigFile(dirname(entry), ts.sys.fileExists);
+  if (!tsconfig) throw new Error("Server entry requires a tsconfig.json.");
+  const read = ts.readConfigFile(tsconfig, ts.sys.readFile);
+  if (read.error) throw new Error(ts.flattenDiagnosticMessageText(read.error.messageText, "\n"));
+  const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(tsconfig));
+  const program = ts.createProgram({
+    rootNames: [entry, ...parsed.fileNames.filter((file) => /\.d\.[cm]?ts$/.test(file))],
+    options: { ...parsed.options, ...typeCheckOnly },
+    projectReferences: parsed.projectReferences,
+  });
+  const diagnostics = [...parsed.errors, ...ts.getPreEmitDiagnostics(program)];
+  if (diagnostics.length)
+    throw new Error(
+      ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+        getCanonicalFileName: (path) => path,
+        getCurrentDirectory: () => root,
+        getNewLine: () => "\n",
+      }),
+    );
+  await mkdir(dirname(outFile), { recursive: true });
+  // Compile beside the output so dependency resolution starts from the owning project.
+  const staging = await mkdtemp(join(dirname(outFile), ".tsplc-server-"));
+  try {
+    const binary = join(staging, "server");
+    const result = await Bun.build({
+      entrypoints: [entry],
+      env: "disable",
+      compile: {
+        outfile: binary,
+        ...(runtime.target ? { target: runtime.target } : {}),
+        autoloadDotenv: false,
+        autoloadBunfig: false,
+        autoloadTsconfig: false,
+        autoloadPackageJson: false,
+      },
+    });
+    if (!result.success) throw new AggregateError(result.logs, "Server executable build failed.");
+    // Bun names a Windows executable itself.
+    await rename(windows ? `${binary}.exe` : binary, outFile);
+    return {
+      server: {
+        executable: outFile,
+        target: runtime.target ?? `bun-${process.platform}-${process.arch}`,
+      },
+    };
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+};