pineforge-codegen 0.6.5__py3-none-any.whl

pineforge_codegen/analyzer/contracts.py

@@ -0,0 +1,163 @@
+"""Output data structures emitted by the analyzer (its contract with the codegen).
+
+These dataclasses form the contract that ``Analyzer.analyze()`` exports
+to the codegen. Pulling them into a sibling module breaks the
+``base`` <-> ``call_handlers`` import cycle: previously
+``analyzer/base.py`` imported ``CallHandlers`` from
+``analyzer/call_handlers.py`` and ``call_handlers.py`` imported
+``FuncInfo`` / ``TACallSite`` / ``FixnanCallSite`` / ``SecurityCallInfo``
+back from ``base.py``. Putting the dataclasses here gives a strict
+DAG (``call_handlers``, ``base``, ``__init__`` all import from
+``contracts``; nothing reaches back).
+
+The module is named ``contracts.py`` rather than the more obvious
+``dataclasses.py`` so it does NOT shadow Python's stdlib
+``dataclasses`` module.
+
+Adding new analyzer outputs: append a new ``@dataclass`` here and
+re-export it through ``analyzer/__init__.py``. Do NOT define them on
+``Analyzer.base`` — that's how the cycle drifts back in.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..symbols import TypeSpec
+
+
+@dataclass
+class TACallSite:
+    """One ``ta.*`` function call-site -> one C++ member instance."""
+    member_name: str           # e.g., "_ta_rsi_1"
+    class_name: str            # e.g., "ta::RSI"
+    ctor_args: list[str]       # e.g., ["14"]
+    compute_args: list         # AST nodes for compute() call args
+    returns_tuple: bool        # e.g., MACD, supertrend
+    node: Any = None           # the FuncCall AST node
+    is_static: bool = False    # true if global scope & arguments are recursively static
+
+
+@dataclass
+class FuncInfo:
+    """Resolved info for a Pine function (or UDT instance method)."""
+    name: str
+    param_types: list          # list of PineType
+    return_type: Any           # PineType
+    node: Any = None           # the FuncDef AST node
+    returns_tuple: bool = False
+    tuple_element_count: int = 0
+    # UDT instance methods: name is "TypeName.methodName"; node is synthetic FuncDef.
+    is_udt_method: bool = False
+    udt_type_name: str | None = None
+    # Parallel to ``node.params``; each entry is the AST default expression
+    # for that parameter, or ``None`` if no default was declared. Currently
+    # populated only for UDT instance methods so codegen can fill in
+    # missing args at the call site (see
+    # ``data/validation/udt-method-probe-04-default-param``).
+    param_defaults: list = field(default_factory=list)
+    # When the function's body returns a UDT instance (last expression is
+    # ``TypeName.new(...)`` for a user-defined type), this is the UDT
+    # struct name. The codegen uses it to (a) emit the function's C++
+    # return type as ``Sample`` instead of the generic ``double`` fallback
+    # and (b) thread the UDT through to the caller's symbol table so
+    # ``Sample s = build_sample(...)`` then ``s.score()`` dispatches
+    # correctly. Probe: data/validation/udt-method-probe-20-udt-return-from-func.
+    udt_return_type: str | None = None
+
+
+@dataclass
+class FixnanCallSite:
+    """Per-call-site state for ``fixnan(...)`` (one previous-value member each)."""
+    member_name: str           # e.g., "_prev_fixnan_1"
+    pine_type: Any             # PineType
+
+
+@dataclass
+class MutableGlobalInfo:
+    """Bookkeeping for a global variable that the codegen may need to shadow inside ``request.security`` evaluators."""
+    name: str
+    pine_type: Any
+    is_series: bool = False
+    is_var: bool = False
+    decl_node: Any = None
+    source_stmts: list = field(default_factory=list)
+
+
+@dataclass
+class SecurityCallInfo:
+    """Resolved metadata for one ``request.security(...)`` /
+    ``request.security_lower_tf(...)`` call-site.
+
+    ``is_lower_tf_array`` distinguishes the two builtins. When true the
+    codegen lowers the call to a ``std::vector<T>`` accumulator (one
+    element per synthesised lower-TF sub-bar of the current chart bar)
+    rather than a scalar ``_req_sec_<id>``; the runtime side rejects
+    the call at validation time if the requested TF is not strictly
+    finer than the chart's input TF."""
+    sec_id: int
+    timeframe: Any
+    expression: Any
+    returns_tuple: bool
+    tuple_size: int
+    gaps: Any = None
+    lookahead: Any = None
+    ta_range: Any = None
+    depends_on_mutable_globals: bool = False
+    mutable_globals: tuple[str, ...] = ()
+    is_lower_tf_array: bool = False
+
+
+@dataclass
+class AnalyzerContext:
+    """Output bundle of the analyzer; consumed by the codegen.
+
+    Keep a single class instead of a dict so consumers can rely on
+    typed attribute access. Fields with mutable defaults use
+    ``field(default_factory=...)`` so multiple ``Analyzer`` runs
+    don't share state."""
+    ast: Any                   # Program node
+    symbols: Any               # SymbolTable
+    ta_call_sites: list = field(default_factory=list)
+    series_vars: set = field(default_factory=set)
+    series_bar_fields: set = field(default_factory=set)
+    var_members: list = field(default_factory=list)   # [(name, PineType, init_expr_str)]
+    func_infos: list = field(default_factory=list)
+    fixnan_sites: list = field(default_factory=list)
+    strategy_params: dict = field(default_factory=dict)
+    diagnostics: list = field(default_factory=list)    # warnings
+    filename: str = "<stdin>"
+    global_var_decls: list = field(default_factory=list)  # [(name, PineType)] non-var global scope vars
+    global_expr_map: dict = field(default_factory=dict)   # name -> defining AST expr (global, non-var)
+    var_member_init_exprs: dict = field(default_factory=dict)  # var-member name -> init AST expr
+    # Per-call-site TA member cloning for user functions:
+    func_ta_ranges: dict = field(default_factory=dict)    # func_name -> (start_idx, end_idx)
+    func_call_cs_map: dict = field(default_factory=dict)  # call_node_id -> (func_name, call_site_index)
+    func_call_site_counts: dict = field(default_factory=dict)  # func_name -> int
+    # UDT / enum definitions:
+    udt_defs: dict = field(default_factory=dict)          # type_name -> {field_name: PineType}
+    enum_defs: dict = field(default_factory=dict)         # enum_name -> [member names]
+    enum_member_strings: dict = field(default_factory=dict)  # enum_name -> [str values]
+    # request.security calls (see SecurityCallInfo):
+    security_calls: list = field(default_factory=list)
+    global_mutable_infos: dict = field(default_factory=dict)  # name -> MutableGlobalInfo
+    # Per-function var_members + series_vars (used when emitting per-function call-site variants):
+    func_var_members: dict = field(default_factory=dict)
+    func_series_vars: dict = field(default_factory=dict)
+    # var_name -> UDT type name for variables instantiated via TypeName.new(...)
+    udt_var_types: dict[str, str] = field(default_factory=dict)
+    # var_name -> structured collection/UDT type metadata
+    collection_types: dict[str, TypeSpec] = field(default_factory=dict)
+    # UDT name -> field_name -> structured type metadata
+    udt_field_type_specs: dict[str, dict[str, TypeSpec]] = field(default_factory=dict)
+    # ``// @pf-trace name=expr`` pragmas in source order. Populated by
+    # :func:`pineforge_codegen.pragmas.extract_pf_trace_pragmas` from
+    # the original source text and attached after :class:`Analyzer`
+    # finishes (the analyzer never sees pragma expressions because the
+    # lexer strips comments). Codegen iterates this list to emit the
+    # ``if (trace_enabled_) { trace(...); ... }`` block at the bottom
+    # of every ``on_bar()``; an empty list means zero overhead is
+    # emitted. Stored as ``list`` (not ``list[PfTracePragma]``) to
+    # keep this module free of imports back into ``pragmas.py``.
+    pf_trace_pragmas: list = field(default_factory=list)

