@styx-api/core 0.6.1 → 0.8.0

package/src/backend/resolve-output-tokens.ts

@@ -1,80 +1,4 @@
-import type {
-  BindingRegistry,
-  GateAtom,
-  OutputScope,
-  ResolvedOutput,
-  ResolvedToken,
-} from "../bindings/index.js";
 import { outputGate } from "../bindings/index.js";
 
 // Re-export the core helper so backends have a single entry point.
 export { outputGate };
-
-/**
- * Compact consecutive literal tokens. Backends that emit string concatenation
- * benefit from a shorter token stream; backends that template each token
- * individually can ignore this and use `output.tokens` directly.
- */
-export function compactTokens(tokens: ResolvedToken[]): ResolvedToken[] {
-  const out: ResolvedToken[] = [];
-  for (const tok of tokens) {
-    const last = out[out.length - 1];
-    if (tok.kind === "literal" && last && last.kind === "literal") {
-      out[out.length - 1] = { kind: "literal", value: last.value + tok.value };
-    } else {
-      out.push(tok);
-    }
-  }
-  return out;
-}
-
-/**
- * One output ready for codegen. `gate` is the wrapper sequence (outermost
- * first); the backend renders each atom as the appropriate scope-introducing
- * statement, then emits the path expression inside the innermost layer.
- */
-export interface OutputEmitPlan {
-  name: string;
-  gate: GateAtom[];
-  tokens: ResolvedToken[];
-  resolved: ResolvedOutput;
-}
-
-export function planOutput(
-  scopeGate: GateAtom[],
-  output: ResolvedOutput,
-  bindings: BindingRegistry,
-): OutputEmitPlan {
-  return {
-    name: output.name,
-    gate: outputGate(scopeGate, output, bindings),
-    tokens: compactTokens(output.tokens),
-    resolved: output,
-  };
-}
-
-/**
- * Does the output have any conditional wrapper? Equivalent to "is at least one
- * atom a `present` or `variant`?". `iter` alone means the output emits a list
- * and is not conditionally absent.
- */
-export function isGated(plan: OutputEmitPlan): boolean {
-  return plan.gate.some((a) => a.kind === "present" || a.kind === "variant");
-}
-
-/** Does the output iterate (emit zero-or-more values)? */
-export function isIterated(plan: OutputEmitPlan): boolean {
-  return plan.gate.some((a) => a.kind === "iter");
-}
-
-/**
- * Convenience for backends emitting all outputs of a scope at once. The caller
- * provides the scope's gate (typically `bindings.get(scope.scope)?.gate ?? []`).
- */
-export function planScope(
-  scope: OutputScope,
-  scopeGate: GateAtom[],
-  bindings: BindingRegistry,
-): OutputEmitPlan[] {
-  return scope.outputs.map((output) => planOutput(scopeGate, output, bindings));
-}

