pineforge-codegen 0.10.4__tar.gz → 1.0.0__tar.gz

pineforge_codegen-1.0.0/CHANGELOG.md

@@ -0,0 +1,245 @@
+# Changelog
+
+Release notes for `pineforge-codegen`. From 1.0.0 on, versions of codegen and
+[`pineforge-engine`](https://github.com/pineforge-4pass/pineforge-engine) are
+supported as exact pairs; on the 0.x line they are independent. See the
+[pairing rule](README.md#engine-pairing).
+
+## Release note policy
+
+- Keep a section for each released version, including prereleases. Use the exact
+  tag version and release date when published; leave a planned release marked
+  **Unreleased** until its tag exists.
+- Summarize changes users can observe: the Python and JSON contract, emitted C++
+  and engine requirements, support or warning changes, packaging, and security
+  fixes. Link the merged pull requests that supply each change.
+- Call out migration steps and compatibility limits explicitly. A pair change
+  requires regenerated C++ and relinked strategy libraries, even when the C
+  ABI number is unchanged.
+- Draft from merged changes since the previous release tag, then verify against
+  the release commit. A prerelease note describes changes since the preceding
+  prerelease or stable tag; the final stable note consolidates the series.
+
+## 1.0.0 — Unreleased
+
+This is the proposed 1.0 release note. It covers the changes merged to `main`
+since 0.10.4 (2026-09-06), through
+[#152](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/152). The
+release lane sets the version and date after the matching engine release is
+ready. Codegen `1.0.0` supports only engine `v1.0.0`; `1.0.0-rc.1` supports
+only engine `v1.0.0-rc.1`. Until then, `main` builds only against engine
+`main`. The notes of 0.10.4 and earlier releases are on the
+[GitHub releases page](https://github.com/pineforge-4pass/pineforge-codegen-oss/releases).
+
+### Compatibility and execution
+
+- Generated strategies use the engine's `PineStrategyHost` source layer and
+  explicitly attach Pine execution policies and cap compatibility
+  ([#127](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/127),
+  [#128](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/128),
+  [#129](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/129)).
+  Regenerate C++ and relink libraries for the exact engine pair.
+- Reused strategy handles reset persistent generated state before a new run
+  ([#126](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/126)).
+  Price-less `strategy.exit` follows the bracket-cancel command and the
+  first-tick predicate uses its accessor
+  ([#130](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/130)).
+- A `strategy()` that omits `initial_capital`, `default_qty_type` or
+  `default_qty_value` gets TradingView's Pine v6 defaults (100,000,
+  `strategy.percent_of_equity`, 100); before, the engine's own defaults
+  applied (1,000,000 and 1 contract)
+  ([#147](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/147)).
+  Such a script sizes its orders differently and can book different trades;
+  declare the arguments to keep the old sizing.
+- `time()` / `time_close()` with a nonzero `bars_back` or
+  `timeframe_bars_back` read another bar's time through the engine host's
+  `pine_time_offset`, which the paired engine provides
+  ([#152](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/152)).
+
+### Pine translation and diagnostics
+
+- Replace Python expression execution in constant folding with bounded
+  evaluation ([#125](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/125)).
+  Preserve `na` when double-valued expressions enter integer slots
+  ([#131](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/131)).
+- Inline `input.*()` TA lengths use the same reset and override path as bound
+  inputs ([#133](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/133)).
+  `ta.change` receives its lookback in `compute()`, and input titles are
+  escaped consistently
+  ([#134](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/134)).
+- Input overrides reach precalculated TA sites; `ta.valuewhen`, VWAP anchors,
+  input keys, and Pine string escapes follow the validated spellings
+  ([#135](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/135)).
+  TA arguments are routed by signature; multiline strings, nested input keys,
+  generic `input()` lengths, and formatted `log.*` calls are covered
+  ([#136](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/136)).
+- Bare `ta.tr`, located parser errors, TradingView numeric text,
+  `str.format(formatString=...)`, string-safe trace pragmas, and the native
+  floating-point contraction flag are pinned by tests
+  ([#138](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/138)).
+  The paired TA1 engine handles ALMA `floor`, KC `useTrueRange`, explicit
+  VWAP anchors, and pivot-level anchors/developing values
+  ([#139](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/139)).
+- `na` follows Pine's rules wherever the generated C++ converts a value: it
+  is false in `if`, `?:`, `and`/`or` and boolean parameters, an integer
+  conversion of `na` stays `na`, and stored booleans and dynamic series
+  indices keep it. Keltner Channel middle bands are `na` until their length
+  is warm, as on TradingView. Standalone `ta.ema` warmup, collection history
+  and a nullable `str.repeat` result, which the engine cannot yet represent
+  exactly, now warn
+  ([#140](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/140)).
+- An inverted `array.fill` range leaves the array unchanged and an inverted
+  `array.slice` raises TradingView's runtime error, as on TradingView; every
+  `array.slice` warns that PineForge copies the slice where TradingView
+  aliases it. `request.security` resolves a chart-symbol name by lexical
+  scope, so a function-local rebind no longer blocks an unrelated global
+  ([#140](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/140)).
+  A `?:` symbol that can select another symbol warned there; see the next
+  section for what it does since #148.
+
+### Libraries and requests for outside data
+
+- Pine library imports are inlined at transpile time: pass the sources as
+  `transpile(..., libraries={"user/name/version": source})`, or let the
+  script's own requests manifest pin them (`$PINEFORGE_PINE_LIBRARIES` with
+  `$PINEFORGE_REQUESTS_ROOT`). Only what the script reaches is inlined, and a
+  v5 library is lowered by v5's rules or refused naming the rule it would
+  need ([#148](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/148)).
+  An import whose alias is `ta`, `math` or `str` and that names only that
+  namespace's built-ins is a no-op
+  ([#146](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/146)).
+  Any other import without a source is still refused.
+- A `request.security` of another symbol whose value can reach a trade reads
+  the feed a requests manifest pins for that symbol, and stops the run where
+  its value is read when none is installed; it never reads the chart's bars in
+  its place. A `?:` symbol that
+  can select another symbol and whose value can reach a trade registers the
+  symbol the run computes
+  ([#148](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/148)).
+- `request.financial`, `request.earnings`, `request.dividends` and
+  `request.splits` read the per-bar series a requests manifest records, and a
+  `request.security` whose expression is `request.footprint(ticks, va)` reads
+  the pinned feed's delta column
+  ([#148](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/148)).
+  Without that data, a request whose value reaches only plots, alerts, tables
+  or logs lowers to `na` with a warning, and one that can reach a trade stops
+  the run where its value is read
+  ([#146](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/146)).
+- A `request.security` symbol, timeframe or payload parameter that reaches the
+  request through helper functions resolves on every call path, one context
+  per value
+  ([#146](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/146),
+  [#148](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/148)).
+  Payloads accept helpers with mixed tuples, multi-statement bodies and `var`
+  state ([#144](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/144)),
+  read `input.source` values and `hl2`-family history on the requested bars,
+  register a computed lower timeframe with its first-bar value, keep epochs in
+  64 bits ([#146](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/146)),
+  and run helper `for` / `while` loops and a global's history on the requested
+  bars ([#152](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/152)).
+
+### Sessions
+
+- `session.ismarket`, `session.ispremarket` and `session.ispostmarket` read the
+  engine's session calendar and in-session facts, and `session.isfirstbar` /
+  `islastbar` and their `_regular` forms read the engine's session-day members
+  ([#142](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/142),
+  [#145](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/145),
+  [#150](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/150)).
+  Inside a `request.security` payload they keep time-of-day predicates and
+  warn. `session.<flag>[k]` reads the flag's history
+  ([#144](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/144)).
+
+### Values that came out silently wrong
+
+- Pine's `int` is 64-bit: constant arithmetic such as `400 * 7200000` folds in
+  64 bits, and an integer sum or product whose operands' known bounds can
+  leave the 32-bit range (`days * 86400000`), or a product that `%` or `/`
+  reads, is computed in 64 bits
+  ([#149](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/149),
+  [#151](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/151),
+  [#152](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/152)).
+- Inputs are read before `var` initializers
+  ([#144](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/144)),
+  and a `var` read with history initializes at its declaration
+  ([#149](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/149)).
+- `fixnan` and 17 other built-in argument slots evaluate their argument once, a
+  function returns its last statement's value, and a script variable read
+  with history inside a function reads that call site's history
+  ([#146](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/146)).
+  An `if` without `else` that runs no arm is `na`
+  ([#148](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/148)).
+- A deleted or collected drawing reads as `na`, and drawings are collected
+  as TradingView collects them
+  ([#146](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/146)).
+- `color.new` / `color.rgb` bind a keyword transparency like a positional one
+  ([#151](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/151)),
+  and a fractional input or series transparency rounds to the nearest alpha
+  byte as TradingView's does, where it was truncated
+  ([#150](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/150)).
+  A fractional constant `color.new` transparency, which TradingView
+  truncates, now rounds too: a known divergence (10.5 reads back 11 where
+  TradingView reads 10).
+- A function whose untyped parameter receives different types gets one body
+  per call site
+  ([#151](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/151)).
+- A binary operator evaluates its left operand first when the other operand
+  can observe its effect
+  ([#147](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/147)).
+
+### Other translation changes
+
+- A `ta.*` length fixed for the run builds the constant-length indicator on
+  its first execution, and a series length of `ta.highest`, `ta.lowest`,
+  `ta.highestbars` or `ta.lowestbars` re-windows every call, and
+  `ta.supertrend` takes a series factor or ATR length and reads the values of
+  its first execution, as TradingView does; a series length of any other
+  `ta.*` stays refused
+  ([#144](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/144)).
+- A `switch` arm written on its `=>` line may be a comma list of statements,
+  library overloads that differ by qualifier bind as TradingView binds them, a
+  generic `input()` takes its default's type, and `syminfo.timezone` spells a
+  UTC exchange zone `Etc/UTC`
+  ([#152](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/152)).
+- A script that declares `use_bar_magnifier = true` exports
+  `strategy_declares_bar_magnifier()` to the host, and `syminfo.mincontract`
+  reads the symbol fact the run declares
+  ([#146](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/146)).
+
+### Limits and generated names
+
+- Untrusted source that would crash or hang the transpiler raises a located
+  `CompileError`: source over 5 MiB (TradingView's 5MB compilation request),
+  nesting over 512 levels, or a transpilation over 120 seconds (TradingView's
+  compile limit). There is no statement-count limit. A 500-link `?:` chain, a
+  500-branch `else if` ladder and a 2,000-element `array.from` transpile and
+  compile; deeply nested calls no longer take exponential time.
+  `transpile()` raises Python's recursion limit to 20,480 frames when it is
+  lower. Numeric literals outside the C++ range raise a located error
+  ([#140](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/140)).
+- A Pine name that is a C++17/C++20 keyword, a standard macro or an engine
+  name (for example `namespace`, `NULL` or `Box`) compiles: the generated C++
+  spells it `pf_safe_<name>`, for variables, parameters, types, fields and
+  tuple or loop bindings alike
+  ([#140](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/140)).
+  A script name that equals a host member the generated class reads is
+  escaped too
+  ([#144](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/144)).
+
+### Packaging and documentation
+
+- Update the direct build-tool `tar` dependency past the reported advisories
+  and require a high-severity npm audit in release and publish gates
+  ([#140](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/140)).
+- Limit the Python source archive to package code and release documents so a
+  VCS-free RC build cannot include installed Node dependencies or generated
+  gate payloads
+  ([#140](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/140)).
+- One `VERSION` value gives every channel its spelling: a prerelease such as
+  `1.0.0-rc.1` ships as PyPI `1.0.0rc1`, on npm dist-tag `next` and as a
+  GitHub prerelease, never as `latest`
+  ([#141](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/141)).
+- Document the supported Python and gate/glue JSON contract, exact engine
+  pairing, contribution checks, and release-note policy. Classify the package
+  as Production/Stable for the 1.0 release
+  ([#140](https://github.com/pineforge-4pass/pineforge-codegen-oss/pull/140)).

pineforge_codegen-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing to pineforge-codegen
+
+This is the source-available PineScript v6 to C++ translator. Read the
+[license and contribution terms](LEGAL.md) before sending a material change.
+Contributions use the Developer Certificate of Origin: add a `Signed-off-by`
+line with `git commit -s`. Material contributions also require a Contributor
+License Agreement so PineForge can include them in its commercial license;
+contact luis@4pass.com.tw before opening a material pull request.
+
+## Local setup
+
+Use Python 3.11 or newer, Node 22, a C++17 compiler, CMake, and a matching
+[`pineforge-engine`](https://github.com/pineforge-4pass/pineforge-engine)
+checkout. Clone codegen and engine as siblings, then install the development
+dependencies from this repository:
+
+```bash
+python -m pip install -e '.[dev]'
+npm ci
+```
+
+Build the paired engine outside its source checkout if you need compile and
+runtime tests. This example enables the source layer (the default) and limits
+the build to four jobs:
+
+```bash
+cmake -S ../pineforge-engine -B /tmp/pineforge-engine-build \
+  -DCMAKE_BUILD_TYPE=Release -DPINEFORGE_BUILD_TESTS=OFF \
+  -DPINEFORGE_BUILD_SOURCE_LAYER=ON
+cmake --build /tmp/pineforge-engine-build -j4
+```
+
+If CMake fetches Eigen, its headers are under the build tree's
+`_deps/eigen-src`; a system Eigen install is also fine. The engine corpus is
+the engine's `corpus` submodule
+([`pineforge-corpus`](https://github.com/pineforge-4pass/pineforge-corpus)),
+and the 1m feed the E2E tests replay is stored in Git LFS:
+
+```bash
+git -C ../pineforge-engine submodule update --init corpus
+git -C ../pineforge-engine/corpus lfs pull
+```
+
+The corpus test skips when it cannot find that tree, and the E2E tests skip
+when the feed is missing or still an LFS pointer, so inspect skip reasons
+before treating a run as complete.
+
+## Engine pairing
+
+Codegen `main` is developed and tested against engine `main`; its generated
+C++ does not compile against any engine release yet. On the 0.x line the two
+version lineages are independent: the released codegen 0.10.4 pairs with
+engine `v0.13.1`, the pair the
+[`pineforge-release`](https://github.com/pineforge-4pass/pineforge-release)
+image `v0.1.25` ships.
+
+From 1.0.0 on, a released codegen `X.Y.Z` is supported only with engine tag
+`vX.Y.Z`, using that release's generated headers and `libpineforge.a`.
+Prereleases match exactly too: codegen `1.0.0-rc.1` requires engine
+`v1.0.0-rc.1`. Do not pair different patch or prerelease tags, even if
+`PF_ABI_VERSION` is equal.
+
+On **every** pair change, rerun codegen on the Pine source, then rebuild and
+relink each generated strategy translation unit against the new pair's headers
+and static library. Replacing only the library, or recompiling old generated
+C++, is not a supported migration. Development branches can test against
+paired in-progress engine commits, but that does not create a supported
+cross-version release pair. See the [public contract](docs/PUBLIC_CONTRACT.md).
+
+## Required checks
+
+Point the test harness at the engine source, its generated header, runtime
+archive, Eigen headers, and public corpus. Adjust these paths for your build:
+
+```bash
+export PINEFORGE_ENGINE_INCLUDE=../pineforge-engine/include
+export PINEFORGE_GENERATED_INCLUDE=/tmp/pineforge-engine-build/include
+export PINEFORGE_ENGINE_LIB=/tmp/pineforge-engine-build/lib/libpineforge.a
+export PINEFORGE_EIGEN_INCLUDE=/tmp/pineforge-engine-build/_deps/eigen-src
+export PINEFORGE_ENGINE_CORPUS=../pineforge-engine/corpus
+export CXX=/usr/bin/c++
+python -m pytest -ra
+python -m pytest -ra tests/test_compile_corpus.py
+```
+
+The full suite includes the corpus sweep; run the corpus command separately so
+its coverage and result are visible. A green suite with compile or E2E skips
+does not verify generated C++ against the engine. If you change engine C++
+headers or sources, rebuild the engine before rerunning these checks. The
+current item count is determined by `python -m pytest --collect-only -q`, not
+by a fixed number in this guide.
+
+Check the Pyodide package and native/Pyodide parity as well:
+
+```bash
+npm ci
+npm audit --audit-level=high
+npm run gate:selftest
+GATE_FULL=1 node gate/run-gate.mjs
+```
+
+The full gate writes `release.json` and the validated archive consumed by
+`node scripts/build-npm-package.mjs`. For release packaging checks, install
+the Python `build` frontend, run `python -m build`, assemble the npm payload,
+then run `npm pack --dry-run` from `npm/`. These commands build local artifacts;
+publishing is a separate release operation.
+
+## Change and review notes
+
+- Add or update tests for behavior changes. Keep the engine corpus compiling;
+  an intentional support drop needs the rationale required by [AGENTS.md](AGENTS.md).
+- If existing scripts emit different C++, list the affected public-corpus
+  translation units and whether their trades move when run with the matching
+  engine.
+- Keep [CHANGELOG.md](CHANGELOG.md) current for user-visible changes. Its
+  release-note policy applies to both stable and prerelease tags.
+- The README describes `main` against the latest release and becomes the PyPI
+  page of the next one: when a version is tagged, update its "Releases and
+  this README" section, its engine-pairing table and its release markers.

{pineforge_codegen-0.10.4 → pineforge_codegen-1.0.0}/LEGAL.md

@@ -17,7 +17,7 @@ A pure-Python PineScript v6 → C++ transpiler that emits source against the pub
 
 ## Third-party components
 
-The transpiler has **no runtime dependencies** (one function, `transpile()`). Development/test extras declared in `pyproject.toml` (`pytest`, etc.) are under their own upstream licenses. The opt-in compile checks invoke a C++ compiler against the separately-licensed Apache-2.0 engine headers; they skip cleanly without an engine checkout.
+The transpiler has **no runtime dependencies** (`transpile()` and `transpile_full()` are its supported Python entry points). Development/test extras declared in `pyproject.toml` (`pytest`, etc.) are under their own upstream licenses. The opt-in compile checks invoke a C++ compiler against the separately-licensed Apache-2.0 engine headers; they skip cleanly without an engine checkout.
 
 ## Trademarks and affiliation
 
@@ -25,7 +25,7 @@ The transpiler has **no runtime dependencies** (one function, `transpile()`). De
 
 ## Contributions
 
-Contributions are accepted under a Developer Certificate of Origin (`Signed-off-by`). Because this project is **dual-licensed** (source-available + a sold commercial license), material contributions require a Contributor License Agreement granting PineForge the right to include the contribution in the commercial license; otherwise it cannot be accepted. See `CONTRIBUTING` (or contact luis@4pass.com.tw) before opening a material PR.
+Contributions are accepted under a Developer Certificate of Origin (`Signed-off-by`). Because this project is **dual-licensed** (source-available + a sold commercial license), material contributions require a Contributor License Agreement granting PineForge the right to include the contribution in the commercial license; otherwise it cannot be accepted. See [CONTRIBUTING.md](CONTRIBUTING.md) (or contact luis@4pass.com.tw) before opening a material PR.
 
 ## No warranty