@styx-api/core 0.6.1 → 0.8.0

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

@@ -0,0 +1,101 @@
+---
+exe: "bet"
+version: "6.0.4"
+authors:
+  - "FMRIB Analysis Group, University of Oxford"
+urls:
+  - "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki"
+---
+
+/// Automated brain extraction tool for FSL
+bet: seq(
+  /// Input image (e.g. img.nii.gz).
+  infile: path,
+
+  /// Output brain mask prefix (e.g. img_bet).
+  maskfile: str = "img_bet",
+
+  set(
+    /// Fractional intensity threshold (0->1). Smaller values give larger
+    /// brain outline estimates.
+    opt("-f", fractional_intensity: float.min(0).max(1).default(0.5)),
+
+    /// Vertical gradient in fractional intensity threshold (-1->1).
+    /// Positive values give larger brain outline at bottom, smaller at top.
+    opt("-g", vg_fractional_intensity: float.min(-1).max(1).default(0)),
+
+    /// XYZ coordinates (voxels, not mm) of the center of gravity of the
+    /// initial mesh surface.
+    opt("-c", center_of_gravity: rep(float).count(3)),
+
+    /// Head radius (mm, not voxels); initial surface sphere is set to half
+    /// of this.
+    opt("-r", head_radius: float),
+
+    /// Generate brain surface outline overlaid onto original image.
+    overlay: opt("-o").output(overlay_file: `{maskfile}_overlay.nii.gz`),
+
+    /// Generate binary brain mask.
+    binary_mask_flag: opt("-m").output(binary_mask: `{maskfile}_mask.nii.gz`),
+
+    /// Generate rough skull image (not as clean as betsurf).
+    approx_skull: opt("-s").output(
+      approx_skull_img: `{maskfile}_skull.nii.gz`,
+      skull_mask:       `{maskfile}_skull_mask.nii.gz`,
+    ),
+
+    /// Don't generate segmented brain image output.
+    no_seg_output: opt("-n"),
+
+    /// Generate brain surface as mesh in .vtk format.
+    vtk_mesh: opt("-e").output(output_vtk_mesh: `{maskfile}_mesh.vtk`),
+
+    /// Apply thresholding to segmented brain image and mask.
+    thresholding: opt("-t"),
+
+    /// More robust brain center estimation by iterating BET with a
+    /// changing center-of-gravity.
+    robust_iters: opt("-R"),
+
+    /// Cleanup residual eye and optic nerve voxels (useful before
+    /// SIENA/SIENAX).
+    residual_optic_cleanup: opt("-S"),
+
+    /// Reduce image bias and residual neck voxels (useful before
+    /// SIENA/SIENAX).
+    reduce_bias: opt("-B"),
+
+    /// Pad end slices in both directions; useful when only a few slices
+    /// are present in the Z direction.
+    slice_padding: opt("-Z"),
+
+    /// Determine brain mask from the first volume of a 4D dataset and
+    /// apply it to the whole set. Intended for FMRI; the -f threshold
+    /// is reduced to 0.3.
+    whole_set_mask: opt("-F"),
+
+    /// Run bet2 + betsurf so skull and scalp surfaces are also produced
+    /// (requires registration to standard space).
+    additional_surfaces: opt("-A").output(
+      out_inskull_mask:  `{maskfile}_inskull_mask.nii.gz`,
+      out_inskull_mesh:  `{maskfile}_inskull_mesh.nii.gz`,
+      out_inskull_off:   `{maskfile}_inskull_mesh.off`,
+      out_outskin_mask:  `{maskfile}_outskin_mask.nii.gz`,
+      out_outskin_mesh:  `{maskfile}_outskin_mesh.nii.gz`,
+      out_outskin_off:   `{maskfile}_outskin_mesh.off`,
+      out_outskull_mask: `{maskfile}_outskull_mask.nii.gz`,
+      out_outskull_mesh: `{maskfile}_outskull_mesh.nii.gz`,
+      out_outskull_off:  `{maskfile}_outskull_mesh.off`,
+    ),
+
+    /// Same as -A, but also takes a T2 image as input to refine the
+    /// skull/scalp surfaces.
+    opt("-A2", additional_surfaces_t2: path),
+
+    /// Switch on diagnostic messages.
+    verbose: opt("-v"),
+
+    /// Don't delete temporary intermediate images.
+    debug: opt("-d"),
+  ),
+).output(outfile: `{maskfile}.nii.gz`)

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

