@tsplc/compiler 0.0.0-stage → 0.2.0

package/src/frontend/blocks.ts

@@ -0,0 +1,419 @@
+import ts from "typescript";
+import {
+  aggregate,
+  defaultValue,
+  instancedBlock,
+  standardBlocks,
+  type StandardBlock,
+  type FunctionBlock,
+  type Variable,
+  type SourceSpan,
+  type PlcType,
+} from "@tsplc/compiler/ir";
+import { calleeName, numericLiteralType, type Fail, type TypeResolver } from "./types.ts";
+
+export interface BlockSource {
+  block: FunctionBlock;
+  method: ts.MethodDeclaration;
+  methods: readonly ts.MethodDeclaration[];
+  inputSymbol: ts.Symbol;
+  inputBindings: ReadonlyMap<string, Variable>;
+  fieldBindings: ReadonlyMap<ts.Symbol, Variable>;
+  initializers: ReadonlyMap<Variable, ts.Expression>;
+}
+export function storageInitializer(
+  node: ts.Expression,
+  types: TypeResolver,
+  fail: Fail,
+): { value: ts.Expression; retain: boolean } {
+  if (!ts.isCallExpression(node)) return { value: node, retain: false };
+  const callee = calleeName(node.expression);
+  if (!callee || types.sdkName(callee) !== "retain") return { value: node, retain: false };
+  if (node.arguments.length !== 1 || (node.typeArguments?.length ?? 0) > 1)
+    fail(node, "PLC3004", "retain requires one static storage initializer.");
+  return { value: node.arguments[0]!, retain: true };
+}
+
+export class BlockResolver {
+  readonly definitions = new Map<string, FunctionBlock>();
+  readonly sources = new Map<ts.Symbol, BlockSource>();
+  private readonly declarations = new Map<ts.Symbol, ts.ClassDeclaration>();
+  private readonly active = new Set<ts.Symbol>();
+  constructor(
+    private readonly types: TypeResolver,
+    private readonly origin: (node: ts.Node) => SourceSpan,
+    private readonly fail: Fail,
+    sdkSpan: SourceSpan,
+  ) {
+    for (const name of Object.keys(standardBlocks) as StandardBlock[]) {
+      const schema = standardBlocks[name],
+        id = `stdlib:${name}`,
+        output = `${id}:out`;
+      const variable = (label: string, type: string, storage: Variable["storage"]): Variable => ({
+        id: `${id}:${label}`,
+        name: label,
+        type,
+        storage,
+        mutable: false,
+        retain: false,
+        span: sdkSpan,
+        ...(storage === "blockOutput" && { initial: defaultValue(type, types.types) }),
+      });
+      const block: FunctionBlock = {
+        id,
+        name,
+        inputs: schema.inputs.map(([label, , type]) => variable(label, type, "parameter")),
+        outputs: schema.outputs.map(([label, , type]) => variable(label, type, "blockOutput")),
+        state: [],
+        locals: [],
+        body: [],
+        result: output,
+        standard: name,
+        span: sdkSpan,
+      };
+      this.definitions.set(id, block);
+      types.types.set(output, {
+        id: output,
+        kind: "record",
+        fields: block.outputs.map((field) => ({
+          name: field.name,
+          type: field.type,
+          readonly: true,
+        })),
+      });
+      const type: PlcType = { id: `block:${id}`, kind: "block", block: id, output };
+      types.types.set(type.id, type);
+      types.standardTypes.set(name, type.id);
+    }
+  }
+
+  index(nodes: readonly ts.ClassDeclaration[]): void {
+    for (const node of nodes) {
+      if (!node.name) this.fail(node, "PLC1001", "Function block classes need names.");
+      this.declarations.set(this.types.symbol(node.name), node);
+    }
+  }
+
+  instanceType(node: ts.NewExpression): string {
+    const name = calleeName(node.expression);
+    if (node.arguments?.length || node.typeArguments?.length || !name)
+      this.fail(
+        node,
+        "PLC1007",
+        "Block instances use a concrete zero-argument constructor at static storage declarations.",
+      );
+    const official = this.types.sdkName(name),
+      standard = official && this.types.standardTypes.get(official);
+    if (standard) return standard;
+    const symbol = this.types.symbol(name),
+      declaration = this.declarations.get(symbol);
+    if (!declaration)
+      this.fail(node, "PLC1007", "Only recognized static function block allocation is supported.");
+    this.collect(declaration);
+    // Successful collection registers this class identity before publishing its source.
+    return this.types.blockTypes.get(symbol)!;
+  }
+
+  /**
+   * `FixedArray<Block, N>` storage allocated with `defaultValue`; its elements are static
+   * instances. The allocation names the type, so an annotation is optional but must agree.
+   */
+  instanceArrayType(annotation: ts.TypeNode | undefined, value: ts.Expression): string | undefined {
+    const blockArray = (type: string) =>
+      this.types.types.get(type)?.kind === "array" && instancedBlock(type, this.types.types)
+        ? type
+        : undefined;
+    const declared = annotation && this.types.resolve(annotation).type;
+    if (declared && !blockArray(declared)) return undefined;
+    const callee = ts.isCallExpression(value) && calleeName(value.expression);
+    const allocation =
+      callee && this.types.sdkName(callee) === "defaultValue" && value.typeArguments?.length === 1
+        ? this.types.resolve(value.typeArguments[0]!).type
+        : undefined;
+    if (!declared) return allocation && blockArray(allocation);
+    if (allocation !== declared)
+      this.fail(
+        value,
+        "PLC1007",
+        "Block arrays allocate with defaultValue<FixedArray<Block, N>>() of their declared type.",
+      );
+    return declared;
+  }
+
+  collect(node: ts.ClassDeclaration): void {
+    if (!node.name) this.fail(node, "PLC1001", "Function block classes need names.");
+    const symbol = this.types.symbol(node.name);
+    if (this.sources.has(symbol)) return;
+    if (this.active.has(symbol) || this.active.size >= 64)
+      this.fail(node, "PLC1007", "Recursive or excessively nested block instance layout.");
+    if (
+      node.typeParameters?.length ||
+      node.modifiers?.some(
+        (modifier) =>
+          modifier.kind === ts.SyntaxKind.Decorator ||
+          modifier.kind === ts.SyntaxKind.AbstractKeyword,
+      )
+    )
+      this.fail(
+        node,
+        "PLC1001",
+        "Block classes are concrete; generic classes and decorators are unsupported.",
+      );
+    const heritage = node.heritageClauses;
+    if (
+      heritage?.length !== 1 ||
+      heritage[0]?.token !== ts.SyntaxKind.ExtendsKeyword ||
+      heritage[0].types.length !== 1
+    )
+      this.fail(
+        node,
+        "PLC1001",
+        "Function block classes extend the canonical FunctionBlock marker only.",
+      );
+    const base = heritage[0].types[0]!;
+    if (
+      this.types.sdkName(base.expression) !== "FunctionBlock" ||
+      !base.typeArguments ||
+      base.typeArguments.length < 1 ||
+      base.typeArguments.length > 2
+    )
+      this.fail(base, "PLC1001", "Extend FunctionBlock<Inputs, Outputs> with concrete schemas.");
+    // Register identity before nested fields; the active set rejects recursive allocation.
+    this.active.add(symbol);
+    const id = this.types.id(node, node.name.text),
+      typeId = `block:${id}`;
+    this.types.types.set(typeId, { id: typeId, kind: "block", block: id });
+    this.types.blockTypes.set(symbol, typeId);
+    try {
+      const inputFields = this.types.inputFields(base.typeArguments[0]!);
+      let result: string | undefined;
+      const outputNode = base.typeArguments[1];
+      if (outputNode && !(ts.isTypeLiteralNode(outputNode) && !outputNode.members.length)) {
+        const resolved = this.types.resolve(outputNode),
+          layout = this.types.types.get(resolved.type);
+        if (
+          resolved.io ||
+          resolved.mode ||
+          this.types.hasReferences(resolved.type) ||
+          layout?.kind !== "record"
+        )
+          this.fail(outputNode, "PLC2001", "Block outputs require a closed value record.");
+        result = resolved.type;
+      }
+      const fieldBindings = new Map<ts.Symbol, Variable>(),
+        initializers = new Map<Variable, ts.Expression>(),
+        state: Variable[] = [];
+      let method: ts.MethodDeclaration | undefined;
+      const methods: ts.MethodDeclaration[] = [];
+      for (const member of node.members) {
+        if (ts.isMethodDeclaration(member)) {
+          if (ts.isIdentifier(member.name) && member.name.text !== "execute") {
+            if (
+              !member.body ||
+              member.asteriskToken ||
+              member.questionToken ||
+              member.typeParameters?.length ||
+              ["update", "out"].includes(member.name.text) ||
+              member.modifiers?.some(
+                (modifier) =>
+                  ![
+                    ts.SyntaxKind.PublicKeyword,
+                    ts.SyntaxKind.PrivateKeyword,
+                    ts.SyntaxKind.ProtectedKeyword,
+                  ].includes(modifier.kind),
+              )
+            )
+              this.fail(
+                member,
+                "PLC1001",
+                "Block methods require concrete instance implementations without generics or overloads.",
+              );
+            methods.push(member);
+            continue;
+          }
+          if (
+            method ||
+            !ts.isIdentifier(member.name) ||
+            member.name.text !== "execute" ||
+            !member.body ||
+            member.asteriskToken ||
+            member.modifiers?.some(
+              (modifier) =>
+                ![ts.SyntaxKind.ProtectedKeyword, ts.SyntaxKind.OverrideKeyword].includes(
+                  modifier.kind,
+                ),
+            ) ||
+            !member.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ProtectedKeyword)
+          )
+            this.fail(member, "PLC1001", "A block implements one protected execute method.");
+          method = member;
+          continue;
+        }
+        const field = this.collectStateField(member, id);
+        state.push(field.variable);
+        fieldBindings.set(field.symbol, field.variable);
+        if (field.initializer) initializers.set(field.variable, field.initializer);
+      }
+      if (method?.parameters.length !== 1 || method.typeParameters?.length)
+        this.fail(node, "PLC1001", "Block execute requires one concrete input record parameter.");
+      const parameter = method.parameters[0]!;
+      if (
+        !ts.isIdentifier(parameter.name) ||
+        !parameter.type ||
+        parameter.initializer ||
+        parameter.questionToken ||
+        parameter.dotDotDotToken
+      )
+        this.fail(
+          parameter,
+          "PLC2001",
+          "Block execute requires one named, explicitly typed input parameter.",
+        );
+      const methodFields = this.types.inputFields(parameter.type);
+      if (JSON.stringify(methodFields) !== JSON.stringify(inputFields))
+        this.fail(
+          parameter,
+          "PLC2001",
+          "execute input schema differs from its FunctionBlock marker.",
+        );
+      if (
+        !method.type ||
+        (result
+          ? this.types.resolve(method.type).type !== result
+          : method.type.kind !== ts.SyntaxKind.VoidKeyword)
+      )
+        this.fail(
+          method,
+          "PLC2001",
+          "execute return annotation must match the complete output record, or void when there are no outputs.",
+        );
+      const inputs = inputFields.map((field) => {
+        // Records and arrays pass by reference, as objects do in TypeScript.
+        const mode =
+          field.mode ?? (aggregate(this.types.types.get(field.type)) ? "inOut" : undefined);
+        return {
+          id: `${id}:input:${field.name}`,
+          name: field.name,
+          type: field.type,
+          storage: "parameter" as const,
+          mutable: mode === "inOut",
+          retain: false,
+          span: this.origin(parameter),
+          ...(mode && { mode }),
+        };
+      });
+      const outputType = result && this.types.types.get(result),
+        outputs: Variable[] =
+          outputType && outputType.kind === "record"
+            ? outputType.fields.map((field) => ({
+                id: `${id}:output:${field.name}`,
+                name: field.name,
+                type: field.type,
+                storage: "blockOutput",
+                mutable: false,
+                retain: false,
+                initial: defaultValue(field.type, this.types.types),
+                span: this.origin(method!),
+              }))
+            : [];
+      const block: FunctionBlock = {
+        id,
+        name: node.name.text,
+        inputs,
+        outputs,
+        state,
+        locals: [],
+        body: [],
+        span: this.origin(node),
+        ...(result && { result }),
+      };
+      this.definitions.set(id, block);
+      this.types.types.set(typeId, {
+        id: typeId,
+        kind: "block",
+        block: id,
+        ...(result && { output: result }),
+      });
+      this.sources.set(symbol, {
+        block,
+        method,
+        methods,
+        inputSymbol: this.types.symbol(parameter.name),
+        inputBindings: new Map(inputs.map((variable) => [variable.name, variable])),
+        fieldBindings,
+        initializers,
+      });
+    } finally {
+      this.active.delete(symbol);
+    }
+  }
+  // Private state fields own storage admission, constructor allocation and initializer capture.
+  // The enclosing collection keeps schema/execute validation separate from this field policy.
+  private collectStateField(
+    member: ts.ClassElement,
+    id: string,
+  ): {
+    variable: Variable;
+    symbol: ts.Symbol;
+    initializer?: ts.Expression;
+  } {
+    if (
+      !ts.isPropertyDeclaration(member) ||
+      !ts.isIdentifier(member.name) ||
+      !member.initializer ||
+      member.questionToken ||
+      member.exclamationToken ||
+      !member.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.PrivateKeyword) ||
+      member.modifiers.some(
+        (modifier) =>
+          ![ts.SyntaxKind.PrivateKeyword, ts.SyntaxKind.ReadonlyKeyword].includes(modifier.kind),
+      )
+    )
+      this.fail(
+        member,
+        "PLC1001",
+        "Block state uses private initialized instance fields; constructors, static fields and decorators are unsupported.",
+      );
+    const initial = storageInitializer(member.initializer, this.types, this.fail);
+    const instanceArray = ts.isNewExpression(initial.value)
+      ? undefined
+      : this.instanceArrayType(member.type, initial.value);
+    let type: string;
+    if (ts.isNewExpression(initial.value)) type = this.instanceType(initial.value);
+    else if (instanceArray) type = instanceArray;
+    else if (member.type) {
+      const annotation = this.types.resolve(member.type);
+      if (annotation.io || annotation.mode || this.types.hasReferences(annotation.type))
+        this.fail(member, "PLC2001", "Borrow and I/O wrappers cannot be stored in block state.");
+      type = annotation.type;
+    } else if (
+      initial.value.kind === ts.SyntaxKind.TrueKeyword ||
+      initial.value.kind === ts.SyntaxKind.FalseKeyword
+    )
+      type = "BOOL";
+    else if (/^-?\d/.test(initial.value.getText()))
+      type = numericLiteralType(initial.value.getText());
+    else this.fail(member, "PLC2001", "Annotate private numeric and aggregate state explicitly.");
+    if (member.type && this.types.resolve(member.type).type !== type)
+      this.fail(member, "PLC2001", "Instance annotation differs from its constructor.");
+    const instance = Boolean(instancedBlock(type, this.types.types));
+    if (this.types.types.get(type)?.kind === "block" && !ts.isNewExpression(initial.value))
+      this.fail(member, "PLC1007", "Block instances require static constructor initialization.");
+    const variable: Variable = {
+      id: `${id}:field:${member.name.text}`,
+      name: member.name.text,
+      type,
+      storage: instance ? "instance" : "field",
+      mutable:
+        !instance &&
+        !member.modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ReadonlyKeyword),
+      retain: initial.retain,
+      span: this.origin(member),
+    };
+    return {
+      variable,
+      symbol: this.types.symbol(member.name),
+      ...(!instance && { initializer: initial.value }),
+    };
+  }
+}

