@kernlang/python 3.5.2

package/README.md

@@ -0,0 +1,26 @@
+# @kernlang/python
+
+[![npm](https://img.shields.io/npm/v/@kernlang/python?color=cb3837&label=npm)](https://www.npmjs.com/package/@kernlang/python)
+[![license](https://img.shields.io/badge/license-AGPL--3.0-blue)](https://github.com/KERNlang/kern/blob/main/LICENSE)
+
+Kern FastAPI Python backend transpiler
+
+Part of the [KERN monorepo](https://github.com/KERNlang/kern).
+
+## Install
+
+```bash
+npm install @kernlang/python
+```
+
+## Usage
+
+```ts
+import { transpileFastAPI } from '@kernlang/python';
+
+const pythonCode = transpileFastAPI(kernSource);
+```
+
+## License
+
+AGPL-3.0

package/dist/codegen-body-python.d.ts

@@ -0,0 +1,152 @@
+/** Native KERN handler-body codegen — Python target (slices 1–3).
+ *
+ *  Mirror of `packages/core/src/codegen/body-ts.ts` for the FastAPI/Python
+ *  target. Walks the children of a handler with `lang=kern` and emits Python
+ *  body lines. Recognized statements:
+ *
+ *    - `let name=X value="EXPR"` — `X = EXPR` (slice 1)
+ *    - `return value="EXPR"` / bare `return` (slice 1)
+ *    - `if cond="EXPR"` / sibling `else` — `if EXPR:\n    body\nelse:\n    body` (slice 2c).
+ *    - `while cond="EXPR"` — `while EXPR:\n    body`
+ *    - `for name=i from=0 to="List.length(xs)"` — `for i in range(...)`
+ *      `else > if(…)` and `else > [if(…), else_inner]` collapse to `elif EXPR:` so
+ *      raw `elif` chains round-trip byte-equivalent through slice 5b migration.
+ *
+ *  Statement-level propagation `?` lowers to:
+ *
+ *      __k_t1 = await call()
+ *      if __k_t1.kind == 'err':
+ *          return __k_t1
+ *      u = __k_t1.value
+ *
+ *  Slice 3 additions:
+ *    - Body emit returns `{ code, imports }`. The generator uses the imports
+ *      set to inject `import math` (etc.) at the top of the function body,
+ *      so `Number.floor`/`ceil`/`round` lowerings work without surfacing
+ *      a `NameError: math`.
+ *    - `BodyEmitOptions.symbolMap` renames KERN identifiers to their
+ *      Python-form equivalents at codegen time. The FastAPI generator builds
+ *      a `userId → user_id` map from the param list so KERN bodies that
+ *      reference `userId` resolve correctly against the snake_cased Python
+ *      signature. Identifiers absent from the map pass through unchanged.
+ *    - Optional-chain lowering for `member` (slice 3d): `a?.b` Python-lowers
+ *      to `(a.b if a is not None else None)`. The receiver must be
+ *      side-effect-free (ident or pure member chain); calls/awaits in the
+ *      receiver throw with a let-bind hint to avoid double-evaluation.
+ *
+ *  Indentation: Python is whitespace-significant, so the recursive walk
+ *  threads a `indent` string. The propagation hoist embeds its own 4-space
+ *  relative indent on the `return __k_tN` line; the wrapper prepends the
+ *  surrounding indent so the post-emit result nests correctly. */
+import type { IRNode, ValueIR } from '@kernlang/core';
+/** Slice 3e — caller-provided options for the Python body emitter.
+ *  Currently only `symbolMap`; future slices may add diagnostics, source-map
+ *  hooks, or per-handler config. Keep this open-ended so 3a/3b/3d/future
+ *  surface extensions can extend without breaking the call-site contract. */
+export interface BodyEmitOptions {
+    /** Slice 3a — KERN-identifier → Python-identifier rename map. The FastAPI
+     *  generator passes `userId → user_id` (etc.) so a body that references
+     *  the KERN-form `userId` resolves to the snake_cased Python parameter.
+     *  Identifiers not in the map pass through unchanged. */
+    symbolMap?: Record<string, string>;
+    /** Slice 4a review fix (Gemini #5) — how to lower the `?` propagation
+     *  hoist's err-branch return:
+     *    - 'value' (default for `fn`): `return __k_tN` so the caller sees
+     *      the err Result and can chain. Matches slice 1 semantics.
+     *    - 'http-exception' (FastAPI routes): `raise HTTPException(500,
+     *      detail=__k_tN.error)` so route handlers don't accidentally
+     *      return a 200 OK with an err body. The route emitter is
+     *      responsible for adding `from fastapi import HTTPException`
+     *      to the file's imports when this style is used.
+     *  The route emitter walks `usedPropagation` in the result to know
+     *  whether the import is actually required. */
+    propagateStyle?: 'value' | 'http-exception';
+    /**
+     * IR-semantics differential harness opt-in (PR-3b). When `eachIterNext`
+     * is true, the `each` loop emits a `_kern_trace({"op":"iter-next", ...})`
+     * call as the FIRST statement inside each iteration — symmetric with
+     * TS body-ts.ts. Production codegen never sets this. See
+     * packages/core/src/ir/semantics/python-leg.ts for the runtime contract.
+     */
+    traceHooks?: {
+        eachIterNext?: boolean;
+    };
+}
+/** Slice 3e — public return shape. `code` is the joined body text;
+ *  `imports` is the per-handler set of import identifiers
+ *  (e.g., `'math'` ⇒ `import math`) that the generator must emit at the
+ *  top of the function body before the code.
+ *
+ *  Slice 4a review fix — `usedPropagation` is true iff the body emitted at
+ *  least one `?` propagation hoist. Callers using `propagateStyle:
+ *  'http-exception'` use this signal to decide whether to add `from
+ *  fastapi import HTTPException` to the route file's imports.
+ *
+ *  PR-4 — `helpers` carries runtime helper function definitions the body
+ *  references (e.g. `_kern_pairs` / `_kern_async_pairs` for `each` pair-mode
+ *  normalization). Consumers must emit each entry at module scope BEFORE the
+ *  body's function definition so the helpers are in scope when the body
+ *  runs. Set semantics give de-dup for free across multiple handlers in the
+ *  same module. */
+export interface BodyEmitResult {
+    code: string;
+    imports: Set<string>;
+    usedPropagation: boolean;
+    helpers: Set<string>;
+}
+/** PR-4 — Python helpers that normalize `each` pair-mode iteration sources.
+ *  Co-located with the codegen so the production emitter and the differential
+ *  harness use byte-identical definitions; consumers emit the string at module
+ *  scope when `BodyEmitResult.helpers` is non-empty.
+ *
+ *  Semantics:
+ *    - `_kern_pairs(v)`: yields `(k, v)` tuples. Uses `v.items()` when present
+ *      (Mapping shapes — dict, OrderedDict, custom Mapping subclasses); falls
+ *      back to `iter(v)` so an iterable of `[k, v]` pairs (list/tuple) also
+ *      destructures cleanly. Matches JS `for (const [k, v] of arrayOfPairs)`
+ *      expressiveness — this is the divergence-1 fix from PR-3b audit.
+ *    - `_kern_async_pairs(v)`: async generator. If `v` has `__aiter__` it
+ *      forwards each item. Otherwise it falls back to `_kern_pairs(v)` so
+ *      `async for` over a sync Mapping or array-of-pairs is well-defined —
+ *      this is the divergence-2/3 fix (`async for` no longer requires an
+ *      async iterable; sync data is wrapped at iteration entry).
+ *
+ *  Both helpers are pure functions on the input; no captures, no globals. */
+export declare const KERN_PAIR_HELPERS_PY: string;
+/** Emit the body of a native KERN handler as Python source. Returns the
+ *  joined body text. Each top-level line is unindented; nested `if`-bodies
+ *  carry one level of 4-space indent per level of nesting.
+ *
+ *  Legacy slice 1/2 signature — returns just the code string. Callers
+ *  that also need the import set (slice 3b: `math` etc.) and/or want to
+ *  pass a symbol map (slice 3a: `userId → user_id`) should use
+ *  `emitNativeKernBodyPythonWithImports`.
+ *
+ *  Slice 3 review fix (OpenCode + Gemini): if the handler requires imports
+ *  (e.g. `Number.floor` ⇒ `math`) and the legacy entry point is used,
+ *  the imports would be silently discarded — the generated Python would
+ *  reference `__k_math.floor(...)` without the matching `import math as
+ *  __k_math`, producing a `NameError` at runtime. Throw instead so the
+ *  caller upgrades to the WithImports variant rather than shipping
+ *  broken code. */
+export declare function emitNativeKernBodyPython(handlerNode: IRNode, options?: BodyEmitOptions): string;
+/** Slice 3e — context-aware variant returning `{ code, imports }`. The
+ *  FastAPI generator uses this to inject `import math` (etc.) at the top
+ *  of the function body and to pass the param-rename map (3a) so the body
+ *  resolves correctly against the snake_cased Python signature.
+ *
+ *  Slice 4a review fix — also returns `usedPropagation` so the route
+ *  emitter can conditionally add `from fastapi import HTTPException`
+ *  when `propagateStyle: 'http-exception'` is in effect. */
+export declare function emitNativeKernBodyPythonWithImports(handlerNode: IRNode, options?: BodyEmitOptions): BodyEmitResult;
+/** Slice-1 ValueIR → Python expression. Covers the surface that body-ts.ts
+ *  emits today; later slices extend per the spec.
+ *
+ *  Slice 3 — accepts an `options` bag so callers can supply a `symbolMap`
+ *  (3a) without having to construct a `BodyEmitContext` directly. Imports
+ *  are still collected during the walk but are not surfaced to the caller
+ *  via this entry point — use `emitNativeKernBodyPythonWithImports` when
+ *  you need the imports set. The internal recursive callers go through
+ *  `emitPyExprCtx` which threads the live ctx (and therefore the live
+ *  imports set) end-to-end. */
+export declare function emitPyExpression(node: ValueIR, options?: BodyEmitOptions): string;