@hoox-sh/pynets 0.1.0 → 0.3.0

package/src/ast/unparse.ts

@@ -5,12 +5,18 @@
  * Slice-1 unparser: expressions plus Assign / ReAssign / var / varip,
  * Tuple / Conditional / ForTo / ForIn / While / Switch / Case /
  * BoolOp / Break / Continue / TypeDef / EnumDef.
+ *
+ * Parenthesization is precedence-driven, ported from PYNE's
+ * pynescript.ast.unparser (Precedence ladder + per-child assignment): a child
+ * is wrapped only when the precedence its parent assigns exceeds the child's
+ * own binding level, so unparse output always reparses to the same tree.
  */
 import type {
   AST,
   Arg,
   Assign,
   Attribute,
+  AugAssign,
   BinOp,
   BoolOp,
   Call,
@@ -27,9 +33,12 @@ import type {
   If,
   Import,
   Name,
+  Once,
   Param,
+  Qualify,
   ReAssign,
   Script,
+  Specialize,
   Subscript,
   Switch,
   Tuple,
@@ -38,6 +47,7 @@ import type {
   While,
   expr,
   stmt,
+  type_qual,
 } from "./nodes.ts";
 
 const OP: Record<string, string> = {
@@ -46,6 +56,18 @@ const OP: Record<string, string> = {
   Mult: "*",
   Div: "/",
   Mod: "%",
+  BitAnd: "&",
+  BitOr: "|",
+  BitXor: "^",
+  LShift: "<<",
+  RShift: ">>",
+};
+
+const TYPE_QUAL: Record<string, string> = {
+  Const: "const",
+  Input: "input",
+  Simple: "simple",
+  Series: "series",
 };
 
 const UOP: Record<string, string> = {
@@ -69,6 +91,93 @@ const BOOLOP: Record<string, string> = {
   Or: "or",
 };
 
+/**
+ * Operator binding levels for parenthesization — port of PYNE's
+ * `pynescript.ast.unparser.Precedence` ladder (higher binds tighter).
+ * A child is wrapped in parens when the precedence its parent assigns to it
+ * is strictly greater than the child's own binding level.
+ */
+const PREC = {
+  TEST: 1, // ternary '?', ':' — loosest
+  OR: 2,
+  AND: 3,
+  BITOR: 4,
+  BITXOR: 5,
+  BITAND: 6,
+  EQ: 7,
+  INEQ: 8, // Python Precedence.CMP alias
+  SHIFT: 9,
+  EXPR: 10,
+  ARITH: 11,
+  TERM: 12,
+  FACTOR: 13, // unary +,-,~,not (Python Precedence.NOT alias)
+  ATOM: 14, // names, literals, attr, calls — tightest
+} as const;
+
+function nextPrec(prec: number): number {
+  return Math.min(prec + 1, PREC.ATOM);
+}
+
+const BINOP_PREC: Record<string, number> = {
+  Add: PREC.ARITH,
+  Sub: PREC.ARITH,
+  Mult: PREC.TERM,
+  Div: PREC.TERM,
+  Mod: PREC.TERM,
+  BitAnd: PREC.BITAND,
+  BitOr: PREC.BITOR,
+  BitXor: PREC.BITXOR,
+  LShift: PREC.SHIFT,
+  RShift: PREC.SHIFT,
+};
+
+// Python assigns NOT = FACTOR (same level) for unary ops.
+const UNOP_PREC = PREC.FACTOR;
+
+const BOOLOP_PREC: Record<string, number> = {
+  And: PREC.AND,
+  Or: PREC.OR,
+};
+
+// Python Precedence.CMP — Compare children are checked against INEQ.
+const COMPARE_PREC = PREC.INEQ;
+
+/**
+ * Natural binding level of an expression node — the precedence the Python
+ * unparser's visitor checks against its parent-assigned level. Node kinds
+ * without an operator (atoms, Call, Attribute, …) never self-parenthesize in
+ * the SoT unparser, hence `undefined`.
+ */
+function ownPrec(node: expr): number | undefined {
+  switch (node.kind) {
+    case "BinOp":
+      return BINOP_PREC[node.op.kind];
+    case "UnaryOp":
+      return UNOP_PREC;
+    case "BoolOp":
+      return BOOLOP_PREC[node.op.kind];
+    case "Compare":
+      return COMPARE_PREC;
+    case "Conditional":
+      return PREC.TEST;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Emit a child expression, parenthesizing it when the parent-assigned
+ * precedence exceeds the child's own binding level. Mirrors Python's
+ * `NodeUnparser.require_parens` / `_needs_parens` rule: compare is strictly
+ * greater-than, so equal levels stay unparenthesized (left-associative
+ * chaining is encoded by the parent's per-slot precedence assignment).
+ */
+function emitChild(node: expr, required: number): string {
+  const src = emitExpr(node);
+  const prec = ownPrec(node);
+  return prec !== undefined && required > prec ? `(${src})` : src;
+}
+
 function quoteString(value: string): string {
   if (value.includes("\n") || value.includes("\r")) {
     if (!value.includes('"""')) return `"""${value}"""`;
@@ -86,13 +195,13 @@ function emitExpr(node: expr): string {
     case "Call":
       return emitCall(node);
     case "Attribute":
-      return `${emitExpr(node.value)}.${node.attr}`;
+      return `${emitChild(node.value, PREC.ATOM)}.${node.attr}`;
     case "Subscript":
       return `${emitExpr(node.value)}[${emitSlice(node.slice)}]`;
     case "BinOp":
-      return `${emitExpr(node.left)} ${OP[node.op.kind] ?? "?"} ${emitExpr(node.right)}`;
+      return emitBinOp(node);
     case "UnaryOp":
-      return `${UOP[node.op.kind] ?? ""}${emitExpr(node.operand)}`;
+      return emitUnaryOp(node);
     case "Compare":
       return emitCompare(node);
     case "If":
@@ -109,19 +218,61 @@ function emitExpr(node: expr): string {
       return emitWhile(node);
     case "Switch":
       return emitSwitch(node);
+    case "Once":
+      return emitOnce(node);
     case "BoolOp":
       return emitBoolOp(node);
+    case "Qualify":
+      return emitQualify(node);
+    case "Specialize":
+      return emitSpecialize(node);
+    case "AugAssign":
+      return emitAugAssign(node);
   }
 }
 
+function emitTypeQual(node: type_qual): string {
+  return TYPE_QUAL[node.kind] ?? node.kind.toLowerCase();
+}
+
+function emitQualify(node: Qualify): string {
+  return `${emitTypeQual(node.qualifier)} ${emitExpr(node.value)}`;
+}
+
+function emitSpecializeArgs(args: expr | null): string {
+  if (args == null) return "";
+  if (args.kind === "Tuple") return args.elts.map(emitExpr).join(", ");
+  return emitExpr(args);
+}
+
+function emitSpecialize(node: Specialize): string {
+  return `${emitExpr(node.value)}<${emitSpecializeArgs(node.args)}>`;
+}
+
 function emitCompare(node: Compare): string {
-  let out = emitExpr(node.left);
+  // Python: all Compare children are checked against CMP.next() (= SHIFT) so
+  // chained comparisons and tighter-binding operands stay unparenthesized.
+  const required = nextPrec(COMPARE_PREC);
+  let out = emitChild(node.left, required);
   for (let i = 0; i < node.ops.length; i++) {
-    out += ` ${CMP[node.ops[i]!.kind] ?? "??"} ${emitExpr(node.comparators[i]!)}`;
+    out += ` ${CMP[node.ops[i]!.kind] ?? "??"} ${emitChild(node.comparators[i]!, required)}`;
   }
   return out;
 }
 
+function emitBinOp(node: BinOp): string {
+  // Python: left child keeps the operator's level, right child uses next()
+  // so `a - b - c` prints bare while `a - (b - c)` re-parenthesizes.
+  const prec = BINOP_PREC[node.op.kind] ?? PREC.TEST;
+  return `${emitChild(node.left, prec)} ${OP[node.op.kind] ?? "?"} ${emitChild(node.right, nextPrec(prec))}`;
+}
+
+function emitUnaryOp(node: UnaryOp): string {
+  // Python: the operand is checked at the unary operator's own level (FACTOR),
+  // so -(a + b) and not (a and b) wrap while -a * b and not not a do not.
+  return `${UOP[node.op.kind] ?? ""}${emitChild(node.operand, UNOP_PREC)}`;
+}
+
 function emitIf(node: If): string {
   const body = node.body.map(emitStmt).join("; ");
   if (node.orelse.length === 0) return `if ${emitExpr(node.test)}\n    ${body}`;
@@ -140,7 +291,9 @@ function emitSlice(slice: expr | null | undefined): string {
 }
 
 function emitConditional(node: Conditional): string {
-  return `${emitExpr(node.test)} ? ${emitExpr(node.body)} : ${emitExpr(node.orelse)}`;
+  // Python: test/body at TEST.next() (nested ternaries there wrap); orelse at
+  // TEST so `a ? b : c ? d : e` stays right-associative without parens.
+  return `${emitChild(node.test, PREC.OR)} ? ${emitChild(node.body, PREC.OR)} : ${emitChild(node.orelse, PREC.TEST)}`;
 }
 
 function emitForBody(body: stmt[]): string {
@@ -169,6 +322,11 @@ function emitWhile(node: While): string {
   return `while ${emitExpr(node.test)}${emitIndentedBody(node.body)}`;
 }
 
+function emitOnce(node: Once): string {
+  const head = node.test ? `once ${emitExpr(node.test)}` : "once";
+  return head + emitIndentedBody(node.body);
+}
+
 function emitCaseBody(body: stmt[]): string {
   if (!body.length) return "";
   if (body.length === 1 && body[0]!.kind === "Expr") {
@@ -192,7 +350,16 @@ function emitSwitch(node: Switch): string {
 
 function emitBoolOp(node: BoolOp): string {
   const op = BOOLOP[node.op.kind] ?? "and";
-  return node.values.map(emitExpr).join(` ${op} `);
+  const base = BOOLOP_PREC[node.op.kind] ?? PREC.AND;
+  // Python raises the required level per value (op.next(), then tighter) so
+  // mixed nesting wraps the way the SoT unparser does.
+  let required = base;
+  return node.values
+    .map((v) => {
+      required = nextPrec(required);
+      return emitChild(v, required);
+    })
+    .join(` ${op} `);
 }
 
 function emitConstant(node: Constant): string {
@@ -216,7 +383,8 @@ function asArgs(args: Arg | Arg[] | null | undefined): Arg[] {
 }
 
 function emitCall(node: Call): string {
-  return `${emitExpr(node.func)}(${asArgs(node.args).map(emitArg).join(", ")})`;
+  // Python forces the callee to ATOM so e.g. a computed callee parenthesizes.
+  return `${emitChild(node.func, PREC.ATOM)}(${asArgs(node.args).map(emitArg).join(", ")})`;
 }
 
 function emitImport(node: Import): string {
@@ -229,6 +397,7 @@ function emitStmt(node: stmt): string {
   if (node.kind === "Expr") return emitExpr(node.value);
   if (node.kind === "Assign") return emitAssign(node);
   if (node.kind === "ReAssign") return emitReAssign(node);
+  if (node.kind === "AugAssign") return emitAugAssign(node);
   if (node.kind === "FunctionDef") return emitFunctionDef(node);
   if (node.kind === "TypeDef") return emitTypeDef(node);
   if (node.kind === "EnumDef") return emitEnumDef(node);
@@ -274,6 +443,7 @@ function emitFunctionDef(node: FunctionDef): string {
   const chunks: string[] = [];
   if (node.export) chunks.push("export");
   if (node.method) chunks.push("method");
+  if (node.returns) chunks.push(emitExpr(node.returns));
   chunks.push(`${node.name}(${asParams(node.args).map(emitParam).join(", ")}) =>`);
   const head = chunks.join(" ");
   const body = node.body;
@@ -305,6 +475,10 @@ function emitReAssign(node: ReAssign): string {
   return `${emitExpr(node.target)} := ${emitExpr(node.value)}`;
 }
 
+function emitAugAssign(node: AugAssign): string {
+  return `${emitExpr(node.target)} ${OP[node.op.kind] ?? "?"}= ${emitExpr(node.value)}`;
+}
+
 export function unparse(node: AST): string {
   if (node.kind === "Script") {
     const s = node as Script;
@@ -317,32 +491,33 @@ export function unparse(node: AST): string {
   if (node.kind === "Expr") return emitExpr((node as Expr).value);
   if (node.kind === "Assign") return emitAssign(node as Assign);
   if (node.kind === "ReAssign") return emitReAssign(node as ReAssign);
+  if (node.kind === "AugAssign") return emitAugAssign(node as AugAssign);
   if (node.kind === "FunctionDef") return emitFunctionDef(node as FunctionDef);
   if (node.kind === "TypeDef") return emitTypeDef(node as TypeDef);
   if (node.kind === "EnumDef") return emitEnumDef(node as EnumDef);
   if (node.kind === "Param") return emitParam(node as Param);
   if (node.kind === "Var") return "var";
   if (node.kind === "VarIp") return "varip";
+  if (node.kind === "Const") return "const";
+  if (node.kind === "Input") return "input";
+  if (node.kind === "Simple") return "simple";
+  if (node.kind === "Series") return "series";
+  if (node.kind === "Qualify") return emitQualify(node as Qualify);
+  if (node.kind === "Specialize") return emitSpecialize(node as Specialize);
   if (node.kind === "Call") return emitCall(node as Call);
   if (node.kind === "Name") return (node as Name).id;
   if (node.kind === "Constant") return emitConstant(node as Constant);
   if (node.kind === "Arg") return emitArg(node as Arg);
   if (node.kind === "Attribute") {
     const a = node as Attribute;
-    return `${emitExpr(a.value)}.${a.attr}`;
+    return `${emitChild(a.value, PREC.ATOM)}.${a.attr}`;
   }
   if (node.kind === "Subscript") {
     const s = node as Subscript;
     return `${emitExpr(s.value)}[${emitSlice(s.slice)}]`;
   }
-  if (node.kind === "BinOp") {
-    const b = node as BinOp;
-    return `${emitExpr(b.left)} ${OP[b.op.kind] ?? "?"} ${emitExpr(b.right)}`;
-  }
-  if (node.kind === "UnaryOp") {
-    const u = node as UnaryOp;
-    return `${UOP[u.op.kind] ?? ""}${emitExpr(u.operand)}`;
-  }
+  if (node.kind === "BinOp") return emitBinOp(node as BinOp);
+  if (node.kind === "UnaryOp") return emitUnaryOp(node as UnaryOp);
   if (node.kind === "Compare") return emitCompare(node as Compare);
   if (node.kind === "If") return emitIf(node as If);
   if (node.kind === "Tuple") return emitTuple(node as Tuple);

package/src/cli/rich.ts

@@ -12,7 +12,7 @@ const MUTED = [203, 204, 189] as const;
 const FAIL = [231, 0, 11] as const;
 const WARN = [235, 169, 65] as const;
 
-export const VERSION = "0.1.0";
+export const VERSION = "0.3.0";
 
 type Rgb = readonly [number, number, number];
 
@@ -122,7 +122,7 @@ export class Rich {
       this.write(this.paint("accent", "COMMANDS"));
     } else {
       this.write(
-        "usage: pynets <check|format|run|dump|info> [file] [--bars N] [--commission N] [--slippage N] [--pyramiding N] [--json] [--plain] [--rich] [--full]",
+        "usage: pynets <check|format|run|dump|info> [file] [--bars N] [--mode interpret|compile|auto] [--commission N] [--slippage N] [--pyramiding N] [--json] [--plain] [--rich] [--full]",
       );
       this.write("");
       this.write("commands:");
@@ -130,7 +130,7 @@ export class Rich {
     const cmds: Array<[string, string]> = [
       ["check", "Parse-only validation (CI-friendly exit codes)"],
       ["format", "Parse → unparse (pretty-print on TTY)"],
-      ["run", "Interpret on synthetic OHLCV"],
+      ["run", "Run on synthetic OHLCV (interpret or compile JS emit)"],
       ["dump", "Dump the ASDL-shaped AST"],
       ["info", "Version and runtime extras"],
     ];
@@ -146,6 +146,7 @@ export class Rich {
     else this.write("options:");
     const opts: Array<[string, string]> = [
       ["--bars N", "Synthetic bar count for run (default 20, max 100000)"],
+      ["--mode MODE", "run engine: interpret | compile | auto (JS emit; default interpret)"],
       ["--commission N", "Broker commission fraction for run (e.g. 0.001)"],
       ["--slippage N", "Broker slippage in price units for run"],
       ["--pyramiding N", "Broker max same-direction adds for run"],

package/src/cli.ts

@@ -20,6 +20,8 @@ import {
   useRich,
 } from "./cli/rich.ts";
 
+export type RunMode = "interpret" | "compile" | "auto";
+
 export const MAX_BARS = 100_000;
 
 export class UsageError extends Error {
@@ -155,6 +157,11 @@ function takeValue(args: string[], i: number, flag: string): { raw: string | und
   return { raw: a.slice(flag.length + 1), next: i };
 }
 
+function requireMode(raw: string | undefined): RunMode {
+  if (raw === "interpret" || raw === "compile" || raw === "auto") return raw;
+  throw new UsageError("error: --mode must be interpret|compile|auto");
+}
+
 export function parseArgs(argv: string[]): {
   cmd: string;
   file: string | undefined;
@@ -162,6 +169,7 @@ export function parseArgs(argv: string[]): {
   json: boolean;
   indent: number;
   full: boolean;
+  mode: RunMode;
   commission: number | undefined;
   slippage: number | undefined;
   pyramiding: number | undefined;
@@ -174,13 +182,14 @@ export function parseArgs(argv: string[]): {
   let json = false;
   let indent = 2;
   let full = false;
+  let mode: RunMode = "interpret";
   let commission: number | undefined;
   let slippage: number | undefined;
   let pyramiding: number | undefined;
   for (let i = 1; i < args.length; i++) {
     const a = args[i]!;
     if (a === "--help" || a === "-h") {
-      return { cmd: "help", file: undefined, bars, json, indent, full, commission, slippage, pyramiding };
+      return { cmd: "help", file: undefined, bars, json, indent, full, mode, commission, slippage, pyramiding };
     }
     if (a === "--json") {
       json = true;
@@ -190,6 +199,12 @@ export function parseArgs(argv: string[]): {
       full = true;
       continue;
     }
+    if (a === "--mode" || a.startsWith("--mode=")) {
+      const got = takeValue(args, i, "--mode");
+      mode = requireMode(got.raw);
+      i = got.next;
+      continue;
+    }
     if (a === "--bars" || a.startsWith("--bars=")) {
       const got = takeValue(args, i, "--bars");
       bars = clampBars(requireUint(got.raw, "--bars"));
@@ -230,7 +245,7 @@ export function parseArgs(argv: string[]): {
     if (file != null) throw new UsageError(`error: unexpected argument: ${a}`);
     file = a;
   }
-  return { cmd, file, bars, json, indent, full, commission, slippage, pyramiding };
+  return { cmd, file, bars, json, indent, full, mode, commission, slippage, pyramiding };
 }
 
 function fmtNum(v: number | null | undefined): string {
@@ -346,21 +361,27 @@ function runJson(out: RuntimeOut): void {
     series: typeof out.series;
     count: number;
     script_name: string | null;
+    mode: RuntimeOut["mode"];
     events?: RuntimeEvent[];
     drawings?: DrawingLike[];
     fills?: RuntimeFill[];
     alerts?: AlertLike[];
+    compile_fallback_reason?: string;
+    auto_backend?: RuntimeOut["auto_backend"];
     error?: string;
   } = {
     plots: out.plots,
     series: out.series,
     count: out.count,
     script_name: out.script_name,
+    mode: out.mode,
   };
   if (out.events != null) payload.events = out.events;
   if (out.drawings != null) payload.drawings = out.drawings;
   if (out.fills != null) payload.fills = out.fills;
   if (out.alerts != null) payload.alerts = out.alerts;
+  if (out.compile_fallback_reason != null) payload.compile_fallback_reason = out.compile_fallback_reason;
+  if (out.auto_backend != null) payload.auto_backend = out.auto_backend;
   if (out.error != null) payload.error = out.error;
   writeJson(payload);
   if (out.error != null) process.exit(1);
@@ -506,11 +527,12 @@ function run(
   bars: number,
   asJson: boolean,
   broker: BrokerSettings,
+  mode: RunMode,
 ): void {
   const t0 = performance.now();
   let out: RuntimeOut;
   try {
-    out = new Runtime("AAPL", { broker }).run(source, syntheticBars(bars));
+    out = new Runtime("AAPL", { broker, mode }).run(source, syntheticBars(bars));
   } catch (err) {
     fail(ui, err instanceof Error ? err.message : String(err), 1);
   }
@@ -538,7 +560,7 @@ function infoPayload(ui: Rich): {
     version: VERSION,
     runtime: "bun",
     bun: typeof Bun !== "undefined" ? Bun.version : null,
-    mode: "interpret",
+    mode: "interpret+compile",
     rich: ui.enabled,
     docs: "https://hoox.sh/pyne",
   };
@@ -558,7 +580,7 @@ function info(ui: Rich, asJson: boolean): void {
       ["package", "@hoox-sh/pynets"],
       ["version", VERSION],
       ["runtime", `bun ${payload.bun ?? "?"}`],
-      ["engine", "interpret"],
+      ["engine", "interpret + compile (JS emit)"],
       ["rich", "yes (TTY)"],
       ["docs", payload.docs],
     ],
@@ -577,7 +599,7 @@ function main(): void {
     failUsage(ui, msg);
   }
 
-  const { cmd, file, bars, json, indent, full } = parsed;
+  const { cmd, file, bars, json, indent, full, mode } = parsed;
   const broker = brokerFromFlags(parsed);
   if (cmd === "help" || cmd === "-h" || cmd === "--help") {
     ui.help();
@@ -610,7 +632,7 @@ function main(): void {
     return;
   }
   if (cmd === "run") {
-    run(ui, readSource(ui, file), file, bars, json, broker);
+    run(ui, readSource(ui, file), file, bars, json, broker, mode);
     return;
   }
   failUsage(ui, `error: unknown command: ${cmd}`);