pineforge_codegen/analyzer/diagnostics.py

@@ -0,0 +1,118 @@
+"""Error / warning emission and diagnostic-string helpers for the analyzer.
+
+The historic ``analyzer.py`` had a small cluster of helpers that
+all dealt with one concern: turning a problem the analyzer noticed
+into a ``Diagnostic`` (warning) or ``CompileError`` (fatal), with
+useful source locations and rough printable forms of expressions.
+This mixin collects them in one place. ``Analyzer`` mixes
+``DiagnosticsHelper`` in alongside the other analyzer mixins.
+
+Mixin contract -- host class must provide the following attributes:
+
+- ``self._diagnostics`` (``list[Diagnostic]``): warning sink that
+  ``_warn`` appends to. Errors are raised as ``CompileError`` and
+  do not pass through this list.
+- ``self._filename`` (``str``): file name used as the fallback
+  ``SourceLocation`` when a caller does not pass one.
+- ``self._symbols`` (``SymbolTable``): consulted by
+  ``_warn_if_unknown_source_id`` to skip the warning when the
+  identifier is a user-defined series variable.
+
+The mixin avoids importing from ``base.py`` to stay free of import
+cycles. ``BAR_FIELDS`` and ``tv_input_choices`` come from sibling
+modules, mirroring how the host class consumes them.
+"""
+
+from __future__ import annotations
+
+from ..ast_nodes import (
+    ASTNode, BinOp, BoolLiteral, FuncCall, Identifier, MemberAccess,
+    NaLiteral, NumberLiteral, StringLiteral, Subscript, Ternary, UnaryOp,
+)
+from ..errors import CompileError, Diagnostic, Level, Phase, SourceLocation
+from .. import tv_input_choices as tv_in
+from .tables import BAR_FIELDS
+
+
+class DiagnosticsHelper:
+    """Diagnostic emission + location + expression-stringification helpers.
+
+    Mixed into ``Analyzer``; not meant to be instantiated standalone.
+    The methods here are the only path the analyzer uses to record a
+    warning or raise a compile error, so keeping them together makes
+    the diagnostic surface easy to audit.
+    """
+
+    def _error(self, message: str, loc: SourceLocation | None = None) -> None:
+        """Raise a compile error."""
+        if loc is None:
+            loc = SourceLocation(file=self._filename, line=1, col=1, end_col=1)
+        diag = Diagnostic(
+            level=Level.ERROR,
+            phase=Phase.ANALYZER,
+            location=loc,
+            message=message,
+        )
+        raise CompileError([diag])
+
+    def _warn(self, message: str, loc: SourceLocation | None = None) -> None:
+        """Record a warning diagnostic."""
+        if loc is None:
+            loc = SourceLocation(file=self._filename, line=1, col=1, end_col=1)
+        diag = Diagnostic(
+            level=Level.WARNING,
+            phase=Phase.ANALYZER,
+            location=loc,
+            message=message,
+        )
+        self._diagnostics.append(diag)
+
+    def _input_diag_loc(self, node: FuncCall, expr: ASTNode | None) -> SourceLocation:
+        if expr is not None and getattr(expr, "loc", None):
+            return expr.loc
+        if node.loc:
+            return node.loc
+        return SourceLocation(file=self._filename, line=1, col=1, end_col=1)
+
+    def _warn_if_unknown_source_id(
+        self, name: str, expr: ASTNode, node: FuncCall,
+    ) -> None:
+        if name in tv_in.INPUT_SOURCE_SERIES_IDS or name in BAR_FIELDS:
+            return
+        sym = self._symbols.resolve(name)
+        if sym is not None and getattr(sym, "is_series", False):
+            return
+        loc = self._input_diag_loc(node, expr)
+        self._warn(
+            f"input defval '{name}' is not a known chart series (open, high, low, close, …); "
+            "verify spelling or use a series variable.",
+            loc,
+        )
+
+    def _expr_to_str(self, node: ASTNode) -> str:
+        """Convert an expression node to a rough string representation."""
+        if isinstance(node, NumberLiteral):
+            return str(node.value)
+        if isinstance(node, StringLiteral):
+            return f'"{node.value}"'
+        if isinstance(node, BoolLiteral):
+            return "true" if node.value else "false"
+        if isinstance(node, NaLiteral):
+            return "na"
+        if isinstance(node, Identifier):
+            return node.name
+        if isinstance(node, MemberAccess):
+            return f"{self._expr_to_str(node.object)}.{node.member}"
+        if isinstance(node, BinOp):
+            return f"{self._expr_to_str(node.left)} {node.op} {self._expr_to_str(node.right)}"
+        if isinstance(node, UnaryOp):
+            return f"{node.op}{self._expr_to_str(node.operand)}"
+        if isinstance(node, FuncCall):
+            args = ", ".join(self._expr_to_str(a) for a in node.args)
+            callee_str = self._expr_to_str(node.callee)
+            return f"{callee_str}({args})"
+        if isinstance(node, Subscript):
+            return f"{self._expr_to_str(node.object)}[{self._expr_to_str(node.index)}]"
+        if isinstance(node, Ternary):
+            return f"{self._expr_to_str(node.condition)} ? {self._expr_to_str(node.true_val)} : {self._expr_to_str(node.false_val)}"
+        return "<?>"