@@ -0,0 +1,114 @@
+/**
+ * AST for the argtype sugar DSL. Mirrors the grammar in the argtype spec
+ * (combinators, terminals, literals, naming, aliases, method chains) and is the
+ * intermediate the parser produces before `lower.ts` translates it to Styx IR.
+ *
+ * Decorations (`name`, `doc`, `default`, value constraints, `.join`/`.count`,
+ * outputs, media types) attach to any node, so they live as optional fields on
+ * the single `AstNode` shape rather than as wrapper nodes - lowering folds them
+ * onto the corresponding `NodeMeta` / terminal attrs.
+ */
+
+/** A combinator keyword. `set`/`any` have no direct IR node (see `lower.ts`). */
+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. */
+  terminal?: Terminal;
+  /** kind === "comb": which combinator + its children. */
+  op?: Combinator;
+  children?: AstNode[];
+  /** kind === "ref": an alias reference (resolved by substitution). */
+  refName?: string;
+
+  // -- Decorations (any node) --
+
+  /** `label:` sugar / `.name("...")`. */
+  name?: string;
+  /** Title: a `# ` heading in a `///` block, or `.title("...")`. */
+  title?: string;
+  /** Description: a `///` block (minus the title), or `.description("...")`. */
+  description?: string;
+  /** `= 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;
+  /** `.max(n)` (int/float only). */
+  max?: number;
+  /** `.join(sep?)` - present means joined; separator defaults to "". */
+  join?: string;
+  /** `.count(n)` (= `.countMin(n).countMax(n)`) / `.countMin(n)` / `.countMax(n)`
+   * (rep only). */
+  countMin?: number;
+  countMax?: number;
+  /** `.mediaType(mime)` (path only; `mediatypes` extension). */
+  mediaTypes?: string[];
+  /** `.mutable()` (path only; `paths` extension). */
+  mutable?: boolean;
+  /** `.resolveParent()` (path only; `paths` extension). */
+  resolveParent?: boolean;
+  /** `.output(...)` (`outputs` extension). */
+  outputs?: AstOutput[];
+}
+
+/** One output template declared via `.output(...)`. */
+export interface AstOutput {
+  /** `label:` on the template / `.name(...)`. */
+  name?: string;
+  /** Title of the produced file (from a `# ` heading in the entry's `///`). */
+  title?: string;
+  /** Description of the produced file (from the entry's `///`). */
+  description?: string;
+  /** Output-level `.or(fallback)` on the template. */
+  fallback?: string;
+  tokens: AstOutputToken[];
+}
+
+/** A piece of an output path template: literal text or a `{ref}` interpolation. */
+export type AstOutputToken =
+  | { kind: "literal"; value: string }
+  | {
+      kind: "ref";
+      /** Target node name; undefined for a self-reference (`{}`). */
+      name?: string;
+      stripSuffix?: string[];
+      stripPrefix?: string[];
+      basename?: boolean;
+      or?: string;
+    };
+
+/** A top-level alias definition (`Name = expr`). */
+export interface AstAlias {
+  name: string;
+  expr: AstNode;
+}
+
+/** The result of parsing a full argtype document. */
+export interface AstDocument {
+  frontmatter?: Record<string, unknown>;
+  aliases: AstAlias[];
+  /** The root definition's name (`name: expr`). Undefined for an anonymous root
+   * (a bare top-level expression); the tool id then falls back to frontmatter. */
+  rootName?: string;
+  root: AstNode;
+}

