openpinescript 0.0.0-stage → 0.1.1

package/dist/types/transpiler/v1/ToJsVisitor.d.ts

@@ -0,0 +1,720 @@
+/**
+ * Pine Script v1 → JavaScript emitter. THE BASE OF THE VISITOR HIERARCHY.
+ *
+ * Target: OpenPineScript Runtime (Series Object Architecture).
+ *
+ * ── RULES FOR EDITING THIS FILE ─────────────────────────────────────────────
+ *
+ * This class implements Pine Script v1 and nothing else. It must not contain a
+ * rule, a flag, or an empty hook that exists only to serve a later version.
+ *
+ * A later version changes behaviour by SUBCLASSING and overriding the relevant
+ * visit* method, usually delegating to `super`:
+ *
+ *     override visitVar_def(ctx: Var_defContext): string {
+ *       this.enforceNoSelfReference(...);      // the v3 rule
+ *       return super.visitVar_def(ctx);        // the inherited emit logic
+ *     }
+ *
+ * That is why the helpers here are `protected` rather than `private`: they are
+ * the documented extension surface. It is also why there is no `restricts(id)`
+ * lookup any more — a rule that applies to v1 fires unconditionally here, and a
+ * rule that does not apply to v1 simply is not written here.
+ *
+ * See transpiler/v3/ToJsVisitor.ts for a worked example, and
+ * docs/common/ARCHITECTURE.md ("Design rules") for the rationale.
+ */
+import { AbstractParseTreeVisitor } from "antlr4ng";
+import type { TerminalNode, ParserRuleContext, ParseTree } from "antlr4ng";
+import type { PineVersion } from "../common/version.js";
+import { Pine_scriptContext, StmtContext, Global_stmtContext, Global_stmt_contentContext, Fun_def_stmtContext, Fun_def_singlelineContext, Fun_def_multilineContext, Fun_headContext, Fun_body_singlelineContext, Local_stmt_singlelineContext, Local_stmt_contentContext, Loop_breakContext, Loop_continueContext, Fun_body_multilineContext, Local_stmts_multilineContext, Local_stmts_listContext, Local_stmt_multilineContext, Var_defContext, Var_defsContext, Ids_arrayContext, Arith_exprsContext, Arith_exprContext, If_exprContext, For_exprContext, Stmts_blockContext, Ternary_exprContext, Or_exprContext, And_exprContext, Eq_exprContext, Cmp_exprContext, Add_exprContext, Mult_exprContext, Unary_exprContext, Sqbr_exprContext, AtomContext, Fun_callContext, Fun_actual_argsContext, Pos_argsContext, Kw_argsContext, Kw_argContext, LiteralContext, Num_literalContext, Other_literalContext, IdContext } from "../../parser/v1/generated/PineV1Parser.js";
+import type { StdlibEntry } from "../../runtime/v1/stdlib/metadata.js";
+import { ScopeInfo } from "../common/passes/ScopeAnalysis.js";
+/**
+ * Anything carrying a source position. Structural rather than
+ * `ParserRuleContext`, because the generated context classes are generic in
+ * their visit result and do not assign to the base type.
+ */
+interface SourceLocated {
+    start?: {
+        line: number;
+        column: number;
+    } | null;
+}
+/**
+ * Is `node` a parse-tree node for the named grammar rule?
+ *
+ * MUST be used instead of `instanceof`. TypeScript is structural, so a v3
+ * `IdContext` satisfies the v1 `IdContext` TYPE and every override in the
+ * hierarchy type-checks — but `instanceof` is nominal at RUNTIME, and each
+ * version generates its own distinct context classes. `node instanceof
+ * IdContext` in this file is therefore FALSE for every v2 or v3 tree, which
+ * silently disables any guard built on it rather than failing loudly.
+ *
+ * Rule indices are no good either: an importing grammar lists its new and
+ * overridden rules first, so the same rule has a different index per version.
+ * The class NAME is the one identifier ANTLR keeps stable across the hierarchy.
+ */
+/**
+ * Names the RUNTIME binds into the sandbox directly, outside the registry.
+ *
+ * initializeSandbox() installs the OHLCV series and both spellings of the bar
+ * counter as Series objects. They have no registry entry because they are DATA
+ * rather than functions, so any check asking "does this name exist?" has to
+ * know about them separately or it rejects `close`.
+ *
+ * `n` and `bar_index` are both here on purpose. Exactly one of them is
+ * spellable at any version, and the one that is not is a poison pill installed
+ * by the profile — which throws its own, better message on read. Rejecting it
+ * here instead would replace "renamed in v4" with "undeclared identifier".
+ */
+export declare const RUNTIME_GLOBALS: ReadonlySet<string>;
+/**
+ * Is `node` a parse-tree node of the named rule?
+ *
+ * ⚠ This dispatches on the CLASS NAME, which makes those names part of the
+ * build contract. Each version's generated parser declares its own
+ * `Kw_argContext`, `Fun_callContext` and so on, so any bundler that merges the
+ * five of them has to rename four — and every check here then silently returns
+ * false for v2-v5. scripts/common/build-dist.mjs passes `keepNames` for
+ * exactly this reason, and conformance/common/bundle.test.ts fails if the
+ * published bundle ever loses it again.
+ */
+export declare function isRule(node: unknown, ruleContextName: string): boolean;
+/**
+ * Fold a WRAPPED string literal back onto one line.
+ *
+ * The lexer admits a newline inside a string when the next line is indented,
+ * because TradingView's line-continuation pass runs before its lexer does and
+ * the wrap never reaches the token. This is the other half of that rule: the
+ * manual states the resulting sequence "adds only one space to the start of the
+ * wrapped lines, and it does not automatically add line terminators", so the
+ * newline and the indentation together become exactly one space.
+ *
+ * Without this the literal would reach the emitter with a real newline in it and
+ * produce JavaScript that does not parse.
+ */
+export declare function unwrapString(text: string): string;
+export declare class V1ToJsVisitor extends AbstractParseTreeVisitor<string> {
+    /**
+     * Depth of user-function bodies currently being emitted.
+     *
+     * Pine scopes a function body separately from script scope, and several
+     * guards need to know which they are in — a name bound only inside some
+     * function says nothing about script scope. Tracked here rather than in a
+     * subclass so every version shares one counter.
+     */
+    protected fnDepth: number;
+    /**
+     * The user function whose body is being emitted, if any.
+     *
+     * ── The bug this exists for ─────────────────────────────────────────────────
+     *
+     * A local's SERIES is registered on the Context under its emitted JavaScript
+     * name, and that name is `opsv2_<pine name>` wherever the local is written.
+     * The JavaScript `let` is per-call and correctly scoped; the SERIES KEY was
+     * global. So two functions that both use the name `result`
+     *
+     *     hex(int value) =>
+     *         string result = ""
+     *         …
+     *     hexMap(array<int> numbers) =>
+     *         result = map.new<int, string>()
+     *         result.put(number, hex(number))
+     *
+     * shared ONE series. `hex()` set it to a string, `hexMap()` read a map back
+     * out of it, and the script died with "'str' has no method 'put'" — a
+     * diagnostic about a name the script never wrote. TradingView's own
+     * `v5-language-maps-09` and `v5-language-maps-18` are both this.
+     *
+     * The same collision applies between a function local and a script-scope
+     * variable of the same name, which is ordinary shadowing and must not alias.
+     *
+     * ── The other half ──────────────────────────────────────────────────────────
+     *
+     * Pine also gives every CALL SITE its own instance of a function's locals.
+     * That is a run-time question — the same declaration is one variable per
+     * frame — so it is answered by `Context.call`, which opens a series namespace
+     * per user-function frame. This half is the compile-time one: two DIFFERENT
+     * functions that happen to use the same word are two variables, whether or
+     * not either is ever called twice.
+     */
+    protected fnScope: string[];
+    /**
+     * The key a variable's Series is registered under.
+     *
+     * The emitted JavaScript identifier at script scope, and that identifier
+     * qualified by the enclosing function's emitted name inside a function body.
+     * Every site that writes a series key goes through here so that a declaration,
+     * a `:=`, and a history read can never disagree about which series they mean.
+     */
+    protected seriesKey(jsName: string): string;
+    /** Depth of for-loop bodies currently being emitted. */
+    protected loopDepth: number;
+    /**
+     * While positive, a block does NOT turn its last statement into a `return`.
+     * Set only for a statement-position `if` inside a loop — see visitIf_expr.
+     */
+    protected suppressBlockReturn: number;
+    /**
+     * The version this emitter implements. Subclasses override it, and every
+     * diagnostic is stamped with it, so an inherited guard reports the version
+     * that actually rejected the code rather than the one that wrote the check.
+     */
+    protected readonly version: PineVersion;
+    /**
+     * The names this VERSION may spell, and what each one means.
+     *
+     * An extension point, not a constant, because the stdlib is not the same set
+     * at every version: v4 renamed a pile of globals into namespaces, so `red`
+     * and `color.red` are each valid at exactly one version and invalid at the
+     * other. A single shared table cannot say that — it would accept both
+     * dialects everywhere and quietly compile scripts TradingView rejects.
+     *
+     * v1–v3 get the generated registry unchanged. v4 overrides this with its own
+     * view. Nothing about v4 appears in this file, which is the point: adding a
+     * version must never mean editing an earlier one
+     * (docs/common/ARCHITECTURE.md ("Design rules")).
+     */
+    protected get registry(): Record<string, StdlibEntry>;
+    protected readonly PREFIX = "opsv2_";
+    protected anonCounter: number;
+    protected scriptKind: 'study' | 'indicator' | 'strategy' | 'library' | undefined;
+    /** Names of user-defined functions; populated at the entry point. */
+    protected userFunctions: ReadonlySet<string>;
+    /**
+     * Script-scope variables READ above the line that declares them.
+     *
+     * v1 and v2 permit forward references, and published code relies on it to
+     * seed a counter from its own previous bar:
+     *
+     *     Seq_Gn_t = seq_diff > 0 ? nz(Seq_Gn[1]) + 1 : 0     // line 705
+     *     Seq_Gn   = Seq_Gn_t > 9 ? 1 : Seq_Gn_t              // line 707
+     *
+     * Emitting `let opsv2_Seq_Gn` at its declaration puts line 705 in the
+     * temporal dead zone. These names get a hoisted `let` prologue instead, so
+     * the binding exists (as undefined) before any read — at which point
+     * ctx.get() falls through to the by-name series lookup, which is the previous
+     * bar's value. That is exactly Pine's semantics.
+     *
+     * v3 rejects forward references outright, so this set is empty there.
+     */
+    protected hoisted: ReadonlySet<string>;
+    /**
+     * Whole-script scope facts, filled by visitPine_script.
+     *
+     * Lives at v1 rather than v2 because `Undeclared identifier` must behave the
+     * same at both — see conformance/v1_equals_v2.test.ts. v2 additionally uses
+     * it for ':=' , which is why the analysis pass was originally introduced
+     * there.
+     */
+    protected scopes: ScopeInfo;
+    /** Prefix every diagnostic with the version that rejected the code. */
+    protected err(ctx: SourceLocated, message: string): Error;
+    protected defaultResult(): string;
+    protected aggregateResult(aggregate: string, nextResult: string): string;
+    visitTerminal(node: TerminalNode): string;
+    /** * Helper: Generates a Deterministic ID based on Source Location.
+     * Example: "@L10:C5" (Line 10, Column 5)
+     */
+    protected getLocId(ctx: SourceLocated): string;
+    /** '==' / '!=' against 'na' silently misbehaves — require the na(x) function. */
+    protected enforceNaComparison(ctx: Eq_exprContext): void;
+    /** User-defined functions cannot recurse — reject direct self-reference. */
+    protected enforceNoRecursion(name: string, body: ParseTree, ctx: SourceLocated): void;
+    /**
+     * A study() script is in indicator mode — the broker emulator is disabled, so
+     * any strategy.* order/state call is a fatal error. Allowed under strategy()
+     * or when no directive is declared (permissive default).
+     */
+    protected enforceStrategyContext(name: string, ctx: SourceLocated): void;
+    /**
+     * The arity of the tuple this call returns BECAUSE ITS ARGUMENT IS ONE, or
+     * null when nothing about the call says it returns a tuple.
+     *
+     * Always null here: tuple expressions are a v4 addition ("the `expression`
+     * parameter can be series or tuple", v4 release notes, May 2020), and before
+     * that a bracketed list is not admitted as an argument at all.
+     */
+    protected tupleArityFromArgument(_call: Fun_callContext): number | null;
+    /**
+     * Whose return type a `[a, b] = <call>` is asking about.
+     *
+     * The call itself here, because before v5 a call is the whole expression.
+     * v5 overrides it: in `arr.maintainQueue(x).calcBB(y)` the value being
+     * unpacked is `calcBB`'s, not `maintainQueue`'s, and reading the base call
+     * asked the wrong function whether it returns a tuple.
+     */
+    protected destructuringCallee(call: Fun_callContext): string;
+    /** User-defined functions cannot return tuples. */
+    protected enforceNoTupleReturn(ctx: SourceLocated, detail?: string): void;
+    /**
+     * Does this subtree reference `name` as a bare identifier?
+     *
+     * `skipCallees` ignores the NAME position of a call while still scanning its
+     * arguments — `sma(x)` is not a reference to the variable `sma`, but
+     * `nz(s[1])` is a reference to `s`.
+     *
+     * `skipCalls` ignores whole call subtrees, arguments included.
+     */
+    protected referencesIdentifier(node: ParseTree | null, name: string, opts?: {
+        skipCalls?: boolean;
+        skipCallees?: boolean;
+    }): boolean;
+    /** Recursively scan a subtree for a call to the named function. */
+    protected callsFunction(node: ParseTree, name: string): boolean;
+    visitPine_script(ctx: Pine_scriptContext): string;
+    /**
+     * Script-scope names whose first READ is above their declaration.
+     *
+     * Only script scope: a function body runs at call time, so a name declared
+     * inside one is not lexically ordered against the script around it.
+     */
+    protected collectForwardReferenced(root: ParseTree): Set<string>;
+    /** Every user-defined function name in the script. */
+    protected collectFunctionNames(node: ParseTree): Set<string>;
+    /**
+     * The emitted name of a user-defined function.
+     *
+     * Pine keeps FUNCTIONS and VARIABLES in separate namespaces; JavaScript does
+     * not. So this is legal Pine:
+     *
+     *     mama(src, fast, slow) => ...
+     *     mama = mama(src, fast, slow)          // variable named after the function
+     *
+     * Emitted with one namespace, the `let opsv2_mama` shadows the function it is
+     * initialised from, and the call hits the temporal dead zone. Built-in callees
+     * were already routed around this through ctx.builtin(); user-defined ones
+     * need their own namespace, which is what the '$' does — it is legal in a
+     * JavaScript identifier and cannot occur in a Pine one, so a collision with a
+     * script variable is impossible rather than merely unlikely.
+     */
+    protected funcName(pineName: string): string;
+    /**
+     * Find the first study()/strategy() directive call in the script, if any.
+     *
+     * The return type admits 'indicator' so a later version can override this
+     * without widening it; v1 knows only the two spellings it tests for.
+     */
+    protected detectDirective(node: ParseTree): 'study' | 'indicator' | 'strategy' | 'library' | undefined;
+    visitStmt(ctx: StmtContext): string;
+    visitGlobal_stmt(ctx: Global_stmtContext): string;
+    visitGlobal_stmt_content(ctx: Global_stmt_contentContext): string;
+    protected visitContent(ctx: Global_stmt_contentContext | Local_stmt_contentContext): string;
+    visitFun_def_stmt(ctx: Fun_def_stmtContext): string;
+    /**
+     * The JavaScript name a function DEFINITION is emitted under.
+     *
+     * The same as `funcName` here, and a seam because v5's method overloads are
+     * not: a name declared for several receiver types needs one JavaScript
+     * function per type, and definition and call site must agree on how that name
+     * is spelled.
+     */
+    protected definitionFunctionName(pineName: string): string;
+    /**
+     * The emitted name a CALL to a user function targets.
+     *
+     * The mirror of `definitionFunctionName`, and a seam for the same reason: v5
+     * lets one name carry several definitions, so the call site has to be able to
+     * choose between them. Identical here, where a name has exactly one body.
+     */
+    protected callFunctionName(pineName: string, _ctx: Fun_callContext): string;
+    visitFun_def_singleline(ctx: Fun_def_singlelineContext): string;
+    visitFun_def_multiline(ctx: Fun_def_multilineContext): string;
+    /**
+     * The PINE names of a function's parameters, in order.
+     *
+     * Emitted onto the function object so `Context.call` can resolve a keyword
+     * argument against it. The built-in registry carries this for every built-in;
+     * a user-defined function has nowhere else to put it, and without it
+     * `f(b = 5)` reaches the function as a positional bundle rather than as `b`.
+     *
+     * A seam because v5's parameters can carry defaults and are a rule of their
+     * own; here a parameter is just an id.
+     */
+    protected paramNames(ctx: Fun_headContext): string[];
+    /**
+     * `fn.__params = [...]`, appended to a function definition.
+     *
+     * A property rather than a lookup table because the two have to survive
+     * bundling together: the emitter's names are preserved by `keepNames`, and a
+     * property name is not mangled at all.
+     */
+    protected paramNamesAssignment(jsName: string, head: Fun_headContext): string;
+    visitFun_head(ctx: Fun_headContext): string;
+    visitFun_body_singleline(ctx: Fun_body_singlelineContext): string;
+    /**
+     * A single-line body — `f(x) => a = 1, b = 2, a + b` — as the INSIDE of a
+     * JavaScript block that hands back the body's value.
+     *
+     * SOURCING. From the manual's user-defined functions page: "The body of the
+     * function must separate all individual statements in its body with commas",
+     * and what a call returns is "the final expression, variable, or tuple in the
+     * function's body".
+     *
+     * So a comma list is a list of STATEMENTS. Joining it with `,` into a
+     * JavaScript comma expression works only while every one of them happens to
+     * BE an expression, and Pine's do not have to be. TradingView's own
+     *
+     *     printTable(txt) => var table t = table.new(...), table.cell(t, 0, 0, txt)
+     *
+     * emitted `return let opsv2_t = ...`, which is not JavaScript — so the script
+     * passed compilation and then threw a SyntaxError the moment it was run.
+     */
+    protected singleLineBody(ctx: Local_stmt_singlelineContext): string;
+    /**
+     * Retained for generic visits only — `singleLineBody` is what the two call
+     * sites for this rule (a single-line function body, and a v5 switch arm) use,
+     * because they need the trailing statement's VALUE and this does not produce
+     * it.
+     */
+    visitLocal_stmt_singleline(ctx: Local_stmt_singlelineContext): string;
+    visitLocal_stmt_content(ctx: Local_stmt_contentContext): string;
+    visitLoop_break(_ctx: Loop_breakContext): string;
+    visitLoop_continue(_ctx: Loop_continueContext): string;
+    visitFun_body_multiline(ctx: Fun_body_multilineContext): string;
+    visitLocal_stmts_multiline(ctx: Local_stmts_multilineContext): string;
+    /**
+     * The variable a trailing BINDING statement evaluates to, or null if the
+     * statement is not a binding.
+     *
+     * A Pine function returns the value of its last statement, whatever form that
+     * statement takes. For an expression the emitted JS already IS the value; for
+     * a binding (`b = x * 2`) the value is the bound variable, and the emitter has
+     * to name it explicitly.
+     *
+     * Subclasses extend this when they add a binding form — v2 adds ':='.
+     */
+    protected trailingValueName(content: Local_stmt_contentContext): string | null;
+    /**
+     * `js`, the emitted form of a block's LAST statement, turned into whatever
+     * hands that statement's value back to the caller.
+     *
+     * Shared with `singleLineBody`, because the rule is the same one either way:
+     * a body evaluates to its final statement.
+     */
+    protected returnLastStatement(content: Local_stmt_contentContext, js: string): string;
+    visitLocal_stmts_list(ctx: Local_stmts_listContext): string;
+    /** @see visitLocal_stmts_list — the flattening there is what this rule needs. */
+    visitLocal_stmt_multiline(ctx: Local_stmt_multilineContext): string;
+    visitVar_def(ctx: Var_defContext): string;
+    visitVar_defs(ctx: Var_defsContext): string;
+    /**
+     * Where a `[a, b] = …` may take its values from, and how many there are.
+     * Throws on a source this version does not admit. A seam: v5 widens it.
+     */
+    protected checkTupleSource(ctx: Var_defsContext, ids: string[]): void;
+    visitIds_array(ctx: Ids_arrayContext): string;
+    visitArith_exprs(ctx: Arith_exprsContext): string;
+    visitArith_expr(ctx: Arith_exprContext): string;
+    /**
+     * Is this `if` a STATEMENT, whose value is discarded, rather than an
+     * expression being bound to something?
+     *
+     * The grammar admits `if_expr` in exactly two places — `*_stmt_content` and
+     * `arith_expr` — so the parent rule answers it.
+     */
+    /**
+     * The `if` this statement IS, or null if the statement is something else.
+     *
+     * `global_stmt_content` names if_expr directly; `local_stmt_content` reaches
+     * it through the transparent `arith_expr` wrapper.
+     */
+    protected statementIf(content: any): any | null;
+    protected isStatementPosition(ctx: If_exprContext): boolean;
+    visitIf_expr(ctx: If_exprContext): string;
+    /**
+     * What an if-EXPRESSION evaluates to when no branch runs.
+     *
+     * `na` here, per the manual sentence quoted in `visitIf_expr`. A seam because
+     * v6 changes the answer for a bool-valued `if`: bools may no longer be `na`,
+     * so the unspecified branch yields `false` — which is the "KNOWN GAP" noted
+     * above, closed for the version where TradingView made it the rule.
+     */
+    protected ifFallthrough(_ctx: If_exprContext): string;
+    /**
+     * The `else` branch, already emitted, or null when the `if` has none.
+     *
+     * A seam, not a behaviour: v1 has exactly one shape of else — a block — and
+     * this returns it. v4 adds `else if`, and overrides here rather than
+     * re-implementing `visitIf_expr`, because everything the chain needs is
+     * decided by the code ABOVE this call:
+     *
+     *   - the IIFE wrapper. One `if/else if/else` is ONE expression, so it gets
+     *     one wrapper. A nested `if` visited normally would build its own, and in
+     *     expression position its value would be computed and then dropped.
+     *   - `suppressBlockReturn`. Every block in the chain is at the same depth
+     *     and must make the same return-or-not decision.
+     *
+     * Both are already set when this runs, so an override inherits them for free.
+     */
+    protected emitElseBranch(ctx: If_exprContext): string | null;
+    visitFor_expr(ctx: For_exprContext): string;
+    /**
+     * Rewrites a loop body's OWN trailing `return X` into `<res> = X`.
+     *
+     * Extracted from `visitFor_expr` so `for … in` (v5) can reuse it verbatim.
+     * Every loop in the language is an EXPRESSION whose value is the last
+     * `return_expression` its body evaluated, and a block emits that value as a
+     * `return` — which inside a real JavaScript `for` would leave the enclosing
+     * function instead.
+     *
+     * ── Why nesting alone is not enough ─────────────────────────────────────
+     *
+     * The body can contain whole FUNCTIONS — an if-expression emits
+     * `(() => { … })()`, and its returns belong to that function, not to the
+     * loop. Ranking by brace depth and taking the shallowest picked one of them
+     * whenever the loop had no trailing return of its own, which is exactly the
+     * case for a statement-`if` body:
+     *
+     *     v = if high > low
+     *             1
+     *         else
+     *             2
+     *
+     * came out as `if (…) { return 1; } else { _res0 = 2; }`, so the else branch
+     * assigned the LOOP's result variable and the expression evaluated to
+     * undefined. Silent: no error, just an `na` on every bar that took the else.
+     *
+     * So function bodies are tracked separately from plain blocks, and only a
+     * return at function depth 0 can be the loop's.
+     */
+    protected captureLoopResult(rawBody: string, res: string): string;
+    /**
+     * A `break`/`continue` that had to leave a function boundary (a v5 `switch`
+     * is emitted as one) arrives as a thrown loop signal; the loop whose body
+     * this is is the one it is for when no loop opened in between. Every loop
+     * form wraps its body with this, `while` included.
+     */
+    protected catchLoopSignals(body: string): string;
+    visitStmts_block(ctx: Stmts_blockContext): string;
+    visitTernary_expr(ctx: Ternary_exprContext): string;
+    visitOr_expr(ctx: Or_exprContext): string;
+    visitAnd_expr(ctx: And_exprContext): string;
+    /**
+     * The operator BETWEEN operand `i - 1` and operand `i`, in a flat chain.
+     *
+     * ── Why not ctx.MUL(i - 1) ────────────────────────────────────────────────
+     *
+     * Because that indexes the list of MUL tokens, not the position in the
+     * expression. In `a * b / c` there is one DIV and it is `DIV(0)`, so asking
+     * `MUL(1) ? "*" : DIV(1) ? "/" : "%"` for the second operator finds neither
+     * and falls through to MODULO:
+     *
+     *     a * b / c    →    (a * b) % c
+     *
+     * Silent, and wrong for every mixed `*`/`/` chain — which is most of them.
+     * `a > b < c` and `a != b == c` had the same defect for the same reason.
+     *
+     * ANTLR alternates children operand, operator, operand, so operand `i` is
+     * preceded by the operator at `i * 2 - 1`. `visitAdd_expr` below already read
+     * it that way; these did not.
+     */
+    protected operatorBefore(ctx: ParserRuleContext, index: number): string;
+    /**
+     * `a == b` / `a != b`.
+     *
+     * Routed through a helper rather than emitted as a bare operator, because
+     * every variable is a Series OBJECT and JavaScript compares two objects by
+     * REFERENCE:
+     *
+     *     x = 1.0
+     *     y = 1.0
+     *     equal = x == y      // false, at every version
+     *
+     * `<`, `>`, `<=` and `>=` coerce through `valueOf` unconditionally, and a
+     * comparison against a literal has only one object in it, so this was the one
+     * shape that reached the reference test — and it was silently, permanently
+     * false. See `safe_eq` for why the helper compares loosely after unwrapping
+     * rather than strictly.
+     */
+    visitEq_expr(ctx: Eq_exprContext): string;
+    visitCmp_expr(ctx: Cmp_exprContext): string;
+    visitAdd_expr(ctx: Add_exprContext): string;
+    visitMult_expr(ctx: Mult_exprContext): string;
+    /**
+     * "v5: Division of two const int values truncates (5/2 = 2). Any input,
+     * simple, or series int keeps the remainder (2.5)." — the v6 migration
+     * guide, describing v5, and TradingView's own log agrees: `5 / 2` logs 2,
+     * while `input.int(5) / 2` and a series 5 / 2 log 2.5
+     * (conformance/common/v5_gaps_golden.test.ts).
+     *
+     * v1-v4 do the same (probes v1..v4-int-div: `1 / 3` is 0, `-7 / 2` is -3,
+     * `7 / 2.0` is 3.5, `bar_index / 7` keeps its fraction).
+     *
+     * Decided per operator, left to right: the chain so far must be a constant
+     * int, and so must the divisor. A seam rather than a flag, because v6
+     * reverses the rule and V6ToJsVisitor overrides `truncatesConstIntDivision`.
+     */
+    protected emitMultOp(left: string, op: string, right: string, ctx: Mult_exprContext, index: number): string;
+    /** v1 through v5 truncate; see emitMultOp. */
+    protected truncatesConstIntDivision(): boolean;
+    visitUnary_expr(ctx: Unary_exprContext): string;
+    /**
+     * Statements to emit immediately before the script-level statement being
+     * visited, or null outside one. Filled by `hoistHistoryBase`.
+     */
+    protected globalPrelude: string[] | null;
+    /**
+     * v2/v3 (any base) and v4 (call-free base) compute the base of `(expr)[n]`
+     * on EVERY bar when it sits in an `if`/`for` body, so TradingView reads true
+     * per-bar history there (v5/v6 carry the last value instead). Checked with
+     * Pine Logs: dev-docs/tv-parity/_probes/version-scope/ (v2-runtime,
+     * v3-runtime, v4-runtime, v6-expr-hist, v3-call-in-if).
+     *
+     * Returns the name of a series written every bar, emitted before the
+     * outermost script-level statement, or null when the hoist is not legal:
+     * not in a body, inside a function body, or a base that reads anything
+     * declared in a block, a loop counter, or a global not yet declared. Those
+     * cases are UNVERIFIED on TradingView and keep the carried series.
+     */
+    protected hoistHistoryBase(ctx: Sqbr_exprContext, base: string, id: string): string | null;
+    /**
+     * `hlc3[1]`, `strategy.equity[1]`: a built-in series keeps its history on
+     * every bar, wherever the `[n]` sits. Emitted in place, the read is a getter
+     * call that only runs when its `if`/`for`/function body does, so the series
+     * had holes (`na`) on the bars the body skipped. Writing it before the
+     * script-level statement records it on every bar (probes:
+     * dev-docs/tv-parity/_probes/hlc3, sizing).
+     *
+     * Returns null when the base is not a bare built-in getter, there is no
+     * statement to hoist to, or it sits in a `security` argument (evaluated in
+     * the other context).
+     */
+    /**
+     * User functions called (directly or through another user function) from
+     * inside a `security` call's arguments. Filled by visitPine_script.
+     */
+    protected securityFunctions: ReadonlySet<string>;
+    protected collectSecurityFunctions(root: ParseTree): Set<string>;
+    protected hoistBuiltinHistory(ctx: Sqbr_exprContext, base: string): {
+        tmp: string;
+        key: string;
+    } | null;
+    visitSqbr_expr(ctx: Sqbr_exprContext): string;
+    visitAtom(ctx: AtomContext): string;
+    visitFun_call(ctx: Fun_callContext): string;
+    /**
+     * Emit a security() call with the `expression` argument deferred as a thunk
+     * `() => (expr)`, so the runtime can evaluate it in the HTF sub-context.
+     * Every other argument (symbol, resolution, gaps, lookahead) is eager.
+     *
+     * KEYWORD ARGUMENTS ARE INCLUDED. This method used to read `pos_args()` only,
+     * which silently discarded them:
+     *
+     *     security(tickerid, "D", close, lookahead=barmerge.lookahead_off)
+     *
+     * emitted no `lookahead` at all, so `resolveLookahead` in
+     * runtime/v1/stdlib/mtf.ts never saw an explicit value and always applied the
+     * version default. That made the documented per-call escape hatch unreachable,
+     * and a v2 script asking for `lookahead_off` silently got `on` — the exact
+     * behaviour the v2→v3 default flip exists to distinguish.
+     *
+     * `ctx.call` maps the keyword object onto positional slots by name, so the
+     * object is appended unchanged and `expression=` is deferred wherever it lands.
+     */
+    protected emitSecurity(ctx: Fun_callContext): string;
+    /** Emit a study()/strategy() directive as a metadata declaration. */
+    protected emitDirective(kind: string, ctx: Fun_callContext): string;
+    visitFun_actual_args(ctx: Fun_actual_argsContext): string;
+    /**
+     * The positional arguments of a call, in order.
+     *
+     * A seam, not a behaviour. v1's `pos_args` is a list of `arith_expr`, and v4
+     * widens it so a BRACKETED LIST can be one — `security(sym, tf,
+     * [close, open])` and `input.string("FQ", "Period", ["FQ", "FH"])`. The
+     * generated context therefore exposes `pos_arg()` at v4 and `arith_expr()`
+     * before it, and every place that walks the argument list has to ask the
+     * same question.
+     */
+    protected positionalArgs(ctx: Pos_argsContext): any[];
+    visitPos_args(ctx: Pos_argsContext): string;
+    visitKw_args(ctx: Kw_argsContext): string;
+    visitKw_arg(ctx: Kw_argContext): string;
+    visitLiteral(ctx: LiteralContext): string;
+    visitNum_literal(ctx: Num_literalContext): string;
+    visitOther_literal(ctx: Other_literalContext): string;
+    /**
+     * The namespace roots this version knows — `strategy`, `barstate`, `color`, …
+     * Derived from the version's own registry, so v4's extra roots appear only
+     * there. Cached: it is a scan of ~250 keys and `visitId` runs constantly.
+     */
+    private namespaceRootCache;
+    protected get namespaceRoots(): ReadonlySet<string>;
+    /**
+     * Is this identifier the NAME of a keyword argument rather than a read?
+     *
+     * `plot(close, title = "x")` reaches visitId twice: once for `close`, which
+     * is a variable read, and once for `title`, which is the callee's parameter
+     * name. Any check hooked on visitId sees both and must not treat the second
+     * as a variable — no script declares `title`.
+     */
+    protected isKeywordArgumentName(ctx: IdContext): boolean;
+    /**
+     * Reject a read of a name that nothing declares — the extension point.
+     *
+     * Lives at v1 so that v1 and v2 — which TradingView states are the same
+     * language, and which conformance/v1_equals_v2.test.ts asserts over the whole
+     * corpus — reject the same scripts. `bound` rather than `declared` is the
+     * right question: v1 and v2 both permit forward references.
+     *
+     * ── Why this exists ─────────────────────────────────────────────────────
+     *
+     * visitId's fallback emits `opsv2_<name>` for anything it does not
+     * recognise. Through `with(sandbox)` an unrecognised name is not a Pine
+     * diagnostic but a JavaScript ReferenceError on the first bar:
+     *
+     *     opsv2_last_bar_index is not defined
+     *
+     * which reads as an engine crash. TradingView answers `Undeclared identifier`
+     * at compile time. Dotted names already had a guard here ("'chart' is not a
+     * namespace"); bare ones had none, so every unimplemented built-in surfaced
+     * as a crash. Running TradingView's own documentation corpus turned up 45
+     * scripts failing that way.
+     */
+    /**
+     * Is a binding of `name` in scope at the point it is READ?
+     *
+     * "The global scope is all of the script that is not inside a function, if
+     *  statement, or other conditional structure ... Only code that is in the
+     *  same local scope can access a local variable."
+     *
+     * Answered by token span rather than by nesting depth, because the question
+     * is about two POSITIONS: a name bound inside one `if` is invisible inside
+     * the `if` beside it, and those are at the same depth. See `scopesOf`.
+     *
+     * A name the analysis pass records no scope for is treated as visible. That
+     * is the safe direction — a binding form the pass does not model yet makes
+     * this check silent rather than making it reject working code.
+     */
+    protected visibleAt(name: string, ctx: IdContext): boolean;
+    protected checkUndeclaredRead(name: string, ctx: IdContext): void;
+    /**
+     * A member of a KNOWN namespace that this version does not have.
+     *
+     * The mirror of `checkUndeclaredRead`, and it existed for neither reason nor
+     * design: an unknown BARE name was rejected, while an unknown MEMBER of a
+     * real namespace fell through to `opsv2_syminfo.opsv2_nonesuch` and read as
+     * `undefined` on every bar. Nothing said so. `color.from_gradient` at v2 — a
+     * v4 addition — compiled, and every colour computed from it was `na` forever.
+     *
+     * Split by whether the name exists at ALL, because the two are different
+     * problems: `syminfo.tickerid` at v2 is a MIGRATION question with a version
+     * for an answer, and `syminfo.nonesuch` is a typo.
+     *
+     * Overridable because v5 has dotted names that are not namespace members —
+     * fields, enum members, library calls — and resolves those first.
+     */
+    protected checkNamespaceMember(root: string, text: string, ctx: IdContext): void;
+    /**
+     * The registry key of the VARIABLE, for a name this version also gives to a
+     * function. `undefined` when the name means only one thing.
+     *
+     * A read resolves to the variable and a call to the function, which is what
+     * Pine's separate namespaces do. Only `tickerid` needs it, and only at v1-v3
+     * — see the comment at the use site.
+     */
+    protected variableSpelling(name: string): string | undefined;
+    visitId(ctx: IdContext): string;
+}
+export {};