package/src/backend/typescript/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";
@@ -92,14 +92,6 @@ function accessOf(binding: Binding, arg: ArgContext): string {
  * 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
@@ -113,20 +105,6 @@ function readAccess(binding: Binding, arg: ArgContext): string {
   return def !== undefined ? `(${accessOf(binding, arg)} ?? ${def})` : accessOf(binding, arg);
 }
 
-/** 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, renderTsLiteral(fi.defaultValue));
-  }
-  return out;
-}
-
 // -- Recursive descent --
 
 let loopVarCounter = 0;
@@ -142,7 +120,7 @@ export function buildArgs(rootExpr: Expr, ctx: CodegenContext, rootType?: BoundT
   const initialCtx: ArgContext = {
     joinDepth: 0,
     loopVars: new Map(),
-    defaults: collectDefaults(ctx, rootType),
+    defaults: collectDefaults(ctx, renderTsLiteral, rootType),
   };
   return walk(rootExpr, ctx, initialCtx);
 }

package/src/backend/typescript/emit.ts

@@ -10,7 +10,10 @@ import { collectFieldInfo, resolveTypeName } from "./types.js";
 
 export function emitJsDoc(cb: CodeBuilder, description?: string): void {
   if (!description) return;
-  const lines = description.split("\n");
+  // Escape `*/` so a description containing it can't terminate the block comment
+  // early (`*\/` is not a comment terminator; the backslash is inert in comments).
+  const safe = description.replace(/\*\//g, "*\\/");
+  const lines = safe.split("\n");
   if (lines.length === 1) {
     cb.line(`/** ${lines[0]} */`);
   } else {
@@ -22,9 +25,9 @@ export function emitJsDoc(cb: CodeBuilder, description?: string): void {
   }
 }
 
-export function emitImports(cb: CodeBuilder, emitOutputs: boolean): void {
-  const inputs = ["Runner", "Execution", "Metadata", "InputPathType"];
-  if (emitOutputs) inputs.push("OutputPathType");
+export function emitImports(cb: CodeBuilder): void {
+  // Every tool emits an Outputs object, so OutputPathType is always needed.
+  const inputs = ["Runner", "Execution", "Metadata", "InputPathType", "OutputPathType"];
   cb.line(`import type { ${inputs.join(", ")} } from "styxdefs";`);
   cb.line('import { getGlobalRunner, StyxValidationError } from "styxdefs";');
 }

package/src/backend/typescript/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 {
@@ -18,6 +12,7 @@ import {
   rootOutput,
   streamFields,
 } from "../collect-output-fields.js";
+import { unionIsMixed, variantAtomUnion } from "../union-variants.js";
 import { emitJsDoc, renderAccess, tsPropAccess } from "./emit.js";
 import { renderTsLiteral } from "./typemap.js";
 
@@ -97,32 +92,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, renderTsLiteral(fi.defaultValue));
-  }
-  return out;
-}
-
 /**
  * Render one output's wrapper stack and emit the assignment inside the
  * innermost wrapper. Nesting is done via recursive callbacks so the
@@ -201,10 +170,17 @@ function renderWrapperOpen(atom: GateAtom, ec: OutputEmitCtx): WrapperRender {
   }
   if (atom.kind === "variant") {
     const access = bindingAccess(atom.binding, ec);
-    return {
-      open: `if (${access}["@type"] === ${JSON.stringify(atom.variant)}) {`,
-      close: `}`,
-    };
+    const check = `${access}["@type"] === ${JSON.stringify(atom.variant)}`;
+    // A mixed union (`0 | Struct`) only carries `@type` on its struct arms; guard
+    // on the object shape first so TS narrows off the bare-literal arm before the
+    // subscript (which would otherwise be a "property does not exist" error).
+    // Mirrors the cargs builder and validator. Pure-struct unions need no guard.
+    const union = variantAtomUnion(atom, ec.ctx.bindings);
+    const cond =
+      union && unionIsMixed(union)
+        ? `typeof ${access} === "object" && ${access} !== null && ${check}`
+        : check;
+    return { open: `if (${cond}) {`, close: `}` };
   }
   // present
   const binding = ec.ctx.bindings.get(atom.binding);
@@ -321,7 +297,7 @@ export function emitBuildOutputs(
       ctx,
       iter: new Map(),
       fieldShapes: new Map(fields.map((f) => [f.id, f.shape])),
-      defaults: collectDefaults(ctx),
+      defaults: collectDefaults(ctx, renderTsLiteral),
     };
 
     // Initialize the outputs object with defaults so wrapper code can assign or

package/src/backend/typescript/typemap.ts

@@ -1,5 +1,13 @@
 import type { BoundType } from "../../bindings/index.js";
 
+// A valid TS identifier can be an unquoted object key; anything else (e.g. a
+// wire key like `4d_input`) must be quoted. Kept local to avoid a cycle with
+// emit.ts (which imports this module).
+const TS_IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function objKey(key: string): string {
+  return TS_IDENT_RE.test(key) ? key : JSON.stringify(key);
+}
+
 export function mapType(type: BoundType, resolve: (type: BoundType) => string | undefined): string {
   switch (type.kind) {
     case "scalar":
@@ -27,7 +35,7 @@ export function mapType(type: BoundType, resolve: (type: BoundType) => string |
       if (name) return name;
       const fields = Object.entries(type.fields)
         .filter(([, v]) => v.kind !== "literal")
-        .map(([k, v]) => `${k}: ${mapType(v, resolve)}`)
+        .map(([k, v]) => `${objKey(k)}: ${mapType(v, resolve)}`)
         .join("; ");
       return `{ ${fields} }`;
     }

package/src/backend/typescript/typescript.ts

@@ -256,6 +256,19 @@ export function buildEmitModel(
 }
 
 export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): string {
+  return generateTypeScriptModule(ctx, packageScope).code;
+}
+
+/**
+ * Emit the module and, alongside it, the dispatch entrypoint carrying the
+ * *scope-registered* execute-function name. Computing the entrypoint here (not
+ * via the scope-blind `appEntrypoint`) keeps the suite dispatcher in sync with
+ * the actual emitted symbol when a shared package scope suffix-bumps a collision.
+ */
+function generateTypeScriptModule(
+  ctx: CodegenContext,
+  packageScope?: Scope,
+): { code: string; entrypoint: AppEntrypoint | undefined } {
   const cb = new CodeBuilder("  ");
   // A package-shared scope keeps top-level names unique across every tool in the
   // suite barrel; without one (standalone emit) a per-tool scope is enough.
@@ -282,9 +295,7 @@ export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): s
   // Every tool emits an Outputs object: at minimum the synthetic `root` output
   // directory (outputFile(".")), plus any declared file/mutable outputs and
   // stdout/stderr stream fields. OutputPathType is therefore always imported.
-  const emitOutputs = true;
-
-  emitImports(cb, true);
+  emitImports(cb);
   cb.blank();
 
   emitMetadata(ctx, names.metadata, cb);
@@ -292,12 +303,10 @@ export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): s
 
   emitTypeDeclarations(typeDecls, namedTypes, ctx, names.params, appId, pkg, cb);
 
-  if (emitOutputs) {
-    emitOutputsInterface(ctx, names.outputs, cb);
-    cb.blank();
-  }
+  emitOutputsInterface(ctx, names.outputs, cb);
+  cb.blank();
 
-  if (emitOutputs && needsStripExtensionsHelper(ctx)) {
+  if (needsStripExtensionsHelper(ctx)) {
     emitStripExtensionsHelper(cb);
     cb.blank();
   }
@@ -327,10 +336,8 @@ export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): s
   emitBuildCargs(ctx, rootType, paramsType, names.cargs, cb);
   cb.blank();
 
-  if (emitOutputs) {
-    emitBuildOutputs(ctx, paramsType, names.outputs, names.outputsFn, cb);
-    cb.blank();
-  }
+  emitBuildOutputs(ctx, paramsType, names.outputs, names.outputsFn, cb);
+  cb.blank();
 
   // Dict-style execute function. For struct roots it's the internal
   // `<tool>Execute`; for other roots it doubles as the user-facing wrapper.
@@ -341,8 +348,8 @@ export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): s
     executeName,
     names.metadata,
     names.cargs,
-    emitOutputs ? names.outputsFn : undefined,
-    emitOutputs ? names.outputs : undefined,
+    names.outputsFn,
+    names.outputs,
     names.validate,
     streamFieldIds(ctx),
     cb,
@@ -357,13 +364,24 @@ export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): s
       names.wrapper,
       names.paramsFn,
       names.execute,
-      emitOutputs ? names.outputs : undefined,
+      names.outputs,
       cb,
     );
     cb.blank();
   }
 
-  return cb.toString();
+  // `executeName` is the scope-registered symbol actually emitted above, so the
+  // dispatcher references the real name even after a collision suffix-bump. Guard
+  // on `ctx.package?.name` (not the destructured `pkg`, which falls back to
+  // "unknown") so a package-less app yields no entrypoint, as before.
+  const entryAppId = ctx.app?.id;
+  const entryPkg = ctx.package?.name;
+  const entrypoint: AppEntrypoint | undefined =
+    entryAppId && entryPkg
+      ? { type: `${entryPkg}/${entryAppId}`, executeFn: executeName }
+      : undefined;
+
+  return { code: cb.toString(), entrypoint };
 }
 
 /**
@@ -381,6 +399,9 @@ export function appModuleName(meta: AppMeta | undefined): string {
  * the dict-style execute function name. Returns undefined when the id or package
  * is unknown (no stable `@type`), so the app is left out of the suite dispatcher.
  */
+// Note: this recomputes the execute name without a package scope, so it reflects
+// the un-bumped name. The emitter (`emitApp`) instead takes the entrypoint from
+// the scope-aware emit pass; use that path when a shared package scope is in play.
 export function appEntrypoint(ctx: CodegenContext): AppEntrypoint | undefined {
   const appId = ctx.app?.id;
   const pkg = ctx.package?.name;
@@ -469,11 +490,13 @@ export class TypeScriptBackend implements Backend {
   readonly target = "typescript";
 
   emitApp(ctx: CodegenContext, scope?: Scope): EmittedApp {
-    const code = generateTypeScript(ctx, scope);
+    // Take the entrypoint from the same pass that emitted the module, so its
+    // execute-function name reflects any shared-scope suffix-bump.
+    const { code, entrypoint } = generateTypeScriptModule(ctx, scope);
     const fileName = `${appModuleName(ctx.app)}.ts`;
     return {
       meta: ctx.app,
-      entrypoint: appEntrypoint(ctx),
+      entrypoint,
       files: new Map([[fileName, code]]),
       errors: [],
       warnings: [],

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

@@ -136,7 +136,10 @@ function emitValue(
       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));
+      // Report the element type (e.g. `int`), not the list type (`int[]`).
+      e.cb.indent(() =>
+        emitValue(e, type.item, itemNode, wireKey, elem, expectedType(e, type.item)),
+      );
       e.cb.line("}");
       return;
     }

package/src/backend/union-variants.ts

@@ -1,4 +1,44 @@
-import type { BoundType, BoundVariant } from "../bindings/index.js";
+import type { BindingRegistry, BoundType, BoundVariant, GateAtom } from "../bindings/index.js";
+
+/**
+ * Whether a union is "mixed": it has at least one non-struct (bare-literal) arm
+ * alongside its struct variants (e.g. ants `n4_correction = Literal[0] | N4On`).
+ *
+ * The `@type` discriminator only exists on the struct arms, so indexing
+ * `value["@type"]` on the union value is unsound (a type error, and a runtime
+ * KeyError if the literal arm is ever hit) until the value is narrowed to a
+ * struct at runtime. Backends that dispatch on `@type` must first emit a shape
+ * guard (Python `isinstance(value, dict)`, TS `typeof value === "object"`) when
+ * this is true; a pure-struct union (every arm a struct) needs no guard.
+ */
+export function unionIsMixed(unionType: Extract<BoundType, { kind: "union" }>): boolean {
+  return unionType.variants.some((v) => v.type.kind !== "struct");
+}
+
+/**
+ * The union type bound by a `variant` gate atom, if the atom's binding resolves
+ * to a union - used by the outputs emitters to decide whether the variant gate
+ * needs a mixed-union shape guard before its `@type` check. Returns `undefined`
+ * for a well-formed non-union (defensive; a variant atom should always name a
+ * union binding).
+ */
+export function variantAtomUnion(
+  atom: Extract<GateAtom, { kind: "variant" }>,
+  bindings: BindingRegistry,
+): Extract<BoundType, { kind: "union" }> | undefined {
+  return resolveUnion(bindings.get(atom.binding)?.type);
+}
+
+function resolveUnion(
+  type: BoundType | undefined,
+): Extract<BoundType, { kind: "union" }> | undefined {
+  if (!type) return undefined;
+  // An `optional<union>` binding can carry a variant gate (the optional wrapper
+  // and the union collapse onto one access path); unwrap to reach the union.
+  if (type.kind === "optional") return resolveUnion(type.inner);
+  if (type.kind === "union") return type;
+  return undefined;
+}
 
 /** 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

package/src/frontend/argdump/parser.ts

@@ -270,10 +270,12 @@ export class ArgdumpParser implements Frontend {
 
     if (isArgparseMarker(nargs)) {
       if (nargs.__argparse__ === "REMAINDER") {
-        // REMAINDER -> rep(str())
+        // REMAINDER -> rep(node), preserving the terminal's meta (name/doc/
+        // default) so the positional's `dest` name survives instead of being
+        // dropped for a solver-derived placeholder.
         const rep: Repeat = {
           kind: "repeat",
-          attrs: { node: { kind: "str", attrs: {} }, countMin: 0 },
+          attrs: { node, countMin: 0 },
         };
         return rep;
       }
@@ -700,32 +702,33 @@ export class ArgdumpParser implements Frontend {
       return null;
     }
 
-    if (alts.length === 1) {
-      return alts[0]!;
-    }
-
-    const alt: Alternative = { kind: "alternative", attrs: { alts } };
+    // A single choice needs no `alternative` wrapper, but must still honor the
+    // subparsers' required-ness (a lone-choice non-required subparser is still
+    // optional) rather than being returned bare as a mandatory node.
+    const node: Expr =
+      alts.length === 1
+        ? alts[0]!
+        : ({ kind: "alternative", attrs: { alts } } satisfies Alternative);
 
     const isRequired = action.subparsers_required === true || action.required === true;
-    if (!isRequired) {
-      const opt: Optional = { kind: "optional", attrs: { node: alt } };
+    const meta = this.buildNodeMeta(action);
 
-      const meta = this.buildNodeMeta(action);
+    if (!isRequired) {
+      const opt: Optional = { kind: "optional", attrs: { node } };
       if (meta) opt.meta = meta;
-
       return opt;
     }
 
-    const meta = this.buildNodeMeta(action);
-    if (meta) alt.meta = meta;
-
-    return alt;
+    // Required: hang the subparsers meta on the alternative wrapper when there is
+    // one; a single bare arm keeps its own sub-command meta instead of having it
+    // clobbered by the action's dest name.
+    if (node.kind === "alternative" && meta) node.meta = meta;
+    return node;
   }
 
   // Mutual exclusion
 
   private applyMutualExclusion(
-    actionsByDest: Map<string, AdAction>,
     groups: unknown[],
     nodes: Expr[],
     nodesByDest: Map<string, Expr>,
@@ -825,7 +828,6 @@ export class ArgdumpParser implements Frontend {
 
     const positionals: Expr[] = [];
     const optionals: Expr[] = [];
-    const actionsByDest = new Map<string, AdAction>();
     const nodesByDest = new Map<string, Expr>();
 
     for (const rawAction of actions) {
@@ -836,7 +838,6 @@ export class ArgdumpParser implements Frontend {
 
       const dest = rawAction.dest;
       if (isString(dest)) {
-        actionsByDest.set(dest, rawAction);
         nodesByDest.set(dest, node);
       }
 
@@ -853,7 +854,7 @@ export class ArgdumpParser implements Frontend {
     // Apply mutual exclusion groups
     const mutexGroups = descriptor.mutually_exclusive_groups;
     if (isArray(mutexGroups) && mutexGroups.length > 0) {
-      allNodes = this.applyMutualExclusion(actionsByDest, mutexGroups, allNodes, nodesByDest);
+      allNodes = this.applyMutualExclusion(mutexGroups, allNodes, nodesByDest);
     }
 
     return { kind: "sequence", attrs: { nodes: allNodes } };

package/src/frontend/argtype/__fixtures__/afni-3dtstat.argtype

@@ -0,0 +1,41 @@
+---
+exe: "3dTstat"
+version: "24.2.06"
+authors:
+  - "RW Cox"
+urls:
+  - "https://afni.nimh.nih.gov/"
+---
+
+/// Compute voxelwise statistics across the time axis of a 3D+time dataset.
+///
+/// All of AFNI is named with a leading digit (3d*, 1d*, 2d*), so the tool
+/// label has to be quoted - a bare identifier cannot start with a digit.
+"3dTstat": seq(
+  set(
+    /// Output dataset prefix (the view and extension are added automatically).
+    opt("-prefix", prefix: str = "stat"),
+
+    /// Compute the mean across time (the default when no statistic is given).
+    mean: opt("-mean"),
+
+    /// Compute the standard deviation across time.
+    stdev: opt("-stdev"),
+
+    /// Compute the median across time.
+    median: opt("-median"),
+
+    /// Percentiles to compute, emitted as a single colon-joined argument
+    /// (for example `25:50:75`).
+    opt("-percentile", percentiles: rep(int.min(0).max(100)).join(":")),
+
+    /// Number of leading time points to ignore.
+    opt("-ignore", ignore_count: int.min(0)),
+  ),
+
+  /// Input 3D+time dataset.
+  input: path,
+).output(
+  /// The statistics dataset header written by `-prefix`.
+  statfile: `{prefix}+orig.HEAD`,
+)