package/src/frontend/argtype/doc.ts

@@ -0,0 +1,56 @@
+/**
+ * Doc-comment title/description handling.
+ *
+ * The `# Title` heading convention is *sugar*: it applies only when splitting a
+ * `///` block (`splitDocText`). The chaining methods `.title()` / `.description()`
+ * set the title / description directly and are not re-parsed for headings.
+ */
+
+export interface DocParts {
+  title?: string;
+  description?: string;
+}
+
+/**
+ * Reflow a `///` description as Markdown-style prose: a single line break is a
+ * soft wrap (the lines join with a space) and a blank line starts a new
+ * paragraph (kept as `\n\n`). This lets an author wrap a long description across
+ * several `///` lines for readability without forcing hard breaks, while real
+ * paragraph structure survives. (It does not preserve Markdown lists or indented
+ * code blocks - their single line breaks are joined like ordinary prose.)
+ */
+function reflowProse(text: string): string {
+  return text
+    .split(/\n{2,}/) // blank line(s) -> paragraph boundary
+    .map((para) =>
+      para
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .join(" "),
+    )
+    .filter((para) => para.length > 0)
+    .join("\n\n");
+}
+
+/**
+ * Split a `///` doc block into title + description. A leading Markdown H1
+ * (`# Title` on the first line) is the title; everything after it is the
+ * description. Without a leading `# `, the whole block is the description (no
+ * title). The description is reflowed as prose (see `reflowProse`): single line
+ * breaks soft-wrap, blank lines separate paragraphs.
+ */
+export function splitDocText(raw: string): DocParts {
+  const newline = raw.indexOf("\n");
+  const firstLine = (newline === -1 ? raw : raw.slice(0, newline)).trim();
+  if (firstLine.startsWith("# ")) {
+    const title = firstLine.slice(2).trim();
+    const description = reflowProse(newline === -1 ? "" : raw.slice(newline + 1));
+    return {
+      ...(title && { title }),
+      ...(description && { description }),
+    };
+  }
+  const description = reflowProse(raw);
+  return description ? { description } : {};
+}

package/src/frontend/argtype/frontmatter.ts

