@styx-api/core 0.1.0

package/src/ir/format.ts

@@ -0,0 +1,157 @@
+import type { AppMeta, Output, OutputToken } from "./meta.js";
+import type { Expr } from "./node.js";
+
+export function format(expr: Expr, meta?: AppMeta): string {
+  const lines: string[] = [];
+
+  if (meta) {
+    lines.push(`app ${meta.id ?? "unknown"}${meta.version ? `@${meta.version}` : ""}`);
+    if (meta.doc?.description) {
+      lines.push(`  "${meta.doc.description}"`);
+    }
+    if (meta.doc?.authors?.length) {
+      lines.push(`  authors: ${meta.doc.authors.join(", ")}`);
+    }
+    if (meta.container) {
+      lines.push(`  container: ${meta.container.image}`);
+    }
+    if (meta.stdout) {
+      lines.push(`  stdout: ${meta.stdout.name}`);
+    }
+    if (meta.stderr) {
+      lines.push(`  stderr: ${meta.stderr.name}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(formatExpr(expr, 0));
+  return lines.join("\n");
+}
+
+function formatOutputToken(token: OutputToken): string {
+  if (token.kind === "literal") return JSON.stringify(token.value);
+  const flags = [
+    token.stripExtensions?.length && `strip=${JSON.stringify(token.stripExtensions)}`,
+    token.fallback !== undefined && `fallback=${JSON.stringify(token.fallback)}`,
+  ].filter(Boolean);
+  const suffix = flags.length > 0 ? ` {${flags.join(", ")}}` : "";
+  return `ref(${token.target.name})${suffix}`;
+}
+
+function formatOutputsBlock(outputs: Output[], indent: number): string {
+  const pad = "  ".repeat(indent);
+  const lines = [`${pad}outputs:`];
+  for (const out of outputs) {
+    const name = out.name ?? "<anon>";
+    const media = out.mediaTypes?.length ? ` (${out.mediaTypes.join(", ")})` : "";
+    const tokens = out.tokens.map(formatOutputToken).join(" + ") || `""`;
+    lines.push(`${pad}  ${name}${media}: ${tokens}`);
+  }
+  return lines.join("\n");
+}
+
+// Splice the outputs block in right after the node's header line (its first
+// line), before any child lines, so outputs read naturally as belonging to
+// the node they decorate.
+function spliceOutputs(body: string, outputsBlock: string): string {
+  if (!outputsBlock) return body;
+  const nl = body.indexOf("\n");
+  if (nl === -1) return `${body}\n${outputsBlock}`;
+  return `${body.slice(0, nl)}\n${outputsBlock}${body.slice(nl)}`;
+}
+
+function formatExpr(expr: Expr, indent: number): string {
+  const pad = "  ".repeat(indent);
+  const name = expr.meta?.name ? ` [${expr.meta.name}]` : "";
+  const outputsBlock = expr.meta?.outputs?.length
+    ? formatOutputsBlock(expr.meta.outputs, indent + 1)
+    : "";
+
+  let body: string;
+  switch (expr.kind) {
+    case "literal":
+      body = `${pad}literal${name} "${expr.attrs.str}"`;
+      break;
+
+    case "str":
+      body = `${pad}str${name}`;
+      break;
+
+    case "int": {
+      const { minValue, maxValue } = expr.attrs;
+      const range =
+        minValue !== undefined || maxValue !== undefined
+          ? ` (${minValue ?? ""}..${maxValue ?? ""})`
+          : "";
+      body = `${pad}int${name}${range}`;
+      break;
+    }
+
+    case "float": {
+      const { minValue, maxValue } = expr.attrs;
+      const range =
+        minValue !== undefined || maxValue !== undefined
+          ? ` (${minValue ?? ""}..${maxValue ?? ""})`
+          : "";
+      body = `${pad}float${name}${range}`;
+      break;
+    }
+
+    case "path": {
+      const flags = [
+        expr.attrs.resolveParent && "resolveParent",
+        expr.attrs.mutable && "mutable",
+      ].filter(Boolean);
+      const suffix = flags.length > 0 ? ` {${flags.join(", ")}}` : "";
+      body = `${pad}path${name}${suffix}`;
+      break;
+    }
+
+    case "sequence": {
+      const join = expr.attrs.join !== undefined ? ` join="${expr.attrs.join}"` : "";
+      const header = `${pad}sequence${name}${join}`;
+      if (expr.attrs.nodes.length === 0) {
+        body = `${header} (empty)`;
+      } else {
+        const children = expr.attrs.nodes.map((n) => formatExpr(n, indent + 1)).join("\n");
+        body = `${header}\n${children}`;
+      }
+      break;
+    }
+
+    case "alternative": {
+      const header = `${pad}alternative${name}`;
+      const children = expr.attrs.alts.map((n) => formatExpr(n, indent + 1)).join("\n");
+      body = `${header}\n${children}`;
+      break;
+    }
+
+    case "optional": {
+      const header = `${pad}optional${name}`;
+      const child = formatExpr(expr.attrs.node, indent + 1);
+      body = `${header}\n${child}`;
+      break;
+    }
+
+    case "repeat": {
+      const { join, countMin, countMax } = expr.attrs;
+      const parts = [
+        join !== undefined && `join="${join}"`,
+        countMin !== undefined && `min=${countMin}`,
+        countMax !== undefined && `max=${countMax}`,
+      ].filter(Boolean);
+      const suffix = parts.length > 0 ? ` {${parts.join(", ")}}` : "";
+      const header = `${pad}repeat${name}${suffix}`;
+      const child = formatExpr(expr.attrs.node, indent + 1);
+      body = `${header}\n${child}`;
+      break;
+    }
+
+    default: {
+      const _exhaustive: never = expr;
+      body = `${pad}unknown`;
+    }
+  }
+
+  return spliceOutputs(body, outputsBlock);
+}

package/src/ir/index.ts

@@ -0,0 +1,32 @@
+export { alt, float, int, lit, opt, path, rep, repJoin, seq, seqJoin, str } from "./builders.js";
+export { format } from "./format.js";
+export type { AppMeta, NodeMeta, NodeRef, Output, OutputToken, StreamOutput } from "./meta.js";
+export { effectiveOutputName, nodeRef } from "./meta.js";
+export type {
+  Alternative,
+  Expr,
+  Float,
+  Int,
+  Literal,
+  Optional,
+  Path,
+  Repeat,
+  Sequence,
+  Str,
+  StructuralNode,
+  Terminal,
+} from "./node.js";
+export { isStructural, isTerminal } from "./node.js";
+export type { Pass, PassResult } from "./passes/index.js";
+export {
+  canonicalize,
+  compose,
+  createPipeline,
+  defaultPipeline,
+  fixpoint,
+  flatten,
+  PassStatus,
+  simplify,
+  removeEmpty,
+} from "./passes/index.js";
+export type { Documentation, MediaTypeIdentifier, ScalarKind } from "./types.js";

package/src/ir/meta.ts

@@ -0,0 +1,91 @@
+import type { Documentation, MediaTypeIdentifier } from "./types.js";
+
+/**
+ * Opaque, name-based reference to an IR node by its `NodeMeta.name`.
+ *
+ * Resolved post-solve against the binding registry, not within IR passes.
+ * Names survive optimization (pointers don't), so token refs stay valid even
+ * after passes rewrite the tree. See `memory/design_outputs.md`.
+ */
+export interface NodeRef {
+  kind: "node-ref";
+  name: string;
+}
+
+/** Construct a NodeRef from a node name. */
+export function nodeRef(name: string): NodeRef {
+  return { kind: "node-ref", name };
+}
+
+/** Output token: literal text or a parameter reference. */
+export type OutputToken =
+  | { kind: "literal"; value: string }
+  | {
+      kind: "ref";
+      target: NodeRef;
+      stripExtensions?: string[];
+      fallback?: string;
+    };
+
+/**
+ * Specification for a file the tool produces. Lives on `NodeMeta.outputs` of
+ * the struct node (root sequence or subcommand sequence) that declared it.
+ * Per-output gating is derived downstream from the scope's binding gate and
+ * each ref binding's gate, so no host node or `optional` flag is stored.
+ */
+export interface Output {
+  name?: string;
+  doc?: Documentation;
+  tokens: OutputToken[];
+  mediaTypes?: MediaTypeIdentifier[];
+}
+
+/** Metadata attached to any IR node. */
+export interface NodeMeta {
+  /** Name identifier for this node (used by solver for binding names). */
+  name?: string;
+  /**
+   * The discriminator (`@type`) tag for this node when it is a union arm (a
+   * Boutiques sub-command). Kept separate from `name`: a single-field
+   * sub-command collapses onto its inner field, whose `name` then wins, so the
+   * tag would otherwise become the inner field's id - e.g. two distinct
+   * sub-commands `VariousString`/`VariousFile` both wrapping an `obj` field
+   * would collide on `@type: "obj"` (and the second arm would be unreachable).
+   * `mergeMeta` preserves this through the collapse and the solver prefers it
+   * for the variant tag, so distinct sub-commands keep distinct, reachable
+   * `@type`s.
+   */
+  variantTag?: string;
+  doc?: Documentation;
+  defaultValue?: string | number | boolean;
+  /** Files produced when this node is active. See `Output`. */
+  outputs?: Output[];
+}
+
+/** Application-level metadata for the root node. */
+export interface AppMeta {
+  id?: string;
+  version?: string;
+  doc?: Documentation;
+  container?: {
+    image: string;
+    type?: "docker" | "singularity";
+  };
+  stdout?: StreamOutput;
+  stderr?: StreamOutput;
+}
+
+export interface StreamOutput {
+  name: string;
+  doc?: Documentation;
+}
+
+/**
+ * Produce a usable name for an Output. Frontends may leave `Output.name`
+ * unset; downstream code (resolver, validator, backends) needs a stable
+ * identifier for diagnostics and field naming. Falls back to `output_<index>`
+ * keyed by the output's position in tree-walk order.
+ */
+export function effectiveOutputName(output: Output, index: number): string {
+  return output.name ?? `output_${index}`;
+}

package/src/ir/node.ts

@@ -0,0 +1,95 @@
+import type { NodeMeta } from "./meta.js";
+import type { MediaTypeIdentifier } from "./types.js";
+
+/** Base structure for all IR nodes */
+interface BaseNode<K extends string, Attrs> {
+  kind: K;
+  meta?: NodeMeta;
+  attrs: Attrs;
+}
+
+// Structural nodes
+
+export type Literal = BaseNode<
+  "literal",
+  {
+    str: string;
+  }
+>;
+
+export type Sequence = BaseNode<
+  "sequence",
+  {
+    nodes: Expr[];
+    join?: string;
+  }
+>;
+
+export type Optional = BaseNode<
+  "optional",
+  {
+    node: Expr;
+  }
+>;
+
+export type Alternative = BaseNode<
+  "alternative",
+  {
+    alts: Expr[];
+  }
+>;
+
+export type Repeat = BaseNode<
+  "repeat",
+  {
+    node: Expr;
+    join?: string;
+    countMin?: number;
+    countMax?: number;
+  }
+>;
+
+// Terminal nodes
+
+export type Int = BaseNode<
+  "int",
+  {
+    minValue?: number;
+    maxValue?: number;
+  }
+>;
+
+export type Float = BaseNode<
+  "float",
+  {
+    minValue?: number;
+    maxValue?: number;
+  }
+>;
+
+export type Str = BaseNode<"str", Record<string, never>>;
+
+export type Path = BaseNode<
+  "path",
+  {
+    resolveParent?: boolean;
+    mutable?: boolean;
+    mediaTypes?: MediaTypeIdentifier[];
+  }
+>;
+
+// Union types
+
+export type StructuralNode = Sequence | Optional | Alternative | Repeat;
+export type Terminal = Literal | Int | Float | Str | Path;
+export type Expr = StructuralNode | Terminal;
+
+// Type guards
+
+export function isTerminal(expr: Expr): expr is Terminal {
+  return ["literal", "int", "float", "str", "path"].includes(expr.kind);
+}
+
+export function isStructural(expr: Expr): expr is StructuralNode {
+  return ["sequence", "optional", "alternative", "repeat"].includes(expr.kind);
+}

package/src/ir/passes/canonicalize.ts

@@ -0,0 +1,108 @@
+import type { Expr } from "../node.js";
+import { PassStatus, type Pass, type PassResult } from "./pass.js";
+
+/**
+ * Canonicalize IR for consistent representation:
+ * - Sort alternatives by kind, then name, then structure
+ * - Deduplicate identical alternatives
+ */
+export const canonicalize: Pass = {
+  name: "canonicalize",
+  apply(expr: Expr): PassResult {
+    let changed = false;
+
+    function structuralHash(node: Expr): string {
+      switch (node.kind) {
+        case "literal":
+          return `lit:${node.attrs.str}`;
+        case "int":
+          return `int:${node.attrs.minValue ?? ""}:${node.attrs.maxValue ?? ""}`;
+        case "float":
+          return `float:${node.attrs.minValue ?? ""}:${node.attrs.maxValue ?? ""}`;
+        case "str":
+          return "str";
+        case "path":
+          return `path:${node.attrs.resolveParent ?? ""}:${node.attrs.mutable ?? ""}`;
+        case "optional":
+          return `opt:${structuralHash(node.attrs.node)}`;
+        case "repeat":
+          return `rep:${node.attrs.join ?? ""}:${structuralHash(node.attrs.node)}`;
+        case "sequence":
+          return `seq:${node.attrs.join ?? ""}:${node.attrs.nodes.map(structuralHash).join(",")}`;
+        case "alternative":
+          return `alt:${node.attrs.alts.map(structuralHash).join(",")}`;
+        default: {
+          const _exhaustive: never = node;
+          return "";
+        }
+      }
+    }
+
+    function sortKey(node: Expr): string {
+      const name = node.meta?.name ?? "";
+      return `${node.kind}:${name}:${structuralHash(node)}`;
+    }
+
+    function visit(node: Expr): Expr {
+      switch (node.kind) {
+        case "alternative": {
+          const children = node.attrs.alts.map(visit);
+
+          // Sort alternatives
+          const sorted = [...children].sort((a, b) => sortKey(a).localeCompare(sortKey(b)));
+
+          // Deduplicate by structural hash
+          const seen = new Set<string>();
+          const alts: Expr[] = [];
+          for (const child of sorted) {
+            const hash = structuralHash(child);
+            if (!seen.has(hash)) {
+              seen.add(hash);
+              alts.push(child);
+            } else {
+              changed = true;
+            }
+          }
+
+          // Check if order changed
+          if (
+            alts.length !== children.length ||
+            alts.some((alt, i) => structuralHash(alt) !== structuralHash(children[i]!))
+          ) {
+            changed = true;
+          }
+
+          return { ...node, attrs: { ...node.attrs, alts } };
+        }
+
+        case "sequence": {
+          const nodes = node.attrs.nodes.map(visit);
+          return { ...node, attrs: { ...node.attrs, nodes } };
+        }
+
+        case "optional":
+          return { ...node, attrs: { node: visit(node.attrs.node) } };
+
+        case "repeat":
+          return { ...node, attrs: { ...node.attrs, node: visit(node.attrs.node) } };
+
+        case "literal":
+        case "int":
+        case "float":
+        case "str":
+        case "path":
+          return node;
+
+        default: {
+          const _exhaustive: never = node;
+          return node;
+        }
+      }
+    }
+
+    return {
+      expr: visit(expr),
+      status: changed ? PassStatus.Changed : PassStatus.Unchanged,
+    };
+  },
+};

package/src/ir/passes/flatten.ts

@@ -0,0 +1,73 @@
+import type { Expr } from "../node.js";
+import { PassStatus, type Pass, type PassResult } from "./pass.js";
+
+/**
+ * Flatten passes
+ * - seq(a, seq(b, c)) -> seq(a, b, c)
+ * - alt(a, alt(b, c)) -> alt(a, b, c)
+ */
+export const flatten: Pass = {
+  name: "flatten",
+  apply(expr: Expr): PassResult {
+    let changed = false;
+
+    function visit(node: Expr): Expr {
+      switch (node.kind) {
+        case "sequence": {
+          const children = node.attrs.nodes.map(visit);
+          const nodes: Expr[] = [];
+
+          for (const child of children) {
+            if (child.kind === "sequence" && child.attrs.join === node.attrs.join && !child.meta) {
+              changed = true;
+              nodes.push(...child.attrs.nodes);
+            } else {
+              nodes.push(child);
+            }
+          }
+
+          return { ...node, attrs: { ...node.attrs, nodes } };
+        }
+
+        case "alternative": {
+          const children = node.attrs.alts.map(visit);
+          const alts: Expr[] = [];
+
+          for (const child of children) {
+            if (child.kind === "alternative" && !child.meta) {
+              changed = true;
+              alts.push(...child.attrs.alts);
+            } else {
+              alts.push(child);
+            }
+          }
+
+          return { ...node, attrs: { ...node.attrs, alts } };
+        }
+
+        case "optional":
+          return { ...node, attrs: { node: visit(node.attrs.node) } };
+
+        case "repeat":
+          return { ...node, attrs: { ...node.attrs, node: visit(node.attrs.node) } };
+
+        case "literal":
+        case "int":
+        case "float":
+        case "str":
+        case "path":
+          return node;
+
+        default: {
+          const _exhaustive: never = node;
+          return node;
+        }
+      }
+    }
+
+    return {
+      expr: visit(expr),
+      status: changed ? PassStatus.Changed : PassStatus.Unchanged,
+    };
+  },
+};

package/src/ir/passes/index.ts

@@ -0,0 +1,7 @@
+export { canonicalize } from "./canonicalize.js";
+export { flatten } from "./flatten.js";
+export type { Pass, PassResult } from "./pass.js";
+export { compose, fixpoint, PassStatus } from "./pass.js";
+export { createPipeline, defaultPipeline } from "./pipeline.js";
+export { simplify } from "./simplify.js";
+export { removeEmpty } from "./remove-empty.js";

package/src/ir/passes/pass.ts

@@ -0,0 +1,86 @@
+import type { Expr } from "../node.js";
+
+export enum PassStatus {
+  Unchanged = "unchanged",
+  Changed = "changed",
+  ChangedNeedsRerun = "changed-needs-rerun",
+}
+
+export interface PassResult {
+  expr: Expr;
+  status: PassStatus;
+  warnings?: string[];
+}
+
+export interface Pass {
+  readonly name: string;
+  apply(expr: Expr): PassResult;
+}
+
+export function compose(...passes: Pass[]): Pass {
+  return {
+    name: passes.map((p) => p.name).join(" → "),
+    apply(expr: Expr): PassResult {
+      let current = expr;
+      let overallStatus = PassStatus.Unchanged;
+      const warnings: string[] = [];
+
+      for (const pass of passes) {
+        const result = pass.apply(current);
+        current = result.expr;
+
+        if (result.status !== PassStatus.Unchanged) {
+          overallStatus = result.status;
+        }
+        if (result.warnings) {
+          warnings.push(...result.warnings);
+        }
+      }
+
+      return {
+        expr: current,
+        status: overallStatus,
+        ...(warnings.length > 0 && { warnings }),
+      };
+    },
+  };
+}
+
+export function fixpoint(pass: Pass, maxIterations = 10): Pass {
+  return {
+    name: `fixpoint(${pass.name})`,
+    apply(expr: Expr): PassResult {
+      let current = expr;
+      const allWarnings: string[] = [];
+
+      for (let i = 0; i < maxIterations; ++i) {
+        const result = pass.apply(current);
+
+        if (result.warnings) {
+          allWarnings.push(...result.warnings);
+        }
+
+        // Stop if unchanged or no rerun needed
+        if (result.status !== PassStatus.ChangedNeedsRerun) {
+          return {
+            expr: result.expr,
+            status:
+              result.status === PassStatus.Unchanged ? PassStatus.Unchanged : PassStatus.Changed,
+            ...(allWarnings.length > 0 && { warnings: allWarnings }),
+          };
+        }
+
+        current = result.expr;
+      }
+
+      return {
+        expr: current,
+        status: PassStatus.Changed,
+        warnings: [
+          ...allWarnings,
+          `${pass.name} did not converge after ${maxIterations} iterations`,
+        ],
+      };
+    },
+  };
+}

package/src/ir/passes/pipeline.ts

@@ -0,0 +1,21 @@
+// import { canonicalize } from "./canonicalize.js";
+import { flatten } from "./flatten.js";
+import type { Pass } from "./pass.js";
+import { compose, fixpoint } from "./pass.js";
+import { removeEmpty } from "./remove-empty.js";
+import { simplify } from "./simplify.js";
+
+export const defaultPipeline: Pass = fixpoint(
+  compose(flatten, removeEmpty, simplify /* canonicalize */),
+);
+
+export function createPipeline(
+  passes: Pass[],
+  options?: { fixpoint?: boolean; maxIterations?: number },
+): Pass {
+  const composed = compose(...passes);
+  if (options?.fixpoint) {
+    return fixpoint(composed, options.maxIterations);
+  }
+  return composed;
+}