@styx-api/core 0.1.0

package/src/solver/resolve-outputs.ts

@@ -0,0 +1,233 @@
+import type {
+  Binding,
+  BindingId,
+  BoundType,
+  OutputDiagnostic,
+  OutputScope,
+  OutputValidationResult,
+  ResolvedOutput,
+  ResolvedToken,
+  SolveResult,
+} from "../bindings/index.js";
+import type { Expr, Output } from "../ir/index.js";
+import { effectiveOutputName } from "../ir/index.js";
+
+export interface OutputResolution {
+  scopes: OutputScope[];
+  diagnostics: OutputValidationResult;
+}
+
+/**
+ * Per-binding map keyed by `Binding.name`. Frontends attach outputs to the
+ * declaring struct, so refs name fields visible in that scope (the resolver
+ * accepts a single global name index because optimization can move bindings
+ * around but never duplicates names within a scope).
+ */
+interface NameIndex {
+  byName: Map<string, Binding>;
+}
+
+/**
+ * Whether a binding resolves to a value that can be interpolated into an output
+ * path token. Scalars/bool/count/literals (and optional/list wrappers of them)
+ * carry a concrete value; structs and complex unions do not.
+ *
+ * This drives the name-tie preference below: an unnamed multi-field struct
+ * inherits its first field's name (`findDeepName`), so a struct and its scalar
+ * field can share a name. An output ref always means the value, so the
+ * interpolable binding must win regardless of which sits shallower.
+ */
+function isInterpolable(type: BoundType): boolean {
+  switch (type.kind) {
+    case "optional":
+      return isInterpolable(type.inner);
+    case "list":
+      return isInterpolable(type.item);
+    case "struct":
+      return false;
+    case "union":
+      // Pure-enum unions are interpolable (the value is a literal); a union with
+      // any struct variant is not.
+      return type.variants.every((v) => isInterpolable(v.type));
+    default:
+      return true;
+  }
+}
+
+/**
+ * `includeRoot` controls whether the binding on `root` itself (depth 0) is
+ * indexed. The global index excludes it (a ref must never resolve to the root
+ * struct, which shares its name with a deep field via `findDeepName`). A
+ * scope-local index includes it: a collapsed single-field union arm boxes its
+ * lone field's binding onto the scope node itself (e.g. ants DenoiseImage's
+ * `correctedOutputFileName` arm), and that binding - with the field's access
+ * path and the arm's variant gate - is exactly what the arm's output ref needs.
+ */
+function indexBindingsByName(
+  root: Expr,
+  resolve: (n: Expr) => Binding | undefined,
+  includeRoot = false,
+): NameIndex {
+  const byNameDepth = new Map<string, { binding: Binding; depth: number }>();
+  function walk(node: Expr, depth: number): void {
+    const binding = resolve(node);
+    if (binding && (depth > 0 || includeRoot)) {
+      const existing = byNameDepth.get(binding.name);
+      if (!existing || preferCandidate({ binding, depth }, existing)) {
+        byNameDepth.set(binding.name, { binding, depth });
+      }
+    }
+    switch (node.kind) {
+      case "sequence":
+        for (const child of node.attrs.nodes) walk(child, depth + 1);
+        break;
+      case "optional":
+      case "repeat":
+        walk(node.attrs.node, depth + 1);
+        break;
+      case "alternative":
+        for (const alt of node.attrs.alts) walk(alt, depth + 1);
+        break;
+    }
+  }
+  walk(root, 0);
+  const byName = new Map<string, Binding>();
+  for (const [name, { binding }] of byNameDepth) byName.set(name, binding);
+  return { byName };
+}
+
+/**
+ * Decide whether `cand` should replace `existing` for a shared name. An
+ * interpolable binding always beats a structured one (the struct/scalar name
+ * collision); otherwise the shallowest binding wins, as before.
+ */
+function preferCandidate(
+  cand: { binding: Binding; depth: number },
+  existing: { binding: Binding; depth: number },
+): boolean {
+  const candLeaf = isInterpolable(cand.binding.type);
+  const exLeaf = isInterpolable(existing.binding.type);
+  if (candLeaf !== exLeaf) return candLeaf;
+  return cand.depth < existing.depth;
+}
+
+/**
+ * Walk the IR collecting `(node, outputs)` pairs in tree order. Outputs attach
+ * to struct/sequence nodes by frontend convention.
+ */
+function collectScopes(root: Expr): { node: Expr; outputs: Output[] }[] {
+  const out: { node: Expr; outputs: Output[] }[] = [];
+  function walk(node: Expr): void {
+    if (node.meta?.outputs?.length) out.push({ node, outputs: node.meta.outputs });
+    switch (node.kind) {
+      case "sequence":
+        for (const child of node.attrs.nodes) walk(child);
+        break;
+      case "optional":
+      case "repeat":
+        walk(node.attrs.node);
+        break;
+      case "alternative":
+        for (const alt of node.attrs.alts) walk(alt);
+        break;
+    }
+  }
+  walk(root);
+  return out;
+}
+
+function resolveOne(
+  output: Output,
+  index: number,
+  localNames: NameIndex,
+  globalNames: NameIndex,
+): { resolved: ResolvedOutput; errors: OutputDiagnostic[] } {
+  const errors: OutputDiagnostic[] = [];
+  const name = effectiveOutputName(output, index);
+  const tokens: ResolvedToken[] = [];
+  for (const token of output.tokens) {
+    if (token.kind === "literal") {
+      tokens.push({ kind: "literal", value: token.value });
+      continue;
+    }
+    // Prefer a binding declared within the output's own scope subtree. Union
+    // arms duplicate field names across scopes (each arm is its own scope), so
+    // the global index alone would resolve an arm's output ref to a sibling
+    // arm's binding, mixing contradictory variant gates into one output. Fall
+    // back to the global index for refs to bindings outside the local subtree.
+    const binding =
+      localNames.byName.get(token.target.name) ?? globalNames.byName.get(token.target.name);
+    if (!binding) {
+      errors.push({
+        output: name,
+        level: "error",
+        message: `token ref '${token.target.name}' has no binding with that name (frontend produced an inconsistent output spec)`,
+      });
+      continue;
+    }
+    tokens.push({
+      kind: "ref",
+      binding: binding.id,
+      ...(token.stripExtensions && { stripExtensions: token.stripExtensions }),
+      ...(token.fallback !== undefined && { fallback: token.fallback }),
+    });
+  }
+  const resolved: ResolvedOutput = {
+    name,
+    ...(output.doc && { doc: output.doc }),
+    tokens,
+    ...(output.mediaTypes && { mediaTypes: output.mediaTypes }),
+  };
+  return { resolved, errors };
+}
+
+/**
+ * Translate each `NodeMeta.outputs` entry against the binding registry,
+ * grouped by the declaring struct binding (the "scope"). The solver forces a
+ * binding on every output-carrying sequence, so an output without a scope
+ * binding indicates a frontend bug (outputs attached to a non-sequence
+ * node) - it is reported as a diagnostic and dropped.
+ */
+export function resolveOutputs(root: Expr, solved: SolveResult): OutputResolution {
+  const names = indexBindingsByName(root, solved.resolve);
+  const collected = collectScopes(root);
+
+  const byScope = new Map<BindingId, OutputScope>();
+  const errors: OutputDiagnostic[] = [];
+  const warnings: OutputDiagnostic[] = [];
+
+  let outputIndex = 0;
+  for (const { node, outputs } of collected) {
+    const scopeBinding = solved.resolve(node);
+    if (!scopeBinding) {
+      for (const output of outputs) {
+        const name = effectiveOutputName(output, outputIndex++);
+        errors.push({
+          output: name,
+          level: "error",
+          message: `output '${name}' is attached to a node without a binding (frontends should attach outputs to struct sequences)`,
+        });
+      }
+      continue;
+    }
+    let bucket = byScope.get(scopeBinding.id);
+    if (!bucket) {
+      bucket = { scope: scopeBinding.id, outputs: [] };
+      byScope.set(scopeBinding.id, bucket);
+    }
+    // Index only the bindings within this scope's subtree (including the scope
+    // node's own binding), so an output ref resolves to the field declared in
+    // the same scope (union arm) before falling back to the global index.
+    const localNames = indexBindingsByName(node, solved.resolve, true);
+    for (const output of outputs) {
+      const { resolved, errors: outErrors } = resolveOne(output, outputIndex++, localNames, names);
+      errors.push(...outErrors);
+      bucket.outputs.push(resolved);
+    }
+  }
+
+  return {
+    scopes: Array.from(byScope.values()),
+    diagnostics: { errors, warnings },
+  };
+}

