@styx-api/core 0.1.0

package/src/backend/typescript/validate-emit.ts

@@ -0,0 +1,341 @@
+import type { BoundType } from "../../bindings/index.js";
+import type { Expr } from "../../ir/index.js";
+import type { CodegenContext } from "../../manifest/index.js";
+import type { CodeBuilder } from "../code-builder.js";
+import type { Scope } from "../scope.js";
+import {
+  findAlternativeNode,
+  findRangeNode,
+  findRepeatNode,
+  structFields,
+} from "../validate-walk.js";
+import { structVariants } from "../union-variants.js";
+import { emitJsDoc, tsPropAccess } from "./emit.js";
+import { mapType } from "./typemap.js";
+
+/**
+ * Emit a `<tool>Validate(params)` function that walks the solved root
+ * `BoundType` and throws `StyxValidationError` on invalid input. Hand-rolled
+ * (no runtime deps): `typeof`/`Array.isArray` stand in for Python's
+ * `isinstance`. Mirrors the Python backend's validation behavior, inlined into
+ * a single function.
+ */
+
+type Resolve = (t: BoundType) => string | undefined;
+
+interface Emit {
+  ctx: CodegenContext;
+  resolve: Resolve;
+  /** Per-function scope for generated locals (loop vars), reserving `params`. */
+  scope: Scope;
+  cb: CodeBuilder;
+}
+
+export function emitValidate(
+  ctx: CodegenContext,
+  rootType: BoundType,
+  rootNode: Expr,
+  paramsType: string,
+  funcName: string,
+  resolve: Resolve,
+  scope: Scope,
+  cb: CodeBuilder,
+): void {
+  const e: Emit = { ctx, resolve, scope: scope.child(["params"]), cb };
+  emitJsDoc(
+    cb,
+    `Validate untrusted parameters. Throws StyxValidationError if \`params\` is not a valid ${paramsType}; narrows it to ${paramsType} on success.`,
+  );
+  // Assertion signature over untyped input: a boundary guard usable on a parsed
+  // dict / config blob, not just an already-typed value. The body walks `params`
+  // dynamically, so the parameter is `any` (the assertion still narrows callers).
+  cb.line(`export function ${funcName}(params: any): asserts params is ${paramsType} {`);
+  cb.indent(() => emitRoot(e, rootType, rootNode));
+  cb.line("}");
+}
+
+function emitRoot(e: Emit, rootType: BoundType, rootNode: Expr): void {
+  if (rootType.kind === "struct") {
+    block(e, `typeof params !== "object" || params === null`, () =>
+      raise(e, "Params object has the wrong type"),
+    );
+    for (const f of structFields(e.ctx, rootType, rootNode)) {
+      emitField(e, f.name, f.type, f.node, f.hasDefault, "params");
+    }
+  } else if (rootType.kind === "union") {
+    emitUnion(e, rootType, rootNode, "params", "params");
+  } else {
+    emitValue(e, rootType, rootNode, "params", "params", expectedType(e, rootType));
+  }
+}
+
+/** Validate one struct field, handling required-presence vs optional gating. */
+function emitField(
+  e: Emit,
+  name: string,
+  fieldType: BoundType,
+  node: Expr | undefined,
+  hasDefault: boolean,
+  base: string,
+): void {
+  if (fieldType.kind === "literal") return;
+
+  const access = tsPropAccess(base, name);
+  const expected = expectedType(e, fieldType);
+  const valueType = fieldType.kind === "optional" ? fieldType.inner : fieldType;
+
+  // Optionals and defaulted fields/flags accept null (null = "use default"), so
+  // gate the body instead of requiring presence.
+  if (fieldType.kind === "optional" || hasDefault) {
+    e.cb.line(`if (${access} != null) {`);
+    e.cb.indent(() => emitValue(e, valueType, node, name, access, expected));
+    e.cb.line("}");
+  } else {
+    block(e, `${access} == null`, () => raise(e, "`" + name + "` must not be null"));
+    emitValue(e, valueType, node, name, access, expected);
+  }
+}
+
+/** Validate a known-present value at `access` against `type`. */
+function emitValue(
+  e: Emit,
+  type: BoundType,
+  node: Expr | undefined,
+  wireKey: string,
+  access: string,
+  expected: string,
+): void {
+  switch (type.kind) {
+    case "optional":
+      emitValue(e, type.inner, node, wireKey, access, expected);
+      return;
+    case "literal":
+      return;
+    case "scalar":
+      switch (type.scalar) {
+        case "str":
+        case "path":
+          checkType(e, `typeof ${access} !== "string"`, wireKey, expected);
+          return;
+        case "int":
+        case "float":
+          checkType(e, `typeof ${access} !== "number"`, wireKey, expected);
+          emitRange(e, node, wireKey, access);
+          return;
+      }
+      return;
+    case "bool":
+      checkType(e, `typeof ${access} !== "boolean"`, wireKey, expected);
+      return;
+    case "count":
+      checkType(e, `typeof ${access} !== "number"`, wireKey, expected);
+      return;
+    case "list": {
+      checkType(e, `!Array.isArray(${access})`, wireKey, expected);
+      emitListLength(e, node, wireKey, access);
+      const itemNode = findRepeatNode(node)?.attrs.node;
+      const elem = e.scope.add("el");
+      e.cb.line(`for (const ${elem} of ${access}) {`);
+      e.cb.indent(() => emitValue(e, type.item, itemNode, wireKey, elem, expected));
+      e.cb.line("}");
+      return;
+    }
+    case "struct": {
+      block(e, `typeof ${access} !== "object" || ${access} === null`, () =>
+        raise(e, "Params object has the wrong type"),
+      );
+      for (const f of structFields(e.ctx, type, node)) {
+        emitField(e, f.name, f.type, f.node, f.hasDefault, access);
+      }
+      return;
+    }
+    case "union":
+      emitUnion(e, type, node, wireKey, access);
+      return;
+  }
+}
+
+function emitUnion(
+  e: Emit,
+  unionType: Extract<BoundType, { kind: "union" }>,
+  node: Expr | undefined,
+  wireKey: string,
+  access: string,
+): void {
+  const litVariants = unionType.variants.filter((v) => v.type.kind === "literal");
+  const hasStruct = unionType.variants.some((v) => v.type.kind === "struct");
+
+  // Pure enum/choice: no struct variants, just literal values (no `@type`).
+  if (!hasStruct) {
+    const values = litVariants.map(
+      (v) => (v.type as Extract<BoundType, { kind: "literal" }>).value,
+    );
+    const allStr = values.every((x) => typeof x === "string");
+    checkType(
+      e,
+      `typeof ${access} !== ${allStr ? '"string"' : '"number"'}`,
+      wireKey,
+      expectedType(e, unionType),
+    );
+    emitLiteralMembership(e, values, wireKey, access);
+    return;
+  }
+
+  const altNode = findAlternativeNode(node);
+  // Struct variants with their indices; throws if two share an `@type` (a
+  // duplicate-tagged variant is unreachable and a mypy `comparison-overlap` in
+  // the Python mirror - frontends must dodge duplicate tags before codegen).
+  // The index keeps each arm aligned with the IR `alts`.
+  const structVars = structVariants(unionType);
+  const emitStructArm = (): void => {
+    // `access` is known to be an object here.
+    block(e, `!("@type" in ${access})`, () => raise(e, "Params object is missing `@type`"));
+    const names = structVars
+      .map(({ variant }) => variant.name)
+      .filter((n): n is string => n !== undefined)
+      .map((n) => JSON.stringify(n));
+    // `.includes` rather than a `!==`-chain: the discriminant is a closed literal
+    // union and an exhaustive chain is rejected by TS as TS2367. It also leaves
+    // the union un-narrowed, so the `switch` dispatch below narrows it.
+    block(e, `![${names.join(", ")}].includes(${access}["@type"])`, () =>
+      raise(e, "Parameter `" + wireKey + "`s `@type` must be one of [" + names.join(", ") + "]"),
+    );
+    // `switch` (mirroring the cargs builder): each `case` narrows correctly,
+    // whereas an `if`/`else if` chain on `===` accumulates narrowing and TS
+    // rejects later arms.
+    e.cb.line(`switch (${access}["@type"]) {`);
+    e.cb.indent(() => {
+      structVars.forEach(({ variant, i }) => {
+        const vt = variant.type as Extract<BoundType, { kind: "struct" }>;
+        e.cb.line(`case ${JSON.stringify(variant.name ?? "")}: {`);
+        e.cb.indent(() => {
+          const fields = structFields(e.ctx, vt, altNode?.attrs.alts[i]).filter(
+            (f) => f.type.kind !== "literal",
+          );
+          for (const f of fields) emitField(e, f.name, f.type, f.node, f.hasDefault, access);
+          e.cb.line("break;");
+        });
+        e.cb.line("}");
+      });
+    });
+    e.cb.line("}");
+  };
+
+  // Pure discriminated union: every variant is a struct with an `@type`.
+  if (litVariants.length === 0) {
+    block(e, `typeof ${access} !== "object" || ${access} === null`, () =>
+      raise(e, "Params object has the wrong type"),
+    );
+    emitStructArm();
+    return;
+  }
+
+  // Mixed union: a value is either a struct (dict with `@type`) or a bare
+  // literal. Branch on the runtime shape - `typeof === "object"` narrows to the
+  // struct members, the `else` to the literal members.
+  e.cb.line(`if (typeof ${access} === "object" && ${access} !== null) {`);
+  e.cb.indent(emitStructArm);
+  e.cb.line(`} else {`);
+  e.cb.indent(() => {
+    const values = litVariants.map(
+      (v) => (v.type as Extract<BoundType, { kind: "literal" }>).value,
+    );
+    emitLiteralMembership(e, values, wireKey, access);
+  });
+  e.cb.line("}");
+}
+
+/** Emit a `.includes`-based membership check over literal values. */
+function emitLiteralMembership(
+  e: Emit,
+  values: (string | number)[],
+  wireKey: string,
+  access: string,
+): void {
+  const rendered = values.map(renderLiteral);
+  block(e, `![${rendered.join(", ")}].includes(${access})`, () =>
+    raise(e, "Parameter `" + wireKey + "` must be one of [" + rendered.join(", ") + "]"),
+  );
+}
+
+function checkType(e: Emit, condition: string, wireKey: string, expected: string): void {
+  block(e, condition, () =>
+    raise(e, "`" + wireKey + "` has the wrong type (expected " + expected + ")"),
+  );
+}
+
+function emitRange(e: Emit, node: Expr | undefined, wireKey: string, access: string): void {
+  const term = findRangeNode(node);
+  if (!term) return;
+  const { minValue, maxValue } = term.attrs;
+  if (minValue !== undefined && maxValue !== undefined) {
+    block(e, `!(${tsNum(minValue)} <= ${access} && ${access} <= ${tsNum(maxValue)})`, () =>
+      raise(e, `Parameter \`${wireKey}\` must be between ${minValue} and ${maxValue} (inclusive)`),
+    );
+  } else if (minValue !== undefined) {
+    block(e, `${access} < ${tsNum(minValue)}`, () =>
+      raise(e, `Parameter \`${wireKey}\` must be at least ${minValue}`),
+    );
+  } else if (maxValue !== undefined) {
+    block(e, `${access} > ${tsNum(maxValue)}`, () =>
+      raise(e, `Parameter \`${wireKey}\` must be at most ${maxValue}`),
+    );
+  }
+}
+
+function emitListLength(e: Emit, node: Expr | undefined, wireKey: string, access: string): void {
+  const rep = findRepeatNode(node);
+  if (!rep) return;
+  const { countMin, countMax } = rep.attrs;
+  if (countMin !== undefined && countMax !== undefined) {
+    block(e, `!(${countMin} <= ${access}.length && ${access}.length <= ${countMax})`, () =>
+      raise(
+        e,
+        `Parameter \`${wireKey}\` must contain between ${countMin} and ${countMax} elements (inclusive)`,
+      ),
+    );
+  } else if (countMin !== undefined) {
+    block(e, `${access}.length < ${countMin}`, () =>
+      raise(
+        e,
+        `Parameter \`${wireKey}\` must contain at least ${countMin} ${plural("element", countMin)}`,
+      ),
+    );
+  } else if (countMax !== undefined) {
+    block(e, `${access}.length > ${countMax}`, () =>
+      raise(
+        e,
+        `Parameter \`${wireKey}\` must contain at most ${countMax} ${plural("element", countMax)}`,
+      ),
+    );
+  }
+}
+
+// -- Emit helpers --
+
+/** Emit `if (<cond>) { <body> }`. */
+function block(e: Emit, condition: string, body: () => void): void {
+  e.cb.line(`if (${condition}) {`);
+  e.cb.indent(body);
+  e.cb.line("}");
+}
+
+function raise(e: Emit, message: string): void {
+  e.cb.line(`throw new StyxValidationError(${JSON.stringify(message)});`);
+}
+
+function expectedType(e: Emit, type: BoundType): string {
+  return mapType(type, e.resolve);
+}
+
+function renderLiteral(value: string | number): string {
+  return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+
+function tsNum(n: number): string {
+  return Number.isFinite(n) ? String(n) : "NaN";
+}
+
+function plural(word: string, count: number): string {
+  return count === 1 ? word : `${word}s`;
+}

package/src/backend/union-variants.ts

@@ -0,0 +1,42 @@
+import type { BoundType, BoundVariant } from "../bindings/index.js";
+
+/** A union's struct variant paired with its index into the union's `variants`
+ * array (which stays parallel to the IR `alts` and the per-arm results a caller
+ * builds, so the index must be threaded through). */
+export interface IndexedStructVariant {
+  variant: BoundVariant;
+  i: number;
+}
+
+/**
+ * The struct variants of a union, each with its index into `variants`.
+ *
+ * A discriminated union dispatches on a unique `@type`, so two struct variants
+ * sharing a tag are a malformed union: the second is unreachable at runtime and
+ * emits a dead branch (a mypy `comparison-overlap` in the Python backend's
+ * `if`/`elif` chain). Producing well-formed, unique-tagged unions is a frontend
+ * responsibility - the Boutiques frontend dodges duplicate sub-command ids
+ * (`orient` -> `orient_2`). This asserts that invariant at the backend boundary
+ * and throws if it is violated, rather than silently emitting a dead branch.
+ */
+export function structVariants(
+  unionType: Extract<BoundType, { kind: "union" }>,
+): IndexedStructVariant[] {
+  const seen = new Set<string>();
+  const out: IndexedStructVariant[] = [];
+  unionType.variants.forEach((variant, i) => {
+    if (variant.type.kind !== "struct") return;
+    const tag = variant.name ?? "";
+    if (seen.has(tag)) {
+      throw new Error(
+        `duplicate union variant @type ${JSON.stringify(tag)}: a discriminated ` +
+          `union dispatches on a unique @type, so a second variant with the same ` +
+          `tag is unreachable. Frontends must dodge duplicate variant tags before ` +
+          `codegen (the Boutiques frontend renames duplicate sub-command ids).`,
+      );
+    }
+    seen.add(tag);
+    out.push({ variant, i });
+  });
+  return out;
+}

package/src/backend/validate-walk.ts

@@ -0,0 +1,111 @@
+import type { BoundType } from "../bindings/index.js";
+import type { Expr, Float, Int, Repeat } from "../ir/index.js";
+import type { CodegenContext } from "../manifest/index.js";
+import { collectFieldInfo } from "./collect-field-info.js";
+import { findStructNode } from "./find-struct-node.js";
+import { resolveFieldBinding } from "./resolve-field-binding.js";
+
+/**
+ * Shared, language-agnostic tree-walk helpers for validation emit.
+ *
+ * Validation walks the solved root `BoundType` for the data shape, but the
+ * runtime constraints it checks (int/float range, list length) live on the
+ * underlying IR nodes, not the `BoundType`. These helpers bridge the two: they
+ * map a struct's fields to their IR binding nodes and locate the IR node that
+ * carries a given constraint within a field's subtree.
+ */
+
+/** A struct field paired with its BoundType and (when resolvable) its IR node. */
+export interface FieldEntry {
+  name: string;
+  type: BoundType;
+  /** The IR node the field's binding was solved from. `undefined` if it could
+   * not be resolved (constraint lookups then degrade gracefully). */
+  node: Expr | undefined;
+  /**
+   * Whether the field has a default value. Such fields (and flags) accept
+   * `None`/`null` to mean "use the default", so validation gates them like
+   * optionals rather than requiring presence - matching v1 niwrap.
+   */
+  hasDefault: boolean;
+}
+
+/**
+ * Enumerate a struct type's fields in declaration order, each paired with the
+ * IR node its binding resolved from. `searchRoot` is the IR subtree known to
+ * contain the struct (the root expr for the top-level struct, or a field /
+ * union-arm node for nested ones).
+ */
+export function structFields(
+  ctx: CodegenContext,
+  structType: Extract<BoundType, { kind: "struct" }>,
+  searchRoot: Expr | undefined,
+): FieldEntry[] {
+  const nodeByName = new Map<string, Expr>();
+  if (searchRoot) {
+    const structNode = findStructNode(searchRoot, ctx, structType);
+    if (structNode) {
+      for (const child of structNode.attrs.nodes) {
+        const match = resolveFieldBinding(child, ctx, structType);
+        if (match) nodeByName.set(match.binding.name, match.binding.node);
+      }
+    }
+  }
+  const fieldInfo = collectFieldInfo(ctx, structType);
+  return Object.entries(structType.fields).map(([name, type]) => ({
+    name,
+    type,
+    node: nodeByName.get(name),
+    hasDefault: fieldInfo.get(name)?.defaultValue !== undefined,
+  }));
+}
+
+/**
+ * Depth-first search for the first node satisfying `pred`, descending through
+ * the transparent structural wrappers the solver may bury a binding under
+ * (sequence/optional/repeat/alternative).
+ */
+export function findNode(node: Expr | undefined, pred: (n: Expr) => boolean): Expr | undefined {
+  if (!node) return undefined;
+  if (pred(node)) return node;
+  switch (node.kind) {
+    case "sequence":
+      for (const child of node.attrs.nodes) {
+        const r = findNode(child, pred);
+        if (r) return r;
+      }
+      return undefined;
+    case "optional":
+      return findNode(node.attrs.node, pred);
+    case "repeat":
+      return findNode(node.attrs.node, pred);
+    case "alternative":
+      for (const alt of node.attrs.alts) {
+        const r = findNode(alt, pred);
+        if (r) return r;
+      }
+      return undefined;
+    default:
+      return undefined;
+  }
+}
+
+/** Locate the int/float node carrying a scalar field's numeric range. */
+export function findRangeNode(node: Expr | undefined): Int | Float | undefined {
+  const found = findNode(node, (n) => n.kind === "int" || n.kind === "float");
+  return found as Int | Float | undefined;
+}
+
+/** Locate the repeat node carrying a list field's length bounds and item. */
+export function findRepeatNode(node: Expr | undefined): Repeat | undefined {
+  const found = findNode(node, (n) => n.kind === "repeat");
+  return found as Repeat | undefined;
+}
+
+/** Locate the alternative node backing a union field, to map arms to variants. */
+export function findAlternativeNode(
+  node: Expr | undefined,
+): Extract<Expr, { kind: "alternative" }> | undefined {
+  const found = findNode(node, (n) => n.kind === "alternative");
+  return found as Extract<Expr, { kind: "alternative" }> | undefined;
+}

package/src/bindings/binding.ts

@@ -0,0 +1,77 @@
+import type { Expr } from "../ir/index.js";
+import type { GateAtom } from "./resolved-output.js";
+import type { BoundType } from "./types.js";
+
+export type BindingId = string;
+
+/**
+ * One step in a binding's access path relative to top-level `params`.
+ *
+ * - `field`: descend into a named field of the enclosing struct scope. Renders
+ *   as `params.name` (TS) / `params["name"]` (Python).
+ * - `iter`: the access base resets to the per-element loop variable bound to
+ *   `binding` (a `repeat`-of-list). The renderer substitutes the active loop
+ *   variable at emit time (from the `iter` gate atom's loop, or the
+ *   arg-builder's local loop), so segments after an `iter` build off the
+ *   element rather than off `params`.
+ *
+ * There is deliberately no `variant` or `directValue` segment: complex-union
+ * variant fields are plain `field` segments off the union's own path (the
+ * `@type` discriminant lives in `GateAtom`, not the access path), and the
+ * solver's wrapper collapses (`optional<scalar>`, scalar lists) are expressed
+ * by a binding simply inheriting its parent wrapper's path.
+ */
+export type AccessSegment = { kind: "field"; name: string } | { kind: "iter"; binding: BindingId };
+
+/**
+ * A binding's location relative to top-level `params`, as a structured segment
+ * sequence. Computed once by the solver (`assignAccessPaths`) and rendered by
+ * each backend's `renderAccess`, so the arg-builder and outputs emitter share
+ * one source of truth instead of each re-deriving paths.
+ */
+export type AccessPath = AccessSegment[];
+
+export interface Binding {
+  id: BindingId;
+  node: Expr;
+  name: string;
+  type: BoundType;
+  /**
+   * Wrapper layers on the path from the root to this binding, root-to-leaf.
+   * Captures the optional/repeat/alternative ancestors as `present`/`iter`/
+   * `variant` atoms. Backends nest wrappers in array order; "is this binding
+   * conditionally active?" reduces to `gate.length > 0`.
+   */
+  gate: GateAtom[];
+  /**
+   * Access path relative to top-level `params`, assigned by the solver's
+   * `assignAccessPaths` pass after types settle. Backends render it via
+   * `renderAccess` rather than re-walking the IR to recompute where this
+   * binding lives.
+   */
+  access: AccessPath;
+}
+
+export type BindingRegistry = Map<BindingId, Binding>;
+
+export type OutputDiagnosticLevel = "error" | "warning";
+
+export interface OutputDiagnostic {
+  output: string;
+  message: string;
+  level: OutputDiagnosticLevel;
+}
+
+export interface OutputValidationResult {
+  errors: OutputDiagnostic[];
+  warnings: OutputDiagnostic[];
+}
+
+export interface SolveResult {
+  bindings: BindingRegistry;
+  resolve: (node: Expr) => Binding | undefined;
+}
+
+export function createRegistry(): BindingRegistry {
+  return new Map();
+}