pineforge_codegen/analyzer/tables.py

@@ -0,0 +1,204 @@
+"""Static lookup tables consumed by the analyzer.
+
+The historic ``analyzer.py`` carried these module-level tables at the
+top of the file. Pulling them out into a dedicated module mirrors the
+codegen package layout (``codegen/tables.py``) and gives the future
+analyzer mixins a single place to import from while letting
+``base.py`` stay focused on the ``Analyzer`` class itself.
+
+External consumers (``codegen/base.py``, ``support_checker.py``, and
+external tests) import these names through the package facade
+(``from pineforge_codegen.analyzer import …``); that contract is
+preserved by re-exports in ``analyzer/__init__.py``.
+
+Naming overlap note: ``BAR_FIELDS`` here is a ``set[str]`` of Pine
+identifiers treated as series-of-bar fields by the *analyzer*. The
+codegen package owns a same-named ``BAR_FIELDS`` ``dict[str, str]``
+that maps those identifiers to C++ accessors. The two never share an
+import path (each lives in its own ``tables.py``), so the name reuse
+is a deliberate, parallel-package convention rather than a collision.
+"""
+
+from __future__ import annotations
+
+from ..symbols import PineType
+
+
+# ---------------------------------------------------------------------------
+# TA mapping tables
+# ---------------------------------------------------------------------------
+
+TA_CLASS_MAP = {
+    "sma": "ta::SMA",
+    "ema": "ta::EMA",
+    "rma": "ta::RMA",
+    "rsi": "ta::RSI",
+    "atr": "ta::ATR",
+    "tr":  "ta::TR",
+    "macd": "ta::MACD",
+    "stoch": "ta::Stoch",
+    "crossover": "ta::Crossover",
+    "crossunder": "ta::Crossunder",
+    "cross": "ta::Cross",
+    "highest": "ta::Highest",
+    "lowest": "ta::Lowest",
+    "change": "ta::Change",
+    "supertrend": "ta::Supertrend",
+    "dmi": "ta::DMI",
+    "sar": "ta::SAR",
+    "bb": "ta::BB",
+    "kc": "ta::KC",
+    "wma": "ta::WMA",
+    "hma": "ta::HMA",
+    "stdev": "ta::StdDev",
+    "pivothigh": "ta::PivotHigh",
+    "pivotlow": "ta::PivotLow",
+    # Task 6
+    "sum": "math::Sum",
+    # Task 7 Batch 1
+    "linreg": "ta::Linreg",
+    "percentrank": "ta::PercentRank",
+    "vwma": "ta::VWMA",
+    # Task 7 Batch 2
+    "mom": "ta::Mom",
+    "roc": "ta::ROC",
+    "rising": "ta::Rising",
+    "falling": "ta::Falling",
+    "cci": "ta::CCI",
+    "cum": "ta::Cum",
+    # Task 7 Batch 3
+    "variance": "ta::Variance",
+    "median": "ta::Median",
+    "highestbars": "ta::HighestBars",
+    "lowestbars": "ta::LowestBars",
+    # Batch 4 — remaining TA functions
+    "alma": "ta::ALMA",
+    "swma": "ta::SWMA",
+    "mfi": "ta::MFI",
+    "cmo": "ta::CMO",
+    "tsi": "ta::TSI",
+    "wpr": "ta::WPR",
+    "cog": "ta::COG",
+    "bbw": "ta::BBW",
+    "kcw": "ta::KCW",
+    "barssince": "ta::BarsSince",
+    "valuewhen": "ta::ValueWhen",
+    "correlation": "ta::Correlation",
+    "percentile_nearest_rank": "ta::PercentileNearestRank",
+    "percentile_linear_interpolation": "ta::PercentileLinearInterpolation",
+    # Task 5 — Volume indicators + statistical
+    "vwap": "ta::VWAP",
+    # 3-arg form: ta.vwap(source, anchor, stdev_mult) → tuple [vwap, upper, lower]
+    "vwap_bands": "ta::VWAPBands",
+    "obv": "ta::OBV",
+    "accdist": "ta::AccDist",
+    "nvi": "ta::NVI",
+    "pvi": "ta::PVI",
+    "pvt": "ta::PVT",
+    "wad": "ta::WAD",
+    "wvad": "ta::WVAD",
+    "iii": "ta::III",
+    "mode": "ta::Mode",
+    "range": "ta::Range",
+    "dev": "ta::Dev",
+    "max": "ta::AllTimeMax",
+    "min": "ta::AllTimeMin",
+    "rci": "ta::RCI",
+}
+
+# Which arg index is the period/length (goes to constructor)
+TA_PERIOD_ARG = {
+    "sma": 1, "ema": 1, "rma": 1, "rsi": 1, "atr": 0,
+    "highest": 1, "lowest": 1, "change": 1,
+    "wma": 1, "hma": 1, "stdev": 1,
+    # Task 6
+    "sum": 1,
+    # Task 7 Batch 1
+    "linreg": 1, "percentrank": 1, "vwma": 1,
+    # Task 7 Batch 2
+    "mom": 1, "roc": 1, "rising": 1, "falling": 1, "cci": 1,
+    # cum has no period arg — handled in TA_NO_CTOR
+    # Task 7 Batch 3
+    "variance": 1, "median": 1, "highestbars": 1, "lowestbars": 1,
+    # Batch 4
+    "cmo": 1, "cog": 1, "correlation": 2,
+    "percentile_nearest_rank": 1, "percentile_linear_interpolation": 1,
+    # Task 5
+    "mode": 1, "range": 1, "dev": 1,
+    "rci": 1,
+}
+
+# Functions that return tuples
+TA_TUPLE_RETURNS = {"macd", "supertrend", "dmi", "bb", "kc", "vwap_bands"}
+
+# Functions with multiple constructor args
+TA_MULTI_CTOR = {
+    "macd": [1, 2, 3],      # fast, slow, signal
+    "stoch": [3],            # length (high, low are compute args)
+    "supertrend": [0, 1],    # factor, atr_period
+    "dmi": [0, 1],           # di_length, adx_smoothing
+    "bb": [1, 2],            # length, mult
+    "kc": [1, 2],            # length, mult
+    "sar": [0, 1, 2],        # start, increment, maximum
+    "pivothigh": [0, 1],     # left_bars, right_bars
+    "pivotlow": [0, 1],      # left_bars, right_bars
+    # Batch 4
+    "alma": [1, 2, 3],      # length, offset, sigma
+    "mfi": [1],              # length (src is compute arg, vol implicit)
+    # Pine signature: ta.tsi(source, short_length, long_length) — positions
+    # 1 and 2 carry the lengths that initialize the four nested EMAs;
+    # source flows to compute() at position 0. The previous `[0, 1]` was
+    # copy-paste off-by-one (caught by a TV-anchored sweep that found
+    # engine TSI returning 0.0 for every bar because compute() was being
+    # called with the long_length integer literal as the "source").
+    "tsi": [1, 2],           # short_length, long_length
+    "wpr": [0],              # length
+    "bbw": [1, 2],           # length, mult
+    "kcw": [1, 2],           # length, mult
+    "tr":  [0],              # handle_na (compile-time bool)
+}
+
+# No-state functions (no constructor args, stateless or self-contained)
+TA_NO_CTOR = {"crossover", "crossunder", "cross", "cum", "swma", "barssince", "valuewhen",
+              "max", "min",
+              "obv", "accdist", "nvi", "pvi", "pvt", "wad", "wvad", "iii", "vwap"}
+
+# TA parameter names are now in signatures.py (sigs.get_param_names)
+
+
+# ---------------------------------------------------------------------------
+# Built-in variables
+# ---------------------------------------------------------------------------
+
+BUILTIN_VARS = {
+    # Price
+    "open": PineType.FLOAT, "high": PineType.FLOAT, "low": PineType.FLOAT,
+    "close": PineType.FLOAT, "volume": PineType.FLOAT,
+    # Derived price
+    "hl2": PineType.FLOAT, "hlc3": PineType.FLOAT, "hlcc4": PineType.FLOAT,
+    "ohlc4": PineType.FLOAT,
+    # Bar info
+    "bar_index": PineType.INT, "time": PineType.INT, "time_close": PineType.INT,
+    "last_bar_index": PineType.INT, "last_bar_time": PineType.INT, "timenow": PineType.INT,
+    "time_tradingday": PineType.INT,
+    # Time & date
+    "hour": PineType.INT, "minute": PineType.INT, "second": PineType.INT,
+    "dayofmonth": PineType.INT, "dayofweek": PineType.INT,
+    "month": PineType.INT, "year": PineType.INT, "weekofyear": PineType.INT,
+    # Special
+    "na": PineType.NA,
+}
+
+# Bar-related price fields (these are series that map to bar.* in C++)
+BAR_FIELDS = {"open", "high", "low", "close", "volume", "hl2", "hlc3", "ohlc4", "hlcc4"}
+
+
+# ---------------------------------------------------------------------------
+# Skip functions (visual -- parse but don't generate code)
+# ---------------------------------------------------------------------------
+
+SKIP_FUNCS = {
+    "plot", "plotshape", "plotchar", "plotcandle", "fill", "hline",
+    "bgcolor", "barcolor", "alert", "alertcondition",
+    "max_bars_back",
+}