@styx-api/core 0.7.0 → 0.8.0

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`,
+)

package/src/frontend/argtype/__fixtures__/bet.argtype

@@ -5,8 +5,6 @@ authors:
   - "FMRIB Analysis Group, University of Oxford"
 urls:
   - "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki"
-extensions:
-  - outputs
 ---
 
 /// Automated brain extraction tool for FSL

package/src/frontend/argtype/__fixtures__/fsl-flirt.argtype

@@ -0,0 +1,50 @@
+---
+exe: "flirt"
+version: "6.0.4"
+authors:
+  - "FMRIB Analysis Group, University of Oxford"
+urls:
+  - "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FLIRT"
+---
+
+/// FMRIB's Linear Image Registration Tool (affine intra-modal registration).
+flirt: seq(
+  /// Input volume to register.
+  opt("-in", infile: path),
+
+  /// Reference volume that defines the target space.
+  opt("-ref", reference: path),
+
+  set(
+    /// Registered output volume.
+    opt("-out", outbase: str).output(outvol: `{outbase}.nii.gz`),
+
+    /// Text file the estimated affine transform is written to.
+    opt("-omat", outmatrix: str),
+
+    /// Number of histogram bins used for the cost function.
+    opt("-bins", bins: int.min(1) = 256),
+
+    /// Degrees of freedom for the transform (6 rigid, 12 full affine).
+    opt("-dof", dof: int.min(3).max(12) = 12),
+
+    /// Cost function to optimize.
+    opt("-cost", cost: alt(
+      "mutualinfo",
+      "corratio",
+      "normcorr",
+      "normmi",
+      "leastsq",
+    ) = "corratio"),
+
+    /// Final interpolation applied when writing `-out`. The union carries a
+    /// default variant (`trilinear`), which the frontend keeps as the node
+    /// default.
+    opt("-interp", interp: alt(
+      "trilinear",
+      "nearestneighbour",
+      "sinc",
+      "spline",
+    ) = "trilinear"),
+  ),
+)

package/src/frontend/argtype/__fixtures__/wb-command-sub.argtype

@@ -0,0 +1,39 @@
+---
+exe: "wb_command"
+version: "1.5.0"
+authors:
+  - "Washington University School of Medicine"
+urls:
+  - "https://www.humanconnectome.org/software/connectome-workbench"
+---
+
+/// Reduce a volume file along the map axis to a single output map.
+///
+/// The executable is `wb_command` and the subcommand is `-volume-reduce`, so
+/// the tool id (`volume_reduce`) deliberately differs from the exe.
+volume_reduce: seq(
+  "-volume-reduce",
+
+  /// The input volume.
+  volume_in: path,
+
+  /// The reduction operation applied across the maps.
+  operation: alt(
+    "MAX",
+    "MIN",
+    "MEAN",
+    "SUM",
+    "STDEV",
+    "VARIANCE",
+    "TSNR",
+  ),
+
+  /// The output volume.
+  volume_out: str,
+
+  /// Exclude outliers by standard deviation before reducing.
+  opt("-exclude-outliers", sigma_below: float.min(0), sigma_above: float.min(0)),
+).output(
+  /// The reduced output volume.
+  reduced: `{volume_out}`,
+)

package/src/frontend/argtype/ast.ts

@@ -15,9 +15,21 @@ export type Combinator = "seq" | "set" | "opt" | "rep" | "alt" | "any";
 /** A terminal keyword. */
 export type Terminal = "int" | "float" | "str" | "path";
 
+/** 1-based source position of a construct, for diagnostics. Points at the node's
+ * primary token (a terminal/combinator keyword, a literal token, or the opening
+ * paren of a group), which is where a misplaced modifier or bad decoration is
+ * most usefully reported. */
+export interface SourceSpan {
+  line: number;
+  column: number;
+}
+
 export interface AstNode {
   kind: "literal" | "terminal" | "comb" | "ref";
 
+  /** Source position of the node's primary token, if known. */
+  span?: SourceSpan;
+
   /** kind === "literal": the fixed token string. */
   value?: string;
   /** kind === "terminal": which terminal. */
@@ -36,7 +48,8 @@ export interface AstNode {
   title?: string;
   /** Description: a `///` block (minus the title), or `.description("...")`. */
   description?: string;