package/src/solver/solver.ts

@@ -0,0 +1,319 @@
+import type { Binding, BindingId, BoundType, GateAtom, SolveResult } from "../bindings/index.js";
+import { createRegistry } from "../bindings/index.js";
+import type { Expr, Literal } from "../ir/index.js";
+import { assignAccessPaths } from "./assign-access.js";
+
+export interface SolveOptions {
+  namingStrategy?: NamingStrategy;
+}
+
+export interface NamingStrategy {
+  getName: (node: Expr, path: string[]) => string;
+  generateId: () => BindingId;
+}
+
+// Shared helper for deep name search
+function findDeepName(node: Expr): string | undefined {
+  if (node.meta?.name) return node.meta.name;
+
+  if (node.kind === "optional" || node.kind === "repeat") {
+    return findDeepName(node.attrs.node);
+  }
+
+  if (node.kind === "sequence") {
+    return node.attrs.nodes
+      .filter((n) => n.kind !== "literal")
+      .map(findDeepName)
+      .find(Boolean);
+  }
+
+  return undefined;
+}
+
+export function defaultNamingStrategy(): NamingStrategy {
+  let counter = 0;
+
+  return {
+    getName: (node, path) => findDeepName(node) ?? path[path.length - 1] ?? `param_${counter++}`,
+    generateId: () => `binding_${counter++}`,
+  };
+}
+
+// Helper to check if alternative should collapse to bool
+function isBooleanLiteralPair(variants: Array<{ type: BoundType }>): boolean {
+  if (variants.length !== 2 || !variants.every((v) => v.type.kind === "literal")) {
+    return false;
+  }
+  const [a, b] = variants.map((v) => (v.type.kind === "literal" ? v.type.value : null));
+  return (
+    (a === 0 && b === 1) ||
+    (a === 1 && b === 0) ||
+    (a === "0" && b === "1") ||
+    (a === "1" && b === "0") ||
+    (a === "false" && b === "true") ||
+    (a === "true" && b === "false")
+  );
+}
+
+// Helper to create literal bound type from IR literal
+function literalFromNode(node: Literal): BoundType {
+  const str = node.attrs.str;
+  const num = Number(str);
+  const isCleanInt = Number.isInteger(num) && !Number.isNaN(num) && String(num) === str;
+  return { kind: "literal", value: isCleanInt ? num : str };
+}
+
+/**
+ * Name to give the single wrapped field when a non-struct variant gets boxed
+ * into a discriminated struct. For a sequence arm the wrapped value is the
+ * inner parameter (`seq(lit("convert"), path{src})` -> `src`), so look past the
+ * arm's own (variant) name; otherwise use the value's own deep name.
+ */
+function innerParamName(armNode: Expr): string {
+  if (armNode.kind === "sequence") {
+    const inner = armNode.attrs.nodes
+      .filter((n) => n.kind !== "literal")
+      .map(findDeepName)
+      .find(Boolean);
+    if (inner) return inner;
+  }
+  return findDeepName(armNode) ?? "value";
+}
+
+/**
+ * Discriminated form of a variant's type: literal variants discriminate by
+ * value (returned unchanged); struct variants get an `@type` field prepended;
+ * anything else is boxed into `{ "@type": <name>, <field>: <type> }`. Pure -
+ * never mutates `type`.
+ */
+function taggedVariantType(name: string, type: BoundType, armNode: Expr): BoundType {
+  if (type.kind === "literal") return type;
+  const tag: BoundType = { kind: "literal", value: name };
+  if (type.kind === "struct") return { kind: "struct", fields: { "@type": tag, ...type.fields } };
+  return { kind: "struct", fields: { "@type": tag, [innerParamName(armNode)]: type } };
+}
+
+export function solve(expr: Expr, options?: SolveOptions): SolveResult {
+  const strategy = options?.namingStrategy ?? defaultNamingStrategy();
+  const registry = createRegistry();
+  const nodeToBinding = new WeakMap<Expr, Binding>();
+
+  // Wrapper bindings (optional/repeat/alternative) need an id BEFORE recursing
+  // into children so the child's `gate` can reference it. Pre-allocate the id
+  // here, then materialize the binding with its computed type after the
+  // recursion settles.
+  function preallocate(): BindingId {
+    return strategy.generateId();
+  }
+
+  function registerBinding(
+    id: BindingId,
+    node: Expr,
+    name: string,
+    type: BoundType,
+    gate: GateAtom[],
+  ): Binding {
+    // `access` is filled by `assignAccessPaths` once all types have settled
+    // (sequence collapse-vs-struct and union arm retyping are only known after
+    // the full recursion). Start empty so the field is always present.
+    const binding: Binding = { id, node, name, type, gate, access: [] };
+    registry.set(id, binding);
+    nodeToBinding.set(node, binding);
+    return binding;
+  }
+
+  function createBinding(node: Expr, name: string, type: BoundType, gate: GateAtom[]): Binding {
+    return registerBinding(strategy.generateId(), node, name, type, gate);
+  }
+
+  function solveNode(node: Expr, path: string[], gate: GateAtom[]): BoundType | null {
+    const name = strategy.getName(node, path);
+
+    switch (node.kind) {
+      case "literal":
+        return null;
+
+      case "optional": {
+        const id = preallocate();
+        const childGate = [...gate, { kind: "present" as const, binding: id }];
+        const inner = solveNode(node.attrs.node, [...path, name], childGate);
+        const type: BoundType = inner === null ? { kind: "bool" } : { kind: "optional", inner };
+        registerBinding(id, node, name, type, gate);
+        return type;
+      }
+
+      case "repeat": {
+        const id = preallocate();
+        // We don't yet know if the inner collapses to a count (no inner
+        // binding -> repeat-of-literal) or to a list. Optimistically tag the
+        // child gate as `iter`; if the inner is null we replace the wrapper
+        // type with `count` and the iter atom never reaches a real binding
+        // (no inner binding consumes the gate).
+        const childGate = [...gate, { kind: "iter" as const, binding: id }];
+        const inner = solveNode(node.attrs.node, [...path, name], childGate);
+        const type: BoundType = inner === null ? { kind: "count" } : { kind: "list", item: inner };
+        registerBinding(id, node, name, type, gate);
+        return type;
+      }
+
+      case "sequence": {
+        const fields: Record<string, BoundType> = {};
+        // Track the single binding-bearing child so the collapse check below can
+        // inspect its node kind (only meaningful when exactly one field exists).
+        let soleFieldChild: Expr | undefined;
+        for (const child of node.attrs.nodes) {
+          const childName = strategy.getName(child, path);
+          const childType = solveNode(child, [...path, childName], gate);
+          if (childType !== null) {
+            fields[childName] = childType;
+            soleFieldChild = child;
+          }
+        }
+        // A sequence that carries `meta.outputs` must always produce a binding,
+        // even when it would otherwise collapse - that binding is the scope key
+        // for the outputs declared on it. Empty- and single-field collapses
+        // would otherwise leave the scope unbound and the outputs orphaned.
+        const hasOutputs = node.meta?.outputs && node.meta.outputs.length > 0;
+        if (Object.keys(fields).length === 0) {
+          if (hasOutputs) {
+            const type: BoundType = { kind: "struct", fields: {} };
+            createBinding(node, name, type, gate);
+            return type;
+          }
+          return null;
+        }
+        // Collapse a single-field sequence to that field - e.g. `-x <val>`
+        // (`seq(lit("-x"), str)`) becomes just the value, so the flag and its
+        // one value read as a single optional/required parameter.
+        //
+        // EXCEPTION: when the field comes from an `optional` child, the
+        // sequence's own literal (e.g. `-whole-file`) can be present while the
+        // optional sub-field (e.g. `-demean`) is absent. Collapsing would
+        // conflate those two independent optional states and drop the sub-field
+        // (it would have no struct to live on). Keep such a sequence a struct so
+        // the sub-field stays addressable. A `repeat`/scalar/alternative child
+        // is tied 1:1 to the flag's presence, so collapsing those stays correct.
+        if (
+          Object.keys(fields).length === 1 &&
+          !hasOutputs &&
+          soleFieldChild?.kind !== "optional"
+        ) {
+          return Object.values(fields)[0]!;
+        }
+        const type: BoundType = { kind: "struct", fields };
+        createBinding(node, name, type, gate);
+        return type;
+      }
+
+      case "alternative": {
+        const id = preallocate();
+        // Resolve each arm's variant name first so child gates can carry it.
+        // `variantTag` (the sub-command id) is preferred over `name`: a
+        // single-field sub-command collapses onto its inner field, whose `name`
+        // wins, so `name` alone would derive the tag from the inner field's id
+        // (two distinct sub-commands wrapping a same-named field would collide).
+        const armNames = node.attrs.alts.map((alt, i) => {
+          if (alt.meta?.variantTag) return alt.meta.variantTag;
+          if (alt.meta?.name) return alt.meta.name;
+          if (alt.kind === "literal") return alt.attrs.str.replace(/^-+/, "");
+          return `variant_${i}`;
+        });
+
+        const variants = node.attrs.alts.map((alt, i) => {
+          const variantName = armNames[i]!;
+          const childGate = [
+            ...gate,
+            { kind: "variant" as const, binding: id, variant: variantName },
+          ];
+          const childType =
+            solveNode(alt, [...path, `variant_${i}`], childGate) ??
+            (alt.kind === "literal" ? literalFromNode(alt) : { kind: "bool" as const });
+          return { name: variantName, type: childType, node: alt };
+        });
+
+        // Pattern: boolean pair -> bool. The pre-allocated variant atoms in
+        // child gates are unreached (literal arms produce no bindings).
+        if (isBooleanLiteralPair(variants)) {
+          const type: BoundType = { kind: "bool" };
+          registerBinding(id, node, name, type, gate);
+          return type;
+        }
+
+        // Discriminate each variant. When an arm carries its own binding (a
+        // multi-field struct), retype it so that binding and the union agree;
+        // collapsed single-field arms keep their inner binding and the boxed
+        // form lives only in the union's `variants`.
+        for (const v of variants) {
+          v.type = taggedVariantType(v.name, v.type, v.node);
+          const armBinding = nodeToBinding.get(v.node);
+          if (armBinding) armBinding.type = v.type;
+        }
+
+        const type: BoundType = {
+          kind: "union",
+          variants: variants.map(({ name, type }) => ({ name, type })),
+        };
+        registerBinding(id, node, name, type, gate);
+        return type;
+      }
+
+      case "int":
+      case "float":
+      case "str":
+      case "path": {
+        const type: BoundType = { kind: "scalar", scalar: node.kind };
+        createBinding(node, name, type, gate);
+        return type;
+      }
+    }
+  }
+
+  const rootType = solveNode(expr, [], []);
+
+  // Ensure a root binding always exists, even when the sequence collapsed
+  // (0 fields -> empty struct, 1 field that's not already a struct -> wrap in single-field struct)
+  if (!nodeToBinding.has(expr) && expr.kind === "sequence") {
+    const name = strategy.getName(expr, []);
+    if (rootType === null) {
+      createBinding(expr, name, { kind: "struct", fields: {} }, []);
+    } else if (rootType.kind === "struct") {
+      // Already a struct (e.g. joined seq with 2+ fields) - use it directly
+      createBinding(expr, name, rootType, []);
+    } else {
+      // Single scalar/optional/list field was collapsed - wrap it in a struct.
+      // The field's binding may not be a direct child: a nested sequence that
+      // collapsed (e.g. one preserved by flatten to keep its `meta.doc`) leaves
+      // the binding buried one or more levels down. Search through collapsed
+      // sequences for it. Using `binding.name` as the field name keeps the
+      // struct field aligned with the access path the backends render
+      // (`params.<binding.name>`).
+      const findCollapsedBinding = (node: Expr): Binding | undefined => {
+        const b = nodeToBinding.get(node);
+        if (b) return b;
+        // Only sequences collapse without leaving a binding; optional/repeat/
+        // alternative always register one, so no need to descend into them.
+        if (node.kind === "sequence") {
+          for (const child of node.attrs.nodes) {
+            const found = findCollapsedBinding(child);
+            if (found) return found;
+          }
+        }
+        return undefined;
+      };
+      const childName = expr.attrs.nodes.map(findCollapsedBinding).find(Boolean)?.name;
+      if (childName) {
+        createBinding(expr, name, { kind: "struct", fields: { [childName]: rootType } }, []);
+      }
+    }
+  }
+
+  const resolve = (node: Expr) => nodeToBinding.get(node);
+
+  // Now that every binding's type has settled (sequence collapse, union arm
+  // retyping, root fixup), walk the IR once more to attach each binding's
+  // access path relative to top-level `params`. Backends render these paths
+  // instead of re-deriving them.
+  assignAccessPaths(expr, resolve);
+
+  return { bindings: registry, resolve };
+}