@tsplc/build 0.0.0-stage → 0.1.0

package/src/sources.ts

@@ -0,0 +1,248 @@
+import { readdir, readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import type { ResolvedConfig } from "./config";
+import { type ObjectKind, type ParsedSource, parseSource } from "./st/parse";
+import { bindStructuredTextIo } from "./io.ts";
+
+export type SourceObject = ParsedSource & {
+  source: string;
+  folder: string[];
+  children: SourceObject[];
+};
+type Files = {
+  combined: string[];
+  declaration: string[];
+  implementation: string[];
+};
+const prefixes: Record<string, ObjectKind> = {
+  FB: "function_block",
+  PRG: "program",
+  FUN: "function",
+  F: "function",
+  I: "interface",
+  ST: "dut",
+  E: "dut",
+  T: "dut",
+  U: "dut",
+  GVL: "gvl",
+};
+const childFolders: Record<string, ObjectKind> = {
+  methods: "method",
+  properties: "property",
+  actions: "action",
+};
+const canOwn = (kind: ObjectKind) =>
+  ["program", "function_block", "interface", "property"].includes(kind);
+const assertUnique = (objects: SourceObject[], scope: string) => {
+  const seen = new Map<string, string>();
+  for (const object of objects) {
+    const key = object.name.toLowerCase();
+    const previous = seen.get(key);
+    if (previous) {
+      throw new Error(
+        `Duplicate IEC name ${object.name} in ${scope}: ${previous} and ${object.source}`,
+      );
+    }
+    seen.set(key, object.source);
+    assertUnique(object.children, `${scope}.${object.name}`);
+  }
+};
+
+const readUnit = async (
+  name: string,
+  files: Files,
+  role?: ObjectKind,
+  interfaceMember = false,
+): Promise<ParsedSource & { source: string }> => {
+  if (!/^[A-Za-z_][A-Za-z_0-9]*$/.test(name)) {
+    throw new Error(`Invalid IEC object name: ${name}`);
+  }
+  for (const [part, candidates] of Object.entries(files)) {
+    if (candidates.length > 1) {
+      throw new Error(`Ambiguous ${part} for ${name}: ${candidates.join(", ")}`);
+    }
+  }
+  const combined = files.combined[0];
+  const declaration = files.declaration[0];
+  const implementation = files.implementation[0];
+  if (combined && (declaration || implementation)) {
+    throw new Error(`Both combined and split sources exist for ${name}`);
+  }
+  const path = combined ?? declaration ?? implementation;
+  if (!path) {
+    throw new Error(`Missing source for ${name}`);
+  }
+  if (role === "action") {
+    if (!combined) {
+      throw new Error(`Actions use one implementation-only .st file: ${path}`);
+    }
+    return {
+      kind: "action",
+      name,
+      declaration: "",
+      implementation: await readFile(combined, "utf8"),
+      source: combined,
+    };
+  }
+  if (role === "get" || role === "set") {
+    if (!combined) {
+      throw new Error(`Property accessors use one .st file: ${path}`);
+    }
+    const body = await readFile(combined, "utf8");
+    const header = `METHOD ${name}\n`;
+    const parsed = parseSource(`${header}${body}\nEND_METHOD`, {
+      filename: combined,
+    });
+    return {
+      ...parsed,
+      kind: role,
+      name,
+      declaration: parsed.declaration.slice(header.length),
+      source: combined,
+    };
+  }
+  if (!combined && !declaration) {
+    throw new Error(`Missing declaration for ${path}`);
+  }
+  const sourcePath = combined ?? declaration ?? path;
+  const parsed = parseSource(await readFile(sourcePath, "utf8"), {
+    filename: sourcePath,
+    name,
+    declarationOnly: !combined || interfaceMember,
+  });
+  if (parsed.name.toLowerCase() !== name.toLowerCase()) {
+    throw new Error(`Source name ${name} does not match declaration ${parsed.name}: ${sourcePath}`);
+  }
+  if (role && parsed.kind !== role) {
+    throw new Error(`Expected ${role}, found ${parsed.kind}: ${sourcePath}`);
+  }
+  if (!role && ["method", "property"].includes(parsed.kind)) {
+    throw new Error(`Child object has no enclosing POU: ${sourcePath}`);
+  }
+  const prefix = /^([A-Z]+)_/.exec(name.toUpperCase())?.[1];
+  if (!role && prefix && prefixes[prefix] && prefixes[prefix] !== parsed.kind) {
+    throw new Error(`Prefix ${prefix}_ conflicts with ${parsed.kind}: ${sourcePath}`);
+  }
+  const declarationOnly =
+    ["dut", "gvl", "interface", "property"].includes(parsed.kind) || interfaceMember;
+  if (declarationOnly && implementation) {
+    throw new Error(`This object has no implementation: ${implementation}`);
+  }
+  if (!combined && !declarationOnly && !implementation) {
+    throw new Error(`Missing implementation for ${sourcePath}`);
+  }
+  return {
+    ...parsed,
+    ...(implementation ? { implementation: await readFile(implementation, "utf8") } : {}),
+    source: sourcePath,
+  };
+};
+
+/** Folder placement organizes the IDE; it never changes IEC names or execution order. */
+export const loadSources = async (
+  config: Pick<ResolvedConfig, "sourceDir" | "entry" | "io" | "tasks">,
+) => {
+  const objects: SourceObject[] = [];
+  const visit = async (
+    directory: string,
+    folder: string[],
+    parent?: SourceObject,
+    role?: ObjectKind,
+  ): Promise<void> => {
+    const entries = (await readdir(directory, { withFileTypes: true })).sort((a, b) =>
+      a.name.localeCompare(b.name, "en"),
+    );
+    const groups = new Map<string, { name: string; files: Files }>();
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) {
+        throw new Error(`Source symlinks are not supported: ${resolve(directory, entry.name)}`);
+      }
+      if (!entry.isFile() || !/\.st$/i.test(entry.name)) {
+        continue;
+      }
+      const stem = entry.name.slice(0, -3);
+      const suffix = /^(.*)\.(declaration|implementation)$/.exec(stem);
+      const generic = ["source", "declaration", "implementation"].includes(stem);
+      const name = generic ? basename(directory) : (suffix?.[1] ?? stem);
+      const section = suffix?.[2] ?? stem;
+      const part = section === "declaration" || section === "implementation" ? section : "combined";
+      const key = name.toLowerCase();
+      const group = groups.get(key) ?? {
+        name,
+        files: { combined: [], declaration: [], implementation: [] },
+      };
+      group.files[part].push(resolve(directory, entry.name));
+      groups.set(key, group);
+    }
+    const units: SourceObject[] = [];
+    const ownKey = basename(directory).toLowerCase();
+    // Read an object's own source before its Get/Set files, which have no POU header.
+    const ordered = [...groups].sort(([a], [b]) => Number(b === ownKey) - Number(a === ownKey));
+    for (const [key, { name, files }] of ordered) {
+      const ownProperty = units.find(
+        (unit) => unit.kind === "property" && unit.name.toLowerCase() === ownKey,
+      );
+      const accessor = ownProperty && (key === "get" || key === "set") ? key : undefined;
+      const unit: SourceObject = {
+        ...(await readUnit(
+          accessor ? `${accessor[0]?.toUpperCase()}${accessor.slice(1)}` : name,
+          files,
+          accessor ?? role,
+          parent?.kind === "interface",
+        )),
+        folder: parent ? [] : folder,
+        children: [],
+      };
+      if (accessor && ownProperty) {
+        if (parent?.kind === "interface") {
+          throw new Error(`Interface properties cannot implement accessors: ${unit.source}`);
+        }
+        ownProperty.children.push(unit);
+      } else {
+        units.push(unit);
+        if (parent) {
+          parent.children.push(unit);
+        } else {
+          objects.push(unit);
+        }
+      }
+    }
+    const own = units.find((unit) => unit.name.toLowerCase() === ownKey && canOwn(unit.kind));
+    if (own && !parent) {
+      own.folder = folder.slice(0, -1);
+    }
+    for (const entry of entries.filter((entry) => entry.isDirectory())) {
+      const childRole = childFolders[entry.name];
+      if (own && childRole) {
+        if (own.kind === "property" || (own.kind === "interface" && childRole === "action")) {
+          throw new Error(`Unsupported ${entry.name} under ${own.name}`);
+        }
+        await visit(resolve(directory, entry.name), [], own, childRole);
+      } else if (parent) {
+        await visit(resolve(directory, entry.name), [], parent, role);
+      } else {
+        await visit(resolve(directory, entry.name), [...folder, entry.name]);
+      }
+    }
+  };
+  await visit(resolve(config.sourceDir), []);
+  assertUnique(objects, "Application");
+  if (config.io) bindStructuredTextIo(objects, config.io);
+  const entry = objects.find((object) => object.source === resolve(config.entry));
+  if (!entry) {
+    throw new Error(`Entry is not a discovered source: ${config.entry}`);
+  }
+  if (entry.kind !== "program") {
+    throw new Error(`Entry must be a PROGRAM: ${config.entry}`);
+  }
+  if (config.tasks) {
+    const programs = new Set(
+      objects.filter((object) => object.kind === "program").map((object) => object.name),
+    );
+    for (const task of config.tasks)
+      for (const program of task.programs)
+        if (!programs.has(program))
+          throw new Error(`Task ${task.name} references an undiscovered PROGRAM ${program}`);
+  }
+  return { entry: entry.name, objects };
+};

