@styx-api/core 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@styx-api/core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Styx compiler core: parses CLI tool descriptors (e.g. Boutiques), optimizes an IR, solves typed parameter bindings, and generates type-safe wrappers (TypeScript, Python, JSON Schema). Part of the Styx/NiWrap ecosystem.",
   "keywords": [
     "styx",
@@ -48,6 +48,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "fast-check": "^4.9.0",
     "rolldown": "1.0.0-rc.1",
     "styxdefs": "^0.2.0",
     "tsdown": "^0.20.1"

package/src/backend/argtype/__fixtures__/microsyntax.argtype

@@ -1,8 +1,6 @@
 ---
 exe: "cut"
 version: "9.0"
-extensions:
-  - mediatypes
 ---
 
 /// Cut fields from each line, exercising join micro-syntax and media types

package/src/backend/argtype/emit.ts

@@ -191,34 +191,6 @@ function syntheticWrap(root: Expr): { child: Expr; outputs?: Output[] } | undefi
   return { child, ...(meta?.outputs && { outputs: meta.outputs }) };
 }
 
-function hasOutputs(expr: Expr): boolean {
-  return walkSome(expr, (n) => (n.meta?.outputs?.length ?? 0) > 0);
-}
-
-function hasMediaTypes(expr: Expr): boolean {
-  return walkSome(expr, (n) => n.kind === "path" && (n.attrs.mediaTypes?.length ?? 0) > 0);
-}
-
-function hasPaths(expr: Expr): boolean {
-  return walkSome(expr, (n) => n.kind === "path" && (!!n.attrs.mutable || !!n.attrs.resolveParent));
-}
-
-function walkSome(node: Expr, pred: (n: Expr) => boolean): boolean {
-  if (pred(node)) return true;
-  switch (node.kind) {
-    case "sequence":
-      return node.attrs.nodes.some((n) => walkSome(n, pred));
-    case "alternative":
-      return node.attrs.alts.some((n) => walkSome(n, pred));
-    case "optional":
-      return walkSome(node.attrs.node, pred);
-    case "repeat":
-      return walkSome(node.attrs.node, pred);
-    default:
-      return false;
-  }
-}
-
 const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 /** A name rendered where an identifier is expected: bare when it is a valid
@@ -342,13 +314,7 @@ class ArgtypeEmitter {
       if (raw.meta) root.meta = raw.meta;
     }
 
-    const frontmatter = this.emitFrontmatter(
-      app,
-      exe,
-      hasOutputs(root),
-      hasMediaTypes(root),
-      hasPaths(root),
-    );
+    const frontmatter = this.emitFrontmatter(app, exe);
     if (frontmatter) {
       lines.push(frontmatter, "");
     }
@@ -641,13 +607,7 @@ class ArgtypeEmitter {
     return quote(value);
   }
 
-  private emitFrontmatter(
-    app: AppMeta | undefined,
-    exe: string | undefined,
-    outputs: boolean,
-    mediaTypes: boolean,
-    paths: boolean,
-  ): string | undefined {
+  private emitFrontmatter(app: AppMeta | undefined, exe: string | undefined): string | undefined {
     const lines: string[] = [];
 
     // `exe` is the executable stripped from the command (argv[0]); emit it only
@@ -690,15 +650,6 @@ class ArgtypeEmitter {
       }
     }
 
-    const extensions: string[] = [];
-    if (outputs) extensions.push("outputs");
-    if (mediaTypes) extensions.push("mediatypes");
-    if (paths) extensions.push("paths");
-    if (extensions.length > 0) {
-      lines.push("extensions:");
-      for (const e of extensions) lines.push(`  - ${e}`);
-    }
-
     if (lines.length === 0) return undefined;
     return ["---", ...lines, "---"].join("\n");
   }

package/src/backend/boutiques/boutiques.ts

@@ -404,28 +404,20 @@ class BoutiquesEmitter {
         wrapperNode,
       );
 
-      // Add flag to command line if present, then value-key
-      if (peeled.flag) {
-        if (
-          fieldType.kind === "bool" ||
-          (fieldType.kind === "optional" && this.isBool(fieldType))
-        ) {
-          // Bool flags: the value-key IS the flag
-          commandParts.push(valueKeyStr);
-        } else {
-          // Value flags: flag then value-key as separate args
-          commandParts.push(valueKeyStr);
-        }
-      } else {
-        commandParts.push(valueKeyStr);
-      }
+      // The value-key alone: a peeled flag rides on the input's
+      // `command-line-flag`, and Boutiques renders it ahead of the value.
+      commandParts.push(valueKeyStr);
 
       inputs.push(input);
     }
 
     bt["command-line"] = commandParts.join(" ");
     bt.inputs = inputs;
-    this.emitOutputFiles(bt, expr, valueKeyByBinding, idScope);
+    // Resolve the output scope from `structNode` (which carries `meta.outputs`
+    // and is what the solver keyed the outputs under), not `expr`: for a plain
+    // or list subcommand `findStructNode` descends past `expr`, so resolving from
+    // `expr` would miss the bucket and silently drop the subcommand's outputs.
+    this.emitOutputFiles(bt, structNode, valueKeyByBinding, idScope);
   }
 
   // Emit `output-files` entries declared on this struct binding. `optional`
@@ -579,6 +571,7 @@ class BoutiquesEmitter {
   // had to fall back to String.
   private finalizeInput(input: BtInput): void {
     if (input.name === undefined) input.name = input.id;
+    this.finalizeSubDescriptors(input);
 
     // A String with a bool default and no choices is really a Flag.
     if (
@@ -624,6 +617,24 @@ class BoutiquesEmitter {
     this.mergeDefaultIntoDescription(input);
   }
 
+  // A sub-descriptor used as an input `type` needs an `id`: it is required by
+  // the schema, and for union variants it doubles as the `@type` discriminator.
+  // Anonymous IR nodes (a struct the frontend never named) leave it unset, so
+  // fall back to the owning input's id, which is already unique in this scope.
+  private finalizeSubDescriptors(input: BtInput): void {
+    const type = input.type;
+    if (Array.isArray(type)) {
+      type.forEach((sub, i) => this.ensureSubDescriptorId(sub, `${input.id}_${i + 1}`));
+    } else if (typeof type === "object" && type !== null) {
+      this.ensureSubDescriptorId(type, input.id);
+    }
+  }
+
+  private ensureSubDescriptorId(sub: BtDescriptor, fallback: string): void {
+    if (sub.id === undefined) sub.id = this.sanitizeId(fallback);
+    if (sub.name === undefined) sub.name = sub.id;
+  }
+
   // Peel wrapper layers from an IR node to extract Boutiques input properties.
   // Walks from outermost to innermost, detecting optional/repeat/flag patterns.
   private peelNode(node: Expr, type: BoundType): PeeledInput {
@@ -652,6 +663,23 @@ class BoutiquesEmitter {
         break;
 
       case "sequence": {
+        // Two shapes both present as `seq(lit, x)` with a struct-typed field,
+        // and only the node tells them apart:
+        //
+        //   struct body    seq(lit("--cifti-output"), optional(choice))
+        //     - the literal is the sub-descriptor's own `command-line`, which
+        //       `buildFromStruct` serializes by walking these same children.
+        //       Peeling it would emit it twice.
+        //   flag wrapper   seq(lit("-i"), seq(fixed, moving))
+        //     - the struct body is `nodes[1]`; the literal is outside it and
+        //       nothing else serializes it. Not peeling it would drop it.
+        //
+        // `findStructNode` returns the body, so identity separates the cases.
+        const structType = this.unwrapType(type);
+        if (structType.kind === "struct" && findStructNode(node, this.ctx, structType) === node) {
+          break;
+        }
+
         // Detect flag pattern: seq(lit(flag), inner)
         const nodes = node.attrs.nodes;
         if (nodes.length === 2 && nodes[0]!.kind === "literal") {
@@ -820,14 +848,9 @@ class BoutiquesEmitter {
       };
     }
 
-    // All-struct union -> SubCommandUnion
-    const allStruct = type.variants.every((v: BoundVariant) => v.type.kind === "struct");
-    if (allStruct) {
-      return { type: this.buildSubCommandUnion(type, node) };
-    }
-
-    // Mixed union -> wrap each variant as a SubCommand descriptor
-    return { type: this.buildMixedUnionAsSubCommands(type, node) };
+    // Any other union (all-struct or mixed) -> one SubCommand descriptor per
+    // variant: struct arms serialize recursively, non-struct arms are wrapped.
+    return { type: this.buildUnionSubCommands(type, node) };
   }
 
   private buildSubCommand(type: Extract<BoundType, { kind: "struct" }>, node: Expr): BtDescriptor {
@@ -844,29 +867,10 @@ class BoutiquesEmitter {
     return bt;
   }
 
-  private buildSubCommandUnion(
-    type: Extract<BoundType, { kind: "union" }>,
-    node: Expr,
-  ): BtDescriptor[] {
-    const alts = node.kind === "alternative" ? node.attrs.alts : [node];
-
-    return type.variants.map((variant: BoundVariant, i: number) => {
-      const altNode = alts[i] ?? node;
-      if (variant.type.kind === "struct") {
-        const bt = this.buildSubCommand(variant.type, altNode);
-        // The variant has its own name; the wrapperNode's name is the
-        // parent (mutex group) name and would otherwise leak down.
-        if (variant.name) {
-          bt.name = variant.name;
-          bt.id = this.sanitizeId(variant.name);
-        }
-        return bt;
-      }
-      return this.wrapAsDescriptor(variant, altNode);
-    });
-  }
-
-  private buildMixedUnionAsSubCommands(
+  // One SubCommand descriptor per union variant. Handles both all-struct and
+  // mixed unions: struct arms serialize recursively, non-struct arms are wrapped
+  // as a trivial single-input descriptor.
+  private buildUnionSubCommands(
     type: Extract<BoundType, { kind: "union" }>,
     node: Expr,
   ): BtDescriptor[] {
@@ -1012,6 +1016,10 @@ class BoutiquesEmitter {
       type: subBt,
       list: true,
       minListEntries: countMin,
+      // A count that tolerates zero occurrences may be omitted entirely.
+      // Without this, Boutiques defaults `optional` to false and rejects an
+      // invocation that leaves the flag out. Mirrors the bounded path above.
+      ...(countMin === 0 && { optional: true }),
     };
   }
 }

package/src/backend/field-defaults.ts

@@ -0,0 +1,40 @@
+import type { Binding, BoundType } from "../bindings/index.js";
+import type { CodegenContext } from "../manifest/index.js";
+import { collectFieldInfo } from "./collect-field-info.js";
+
+/** Renders a default value as a target-language literal. */
+export type RenderLiteral = (value: string | number | boolean) => string;
+
+/**
+ * Build the field-name -> rendered-default map for a struct root (else empty).
+ * Includes only non-optional defaulted fields (optional fields are
+ * presence-guarded; their default comes from the factory's kwarg signature).
+ *
+ * `rootType` defaults to the resolved root type; callers that already have it
+ * (the arg-builders) pass it to avoid re-resolving.
+ */
+export function collectDefaults(
+  ctx: CodegenContext,
+  renderLiteral: RenderLiteral,
+  rootType: BoundType | undefined = ctx.resolve(ctx.expr)?.type,
+): Map<string, string> {
+  const out = new Map<string, string>();
+  if (rootType?.kind !== "struct") return out;
+  for (const [name, fi] of collectFieldInfo(ctx, rootType)) {
+    if (fi.defaultValue === undefined) continue;
+    if (rootType.fields[name]?.kind === "optional") continue;
+    out.set(name, renderLiteral(fi.defaultValue));
+  }
+  return out;
+}
+
+/** The rendered default for a binding iff it is a root-level defaulted field. */
+export function rootFieldDefault(
+  binding: Binding | undefined,
+  defaults: ReadonlyMap<string, string>,
+): string | undefined {
+  if (!binding) return undefined;
+  const a = binding.access;
+  if (a.length === 1 && a[0]?.kind === "field") return defaults.get(binding.name);
+  return undefined;
+}

