/**
 * Phantom-typed JSONata value references for the Step Functions program DSL.
 *
 * An {@link Expr} is a *typed reference to a value that will exist at
 * execution time* — the execution input, the result of a previous state
 * (an ASL variable), the current Map item, etc. Property access is a Proxy
 * that builds up a JSONata path (`$states.context.Execution.Input.customerId`
 * style); comparator helpers (`eq`, `gt`, `and`, …) build boolean
 * expressions for Choice states.
 *
 * The same expression AST has two interpreters:
 * - `compile.ts` renders it to a `{% ... %}` JSONata string in the ASL
 *   definition,
 * - `simulate.ts` evaluates it in-process against a variable environment.
 */

/** Brand key carried by every {@link Expr} proxy. */
export const ExprTypeId = Symbol.for("alchemy/AWS/StepFunctions/JsonataExpr");
export type ExprTypeId = typeof ExprTypeId;

/** The value roots a JSONata path can start from. */
export type ExprRoot =
  /** The state machine execution input (`$states.context.Execution.Input`). */
  | { readonly kind: "input" }
  /** An ASL variable assigned by an earlier state (`$name`). */
  | { readonly kind: "variable"; readonly name: string }
  /** The callback task token (`$states.context.Task.Token`). */
  | { readonly kind: "token" };

/** Binary comparison / boolean operators supported by the expression AST. */
export type ExprOperator = "=" | "!=" | ">" | ">=" | "<" | "<=" | "and" | "or";

/**
 * The untyped expression AST behind an {@link Expr} proxy. Plain data — both
 * the ASL printer and the local simulator interpret it structurally.
 */
export type ExprNode =
  | { readonly _: "root"; readonly root: ExprRoot }
  | { readonly _: "prop"; readonly parent: ExprNode; readonly name: string }
  | { readonly _: "literal"; readonly value: unknown }
  | {
      readonly _: "binop";
      readonly op: ExprOperator;
      readonly left: ExprNode;
      readonly right: ExprNode;
    }
  | { readonly _: "not"; readonly inner: ExprNode }
  /** Raw JSONata escape hatch — compiles verbatim, unsupported by simulate. */
  | { readonly _: "raw"; readonly jsonata: string };

interface ExprBrand<T> {
  readonly [ExprTypeId]: {
    readonly node: ExprNode;
    readonly _T: (_: never) => T;
  };
}

/**
 * A typed JSONata value reference. Property access is typed: given
 * `input: Expr<{ order: { total: number } }>`, `input.order.total` is an
 * `Expr<number>` that renders as `….order.total`.
 *
 * Arrays are opaque references (pass them to `Sfn.forEach`); primitives are
 * leaf references usable in comparators and payloads.
 */
export type Expr<T = any> = ExprBrand<T> &
  ([T] extends [readonly any[]]
    ? {}
    : [T] extends [object]
      ? { readonly [K in keyof T & string]-?: Expr<T[K]> }
      : {});

/** A value of `T`, a typed reference to one, or `Expr<any>` (untyped hole). */
export type ExprInput<T> = T | Expr<T> | Expr<any>;

/** Recursively replace `Expr<T>` references with their referent type. */
export type UnwrapExpr<T> =
  T extends Expr<infer A>
    ? A
    : T extends readonly (infer U)[]
      ? UnwrapExpr<U>[]
      : T extends object
        ? { [K in keyof T]: UnwrapExpr<T[K]> }
        : T;

/** Runtime guard for {@link Expr} proxies. */
export const isExpr = (value: unknown): value is Expr<any> =>
  (typeof value === "object" || typeof value === "function") &&
  value !== null &&
  (value as ExprBrand<any>)[ExprTypeId] !== undefined;

/** Extract the AST node from an {@link Expr}. */
export const nodeOf = (expr: Expr<any>): ExprNode => expr[ExprTypeId].node;

/**
 * Wrap an AST node in the typed Proxy. String property access appends a
 * `prop` node; everything else (symbols, `then`, iteration protocols) is
 * absent so the proxy never masquerades as a Promise, Effect, or Output.
 */
export const makeExpr = <T>(node: ExprNode): Expr<T> => {
  const brand = { node, _T: undefined as never };
  return new Proxy(
    {},
    {
      get: (_, prop) => {
        if (prop === ExprTypeId) return brand;
        if (typeof prop !== "string") return undefined;
        // `toJSON`/`then` lookups happen when host code probes values
        // (JSON.stringify, await). Treat them as path segments would be
        // wrong; renderers detect Exprs *before* serialization, so any
        // such probe reaching here is a misuse — return a child expr
        // anyway (harmless, typed access never sees these names).
        return makeExpr({ _: "prop", parent: node, name: prop });
      },
      has: (_, prop) => prop === ExprTypeId,
    },
  ) as Expr<T>;
};

const literalNode = (value: unknown): ExprNode => ({ _: "literal", value });

