openpinescript 0.0.0-stage → 0.1.1

package/dist/types/transpiler/common/passes/ScopeAnalysis.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Pre-emit analysis pass.
+ *
+ * Collects facts about the whole script that a single-pass emitter cannot see,
+ * because they depend on code that appears LATER in the file:
+ *
+ *  - which identifiers are declared, and where (forward-reference detection)
+ *  - which identifiers are ever mutated with ':=' (v3 forbids passing those to
+ *    security(), because the HTF sub-evaluation would see the wrong value)
+ *  - which identifiers hold a boolean (v3 forbids implicit bool→number
+ *    arithmetic, and the operand is usually a variable rather than a literal)
+ *
+ * Runs before ToJsVisitor and hands it a read-only ScopeInfo.
+ */
+import type { ParseTree, ParserRuleContext } from "antlr4ng";
+export interface Declaration {
+    line: number;
+    column: number;
+}
+export interface ScopeInfo {
+    /** name → position of its first '=' binding, script scope only. */
+    declared: ReadonlyMap<string, Declaration>;
+    /**
+     * Names assigned with ':=' AT SCRIPT SCOPE.
+     *
+     * Scope-aware for the same reason `declared` is. These were collected
+     * script-wide, so a function local shadowing a global made the global look
+     * mutable, and v3's security() guard rejected valid code:
+     *
+     *     f(z) =>
+     *         src = z
+     *         src := src * 2      // function-local
+     *         src
+     *     src = close             // never mutated
+     *     a = security(tickerid, "D", src)   → "cannot use mutable variable 'src'"
+     */
+    mutated: ReadonlySet<string>;
+    /**
+     * Names whose declared value is statically a boolean, AT SCRIPT SCOPE.
+     *
+     * Same fix, same reason — a function-local `up = close > open` made a global
+     * numeric `up` look boolean and v3's arithmetic guard rejected `up + 1`.
+     *
+     * The trade-off is a false NEGATIVE inside function bodies: bool arithmetic on
+     * a function-local is no longer caught statically. That is the safe direction —
+     * the runtime backstop in the arithmetic helpers still sees it, whereas a false
+     * positive rejects a script outright.
+     */
+    booleans: ReadonlySet<string>;
+    /** user-defined function names. */
+    functions: ReadonlySet<string>;
+    /** all identifiers bound anywhere, including function parameters and loop vars. */
+    bound: ReadonlySet<string>;
+    /**
+     * Names bound INSIDE a function body — parameters and locals.
+     *
+     * A function body runs at CALL time, so a name that is local to a function
+     * says nothing about the lexical position of a same-named global. Without
+     * this, a function whose body declares `src` was reported as forward-
+     * referencing a global `src` declared further down the file, which rejected
+     * valid published code (v3/cci_commodity_channel_index.pine).
+     */
+    functionScoped: ReadonlySet<string>;
+    /**
+     * name → the LOCAL SCOPE of each of its bindings, `null` for a binding at
+     * script scope.
+     *
+     * From the manual's programming FAQ: "The global scope is all of the script
+     * that is not inside a function, if statement, or other conditional
+     * structure", and "only code that is in the same local scope can access a
+     * local variable."
+     *
+     * `bound` and `declared` are flat sets, so a name bound only inside an `if`
+     * block looked declared everywhere. TradingView's own "Scope demo" —
+     *
+     *     if barstate.isconfirmed
+     *         int localValue = close > open ? 1 : -1
+     *     plot(localValue, ...)
+     *
+     * — exists to show that this is an error, and the page names it: "gives an
+     * 'Undeclared identifier' error when we try to access a local variable from
+     * the global scope". Here it emitted `opsv2_localValue`, which `with(sandbox)`
+     * turned into a ReferenceError on the first bar. It was the last such crash
+     * in the whole documentation corpus.
+     *
+     * A SPAN rather than a depth, because visibility is a question about two
+     * positions and not about nesting: a name bound in one block is invisible in
+     * its SIBLING, which is at the same depth.
+     */
+    scopesOf: ReadonlyMap<string, ReadonlyArray<Span | null>>;
+    /**
+     * user function name → how many values its tuple body returns.
+     *
+     * "Programmers can write functions that return multiple values or references
+     *  by using a tuple as the FINAL STATEMENT in the function's body" — so the
+     * arity is a property of the definition and nothing else can supply it. The
+     * destructuring site needs it to check `[a, b] = f()` against `f`, and Pine
+     * permits forward references, so it cannot be read off the emitter's own
+     * left-to-right walk.
+     *
+     * Absent for a function whose last statement is not a `[ ... ]` list, which
+     * is how the destructuring site tells "returns a tuple of the wrong size"
+     * from "does not return a tuple at all".
+     */
+    tupleArity: ReadonlyMap<string, number>;
+    /**
+     * Functions whose body COULD end in a tuple without stating its width —
+     * a call, a switch — so a `[a, b] = f()` against them cannot be refused.
+     */
+    mayReturnTuple: ReadonlySet<string>;
+    /**
+     * name → its Pine TYPE, where that is knowable without evaluating anything.
+     *
+     * v5 dispatches an overloaded method on its receiver: "The underlying type of
+     * each variable determines which overload of `getType()` the compiler will
+     * use." So the compiler needs a type for a bare name, and this is the least
+     * machinery that supplies one.
+     *
+     * Deliberately conservative — it answers "provably this type", not "probably
+     * this type", and is absent for anything it cannot prove. The consumer turns
+     * an absence into a diagnostic that names the overloads it could not choose
+     * between, so a wrong guess is never silently dispatched on.
+     *
+     * Script scope only, for the same reason `booleans` is: a function-local
+     * shadowing a global would otherwise retype the global.
+     */
+    staticTypes: ReadonlyMap<string, string>;
+    /**
+     * name → the initialiser of a bare script-scope `name = expr` binding.
+     *
+     * Only the plain form — no `var`/`varip`, no qualifier, no type — because
+     * that is the one whose constness follows from its initialiser alone.
+     * Consulted by `isConstNumber`, which also requires the name to be bound
+     * once and never reassigned.
+     */
+    inits: ReadonlyMap<string, any>;
+}
+/** Half-open in neither direction: both token indices are inside the scope. */
+export interface Span {
+    start: number;
+    stop: number;
+}
+/**
+ * The width of each way out of an `if` or `switch` that initialises a tuple:
+ * the length of a `[ … ]` it ends in, 1 for a plain expression with no call
+ * in it, and null where the width is not visible here (a call, a loop, a
+ * statement). Nested conditionals contribute their own branches.
+ */
+export declare function branchTupleWidths(node: any): Array<number | null>;
+/**
+ * Is this expression statically known to be a boolean?
+ *
+ * Deliberately conservative — it answers "provably bool", not "possibly bool".
+ * A false negative is caught by the runtime backstop in the arithmetic
+ * helpers; a false positive would reject valid code.
+ */
+export declare function isStaticallyBool(node: any, booleans: ReadonlySet<string>): boolean;
+export declare function analyseScopes(tree: ParseTree | ParserRuleContext): ScopeInfo;