package/src/frontend/configuration.ts

@@ -0,0 +1,167 @@
+import { runtimeSources } from "./module-graph.ts";
+import ts from "typescript";
+import { dirname } from "node:path";
+import { error, type Diagnostic } from "@tsplc/compiler/ir";
+
+const symbolAt = (checker: ts.TypeChecker, node: ts.Node) => {
+  let symbol = checker.getSymbolAtLocation(node);
+  while (symbol && symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+  return symbol;
+};
+
+export const lowerEnvironment = (program: ts.Program, sdk: string) => {
+  const checker = program.getTypeChecker();
+  const sources = new Map<string, string>();
+  const diagnostics: Diagnostic[] = [];
+  for (const source of runtimeSources(program)) {
+    if (source.isDeclarationFile) continue;
+    const edits: { start: number; end: number; text: string }[] = [];
+    const visit = (node: ts.Node): void => {
+      if (ts.isCallExpression(node)) {
+        const symbol = symbolAt(checker, node.expression);
+        if (
+          symbol?.name === "env" &&
+          symbol.declarations?.some((declaration) =>
+            declaration.getSourceFile().fileName.startsWith(dirname(sdk) + "/"),
+          )
+        ) {
+          const name = node.arguments[0];
+          let owner: ts.Node | undefined = node.parent;
+          while (owner && !ts.isVariableDeclaration(owner) && !ts.isFunctionLike(owner))
+            owner = owner.parent;
+          const moduleConst =
+            owner &&
+            ts.isVariableDeclaration(owner) &&
+            ts.isVariableDeclarationList(owner.parent) &&
+            Boolean(owner.parent.flags & ts.NodeFlags.Const) &&
+            ts.isVariableStatement(owner.parent.parent) &&
+            ts.isSourceFile(owner.parent.parent.parent);
+          const value = name && ts.isStringLiteral(name) ? process.env[name.text] : undefined;
+          let message: string | undefined;
+          if (
+            !moduleConst ||
+            node.arguments.length !== 1 ||
+            !name ||
+            !ts.isStringLiteral(name) ||
+            node.typeArguments?.length !== 1
+          )
+            message =
+              "env<STRING<N>> requires a literal environment name in module-level const configuration.";
+          else if (value === undefined || value.length === 0)
+            message = `Required environment value ${name.text} is missing.`;
+          else if (value.includes("\0"))
+            message = `Environment value ${name.text} contains an unsupported NUL byte.`;
+          if (message) {
+            const start = node.getStart(source),
+              position = source.getLineAndCharacterOfPosition(start);
+            diagnostics.push(
+              error("PLC1011", message, {
+                file: source.fileName,
+                start,
+                end: node.end,
+                line: position.line + 1,
+                column: position.character + 1,
+              }),
+            );
+          } else if (value !== undefined)
+            edits.push({
+              start: node.getStart(source),
+              end: node.end,
+              text: JSON.stringify(value),
+            });
+          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);
+    sources.set(source.fileName, text);
+  }
+  return { sources, diagnostics };
+};
+
+/** URL expressions are compile-time values, never reads from mutable PLC state. */
+export const staticString = (checker: ts.TypeChecker, root: ts.Expression): string | undefined => {
+  const active = new Set<ts.Node>();
+  const valueNode = (node: ts.Node): ts.Node | undefined => {
+    if (ts.isParenthesizedExpression(node)) return node.expression;
+    if (ts.isIdentifier(node)) {
+      const declaration = symbolAt(checker, node)?.declarations?.find(ts.isVariableDeclaration);
+      if (
+        declaration &&
+        ts.isVariableDeclarationList(declaration.parent) &&
+        declaration.parent.flags & ts.NodeFlags.Const
+      )
+        return declaration.initializer;
+    }
+    if (ts.isPropertyAccessExpression(node)) {
+      const field = symbolAt(checker, node.name);
+      if (
+        !field?.declarations?.some(
+          (declaration) =>
+            ts.canHaveModifiers(declaration) &&
+            ts
+              .getModifiers(declaration)
+              ?.some((modifier) => modifier.kind === ts.SyntaxKind.ReadonlyKeyword),
+        )
+      )
+        return;
+      const object = resolve(node.expression);
+      if (object && ts.isObjectLiteralExpression(object)) {
+        for (const property of object.properties) {
+          if (
+            ts.isPropertyAssignment(property) &&
+            (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+            property.name.text === node.name.text
+          )
+            return property.initializer;
+        }
+      }
+      return;
+    }
+    return node;
+  };
+  const resolve = (node: ts.Node): ts.Node | undefined => {
+    if (active.has(node)) return;
+    active.add(node);
+    try {
+      const next = valueNode(node);
+      return next && next !== node ? resolve(next) : next;
+    } finally {
+      active.delete(node);
+    }
+  };
+  const read = (node: ts.Node): string | undefined => {
+    const resolved = resolve(node);
+    if (!resolved || active.has(resolved)) return;
+    active.add(resolved);
+    try {
+      if (ts.isStringLiteral(resolved) || ts.isNoSubstitutionTemplateLiteral(resolved))
+        return resolved.text;
+      if (ts.isTemplateExpression(resolved)) {
+        let value = resolved.head.text;
+        for (const part of resolved.templateSpans) {
+          const item = read(part.expression);
+          if (item === undefined) return;
+          value += item + part.literal.text;
+        }
+        return value;
+      }
+      if (
+        ts.isBinaryExpression(resolved) &&
+        resolved.operatorToken.kind === ts.SyntaxKind.PlusToken
+      ) {
+        const left = read(resolved.left),
+          right = read(resolved.right);
+        if (left !== undefined && right !== undefined) return left + right;
+      }
+    } finally {
+      active.delete(resolved);
+    }
+  };
+  return read(root);
+};