/** Lift a value or Expr to an AST node. */
export const toNode = (value: unknown): ExprNode =>
  isExpr(value) ? nodeOf(value) : literalNode(value);

/** Lift a constant into a typed expression. */
export const literal = <T>(value: T): Expr<T> => makeExpr(literalNode(value));

/**
 * Raw JSONata escape hatch. Compiles verbatim into the definition
 * (`{% <jsonata> %}`); `simulate` rejects it with a `SimulateError`.
 */
export const jsonata = <T = unknown>(expression: string): Expr<T> =>
  makeExpr({ _: "raw", jsonata: expression });

const binop = (
  op: ExprOperator,
  left: unknown,
  right: unknown,
): Expr<boolean> =>
  makeExpr({ _: "binop", op, left: toNode(left), right: toNode(right) });

/** `left = right` (JSONata equality). */
export const eq = <T>(left: ExprInput<T>, right: ExprInput<T>): Expr<boolean> =>
  binop("=", left, right);
/** `left != right`. */
export const ne = <T>(left: ExprInput<T>, right: ExprInput<T>): Expr<boolean> =>
  binop("!=", left, right);
/** `left > right`. */
export const gt = (
  left: ExprInput<number>,
  right: ExprInput<number>,
): Expr<boolean> => binop(">", left, right);
/** `left >= right`. */
export const gte = (
  left: ExprInput<number>,
  right: ExprInput<number>,
): Expr<boolean> => binop(">=", left, right);
/** `left < right`. */
export const lt = (
  left: ExprInput<number>,
  right: ExprInput<number>,
): Expr<boolean> => binop("<", left, right);
/** `left <= right`. */
export const lte = (
  left: ExprInput<number>,
  right: ExprInput<number>,
): Expr<boolean> => binop("<=", left, right);
/** Boolean conjunction. */
export const and = (
  ...conditions: [
    ExprInput<boolean>,
    ExprInput<boolean>,
    ...ExprInput<boolean>[],
  ]
): Expr<boolean> =>
  conditions
    .slice(1)
    .reduce<Expr<boolean>>(
      (acc, c) => binop("and", acc, c),
      isExpr(conditions[0])
        ? (conditions[0] as Expr<boolean>)
        : literal(conditions[0] as boolean),
    );
/** Boolean disjunction. */
export const or = (
  ...conditions: [
    ExprInput<boolean>,
    ExprInput<boolean>,
    ...ExprInput<boolean>[],
  ]
): Expr<boolean> =>
  conditions
    .slice(1)
    .reduce<Expr<boolean>>(
      (acc, c) => binop("or", acc, c),
      isExpr(conditions[0])
        ? (conditions[0] as Expr<boolean>)
        : literal(conditions[0] as boolean),
    );
/** Boolean negation (`$not(...)`). */
export const not = (condition: ExprInput<boolean>): Expr<boolean> =>
  makeExpr({ _: "not", inner: toNode(condition) });

/** The execution-input root expression. */
export const inputExpr = <T>(): Expr<T> =>
  makeExpr({ _: "root", root: { kind: "input" } });

/** A reference to the ASL variable `name`. */
export const variableExpr = <T>(name: string): Expr<T> =>
  makeExpr({ _: "root", root: { kind: "variable", name } });

/**
 * The callback task token (`$states.context.Task.Token`) — embed inside
 * `Sfn.waitForTaskToken` arguments so the callback side can complete the
 * task via `SendTaskSuccess`/`SendTaskFailure`.
 */
export const taskToken: Expr<string> = makeExpr({
  _: "root",
  root: { kind: "token" },
});

// ---------------------------------------------------------------------------
// JSONata printer (used by compile.ts)
// ---------------------------------------------------------------------------

const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;

const renderRoot = (root: ExprRoot): string => {
  switch (root.kind) {
    case "input":
      return "$states.context.Execution.Input";
    case "variable":
      return `$${root.name}`;
    case "token":
      return "$states.context.Task.Token";
  }
};

/** Render an AST node to JSONata source (without the `{% %}` wrapper). */
export const renderNode = (node: ExprNode): string => {
  switch (node._) {
    case "root":
      return renderRoot(node.root);
    case "prop": {
      const parent =
        node.parent._ === "root" || node.parent._ === "prop"
          ? renderNode(node.parent)
          : `(${renderNode(node.parent)})`;
      return IDENT.test(node.name)
        ? `${parent}.${node.name}`
        : `${parent}.\`${node.name}\``;
    }
    case "literal":
      return JSON.stringify(node.value === undefined ? null : node.value);
    case "binop":
      return `(${renderNode(node.left)} ${node.op} ${renderNode(node.right)})`;
    case "not":
      return `$not(${renderNode(node.inner)})`;
    case "raw":
      return node.jsonata;
  }
};

/** Render an {@link Expr} to a `{% ... %}`-wrapped ASL JSONata string. */
export const renderExprString = (expr: Expr<any>): string =>
  `{% ${renderNode(nodeOf(expr))} %}`;