@styx-api/core 0.1.0

package/src/ir/passes/remove-empty.ts

@@ -0,0 +1,76 @@
+import type { Expr } from "../node.js";
+import { PassStatus, type Pass, type PassResult } from "./pass.js";
+
+/**
+ * Remove empty nodes:
+ * - seq() → removed
+ * - alt() → removed
+ * - opt(seq()) → removed
+ * - rep(alt()) → removed
+ */
+export const removeEmpty: Pass = {
+  name: "remove-empty",
+  apply(expr: Expr): PassResult {
+    let changed = false;
+
+    function isEmpty(node: Expr): boolean {
+      return (
+        (node.kind === "sequence" && node.attrs.nodes.length === 0) ||
+        (node.kind === "alternative" && node.attrs.alts.length === 0)
+      );
+    }
+
+    function isRemovable(node: Expr): boolean {
+      if (node.meta) return false; // Preserve metadata
+      return (
+        isEmpty(node) ||
+        ((node.kind === "optional" || node.kind === "repeat") && isEmpty(node.attrs.node))
+      );
+    }
+
+    function visit(node: Expr): Expr {
+      switch (node.kind) {
+        case "sequence": {
+          const nodes = node.attrs.nodes.map(visit).filter((child) => {
+            const removable = isRemovable(child);
+            if (removable) changed = true;
+            return !removable;
+          });
+          return { ...node, attrs: { ...node.attrs, nodes } };
+        }
+
+        case "alternative": {
+          const alts = node.attrs.alts.map(visit).filter((child) => {
+            const removable = isRemovable(child);
+            if (removable) changed = true;
+            return !removable;
+          });
+          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/simplify.ts

@@ -0,0 +1,179 @@
+import type { NodeMeta } from "../meta.js";
+import type { Expr } from "../node.js";
+import { PassStatus, type Pass, type PassResult } from "./pass.js";
+
+/**
+ * Merge two `NodeMeta` when collapsing a wrapper layer (the child is the
+ * inner/surviving node). Name, doc fields and defaultValue take the innermost
+ * value; `outputs` from both layers are concatenated so an output attached to
+ * a collapsed wrapper survives on whatever node absorbs it.
+ */
+function mergeMeta(parent?: NodeMeta, child?: NodeMeta): NodeMeta | undefined {
+  if (!parent && !child) return undefined;
+  if (!parent) return child;
+  if (!child) return parent;
+
+  const merged: NodeMeta = {};
+
+  const name = child.name ?? parent.name;
+  if (name !== undefined) merged.name = name;
+
+  // The variant tag is the union discriminator (the sub-command id); unlike
+  // `name` it must survive a single-field sub-command collapsing onto its inner
+  // field (whose `name` wins above), so the `@type` stays the sub-command id
+  // rather than the inner field's id. The parent (the sub-command wrapper)
+  // carries it; the inner field has none.
+  const variantTag = parent.variantTag ?? child.variantTag;
+  if (variantTag !== undefined) merged.variantTag = variantTag;
+
+  const defaultValue = child.defaultValue ?? parent.defaultValue;
+  if (defaultValue !== undefined) merged.defaultValue = defaultValue;
+
+  if (parent.doc || child.doc) {
+    merged.doc = {
+      title: child.doc?.title ?? parent.doc?.title,
+      description: child.doc?.description ?? parent.doc?.description,
+      authors: [...(parent.doc?.authors ?? []), ...(child.doc?.authors ?? [])],
+      literature: [...(parent.doc?.literature ?? []), ...(child.doc?.literature ?? [])],
+      urls: [...(parent.doc?.urls ?? []), ...(child.doc?.urls ?? [])],
+      comment: child.doc?.comment ?? parent.doc?.comment,
+    };
+  }
+
+  const outputs = [...(parent.outputs ?? []), ...(child.outputs ?? [])];
+  if (outputs.length > 0) merged.outputs = outputs;
+
+  return merged;
+}
+
+/**
+ * Simplify passes:
+ * - optional(optional(T)) -> optional(T)
+ * - repeat(repeat(T)) -> repeat(T) with merged constraints
+ * - seq(T) -> T, alt(T) -> T (singleton unwrapping)
+ * - seq(lit("a"), lit("b")) -> seq(lit("ab")) (merge consecutive literals)
+ *
+ * Every collapse that drops a wrapper layer merges that layer's `NodeMeta`
+ * into the surviving node via `mergeMeta`, so names and attached outputs are
+ * never lost.
+ */
+export const simplify: Pass = {
+  name: "simplify",
+  apply(expr: Expr): PassResult {
+    let changed = false;
+
+    function visit(node: Expr): Expr {
+      switch (node.kind) {
+        case "optional": {
+          const inner = visit(node.attrs.node);
+
+          // optional(optional(T)) -> optional(T)
+          if (inner.kind === "optional") {
+            changed = true;
+            return {
+              ...node,
+              attrs: { node: inner.attrs.node },
+              meta: mergeMeta(node.meta, inner.meta),
+            };
+          }
+
+          return { ...node, attrs: { node: inner } };
+        }
+
+        case "repeat": {
+          const inner = visit(node.attrs.node);
+
+          // repeat(repeat(T)) -> repeat(T) with merged constraints
+          if (inner.kind === "repeat") {
+            changed = true;
+            return {
+              ...node,
+              attrs: {
+                node: inner.attrs.node,
+                join: node.attrs.join ?? inner.attrs.join,
+                countMin: Math.max(node.attrs.countMin ?? 0, inner.attrs.countMin ?? 0),
+                countMax:
+                  node.attrs.countMax === undefined || inner.attrs.countMax === undefined
+                    ? undefined
+                    : Math.min(node.attrs.countMax, inner.attrs.countMax),
+              },
+              meta: mergeMeta(node.meta, inner.meta),
+            };
+          }
+
+          return { ...node, attrs: { ...node.attrs, node: inner } };
+        }
+
+        case "sequence": {
+          const children = node.attrs.nodes.map(visit);
+
+          // Merge consecutive metadata-less literals, but only in an explicit
+          // concatenation context (`join === ""`). The merge is separator-free
+          // (`prev.str += child.str`), which only matches the semantics of an
+          // empty join. A sequence with no join joins its children with a space
+          // (they become separate argv tokens at the top level), so merging
+          // adjacent literals there would wrongly fuse two arguments into one
+          // (e.g. `seq(lit("wb_command"), lit("-foo"))` -> `"wb_command-foo"`).
+          // Inside a join context the backend concatenates anyway, so leaving
+          // such literals unmerged stays correct (just one node larger).
+          const nodes: Expr[] = [];
+          for (const child of children) {
+            const prev = nodes[nodes.length - 1];
+            if (
+              prev?.kind === "literal" &&
+              child.kind === "literal" &&
+              !prev.meta &&
+              !child.meta &&
+              node.attrs.join === ""
+            ) {
+              changed = true;
+              prev.attrs.str += child.attrs.str;
+            } else {
+              nodes.push(child);
+            }
+          }
+
+          // seq(T) -> T, carrying the seq's meta down onto the child.
+          if (nodes.length === 1) {
+            const child = nodes[0]!;
+            changed = true;
+            const mergedMeta = mergeMeta(node.meta, child.meta);
+            return mergedMeta ? { ...child, meta: mergedMeta } : child;
+          }
+
+          return { ...node, attrs: { ...node.attrs, nodes } };
+        }
+
+        case "alternative": {
+          const alts = node.attrs.alts.map(visit);
+
+          // alt(T) -> T. Only when the alt carries no metadata of its own
+          // (otherwise the collapse would orphan it).
+          if (alts.length === 1 && !node.meta) {
+            changed = true;
+            return alts[0]!;
+          }
+
+          return { ...node, attrs: { ...node.attrs, alts } };
+        }
+
+        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/types.ts

@@ -0,0 +1,15 @@
+/** Scalar type kinds for terminal nodes */
+export type ScalarKind = "int" | "float" | "str" | "path";
+
+/** Media type identifier (MIME type) */
+export type MediaTypeIdentifier = string;
+
+/** Human-facing documentation metadata */
+export interface Documentation {
+  title?: string;
+  description?: string;
+  authors?: string[];
+  literature?: string[];
+  urls?: string[];
+  comment?: string;
+}

package/src/manifest/context.ts

@@ -0,0 +1,36 @@
+import type {
+  BindingRegistry,
+  OutputScope,
+  OutputValidationResult,
+  SolveResult,
+} from "../bindings/index.js";
+import type { AppMeta, Expr } from "../ir/index.js";
+import type { OutputResolution } from "../solver/index.js";
+import type { PackageMeta, ProjectMeta } from "./types.js";
+
+export interface CodegenContext {
+  expr: Expr;
+  bindings: BindingRegistry;
+  resolve: SolveResult["resolve"];
+  outputScopes: OutputScope[];
+  outputDiagnostics: OutputValidationResult;
+  app?: AppMeta;
+  package?: PackageMeta;
+  project?: ProjectMeta;
+}
+
+export function createContext(
+  expr: Expr,
+  solveResult: SolveResult,
+  outputs: OutputResolution,
+  meta?: { app?: AppMeta; package?: PackageMeta; project?: ProjectMeta },
+): CodegenContext {
+  return {
+    expr,
+    bindings: solveResult.bindings,
+    resolve: solveResult.resolve,
+    outputScopes: outputs.scopes,
+    outputDiagnostics: outputs.diagnostics,
+    ...meta,
+  };
+}

package/src/manifest/index.ts

@@ -0,0 +1,3 @@
+export type { CodegenContext } from "./context.js";
+export { createContext } from "./context.js";
+export type { PackageMeta, ProjectMeta } from "./types.js";

package/src/manifest/types.ts

@@ -0,0 +1,15 @@
+import type { Documentation } from "../ir/index.js";
+
+export interface ProjectMeta {
+  name?: string;
+  version?: string;
+  doc?: Documentation;
+  license?: Documentation;
+}
+
+export interface PackageMeta {
+  name?: string;
+  version?: string;
+  docker?: string;
+  doc?: Documentation;
+}

package/src/solver/assign-access.ts

@@ -0,0 +1,218 @@
+import type { AccessPath, AccessSegment, Binding, BoundType } from "../bindings/index.js";
+import type { Expr } from "../ir/index.js";
+
+/**
+ * Attach `Binding.access` to every binding by walking the IR once, threading
+ * the same scope state the backend walkers used to re-derive independently
+ * (`arg-builder.walk` and `outputs-emit.walkAccess`). Producing the paths here,
+ * after types settle, collapses both walkers into pure `renderAccess` lookups
+ * and removes the drift class between them.
+ *
+ * The walk faithfully mirrors the (post-`ca61dc8`) arg-builder/outputs-emit
+ * scope handling for sequence/optional/alternative, and adopts the
+ * arg-builder's `repeat` recursion (which `walkAccess` lacked) so bindings
+ * inside a `repeat`-of-list get an `iter`-rooted path instead of being absent.
+ */
+export function assignAccessPaths(expr: Expr, resolve: (node: Expr) => Binding | undefined): void {
+  const rootBinding = resolve(expr);
+  walk(expr, resolve, { path: [], currentStructType: rootBinding?.type });
+}
+
+/**
+ * Scope state threaded down the walk, mirroring the arg-builder's `ArgContext`
+ * but carrying structured paths instead of rendered strings.
+ */
+interface AccessCtx {
+  /** Access path of the enclosing struct scope (the base for child fields). */
+  path: AccessPath;
+  /**
+   * When set, the next binding's value lives at this exact path rather than at
+   * `path + field(name)` - the wrapper collapsed the inner value onto its own
+   * path (`optional<scalar>`/`optional<bool>`, scalar lists). Mirrors the
+   * arg-builder's `directValue`. Not a rendered segment: it is "inherit the
+   * parent's path, append nothing".
+   */
+  directPath?: AccessPath;
+  /** The struct type at the current scope level (prevents double-scoping). */
+  currentStructType?: BoundType;
+}
+
+function field(name: string): AccessSegment {
+  return { kind: "field", name };
+}
+
+function iter(binding: string): AccessSegment {
+  return { kind: "iter", binding };
+}
+
+/** The path at which a binding's own value lives in the current scope. */
+function ownAccess(arg: AccessCtx, name: string): AccessPath {
+  return arg.directPath ?? [...arg.path, field(name)];
+}
+
+/** Whether a BoundType contains a struct that requires scoping when entered. */
+function hasStructScope(type: BoundType): boolean {
+  switch (type.kind) {
+    case "optional":
+      return hasStructScope(type.inner);
+    case "list":
+      return hasStructScope(type.item);
+    case "struct":
+      return true;
+    default:
+      return false;
+  }
+}
+
+/** Unwrap optional/list to find the inner struct type, if any. */
+function unwrapToStruct(type: BoundType): Extract<BoundType, { kind: "struct" }> | undefined {
+  switch (type.kind) {
+    case "optional":
+      return unwrapToStruct(type.inner);
+    case "list":
+      return unwrapToStruct(type.item);
+    case "struct":
+      return type;
+    default:
+      return undefined;
+  }
+}
+
+function walk(node: Expr, resolve: (node: Expr) => Binding | undefined, arg: AccessCtx): void {
+  const binding = resolve(node);
+
+  switch (node.kind) {
+    case "literal":
+      return;
+
+    case "int":
+    case "float":
+    case "str":
+    case "path": {
+      if (binding) binding.access = ownAccess(arg, binding.name);
+      return;
+    }
+
+    case "sequence": {
+      let childArg = arg;
+      if (binding && hasStructScope(binding.type) && binding.type !== arg.currentStructType) {
+        // A nested struct: children access fields under this binding's path.
+        const access: AccessPath = [...arg.path, field(binding.name)];
+        binding.access = access;
+        childArg = {
+          path: access,
+          currentStructType: unwrapToStruct(binding.type) ?? arg.currentStructType,
+        };
+      } else if (binding) {
+        // Root struct or a struct already scoped by an enclosing wrapper: the
+        // binding reuses the current path (collapse / already-scoped).
+        binding.access = arg.directPath ?? arg.path;
+      }
+      for (const child of node.attrs.nodes) walk(child, resolve, childArg);
+      return;
+    }
+
+    case "optional": {
+      if (!binding) {
+        walk(node.attrs.node, resolve, arg);
+        return;
+      }
+      const access: AccessPath = [...arg.path, field(binding.name)];
+      binding.access = access;
+      // The inner node, after unwrapping the optional from the binding type.
+      const innerType = binding.type.kind === "optional" ? binding.type.inner : binding.type;
+      let childArg: AccessCtx;
+      if (binding.type === arg.currentStructType) {
+        // This optional IS the boxed single-field union variant: a collapsed
+        // single-input arm whose type the solver retyped to the variant's
+        // struct (so `binding.type === currentStructType`). It maps to the
+        // variant's lone field, so the inner value collapses onto this
+        // optional's own field access. Without this, the struct-scope branch
+        // below would add a spurious extra segment named after the inner IR
+        // node (e.g. `params.opts.exponential_options.smoothing_standard_deviation`)
+        // instead of the boxed field (`params.opts.exponential_options`). The
+        // sequence case guards the same way via its `!== currentStructType` test.
+        childArg = { ...arg, directPath: access };
+      } else if (innerType.kind === "list") {
+        // optional<list>: the inner node is a `repeat` that represents this same
+        // value and assigns its own (iter-based) child scope. It must reuse this
+        // optional's path rather than append its field again - otherwise a
+        // struct-list field whose name matches the optional's collides into a
+        // doubled path (`params.config.config`). `directPath` = "inherit this
+        // path, append nothing". Scalar lists already reached here via the
+        // optional/bool branch below; struct lists previously fell into the
+        // `hasStructScope` branch and got the doubled path.
+        childArg = { ...arg, directPath: access };
+      } else if (hasStructScope(binding.type)) {
+        childArg = {
+          path: access,
+          currentStructType: unwrapToStruct(binding.type) ?? arg.currentStructType,
+        };
+      } else if (binding.type.kind === "optional" || binding.type.kind === "bool") {
+        // Collapsed non-struct: the inner value lives at the optional's path.
+        childArg = { ...arg, directPath: access };
+      } else {
+        childArg = arg;
+      }
+      walk(node.attrs.node, resolve, childArg);
+      return;
+    }
+
+    case "repeat": {
+      // The solver always binds repeat nodes, so this is defensive only; unlike
+      // optional/alternative there are no children to recurse into without it.
+      if (!binding) return;
+      // The list/count binding lives at its own access path.
+      binding.access = ownAccess(arg, binding.name);
+
+      if (binding.type.kind === "count") {
+        // Count repeats wrap a literal (no inner binding); recurse harmlessly
+        // with the scope unchanged, mirroring the arg-builder.
+        walk(node.attrs.node, resolve, arg);
+        return;
+      }
+
+      // List repeat: inner bindings are iteration-scoped. Reset the base to an
+      // `iter` segment bound to this repeat; the renderer substitutes the loop
+      // variable. Scalar lists collapse the element onto the loop var directly
+      // (directPath), struct lists scope into the element type.
+      const itemType = binding.type.kind === "list" ? binding.type.item : undefined;
+      const isScalar = !itemType || !hasStructScope(itemType);
+      const elementPath: AccessPath = [iter(binding.id)];
+      const childArg: AccessCtx = {
+        path: elementPath,
+        directPath: isScalar ? elementPath : undefined,
+        currentStructType:
+          !isScalar && itemType?.kind === "struct" ? itemType : arg.currentStructType,
+      };
+      walk(node.attrs.node, resolve, childArg);
+      return;
+    }
+
+    case "alternative": {
+      if (!binding) {
+        for (const alt of node.attrs.alts) walk(alt, resolve, arg);
+        return;
+      }
+      const access = ownAccess(arg, binding.name);
+      binding.access = access;
+      const isComplexUnion =
+        binding.type.kind === "union" &&
+        !binding.type.variants.every((v) => v.type.kind === "literal");
+      node.attrs.alts.forEach((alt, i) => {
+        if (isComplexUnion && binding.type.kind === "union") {
+          // A complex-union variant's fields are accessed via the union's own
+          // path (the `@type` discriminant narrows it), so scope into `access`.
+          const variantType = binding.type.variants[i]?.type;
+          walk(alt, resolve, {
+            path: access,
+            currentStructType: variantType?.kind === "struct" ? variantType : arg.currentStructType,
+          });
+        } else {
+          walk(alt, resolve, arg);
+        }
+      });
+      return;
+    }
+  }
+}

package/src/solver/index.ts

@@ -0,0 +1,4 @@
+export type { OutputResolution } from "./resolve-outputs.js";
+export { resolveOutputs } from "./resolve-outputs.js";
+export type { NamingStrategy, SolveOptions } from "./solver.js";
+export { defaultNamingStrategy, solve } from "./solver.js";