@elaraai/east-codex-plugin 1.0.90 → 1.0.92
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.build/daemon/lsp.js +122 -13
- package/.build/daemon/server.js +122 -13
- package/.codex-plugin/plugin.json +1 -1
- package/index.json +844 -799
- package/package.json +1 -1
- package/skills/east-py/SKILL.md +58 -53
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@elaraai/east-codex-plugin",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.92",
|
|
4
4
|
"description": "East programming language ecosystem - a statically typed, expression-based language for business logic, data processing, UI definitions, and durable execution",
|
|
5
5
|
"license": "AGPL-3.0-or-later",
|
|
6
6
|
"type": "module",
|
package/skills/east-py/SKILL.md
CHANGED
|
@@ -102,10 +102,12 @@ platform = East.platform_functions(__name__) # pass to East.compile(fn, platfo
|
|
|
102
102
|
A body's parameters are expressions already. A python scalar or `datetime` inside
|
|
103
103
|
a body lifts to a literal; `East.value(v, T)` / `b.const(v)` lift anything else
|
|
104
104
|
(TS `East.value` / `$.const`); an East COLLECTION an `East.function` body closes
|
|
105
|
-
over is snapshot into the IR
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
105
|
+
over is snapshot into the IR as a literal of its contents, rebuilt wherever the
|
|
106
|
+
body reads it — `t = b.const(table)` builds it once per call, and `.bind(table)`
|
|
107
|
+
as a trailing parameter keeps it live. The other way, an artifact is a plain
|
|
108
|
+
callable on values, every eager method accepts one (a VALUE takes no block),
|
|
109
|
+
and one called inside another body is a call of its inline Function node — see
|
|
110
|
+
[Python values vs East expressions](#python-values-vs-east-expressions).
|
|
109
111
|
|
|
110
112
|
## Decision Tree: What Do You Need?
|
|
111
113
|
|
|
@@ -140,7 +142,7 @@ Task → What do you need?
|
|
|
140
142
|
│ ├─ Call python from a body → the @East.platform_function you hold IS the Platform node (no declaration) · East.platform /
|
|
141
143
|
│ │ asyncPlatform / genericPlatform only for one implemented elsewhere · East.compile(fn, platform=East.platform_functions(__name__))
|
|
142
144
|
│ │ → "Declare, implement, build, compile", "Platform functions"
|
|
143
|
-
│ ├─ Make it fast → data stays in East · chain ·
|
|
145
|
+
│ ├─ Make it fast → data stays in East · chain · bind shared work with b.const · b.const a captured table, .bind big ones
|
|
144
146
|
│ │ → "Performance — the levers, ranked"
|
|
145
147
|
│ ├─ IR ↔ python → to_python_source · east-py transpile · compile_from_beast2 / json / east / value · east-c ir … → "IR ↔ python"
|
|
146
148
|
│ ├─ Refusals at edit time → east-py lint · flake8 --select EAS · east-py lsp; TYPE errors → east-py check
|
|
@@ -171,9 +173,10 @@ Task → What do you need?
|
|
|
171
173
|
│ └─ Let East call python → @East.platform_function · @East.generic_platform_function · @memoize → "Platform functions"
|
|
172
174
|
│
|
|
173
175
|
├─ C. Cross between them → a body's parameters are expressions · python scalars and datetimes lift · East.value(v, T) /
|
|
174
|
-
│ b.const(v) · a captured East collection is a build-time SNAPSHOT
|
|
175
|
-
│ live · an East function is a callable on
|
|
176
|
-
│
|
|
176
|
+
│ b.const(v) · a captured East collection is a build-time SNAPSHOT, a literal rebuilt at each read (an eager callback
|
|
177
|
+
│ refuses it) — b.const(table) builds it once per call, .bind(table) keeps it live · an East function is a callable on
|
|
178
|
+
│ values, and a VALUE takes no block · east.runtime.compiler.eager_stats() shows how a hot call ran
|
|
179
|
+
│ → "Python values vs East expressions", "Performance"
|
|
177
180
|
│
|
|
178
181
|
└─ D. Run a program from the shell → east-py run (IR + input files → a result) · exec (a unit: the runner protocol e3
|
|
179
182
|
speaks) · convert (a beast2 value → East text) · version · where its time goes: --profile / EAST_PROFILE=1
|
|
@@ -313,12 +316,12 @@ artifact used as an `East.if_else` arm evaluates only when that arm is taken,
|
|
|
313
316
|
an error inside it names its own lines, and a profile lists it as an entry of
|
|
314
317
|
its own, placed where it was written and where it was called. (One called with
|
|
315
318
|
arguments narrower than its parameters — a column projection's narrowed rows —
|
|
316
|
-
re-runs its source in its own frame and splices in instead
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
319
|
+
re-runs its source in its own frame and splices in instead.) An artifact that
|
|
320
|
+
mutates or raises, called and DISCARDED, is the build's "evaluated and thrown
|
|
321
|
+
away" error — spell it `b.do(push(xs))` / `East.block(push(xs), result)`, as
|
|
322
|
+
with any mutation. An artifact that calls platform functions stays first-class
|
|
323
|
+
(composable, serializable) but raises until `East.compile` pairs it with
|
|
324
|
+
implementations.
|
|
322
325
|
`East.function(...)` spelled INSIDE a body is the inline `Function` node, a
|
|
323
326
|
Function-typed expression: bind it with `b.const`, hand it to a callback slot,
|
|
324
327
|
or call it (a `Call`; in an `East.asyncFunction`, calling an async one is a
|
|
@@ -516,7 +519,7 @@ East values. A worked example is in
|
|
|
516
519
|
| `East.while_(state, cond, body, label=…)` | `While` | `cond(b, s) -> Boolean`, `body(b, s) -> next state` |
|
|
517
520
|
| `East.for_(coll, state, body, label=…)` | `ForArray`/`ForSet`/`ForDict` | Array `body(b, s, el[, i])`, Set `body(b, s, el)`, Dict `body(b, s, k, v)` |
|
|
518
521
|
| `East.block(a, b, …)` | `Block` | evaluates in order, yields the last — the sequencing point for mutators (`East.block(lambda b: …)` is the statement form) |
|
|
519
|
-
| `East.let(value, fn)` | `Let` | `fn(b, bound)` — bind once, use many times (
|
|
522
|
+
| `East.let(value, fn)` | `Let` | `fn(b, bound)` — bind once, use many times, inside an expression body (`b.const` is the statement form) |
|
|
520
523
|
| `East.ref(v)` | `NewRef` | a cell — `.get()` / `.update(v)` / `.merge(v, fn(b, current, patch))` |
|
|
521
524
|
| `East.label(name=None)` | — | names a loop, for `break_`/`continue_` from a NESTED one |
|
|
522
525
|
| `East.break_(state=…, label=…)` / `East.continue_(state=…, label=…)` | `Break` / `Continue` | leave / next iteration, optionally committing a last state |
|
|
@@ -539,10 +542,10 @@ counts = East.for_(rows, {"counts": East.new_dict(StringType, IntegerType)},
|
|
|
539
542
|
```
|
|
540
543
|
|
|
541
544
|
⚠️ Seed accumulators with `East.new_array/new_set/new_dict`. A captured
|
|
542
|
-
`EastArray(T)` works too — a
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
545
|
+
`EastArray(T)` works too — a captured collection is a snapshot of its
|
|
546
|
+
contents, rebuilt wherever the body reads it, so a seed is fresh per call —
|
|
547
|
+
but mutating one anywhere ELSE changes a copy nothing else sees, and the
|
|
548
|
+
build raises rather than compile a mutation that persists nowhere.
|
|
546
549
|
|
|
547
550
|
### Queries — `East.jq`
|
|
548
551
|
|
|
@@ -625,34 +628,39 @@ element**.
|
|
|
625
628
|
crossing per element — convert at most once, at the very end.
|
|
626
629
|
2. **Let the callbacks build, and chain on the results** — a chain of
|
|
627
630
|
`map`/`filter`/`reduce` stays native between steps. Return a dict literal
|
|
628
|
-
(`lambda b, r: {"a": …, "b": …}`) to derive every column in ONE pass. **
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
631
|
+
(`lambda b, r: {"a": …, "b": …}`) to derive every column in ONE pass. **Bind
|
|
632
|
+
shared work with `b.const`** — the builder emits exactly what the body
|
|
633
|
+
spells, as TypeScript's does, so a python variable holding an expression is
|
|
634
|
+
re-emitted (and re-evaluated) at every read: `fields = r.data.split("|")`
|
|
635
|
+
read for 30 columns runs the split 30 times per row, and `table =
|
|
636
|
+
derive(rec)` read inside a `.map` runs `derive` once per element. `fields =
|
|
637
|
+
b.const(r.data.split("|"))` and `table = b.const(derive(rec))` run each
|
|
638
|
+
once, as `$.const` does — the `no-reinlined-east-binding` rule (`east-py
|
|
639
|
+
lint`, the LSP) points at every such read. There is no optimisation pass
|
|
640
|
+
(#1312 removed the trace-time CSE: it moved reads across mutations it could
|
|
641
|
+
not see), so what you write is what runs — a callback that pushes onto
|
|
642
|
+
`order` and returns `order.size() - 1` reads the size after its push.
|
|
643
|
+
3. **Side tables: `b.const` a captured one, `bind` big ones** — opposite contracts:
|
|
639
644
|
- **Capture (snapshot).** A collection captured by an `East.function` body
|
|
640
|
-
is snapshot into its IR
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
645
|
+
is snapshot into its IR as a literal of its contents — exactly as a
|
|
646
|
+
TypeScript literal is — and rebuilt wherever the body reads it: per call
|
|
647
|
+
at the function's top level, per element inside a callback. **Bind it
|
|
648
|
+
once per call with `t = b.const(TABLE)`** and read `t`. Right for small
|
|
649
|
+
tables (up to a few thousand entries): the literal's size rides the IR,
|
|
650
|
+
every call rebuilds it, and later mutations are **not** seen. Only an
|
|
644
651
|
EXPLICIT build snapshots: an eager callback refuses a mutable capture.
|
|
645
652
|
- **`East.function(...).bind(table)` (by reference, live).** Declare the
|
|
646
|
-
table as a trailing parameter and pre-bind it: zero copy, O(1) at any
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
`TypeError`.
|
|
653
|
+
table as a trailing parameter and pre-bind it: zero copy, O(1) at any
|
|
654
|
+
size, nothing rebuilt per call, and the function **sees later
|
|
655
|
+
mutations**. Rebinding gives independent callables, the unbound function
|
|
656
|
+
stays usable, and a wrong-typed value raises `TypeError`.
|
|
651
657
|
|
|
652
658
|
```python
|
|
653
659
|
fx = EastDict(StringType, FloatType, rates) # small table → capture
|
|
654
|
-
|
|
655
|
-
|
|
660
|
+
@East.function([Row], FloatType) # (the EXPLICIT build
|
|
661
|
+
def to_usd(b, r): # opts into the snapshot)
|
|
662
|
+
t = b.const(fx) # the literal, once per call
|
|
663
|
+
return r.amount * t.get_or_default(r.ccy, 1.0)
|
|
656
664
|
|
|
657
665
|
TableT = DictType(StringType, FloatType) # huge table → bind
|
|
658
666
|
conv = East.function([Row, TableT], FloatType,
|
|
@@ -684,7 +692,7 @@ REBUILDS it through the surface above:
|
|
|
684
692
|
|
|
685
693
|
```python
|
|
686
694
|
from east.codegen import to_python_source
|
|
687
|
-
print(to_python_source(classify)) # `@East.function(
|
|
695
|
+
print(to_python_source(classify)) # `@East.function(...)` / `def main(b, …)`
|
|
688
696
|
```
|
|
689
697
|
|
|
690
698
|
```bash
|
|
@@ -793,6 +801,7 @@ The rules — `east-py lint --list-rules` prints them:
|
|
|
793
801
|
| `no-python-string-building` (EAS023, warning) | an f-string assembling an East string CONSTANT — a regex, a template, a key | spell the constant out |
|
|
794
802
|
| `no-derived-struct-fields` (EAS024, warning) | `Derived = StructType([… for f in Other.value])` | a type declaration is a wire format — spell the fields |
|
|
795
803
|
| `no-python-data-work` (EAS025, warning) | a python helper doing parse / strip / null-check / coerce work on an EXPRESSION a body hands it | express it in East, where it runs on every row |
|
|
804
|
+
| `no-reinlined-east-binding` (EAS026, warning) | a python local holding an EXPRESSION (`n = xs.size()`, not a `b.let`/`b.const` binding) read more than once in one body, or read inside a per-element callback, a loop body or a nested function below the body that bound it | each read re-emits — and re-evaluates — the expression: bind it once, `n = b.const(xs.size())`, where it is needed (the TypeScript rule of the same name) |
|
|
796
805
|
|
|
797
806
|
Configure it once in the project's `pyproject.toml`; every surface reads it, and
|
|
798
807
|
`east-py lint`'s own flags add to it:
|
|
@@ -815,10 +824,7 @@ A file that does not import `east` is never diagnosed; a line ending in `# noqa`
|
|
|
815
824
|
`node_modules`, `dist`, `build`, `.git`, `__pycache__`, `tests` and `test` are not
|
|
816
825
|
walked. The rules are syntactic, so a clean `lint` is necessary, not sufficient —
|
|
817
826
|
the type errors live behind `east-py check`. The rules are disjoint (each
|
|
818
|
-
mistake is one rule's to report).
|
|
819
|
-
purpose: `no-reinlined-east-binding` warns that a JS `const` holding an `Expr`
|
|
820
|
-
re-inlines it at each use, but the python build's CSE binds a reused python local
|
|
821
|
-
to ONE `Let`, so the hazard does not exist here.
|
|
827
|
+
mistake is one rule's to report).
|
|
822
828
|
|
|
823
829
|
### Cross-language functions: `east-py export-functions` and `East.import_function`
|
|
824
830
|
|
|
@@ -837,12 +843,11 @@ from east.types.types import FloatType, StructType, IntegerType
|
|
|
837
843
|
Row = StructType([("qty", IntegerType), ("price", FloatType)])
|
|
838
844
|
score = East.function([Row], FloatType, lambda b, r: r.qty.to_float() * r.price)
|
|
839
845
|
east_functions = {"score": score} # name -> East.function artifact. CLOSED values: the
|
|
840
|
-
# exported IR must BIND every name it reads. A
|
|
841
|
-
#
|
|
842
|
-
#
|
|
843
|
-
#
|
|
844
|
-
#
|
|
845
|
-
# variable is refused BY NAME
|
|
846
|
+
# exported IR must BIND every name it reads. A captured
|
|
847
|
+
# lookup table or a stdlib format string is a literal in
|
|
848
|
+
# the body and closes over nothing; a .bind result (no IR
|
|
849
|
+
# of its own) and an unresolved import are refused, and a
|
|
850
|
+
# genuinely free variable is refused BY NAME
|
|
846
851
|
```
|
|
847
852
|
|
|
848
853
|
```typescript
|
|
@@ -1639,7 +1644,7 @@ CUTOFF = 100
|
|
|
1639
1644
|
@East.function([Row], FloatType)
|
|
1640
1645
|
def usd(b, r):
|
|
1641
1646
|
return East.if_else(r.amount > CUTOFF, # a scalar constant lifts (TS East.value)
|
|
1642
|
-
r.amount * RATES.get_or_default(r.ccy, 1.0), # an EXPLICIT build snapshots the dict
|
|
1647
|
+
r.amount * RATES.get_or_default(r.ccy, 1.0), # an EXPLICIT build snapshots the dict: a literal, rebuilt per call
|
|
1643
1648
|
0.0)
|
|
1644
1649
|
|
|
1645
1650
|
rows.map(lambda b, r: r.amount * RATES.get_or_default(r.ccy, 1.0)) # ❌ an eager callback REFUSES
|