-  /** `= value` sugar / `.default(...)` (terminal only). */
+  /** `= value` sugar / `.default(...)`. Meaningful on a terminal and on
+   * `opt`/`alt`/`rep`; dropped with a warning on a `seq`/`set` struct. */
   default?: string | number;
   /** `.min(n)` (int/float only). */
   min?: number;

package/src/frontend/argtype/frontmatter.ts

@@ -2,11 +2,11 @@
  * Frontmatter handling for argtype documents.
  *
  * A document may begin with a `---` fenced block of YAML-ish metadata (`exe`,
- * `version`, `extensions`, `container`, `authors`, `stdout`, ...). Rather than
- * pull in a full YAML dependency, this parses the small subset the format uses:
- * scalar `key: value`, block sequences (`- item`), and one level of nested
- * mappings. That covers every key the lowering step consumes; anything more
- * exotic is read as a raw string and ignored downstream.
+ * `version`, `container`, `authors`, `stdout`, ...). Rather than pull in a full
+ * YAML dependency, this parses the small subset the format uses: scalar
+ * `key: value`, block sequences (`- item`), inline flow sequences (`[a, b]`),
+ * and one level of nested mappings. That covers every key the lowering step
+ * consumes; anything more exotic is read as a raw string and ignored downstream.
  */
 
 export interface SplitResult {
@@ -174,7 +174,51 @@ function unescapeScalar(s: string): string {
   );
 }
 
+/** Split a flow-sequence body (`a, "b, c", [d, e]`) on top-level commas, keeping
+ * commas inside quotes or a nested `[...]` intact. Empty segments (from a leading,
+ * trailing, or doubled comma, or an empty `[]` body) are dropped, matching YAML;
+ * a quoted empty string keeps its quotes and so survives. */
+function splitFlow(body: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let inQuote: string | null = null;
+  let cur = "";
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i]!;
+    if (inQuote === '"' && ch === "\\") {
+      cur += ch + (body[i + 1] ?? "");
+      i++;
+      continue;
+    }
+    if (inQuote) {
+      if (ch === inQuote) inQuote = null;
+      cur += ch;
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+      cur += ch;
+    } else if (ch === "[") {
+      depth++;
+      cur += ch;
+    } else if (ch === "]") {
+      depth--;
+      cur += ch;
+    } else if (ch === "," && depth === 0) {
+      parts.push(cur);
+      cur = "";
+    } else {
+      cur += ch;
+    }
+  }
+  parts.push(cur);
+  return parts.map((p) => p.trim()).filter((p) => p !== "");
+}
+
 function parseScalar(text: string): unknown {
+  // Inline flow sequence: `[a, b, c]` (valid YAML the block-list parser would
+  // otherwise read as a bare string). `[]` is the empty list.
+  if (text.startsWith("[") && text.endsWith("]") && text.length >= 2) {
+    return splitFlow(text.slice(1, -1)).map(parseScalar);
+  }
   if (text.startsWith('"') && text.endsWith('"') && text.length >= 2) {
     return unescapeScalar(text.slice(1, -1));
   }

package/src/frontend/argtype/lexer.ts

@@ -195,6 +195,26 @@ export function lex(source: string): LexResult {
           });
         }
       }
+      // A plain integer run abutting a letter/underscore (`3dTstat`, all of
+      // AFNI's `3d*` tools) is a digit-led identifier: not a valid number and
+      // not a valid bare identifier. Consume the whole run and emit the fix
+      // directly rather than splitting into `number` + `ident` (which surfaces
+      // as a baffling "expected a definition"); recover as an `ident` so the
+      // rest still parses. Only a pure integer run qualifies: a decimal,
+      // signed, or malformed-exponent `num` is a broken number, not a name, so
+      // it keeps its own number/error path instead of being quoted as an ident.
+      if (/^\d+$/.test(num) && isIdentStart(peek())) {
+        let rest = "";
+        while (i < source.length && isIdentPart(peek())) rest += advance();
+        const full = num + rest;
+        errors.push({
+          message: `Identifier cannot start with a digit; quote it as "${full}"`,
+          line: startLine,
+          column: startCol,
+        });
+        push("ident", full, startLine, startCol);
+        continue;
+      }
       push("number", num, startLine, startCol);
       continue;
     }