package/dist/types/transpiler/common/passes/TypeRules.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What the emitter can PROVE about the type of an expression, for the type
+ * errors TradingView raises at compile time (v4+): a float stored in an `int`,
+ * a float passed where an `int` length is required.
+ *
+ * Every answer here is "provably", never "probably". A false positive rejects
+ * a script TradingView accepts; a miss leaves the status quo. So anything not
+ * listed below is "unknown", and unknown never produces an error. Narrower than
+ * `isStaticallyNumeric` in ../../v6/rules.ts on purpose: that one answers
+ * "int or float", this one answers "float".
+ */
+import type { ScopeInfo } from "./ScopeAnalysis.js";
+/** Is `node` provably a float? */
+export declare function isProvablyFloat(node: any, scopes: ScopeInfo): boolean;
+/** Is `node` the bare identifier `na`? */
+export declare function isPlainNa(node: any): boolean;
+/**
+ * Is `node` provably a CONSTANT number — a literal, `math.pi`, or `+ - * / %`
+ * over constants, directly or through a script-scope name bound once to one
+ * and never reassigned? TradingView prints a constant float differently from a
+ * series one in v4/v5 `str.tostring` (see runtime/v1/stdlib/str.ts).
+ *
+ * Provably, as everywhere here: anything else — inputs, `syminfo.*`, calls,
+ * ternaries, a name in a function or block — is not constant.
+ */
+export declare function isConstNumber(node: any, scopes: ScopeInfo, seen?: Set<string>): boolean;

