@styx-api/core 0.1.0

package/src/bindings/format.ts

@@ -0,0 +1,176 @@
+import type { Expr } from "../ir/node.js";
+import type { AccessPath, BindingRegistry, OutputValidationResult } from "./binding.js";
+import type { SolveResult } from "./index.js";
+import { outputGate } from "./output-gate.js";
+import type { GateAtom, OutputScope, ResolvedOutput, ResolvedToken } from "./resolved-output.js";
+import type { BoundType } from "./types.js";
+
+export interface FormatExtras {
+  scopes?: OutputScope[];
+  diagnostics?: OutputValidationResult;
+}
+
+export function formatSolveResult(result: SolveResult, expr: Expr, extras?: FormatExtras): string {
+  const binding = result.resolve(expr);
+  const rootLine = binding ? `${binding.name}: ${formatType(binding.type)}` : "(no binding)";
+
+  const sections = [rootLine];
+
+  const gatedBindings = [...result.bindings.values()].filter(
+    (b) => b.gate.length > 0 && b !== binding,
+  );
+  if (gatedBindings.length > 0) {
+    sections.push("", "gates:");
+    for (const b of gatedBindings) {
+      sections.push(`  ${b.name}: ${formatGate(b.gate, result.bindings)}`);
+    }
+  }
+
+  const accessBindings = [...result.bindings.values()].filter((b) => b.access.length > 0);
+  if (accessBindings.length > 0) {
+    sections.push("", "access:");
+    for (const b of accessBindings) {
+      sections.push(`  ${b.name}: ${formatAccess(b.access, result.bindings)}`);
+    }
+  }
+
+  if (extras?.scopes?.length) {
+    sections.push("", "outputs:");
+    for (const scope of extras.scopes) {
+      const scopeBinding = result.bindings.get(scope.scope);
+      const header = scopeBinding ? `  on ${scopeBinding.name}:` : "  on <unbound>:";
+      sections.push(header);
+      const scopeGate = scopeBinding?.gate ?? [];
+      for (const out of scope.outputs) {
+        sections.push(formatResolvedOutput(out, scopeGate, result.bindings, 2));
+      }
+    }
+  }
+
+  const diags = [...(extras?.diagnostics?.errors ?? []), ...(extras?.diagnostics?.warnings ?? [])];
+  if (diags.length > 0) {
+    sections.push("", "diagnostics:");
+    for (const d of diags) sections.push(`  [${d.level}] ${d.output}: ${d.message}`);
+  }
+
+  return sections.join("\n");
+}
+
+function formatResolvedOutput(
+  out: ResolvedOutput,
+  scopeGate: GateAtom[],
+  bindings: BindingRegistry,
+  indent: number,
+): string {
+  const pad = "  ".repeat(indent);
+  const media = out.mediaTypes?.length ? ` (${out.mediaTypes.join(", ")})` : "";
+  const tokens = out.tokens.map((t) => formatResolvedToken(t, bindings)).join(" + ") || `""`;
+  const gateAtoms = outputGate(scopeGate, out, bindings);
+  const optional = gateAtoms.some((a) => a.kind === "present" || a.kind === "variant");
+  const optTag = optional ? " [optional]" : "";
+  const gate =
+    gateAtoms.length > 0
+      ? ` when (${gateAtoms.map((a) => formatGateAtom(a, bindings)).join(" AND ")})`
+      : "";
+  return `${pad}${out.name}${optTag}${media}: ${tokens}${gate}`;
+}
+
+function bindingName(bindings: BindingRegistry, id: string): string {
+  return bindings.get(id)?.name ?? `<${id}>`;
+}
+
+export function formatResolvedToken(token: ResolvedToken, bindings: BindingRegistry): 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(${bindingName(bindings, token.binding)})${suffix}`;
+}
+
+export function formatGateAtom(atom: GateAtom, bindings: BindingRegistry): string {
+  switch (atom.kind) {
+    case "present":
+      return `present(${bindingName(bindings, atom.binding)})`;
+    case "variant":
+      return `${bindingName(bindings, atom.binding)}=${atom.variant}`;
+    case "iter":
+      return `iter(${bindingName(bindings, atom.binding)})`;
+  }
+}
+
+export function formatGate(gate: GateAtom[], bindings: BindingRegistry): string {
+  if (gate.length === 0) return "(unconditional)";
+  return gate.map((a) => formatGateAtom(a, bindings)).join(" / ");
+}
+
+/**
+ * Render a binding's access path for debugging, e.g. `params.sub.x` or
+ * `<iter:things>.file`. An `iter` segment shows the repeat it loops, since the
+ * concrete loop variable is a backend emit-time detail.
+ */
+export function formatAccess(access: AccessPath, bindings: BindingRegistry): string {
+  let out = "params";
+  for (const seg of access) {
+    out =
+      seg.kind === "field" ? `${out}.${seg.name}` : `<iter:${bindingName(bindings, seg.binding)}>`;
+  }
+  return out;
+}
+
+function formatType(type: BoundType, indent = 0): string {
+  const pad = "  ".repeat(indent);
+  const inner = (t: BoundType) => formatType(t, indent + 1);
+
+  switch (type.kind) {
+    case "scalar":
+      return type.scalar;
+    case "bool":
+      return "bool";
+    case "count":
+      return "count";
+    case "literal":
+      return typeof type.value === "number" ? String(type.value) : `"${type.value}"`;
+    case "optional":
+      return `optional<${inner(type.inner)}>`;
+    case "list":
+      return `list<${inner(type.item)}>`;
+
+    case "struct": {
+      const entries = Object.entries(type.fields);
+      if (entries.length === 0) return "struct {}";
+      if (entries.length === 1) {
+        const [name, t] = entries[0]!;
+        return `struct { ${name}: ${formatType(t)} }`;
+      }
+      const fields = entries.map(([name, t]) => `${pad}  ${name}: ${inner(t)}`).join("\n");
+      return `struct {\n${fields}\n${pad}}`;
+    }
+
+    case "union": {
+      if (type.variants.length === 0) return "union {}";
+
+      // If all variants are literals, display inline
+      const allLiterals = type.variants.every((v) => v.type.kind === "literal");
+      if (allLiterals) {
+        return type.variants
+          .map((v) =>
+            v.type.kind === "literal"
+              ? typeof v.type.value === "number"
+                ? String(v.type.value)
+                : `"${v.type.value}"`
+              : "?",
+          )
+          .join(" | ");
+      }
+
+      // Otherwise multi-line union
+      const variants = type.variants.map((v) => `${pad}  | ${v.name}: ${inner(v.type)}`).join("\n");
+      return `union {\n${variants}\n${pad}}`;
+    }
+
+    default:
+      return ((_x: never) => "unknown")(type);
+  }
+}

package/src/bindings/index.ts

@@ -0,0 +1,16 @@
+export type {
+  AccessPath,
+  AccessSegment,
+  Binding,
+  BindingId,
+  BindingRegistry,
+  OutputDiagnostic,
+  OutputDiagnosticLevel,
+  OutputValidationResult,
+  SolveResult,
+} from "./binding.js";
+export { createRegistry } from "./binding.js";
+export { atomKey, outputGate } from "./output-gate.js";
+export type { GateAtom, OutputScope, ResolvedOutput, ResolvedToken } from "./resolved-output.js";
+export type { BoundType, BoundVariant } from "./types.js";
+export { formatSolveResult } from "./format.js";

package/src/bindings/output-gate.ts

@@ -0,0 +1,50 @@
+import type { BindingRegistry } from "./binding.js";
+import type { GateAtom, ResolvedOutput } from "./resolved-output.js";
+
+/**
+ * The unified wrapper sequence for a single output: the scope's gate, then for
+ * each ref token both the ref binding's path-gate and (if its type is itself
+ * "thick" - nullable or iterable) a self-atom on the ref binding. Atoms are
+ * deduped while preserving first-occurrence order.
+ *
+ * The self-atom encodes facts derivable from `Binding.type` alone:
+ * - `optional`, `bool`, `count` -> `present(binding)` (value may be absent)
+ * - `list` -> `iter(binding)` (iterate per element)
+ *
+ * `scopeGate` is the gate of the scope's struct binding (often `[]` at the
+ * root). Backends nest wrappers in array order; the atom kind decides whether
+ * it renders as a guard (`present` / `variant`) or a loop (`iter`).
+ */
+export function outputGate(
+  scopeGate: GateAtom[],
+  output: ResolvedOutput,
+  bindings: BindingRegistry,
+): GateAtom[] {
+  const seen = new Set<string>();
+  const result: GateAtom[] = [];
+  const push = (atom: GateAtom): void => {
+    const key = atomKey(atom);
+    if (seen.has(key)) return;
+    seen.add(key);
+    result.push(atom);
+  };
+  for (const atom of scopeGate) push(atom);
+  for (const token of output.tokens) {
+    if (token.kind !== "ref") continue;
+    const refBinding = bindings.get(token.binding);
+    if (!refBinding) continue;
+    for (const atom of refBinding.gate) push(atom);
+    const kind = refBinding.type.kind;
+    if (kind === "optional" || kind === "bool" || kind === "count") {
+      push({ kind: "present", binding: refBinding.id });
+    } else if (kind === "list") {
+      push({ kind: "iter", binding: refBinding.id });
+    }
+  }
+  return result;
+}
+
+export function atomKey(atom: GateAtom): string {
+  if (atom.kind === "variant") return `v:${atom.binding}:${atom.variant}`;
+  return `${atom.kind[0]}:${atom.binding}`;
+}

package/src/bindings/resolved-output.ts

@@ -0,0 +1,56 @@
+import type { Documentation, MediaTypeIdentifier } from "../ir/types.js";
+import type { BindingId } from "./binding.js";
+
+/**
+ * Resolved token in an output path template. Refs point at solved bindings;
+ * literals are emitted verbatim.
+ */
+export type ResolvedToken =
+  | { kind: "literal"; value: string }
+  | {
+      kind: "ref";
+      binding: BindingId;
+      stripExtensions?: string[];
+      fallback?: string;
+    };
+
+/**
+ * One wrapper layer on a binding's path from the root. Atoms are stored
+ * root-to-leaf in `Binding.gate`; backends nest wrappers in array order.
+ *
+ * - `present`: the binding is inside the active branch of `binding` (a non-null
+ *   `optional`, `true` for a `bool`, `> 0` for a `count`). Reads as a boolean
+ *   guard at codegen.
+ * - `variant`: the binding is inside the `variant` arm of the union bound by
+ *   `binding`. Reads as a discriminator check.
+ * - `iter`: the binding is inside a `repeat` whose value is a `list`. Reads as
+ *   a per-element loop variable bound to `binding`.
+ */
+export type GateAtom =
+  | { kind: "present"; binding: BindingId }
+  | { kind: "variant"; binding: BindingId; variant: string }
+  | { kind: "iter"; binding: BindingId };
+
+/**
+ * Output specification translated against the binding registry. Pure template
+ * data: a name and a token sequence. Per-output gating is derived at codegen
+ * time from the declaring scope's gate plus each ref binding's gate.
+ */
+export interface ResolvedOutput {
+  name: string;
+  doc?: Documentation;
+  tokens: ResolvedToken[];
+  mediaTypes?: MediaTypeIdentifier[];
+}
+
+/**
+ * Outputs declared on one struct binding, grouped under that scope. The
+ * solver guarantees a binding on every output-carrying sequence (forcing a
+ * struct binding even when it would otherwise collapse), so the scope is
+ * always a real BindingId. Per-output gating derives from the scope binding's
+ * `gate` plus each ref binding's `gate`.
+ */
+export interface OutputScope {
+  scope: BindingId;
+  outputs: ResolvedOutput[];
+}

package/src/bindings/types.ts

@@ -0,0 +1,16 @@
+import type { ScalarKind } from "../ir/index.js";
+
+export type BoundType =
+  | { kind: "scalar"; scalar: ScalarKind }
+  | { kind: "bool" }
+  | { kind: "count" }
+  | { kind: "literal"; value: string | number }
+  | { kind: "optional"; inner: BoundType }
+  | { kind: "list"; item: BoundType }
+  | { kind: "struct"; fields: Record<string, BoundType> }
+  | { kind: "union"; variants: BoundVariant[] };
+
+export interface BoundVariant {
+  name?: string;
+  type: BoundType;
+}

package/src/frontend/argdump/index.ts

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