package/src/st/declarations.ts

@@ -0,0 +1,229 @@
+import type { Token } from "./lexer";
+import type { TokenReader } from "./reader";
+
+export const objectKinds = {
+  PROGRAM: "program",
+  FUNCTION_BLOCK: "function_block",
+  FUNCTIONBLOCK: "function_block",
+  FUNCTION: "function",
+  METHOD: "method",
+  INTERFACE: "interface",
+  PROPERTY: "property",
+} as const;
+
+const modifiers = new Set([
+  "PUBLIC",
+  "PRIVATE",
+  "PROTECTED",
+  "INTERNAL",
+  "FINAL",
+  "ABSTRACT",
+  "OVERRIDE",
+]);
+export const globalSections = new Set(["VAR_GLOBAL", "VAR_CONFIG"]);
+export const variableSections = new Set([
+  ...globalSections,
+  "VAR",
+  "VAR_INPUT",
+  "VAR_OUTPUT",
+  "VAR_IN_OUT",
+  "VAR_TEMP",
+  "VAR_STAT",
+  "VAR_INST",
+  "VAR_EXTERNAL",
+  "VAR_ACCESS",
+  "VAR_GENERIC",
+]);
+const closingObjects = new Set(Object.keys(objectKinds).map((kind) => `END_${kind}`));
+export const declarationKeywords = new Set([
+  ...Object.keys(objectKinds),
+  ...closingObjects,
+  ...variableSections,
+  "END_VAR",
+  "TYPE",
+  "END_TYPE",
+  "STRUCT",
+  "END_STRUCT",
+  "UNION",
+  "END_UNION",
+  "ACTION",
+  "END_ACTION",
+  "CONFIGURATION",
+  "END_CONFIGURATION",
+]);
+
+const conditionalDirective = (token?: Token) => {
+  if (token?.kind === "pragma") {
+    return /^\{\s*(IF|ELSIF|ELSE|END_IF)\b/i.exec(token.value)?.[1]?.toUpperCase();
+  }
+};
+const isDeclarationPragma = (token?: Token) =>
+  token?.kind === "pragma" && !conditionalDirective(token);
+
+export const readDeclarationPragmas = (reader: TokenReader) => {
+  while (isDeclarationPragma(reader.peek())) {
+    reader.take();
+  }
+};
+
+export const readDeclarationSemicolon = (reader: TokenReader) => {
+  const token = reader.peek();
+  // A semicolon on the next line may be the body's first empty statement.
+  // Only attach it to a declaration when it terminates that same line.
+  if (token?.value === ";" && !/[\r\n]/.test(reader.source.slice(reader.end, token.start))) {
+    reader.take();
+  }
+};
+
+export const readIdentifier = (reader: TokenReader) => {
+  const token = reader.take();
+  if (token.kind !== "word" || declarationKeywords.has(token.value)) {
+    reader.fail("Expected an IEC identifier", token);
+  }
+  return reader.source.slice(token.start, token.end);
+};
+
+const isOverrideModifier = (reader: TokenReader) => {
+  // OVERRIDE is also an established IEC name (e.g. OSCAT's function).
+  // A modifier needs a following name on the same line, not a body statement.
+  const name = reader.peek(1);
+  return (
+    name?.kind === "word" &&
+    !declarationKeywords.has(name.value) &&
+    !["(", "[", ":=", ".", "^"].includes(reader.peek(2)?.value ?? "") &&
+    !/[\r\n]/.test(reader.source.slice(reader.peek()?.end, name.start))
+  );
+};
+
+export const readModifiers = (reader: TokenReader) => {
+  while (modifiers.has(reader.peek()?.value ?? "")) {
+    if (reader.peek()?.value === "OVERRIDE" && !isOverrideModifier(reader)) {
+      return;
+    }
+    reader.take();
+  }
+};
+
+const typeDelimiters = { "(": ")", "[": "]", "<": ">" } as const;
+
+const readDelimitedType = (reader: TokenReader, open: keyof typeof typeDelimiters) => {
+  reader.expect(open);
+  const closings = [typeDelimiters[open]];
+  while (closings.length) {
+    const token = reader.take();
+    if (token.kind === "string" || token.kind === "pragma") {
+      continue;
+    }
+    if (token.value === "(" || token.value === "[") {
+      closings.push(typeDelimiters[token.value]);
+    } else if (token.value === ")" || token.value === "]") {
+      if (closings.pop() !== token.value) {
+        reader.fail(`Mismatched delimiter ${token.value}`, token);
+      }
+    } else if (open === "<" && closings.at(-1) === ">") {
+      // Inside parentheses, < and > are comparisons, not generic delimiters:
+      // FB_Base<(Size := BOOL_TO_INT(1 < 2))>.
+      if (token.value === "<") {
+        closings.push(">");
+      }
+      if (token.value === ">") {
+        closings.pop();
+      }
+    }
+    if (declarationKeywords.has(token.value) || token.value === ";") {
+      reader.fail(`Unclosed ${open}`, token);
+    }
+  }
+};
+
+export const readType = (reader: TokenReader): string => {
+  const start = reader.peek()?.start ?? reader.source.length;
+  // Prefix types can nest arbitrarily; iteration avoids a JavaScript stack limit.
+  while (true) {
+    if (["POINTER", "REFERENCE", "REF_TO"].includes(reader.peek()?.value ?? "")) {
+      if (reader.take().value !== "REF_TO") {
+        reader.expect("TO");
+      }
+      continue;
+    }
+    if (reader.consume("ARRAY")) {
+      readDelimitedType(reader, "[");
+      reader.expect("OF");
+      continue;
+    }
+    break;
+  }
+  readIdentifier(reader);
+  while (reader.consume(".")) {
+    readIdentifier(reader);
+  }
+  for (const open of ["(", "[", "<"] as const) {
+    if (reader.peek()?.value === open) {
+      readDelimitedType(reader, open);
+    }
+  }
+  return reader.source.slice(start, reader.end);
+};
+
+export const readVariableSection = (reader: TokenReader) => {
+  reader.take();
+  const conditionals: { hasElse: boolean }[] = [];
+  while (reader.peek()?.value !== "END_VAR") {
+    const token = reader.take();
+    if (variableSections.has(token.value) || closingObjects.has(token.value)) {
+      reader.fail("Missing END_VAR", token);
+    }
+    const directive = conditionalDirective(token);
+    if (!directive) {
+      continue;
+    }
+    if (directive === "IF") {
+      conditionals.push({ hasElse: false });
+      continue;
+    }
+    const current = conditionals.at(-1);
+    if (!current) {
+      return reader.fail("Unmatched conditional pragma", token);
+    }
+    if (directive === "END_IF") {
+      conditionals.pop();
+      continue;
+    }
+    if (current.hasElse) {
+      reader.fail("Conditional branch after ELSE", token);
+    }
+    current.hasElse = directive === "ELSE";
+  }
+  if (conditionals.length) {
+    reader.fail("Conditional pragmas must remain inside one variable section");
+  }
+  reader.take();
+  readDeclarationSemicolon(reader);
+};
+
+export const readDeclarationSections = (reader: TokenReader) => {
+  while (reader.peek()) {
+    // Pragmas belong to the declaration only when another declaration follows.
+    // Look ahead without consuming them so a pragma-only body stays intact.
+    let ahead = 0;
+    while (isDeclarationPragma(reader.peek(ahead))) {
+      ahead++;
+    }
+    const next = reader.peek(ahead)?.value ?? "";
+    if (variableSections.has(next)) {
+      readDeclarationPragmas(reader);
+      readVariableSection(reader);
+      continue;
+    }
+    if (next !== "EXTENDS" && next !== "IMPLEMENTS") {
+      return;
+    }
+    // CODESYS generic FBs can place these clauses after VAR_GENERIC.
+    readDeclarationPragmas(reader);
+    reader.take();
+    readType(reader);
+    while (reader.consume(",")) {
+      readType(reader);
+    }
+  }
+};

package/src/st/lexer.ts

@@ -0,0 +1,125 @@
+export type Token = {
+  kind: "word" | "string" | "pragma" | "symbol";
+  value: string;
+  start: number;
+  end: number;
+};
+
+export class StSyntaxError extends Error {
+  constructor(source: string, offset: number, filename: string, message: string) {
+    const lines = source.slice(0, offset).split(/\r\n|\r|\n/);
+    super(`${filename}:${lines.length}:${(lines.at(-1)?.length ?? 0) + 1}: ${message}`);
+    this.name = "StSyntaxError";
+  }
+}
+
+/** Keep original offsets: splitting must preserve comments, pragmas and source spelling. */
+export const tokenize = (source: string, filename = "<source>"): Token[] => {
+  const tokens: Token[] = [];
+  let offset = 0;
+  const fail = (start: number, message: string): never => {
+    throw new StSyntaxError(source, start, filename, message);
+  };
+  const quoted = () => {
+    const start = offset;
+    const quote = source[offset++];
+    while (offset < source.length) {
+      // IEC strings escape characters (including quotes and $ itself) with $.
+      if (source[offset] === "$") {
+        offset += 2;
+      } else if (source[offset++] === quote) {
+        return;
+      }
+    }
+    fail(start, "Unterminated string");
+  };
+  while (offset < source.length) {
+    const start = offset;
+    const character = source[offset] ?? "";
+    if (/\s|\uFEFF/.test(character)) {
+      offset++;
+      continue;
+    }
+    if (source.startsWith("//", offset)) {
+      while (offset < source.length && !/[\r\n]/.test(source[offset] ?? "")) {
+        offset++;
+      }
+      continue;
+    }
+    if (source.startsWith("(*", offset)) {
+      offset += 2;
+      let depth = 1;
+      while (offset < source.length && depth > 0) {
+        if (source.startsWith("(*", offset)) {
+          depth++;
+          offset += 2;
+        } else if (source.startsWith("*)", offset)) {
+          depth--;
+          offset += 2;
+        } else {
+          offset++;
+        }
+      }
+      if (depth) {
+        fail(start, "Unterminated block comment");
+      }
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quoted();
+      tokens.push({
+        kind: "string",
+        value: source.slice(start, offset),
+        start,
+        end: offset,
+      });
+      continue;
+    }
+    if (character === "{") {
+      offset++;
+      while (offset < source.length && source[offset] !== "}") {
+        if (source[offset] === "'" || source[offset] === '"') {
+          quoted();
+        } else {
+          offset++;
+        }
+      }
+      if (offset === source.length) {
+        fail(start, "Unterminated pragma");
+      }
+      offset++;
+      tokens.push({
+        kind: "pragma",
+        value: source.slice(start, offset),
+        start,
+        end: offset,
+      });
+      continue;
+    }
+    if (/[A-Za-z_]/.test(character)) {
+      offset++;
+      while (/[A-Za-z_0-9]/.test(source[offset] ?? "")) {
+        offset++;
+      }
+      tokens.push({
+        kind: "word",
+        value: source.slice(start, offset).toUpperCase(),
+        start,
+        end: offset,
+      });
+      continue;
+    }
+    offset++;
+    const pair = source.slice(start, offset + 1);
+    if ([":=", "=>", "..", "<=", ">=", "<>", "**"].includes(pair)) {
+      offset++;
+    }
+    tokens.push({
+      kind: "symbol",
+      value: source.slice(start, offset),
+      start,
+      end: offset,
+    });
+  }
+  return tokens;
+};