package/dist/types/transpiler/common/profiles/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Language profiles — per-version RUNTIME configuration.
+ *
+ * ── SCOPE, AND WHAT USED TO BE HERE ─────────────────────────────────────────
+ *
+ * This file once carried a `restrictions: Set<RestrictionId>` that the emitter
+ * consulted on every guard (`if (!this.restricts("no_reassignment")) return`).
+ * That is gone. Language rules now live in the version that owns them:
+ *
+ *   - SYNTAX differences are grammar files    (grammar/v{N}/PineV{N}Lexer|Parser.g4)
+ *   - EMIT differences are visitor subclasses (transpiler/v{N}/ToJsVisitor.ts)
+ *
+ * A flag table cannot express "v1 has never heard of ':='" — it can only express
+ * "v1 parses ':=' and then complains", which is not what TradingView does.
+ * Inheritance can.
+ *
+ * What remains is configuration the RUNTIME reads at execution time, which has
+ * no parse tree to hang off: banned identifiers and behavioural defaults.
+ *
+ * Sources for every entry: docs/common/VERSIONS.md, which cites
+ * TradingView's official migration guides.
+ */
+import { PineVersion } from "../version.js";
+export interface LanguageProfile {
+    readonly version: PineVersion;
+    /**
+     * Identifiers that must throw when read, mapped to their message.
+     * v1–v3 ban `bar_index` (the v2-era name is `n`); v4+ invert this and ban `n`.
+     */
+    readonly banned: ReadonlyMap<string, string>;
+    readonly defaults: {
+        /** The indicator-declaration directive. v5 renames study() to indicator(). */
+        readonly scriptDirective: "study" | "indicator";
+        /**
+         * security()'s `lookahead` default. Read by runtime/v1/stdlib/mtf.ts.
+         * v1/v2 default to lookahead_on; the v2→v3 migration flipped it to off.
+         *
+         * Only fields with a real consumer belong here — a default nothing reads
+         * lets a test assert the constant against itself and call it coverage.
+         */
+        readonly securityLookahead: "on" | "off";
+        /**
+         * ── v6 behavioural flags ──────────────────────────────────────────────
+         *
+         * Optional, and ABSENT on v1–v5 rather than set to a v5 value. Absence is
+         * what "this version predates the question" looks like, and it keeps the
+         * five earlier profile literals byte-identical — so no v5 script can pick
+         * up a v6 default by way of an edit to a shared helper.
+         *
+         * Each is read in exactly one place, named on the field.
+         */
+        /**
+         * Colour constants whose VALUE changed, keyed by their dotted name.
+         * MG §"Color changes". Read by createStdlib in runtime/v1/stdlib/index.ts.
+         */
+        readonly palette?: Readonly<Record<string, string>>;
+        /**
+         * `time(timeframe)` returns the start of that timeframe's bar, not the
+         * chart bar's own time. Verified for v5 against TradingView's log
+         * (conformance/common/v5_gaps_golden.test.ts). Read by `time()` in
+         * runtime/v1/stdlib/time.ts.
+         */
+        readonly alignsTimeframe?: boolean;
+        /**
+         * `timeframe.period` always carries a multiplier: "D" -> "1D".
+         * MG §"Timeframes must include a multiplier". Read by `period()` in
+         * runtime/v1/stdlib/chart.ts.
+         */
+        readonly timeframeAlwaysMultiplied?: boolean;
+        /**
+         * Array accessors read -1 as the last element. MG §"Negative indices in
+         * arrays". Read by the index check in runtime/v1/stdlib/arrays.ts.
+         */
+        readonly negativeArrayIndices?: boolean;
+        /**
+         * A bool can never be `na`, so history past the start of a bool series is
+         * `false`. MG §"Boolean values cannot be na". Read by Context.get.
+         */
+        readonly boolsCanBeNa?: boolean;
+        /**
+         * How many of the most recent closed trades stay inspectable. Older ones
+         * are "trimmed": `strategy.closedtrades.*()` returns na for them and
+         * `strategy.closedtrades.first_index` names the oldest kept. MG §"Excess
+         * orders are trimmed", detailed on the Strategies page's trade-limit
+         * section. Read by `closed()` in runtime/v1/stdlib/trades.ts.
+         */
+        readonly retainedClosedTrades?: number;
+    };
+}
+export declare const LANGUAGE_PROFILES: Readonly<Record<PineVersion, LanguageProfile>>;
+export declare function profileFor(version: PineVersion): LanguageProfile;
+export declare const DEFAULT_PROFILE: LanguageProfile;
+export declare class UnimplementedVersionError extends Error {
+    readonly version: PineVersion;
+    constructor(version: PineVersion);
+}

package/dist/types/transpiler/common/version.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pine Script version detection.
+ *
+ * The `//@version=N` annotation is a comment, and the ANTLR lexer skips
+ * comments — so detection happens here, in a pre-parse scan of the raw source,
+ * rather than in the grammar.
+ *
+ * TradingView treats a script with no annotation as v1.
+ */
+export type PineVersion = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Versions this engine can PARSE an annotation for. Not the same as the
+ * versions it can run — see LANGUAGE_PROFILES[v].implemented for that.
+ */
+export declare const KNOWN_VERSIONS: readonly PineVersion[];
+/** A script with no //@version annotation is Pine Script v1. */
+export declare const DEFAULT_VERSION: PineVersion;
+export declare function registerImplementedVersions(versions: readonly PineVersion[]): void;
+/**
+ * Exported so the profiles module can name what really runs without importing
+ * transpiler/common/index.ts, which imports profiles — the same cycle
+ * `registerImplementedVersions` exists to avoid.
+ */
+export declare function implementedVersions(): readonly PineVersion[];
+export declare class UnsupportedVersionError extends Error {
+    readonly requested: number;
+    constructor(requested: number, implemented?: readonly PineVersion[]);
+}
+/**
+ * True when the source has a `//@version` line of any form, valid or not. A
+ * script with none is read as v1, which is worth telling its author when the
+ * body is newer.
+ */
+export declare function hasVersionLine(source: string): boolean;
+/**
+ * Reads the `//@version=N` annotation. Returns 1 when absent.
+ * @throws UnsupportedVersionError for a well-formed annotation naming a version
+ *         we do not implement.
+ */
+export declare function detectVersion(source: string): PineVersion;