@@ -0,0 +1,237 @@
+/**
+ * Frontmatter handling for argtype documents.
+ *
+ * A document may begin with a `---` fenced block of YAML-ish metadata (`exe`,
+ * `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 {
+  frontmatter?: Record<string, unknown>;
+  /** The document body. Frontmatter lines are blanked (not removed) so token
+   * line numbers still line up with the original source. */
+  body: string;
+  errors: string[];
+}
+
+export function splitFrontmatter(source: string): SplitResult {
+  // Tolerate a leading BOM / blank lines before the opening fence.
+  const lines = source.split("\n");
+  let start = 0;
+  while (start < lines.length && lines[start]!.trim() === "") start++;
+
+  if (lines[start]?.trim() !== "---") {
+    return { body: source, errors: [] };
+  }
+
+  // Find the closing fence.
+  let end = -1;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i]!.trim() === "---") {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) {
+    return { body: source, errors: ["Unterminated frontmatter block (missing closing '---')"] };
+  }
+
+  const fmLines = lines.slice(start + 1, end);
+  const { value, errors } = parseYamlish(fmLines);
+
+  // Blank out the frontmatter region (fences + content) to preserve line numbers.
+  const blanked = lines.map((line, i) => (i >= start && i <= end ? "" : line));
+  return { frontmatter: value, body: blanked.join("\n"), errors };
+}
+
+interface Line {
+  indent: number;
+  content: string;
+}
+
+function tokenizeLines(raw: string[]): Line[] {
+  const out: Line[] = [];
+  for (const line of raw) {
+    const noComment = stripComment(line);
+    if (noComment.trim() === "") continue;
+    const indent = noComment.length - noComment.trimStart().length;
+    out.push({ indent, content: noComment.trim() });
+  }
+  return out;
+}
+
+/** Strip a trailing `#` comment that is not inside quotes. Following YAML, a
+ * `#` only starts a comment at the start of the line or after whitespace, so an
+ * unquoted value containing `#` (e.g. a URL fragment `https://x/#frag`) is kept
+ * intact. */
+function stripComment(line: string): string {
+  let inQuote: string | null = null;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]!;
+    // A backslash escape inside a double-quoted value hides the next char (so
+    // `\"` does not close the string).
+    if (inQuote === '"' && ch === "\\") {
+      i++;
+      continue;
+    }
+    if (inQuote) {
+      if (ch === inQuote) inQuote = null;
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === "#" && (i === 0 || line[i - 1] === " " || line[i - 1] === "\t")) {
+      return line.slice(0, i);
+    }
+  }
+  return line;
+}
+
+function parseYamlish(raw: string[]): { value: Record<string, unknown>; errors: string[] } {
+  const lines = tokenizeLines(raw);
+  const errors: string[] = [];
+  let pos = 0;
+
+  function parseBlock(minIndent: number): Record<string, unknown> | unknown[] {
+    // Sequence block?
+    if (
+      pos < lines.length &&
+      lines[pos]!.indent >= minIndent &&
+      lines[pos]!.content.startsWith("- ")
+    ) {
+      const seq: unknown[] = [];
+      const indent = lines[pos]!.indent;
+      while (
+        pos < lines.length &&
+        lines[pos]!.indent === indent &&
+        lines[pos]!.content.startsWith("- ")
+      ) {
+        seq.push(parseScalar(lines[pos]!.content.slice(2).trim()));
+        pos++;
+      }
+      return seq;
+    }
+
+    // Mapping block.
+    const map: Record<string, unknown> = {};
+    if (pos >= lines.length) return map;
+    const indent = lines[pos]!.indent;
+    while (
+      pos < lines.length &&
+      lines[pos]!.indent === indent &&
+      !lines[pos]!.content.startsWith("- ")
+    ) {
+      const { content } = lines[pos]!;
+      const colon = findColon(content);
+      if (colon === -1) {
+        errors.push(`Malformed frontmatter line: '${content}'`);
+        pos++;
+        continue;
+      }
+      const key = content.slice(0, colon).trim();
+      const valueText = content.slice(colon + 1).trim();
+      pos++;
+      if (valueText !== "") {
+        map[key] = parseScalar(valueText);
+      } else if (pos < lines.length && lines[pos]!.indent > indent) {
+        map[key] = parseBlock(lines[pos]!.indent);
+      } else {
+        map[key] = null;
+      }
+    }
+    return map;
+  }
+
+  const value = parseBlock(0);
+  return { value: isRecord(value) ? value : { _root: value }, errors };
+}
+
+function findColon(s: string): number {
+  let inQuote: string | null = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]!;
+    if (inQuote === '"' && ch === "\\") {
+      i++;
+      continue;
+    }
+    if (inQuote) {
+      if (ch === inQuote) inQuote = null;
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === ":") {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/** Reverse the backslash escapes an emitter applies to a quoted scalar
+ * (`\n`, `\t`, `\r`, `\"`, `\\`), so values with newlines/quotes round-trip. */
+function unescapeScalar(s: string): string {
+  return s.replace(/\\(.)/g, (_, c) =>
+    c === "n" ? "\n" : c === "t" ? "\t" : c === "r" ? "\r" : c,
+  );
+}
+
+/** 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));
+  }
+  if (text.startsWith("'") && text.endsWith("'") && text.length >= 2) {
+    return text.slice(1, -1);
+  }
+  if (text === "true") return true;
+  if (text === "false") return false;
+  if (text === "null" || text === "~") return null;
+  if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text);
+  return text;
+}
+
+function isRecord(x: unknown): x is Record<string, unknown> {
+  return typeof x === "object" && x !== null && !Array.isArray(x);
+}

package/src/frontend/argtype/index.ts

@@ -0,0 +1 @@
+export { ArgtypeParser } from "./parser-frontend.js";