package/src/backend/find-struct-node.ts

@@ -24,6 +24,13 @@ export function findStructNode(
   ctx: CodegenContext,
   structType: Extract<BoundType, { kind: "struct" }>,
 ): Extract<Expr, { kind: "sequence" }> | undefined {
+  // An empty struct (no fields) has no field bindings to match, but it is still a
+  // real scope: a parameterless output-bearing command like `seq(lit("run"))`
+  // with an output-file. Its scope node is simply the sequence carrying it, so a
+  // backend can emit the (field-less) command line and its outputs.
+  if (node.kind === "sequence" && Object.keys(structType.fields).length === 0) {
+    return node;
+  }
   switch (node.kind) {
     case "sequence": {
       // Phase 1: Check if any direct child has a binding matching a struct field

package/src/backend/index.ts

@@ -22,15 +22,7 @@ export { generateNipype, NipypeBackend, nipypeNames } from "./nipype/index.js";
 export type { PydraNames } from "./pydra/index.js";
 export { generatePydra, PydraBackend, pydraNames } from "./pydra/index.js";
 export { resolveFieldBinding } from "./resolve-field-binding.js";
-export type { OutputEmitPlan } from "./resolve-output-tokens.js";
-export {
-  compactTokens,
-  isGated,
-  isIterated,
-  outputGate,
-  planOutput,
-  planScope,
-} from "./resolve-output-tokens.js";
+export { outputGate } from "./resolve-output-tokens.js";
 export { buildEmitModel, generatePython, PythonBackend, renderPythonCall } from "./python/index.js";
 export { Scope } from "./scope.js";
 export type { JsonSchema } from "./schema/index.js";

package/src/backend/nipype/emit.ts

@@ -116,11 +116,19 @@ export function renderInputTrait(p: TypedParam): string {
       ]);
     case "enum": {
       const choices = p.choices ?? [];
-      // nipype's first Enum arg is the default; put the styx default first.
-      const ordered = hasDef ? [def!, ...choices.filter((c) => c !== def)] : choices;
+      // nipype's first Enum arg is the default; put the styx default first, but
+      // only when it is actually one of the choices - prepending an out-of-spec
+      // default would silently widen the allowed set. (Enum choices are never
+      // booleans, so a boolean default can't be one.)
+      const defChoice =
+        hasDef && def !== undefined && typeof def !== "boolean" && choices.includes(def)
+          ? def
+          : undefined;
+      const ordered =
+        defChoice !== undefined ? [defChoice, ...choices.filter((c) => c !== defChoice)] : choices;
       return call("traits.Enum", [
         ...ordered.map((c) => renderPyLiteral(c)),
-        ...(hasDef ? ["usedefault=True"] : []),
+        ...(defChoice !== undefined ? ["usedefault=True"] : []),
         ...tail,
       ]);
     }

package/src/backend/python/arg-builder.ts

@@ -1,5 +1,5 @@
 import type { Binding, BindingId, BoundType, BoundVariant } from "../../bindings/index.js";
-import { collectFieldInfo } from "../collect-field-info.js";
+import { collectDefaults, rootFieldDefault } from "../field-defaults.js";
 import type { Expr } from "../../ir/index.js";
 import type { CodegenContext } from "../../manifest/index.js";
 import { CodeBuilder } from "../code-builder.js";
@@ -97,15 +97,6 @@ interface ArgContext {
  * carrying a Boutiques default. Restricted to single-segment (root) field access
  * so a nested field can never accidentally pick up a same-named root default.
  */
-function rootFieldDefault(
-  binding: Binding,
-  defaults: ReadonlyMap<string, string>,
-): string | undefined {
-  const a = binding.access;
-  if (a.length === 1 && a[0]?.kind === "field") return defaults.get(binding.name);
-  return undefined;
-}
-
 /**
  * Render a binding's access for an UNCONDITIONAL value read (terminal, repeat
  * loop, alternative dispatch): substitutes the field's default via
@@ -145,22 +136,6 @@ function accessOf(binding: Binding, arg: ArgContext, opts: AccessOpts = {}): str
   );
 }
 
-/**
- * Build the field-name -> rendered-default map for a struct root (else empty).
- * Includes only non-optional defaulted fields (optional fields are
- * presence-guarded; their default comes from the factory's kwarg signature).
- */
-function collectDefaults(ctx: CodegenContext, rootType?: BoundType): Map<string, string> {
-  const out = new Map<string, string>();
-  if (rootType?.kind !== "struct") return out;
-  for (const [name, fi] of collectFieldInfo(ctx, rootType)) {
-    if (fi.defaultValue === undefined) continue;
-    if (rootType.fields[name]?.kind === "optional") continue;
-    out.set(name, renderPyLiteral(fi.defaultValue));
-  }
-  return out;
-}
-
 // -- Recursive descent --
 
 let loopVarCounter = 0;
@@ -179,7 +154,7 @@ export function buildArgs(rootExpr: Expr, ctx: CodegenContext, rootType?: BoundT
     joinDepth: 0,
     loopVars: new Map(),
     valueSubst: new Map(),
-    defaults: collectDefaults(ctx, rootType),
+    defaults: collectDefaults(ctx, renderPyLiteral, rootType),
   };
   return walk(rootExpr, ctx, initialCtx);
 }

package/src/backend/python/emit.ts

@@ -17,8 +17,13 @@ import { collectFieldInfo, resolveTypeName } from "./types.js";
  */
 export function emitDocstring(cb: CodeBuilder, text?: string): void {
   if (!text) return;
-  const lines = text.split("\n");
-  if (lines.length === 1 && !lines[0]!.includes('"')) {
+  // Escape embedded triple-quotes so a `"""` in the text can't close the
+  // docstring early.
+  const escaped = text.replace(/"""/g, '\\"\\"\\"');
+  const lines = escaped.split("\n");
+  // Single-line form only when safe: no embedded quote, and no trailing
+  // backslash (which would escape the closing quotes, e.g. `"""x\"""`).
+  if (lines.length === 1 && !lines[0]!.includes('"') && !lines[0]!.endsWith("\\")) {
     cb.line(`"""${lines[0]}"""`);
     return;
   }
@@ -27,13 +32,20 @@ export function emitDocstring(cb: CodeBuilder, text?: string): void {
   cb.line(`"""`);
 }
 
-export function emitImports(cb: CodeBuilder, emitOutputs: boolean): void {
-  cb.line("import dataclasses");
+export function emitImports(cb: CodeBuilder): void {
   cb.line("import pathlib");
   cb.line("import typing");
   cb.blank();
-  const fromStyxdefs = ["Execution", "InputPathType", "Metadata", "Runner", "StyxValidationError"];
-  if (emitOutputs) fromStyxdefs.push("OutputPathType");
+  // Every tool emits an Outputs object, so OutputPathType is always needed.
+  // (Kept last to preserve the previously emitted import order.)
+  const fromStyxdefs = [
+    "Execution",
+    "InputPathType",
+    "Metadata",
+    "Runner",
+    "StyxValidationError",
+    "OutputPathType",
+  ];
   cb.line(`from styxdefs import ${fromStyxdefs.join(", ")}, get_global_runner`);
 }
 

package/src/backend/python/outputs-emit.ts

@@ -1,12 +1,6 @@
-import type {
-  Binding,
-  BindingId,
-  BoundType,
-  GateAtom,
-  ResolvedToken,
-} from "../../bindings/index.js";
+import type { BindingId, BoundType, GateAtom, ResolvedToken } from "../../bindings/index.js";
 import { outputGate } from "../../bindings/index.js";
-import { collectFieldInfo } from "../collect-field-info.js";
+import { collectDefaults, rootFieldDefault } from "../field-defaults.js";
 import type { CodegenContext } from "../../manifest/index.js";
 import { CodeBuilder } from "../code-builder.js";
 import {
@@ -17,6 +11,7 @@ import {
   rootOutput,
   streamFields,
 } from "../collect-output-fields.js";
+import { unionIsMixed, variantAtomUnion } from "../union-variants.js";
 import { PY_KEYWORDS, emitDocstring } from "./emit.js";
 import { pyStr, renderAccess, renderPyLiteral } from "./typemap.js";
 
@@ -40,10 +35,11 @@ export function streamFieldIds(ctx: CodegenContext): { stdout?: string; stderr?:
   return res;
 }
 
-/** Emit `@dataclasses.dataclass\nclass <outputsType>:` declaration. */
+/** Emit `class <outputsType>(typing.NamedTuple):` declaration. */
 export function emitOutputsClass(ctx: CodegenContext, outputsType: string, cb: CodeBuilder): void {
-  cb.line("@dataclasses.dataclass");
-  cb.line(`class ${outputsType}:`);
+  // A NamedTuple (not a dataclass) matches the styx1 / NiWrap convention: outputs
+  // are an immutable, tuple-shaped result built once from keyword args.
+  cb.line(`class ${outputsType}(typing.NamedTuple):`);
   cb.indent(() => {
     emitDocstring(cb, "Output paths produced by the tool.");
     const fields = collectOutputFields(ctx, pyId);
@@ -89,32 +85,6 @@ interface OutputEmitCtx {
   defaults: ReadonlyMap<string, string>;
 }
 
-/** The rendered default for a binding iff it is a root-level defaulted field. */
-function rootFieldDefault(
-  binding: Binding | undefined,
-  defaults: ReadonlyMap<string, string>,
-): string | undefined {
-  if (!binding) return undefined;
-  const a = binding.access;
-  if (a.length === 1 && a[0]?.kind === "field") return defaults.get(binding.name);
-  return undefined;
-}
-
-/** Build the field-name -> rendered-default map for the struct root (else empty).
- * Includes only non-optional defaulted fields (optional fields are
- * presence-guarded; their default comes from the factory's kwarg signature). */
-function collectDefaults(ctx: CodegenContext): Map<string, string> {
-  const out = new Map<string, string>();
-  const rootType = ctx.resolve(ctx.expr)?.type;
-  if (rootType?.kind !== "struct") return out;
-  for (const [name, fi] of collectFieldInfo(ctx, rootType)) {
-    if (fi.defaultValue === undefined) continue;
-    if (rootType.fields[name]?.kind === "optional") continue;
-    out.set(name, renderPyLiteral(fi.defaultValue));
-  }
-  return out;
-}
-
 interface WrapperRender {
   open: string;
   loopVar?: string;
@@ -134,7 +104,17 @@ function renderWrapperOpen(atom: GateAtom, ec: OutputEmitCtx): WrapperRender {
   }
   if (atom.kind === "variant") {
     const access = bindingAccess(atom.binding, ec);
-    return { open: `if ${access}["@type"] == ${pyStr(atom.variant)}:` };
+    const check = `${access}["@type"] == ${pyStr(atom.variant)}`;
+    // A mixed union (`Literal[0] | Struct`) only carries `@type` on its struct
+    // arms; guard on the dict shape first so mypy narrows off the bare-literal
+    // arm before the subscript (which would otherwise be a non-indexable type
+    // error, and a runtime KeyError on the literal). Mirrors the cargs builder
+    // and validator. Pure-struct unions are always indexable - no guard needed.
+    const union = variantAtomUnion(atom, ec.ctx.bindings);
+    if (union && unionIsMixed(union)) {
+      return { open: `if isinstance(${access}, dict) and ${check}:` };
+    }
+    return { open: `if ${check}:` };
   }
   // present
   const binding = ec.ctx.bindings.get(atom.binding);
@@ -339,7 +319,7 @@ export function emitBuildOutputs(
       ctx,
       iter: new Map(),
       subst: new Map(),
-      defaults: collectDefaults(ctx),
+      defaults: collectDefaults(ctx, renderPyLiteral),
     };
 
     const fields = collectOutputFields(ctx, pyId);
@@ -393,11 +373,16 @@ export function emitBuildOutputs(
   });
 }
 
-/** Sanitize an output name to a valid Python identifier. */
+/**
+ * Sanitize an output name to a valid Python identifier. Uses a *letter*-leading
+ * prefix (`v_`) for digit-leading / empty names, never a leading underscore:
+ * the Outputs type is a `typing.NamedTuple`, which raises `ValueError` at import
+ * time for a field whose name starts with `_`. Matches styx1 and `pyScrubIdent`.
+ * (A trailing underscore for keywords is fine - only leading underscores fail.)
+ */
 export function pyId(name: string): string {
   let s = name.replace(/[^a-zA-Z0-9_]/g, "_");
-  if (/^\d/.test(s)) s = "_" + s;
-  if (s === "") s = "_";
+  if (/^\d/.test(s) || s === "") s = "v_" + s;
   if (PY_KEYWORDS.has(s)) s = s + "_";
   return s;
 }