@kernlang/core 3.4.6 → 3.4.7-canary.100.1.95f0eb11

package/dist/schema.js

@@ -30,6 +30,14 @@ export const NODE_SCHEMAS = {
             code: { kind: 'rawBlock' },
         },
     },
+    comment: {
+        description: 'Native body comment preserved during raw-handler migration. `raw=` may keep a host-style single-line comment; `text=` emits a target-native line comment.',
+        example: 'comment text="explain the early return"',
+        props: {
+            raw: { kind: 'string' },
+            text: { kind: 'string' },
+        },
+    },
     type: {
         description: 'TypeScript type alias — union of string literals, or alias to another type (including tuple types like [string, number]). Use generics="<T>" for parameterised aliases.',
         example: 'type name=Status values="active|inactive|banned"',
@@ -211,7 +219,16 @@ export const NODE_SCHEMAS = {
             // Validated by parser-validate-effects.ts; see docs/language/effects-pure-spec.md.
             effects: { kind: 'string' },
         },
-        allowedChildren: ['handler', 'signal', 'cleanup', 'overload', 'param'],
+        allowedChildren: ['decorator', 'handler', 'signal', 'cleanup', 'overload', 'param'],
+    },
+    decorator: {
+        description: 'KERN decorator metadata attached to a declaration',
+        example: '@http.get("/users/:id")\nfn getUser(id: string): User',
+        props: {
+            name: { required: true, kind: 'string' },
+            args: { kind: 'string' },
+        },
+        allowedChildren: [],
     },
     machine: {
         description: 'State machine with states and guarded transitions — 12 lines of KERN generates 140+ lines of TypeScript',
@@ -234,6 +251,15 @@ export const NODE_SCHEMAS = {
             debounce: { kind: 'number' },
         },
     },
+    cell: {
+        description: 'Body-statement reactive state cell — KERN-canonical state primitive inside a `handler lang="kern"` body. Read the cell via its `name`; update via `set name=X to=...` or `assign target=X value=...`. Target lowering: TS+React → `const [X, setX] = useState<T>(initial);` (writes auto-rewrite to setter calls). Python+FastAPI → plain mutable `X = initial` (FastAPI per-request handlers don\'t need reactivity; each request resets). Must be a direct child of `handler lang="kern"` — placing it inside `if`/`for`/`while`/`try` violates React\'s Rules of Hooks.',
+        example: 'fn name=Counter\n  handler lang="kern"\n    cell name=count initial=0 type=number\n    set name=count to="count + 1"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            initial: { kind: 'expression' },
+            type: { kind: 'typeAnnotation' },
+        },
+    },
     animation: {
         description: 'Interval-driven state update — generates useEffect with setInterval and auto-cleanup',
         example: 'animation name=frame interval=100 update="(prev) => (prev + 1) % 4"',
@@ -509,10 +535,12 @@ export const NODE_SCHEMAS = {
             'handler',
             'catch',
             'finally',
+            'comment',
             'let',
             'assign',
             'destructure',
             'do',
+            'fmt',
             'return',
             'if',
             'else',
@@ -543,10 +571,12 @@ export const NODE_SCHEMAS = {
         },
         allowedChildren: [
             'handler',
+            'comment',
             'let',
             'assign',
             'destructure',
             'do',
+            'fmt',
             'return',
             'if',
             'else',
@@ -565,9 +595,11 @@ export const NODE_SCHEMAS = {
         example: 'try\n  let name=conn value="acquire()"\n  do value="conn.use()"\nfinally\n  do value="conn.release()"',
         props: {},
         allowedChildren: [
+            'comment',
             'let',
             'assign',
             'do',
+            'fmt',
             'return',
             'if',
             'else',
@@ -1159,14 +1191,14 @@ export const NODE_SCHEMAS = {
         },
     },
     each: {
-        description: 'Iteration — renders children for each item in a collection. Inside a render block emits `items.map(...)` with auto-key; elsewhere emits `for...of`. `let` children become iteration-scoped `const` bindings inside the callback (hook-safe, unlike `derive`). Three forms in body-statement position: (1) `each name=x in=xs` → `for (const x of xs)`; (2) `each name=x index=i in=xs` → `for (const [i, x] of xs.entries())`; (3) `each pairKey=k pairValue=v in=map` → `for (const [k, v] of map)` (TS) / `for k, v in map.items():` (Python). Add `type=` to preserve a TS item binding annotation in body-statement form (`each name=x type=User in=users` → `for (const x: User of users)`). Add `await=true` for async iterables (`for await` / `async for`); it cannot be combined with `index=` and is rejected inside render JSX. Async pair-mode expects an async iterable of pairs, not a mapping (`async for k, v in stream`). In pair-mode `name` is optional. `key=` (render-only) is the React render key, distinct from `pairKey=`.',
+        description: 'Iteration — renders children for each item in a collection. Inside a render block emits `items.map(...)` with auto-key; elsewhere emits `for...of`. `let` children become iteration-scoped `const` bindings inside the callback (hook-safe, unlike `derive`). Body-statement forms: (1) `each name=x in=xs` → `for (const x of xs)`; (2) `each name=x index=i in=xs` → `for (const [i, x] of xs.entries())`; (3) `each pairKey=k pairValue=v in=map` → `for (const [k, v] of map)` (TS) / `for k, v in map.items():` (Python). Use `entries=true` with keyed-entry modes for object/dict entries: `pairKey`/`pairValue` lowers to `Object.entries(obj)` / `obj.items()`, `entryKey` lowers to `Object.entries(obj)` / `obj.keys()`, and `entryValue` lowers to `Object.entries(obj)` / `obj.values()`. Add `type=` to preserve a TS item binding annotation in body-statement form (`each name=x type=User in=users` → `for (const x: User of users)`). Add `await=true` for async iterables (`for await` / `async for`); it cannot be combined with `index=` and is rejected inside render JSX. Async pair-mode expects an async iterable of pairs, not a mapping (`async for k, v in stream`). In keyed-entry modes `name` is optional. `key=` (render-only) is the React render key, distinct from `pairKey=` / `entryKey=`.',
         example: 'each name=f in=files index=i key="f.path"\n  let name=isSel expr="focused && i === selIdx"\n  handler <<<\n    <Text bold={isSel}>{f.path}</Text>\n  >>>',
         props: {
             // `name` is required schema-side for the array-iteration forms; the
-            // pair-mode (`pairKey` + `pairValue`) form relaxes this via a
+            // keyed-entry (`pairKey` + `pairValue`, `entryKey`, `entryValue`) forms relax this via a
             // conditional-required exemption inside `checkRequiredProps` in this
-            // same file. (The `each-pair-mode-body-stmt-only` semantic rule in
-            // semantic-validator.ts is unrelated — it just blocks pair-mode in
+            // same file. (The `each-keyed-mode-body-stmt-only` semantic rule in
+            // semantic-validator.ts is unrelated — it just blocks keyed modes in
             // render/group ancestor scope.)
             name: { required: true, kind: 'identifier' },
             in: { required: true, kind: 'rawExpr' },
@@ -1175,6 +1207,9 @@ export const NODE_SCHEMAS = {
             type: { kind: 'typeAnnotation' },
             pairKey: { kind: 'identifier' },
             pairValue: { kind: 'identifier' },
+            entryKey: { kind: 'identifier' },
+            entryValue: { kind: 'identifier' },
+            entries: { kind: 'boolean' },
             await: { kind: 'boolean' },
         },
         // Intentionally unrestricted — statement-form `each` composes with `derive`,
@@ -1435,16 +1470,22 @@ export const NODE_SCHEMAS = {
         props: {
             code: { kind: 'rawBlock' },
             lang: { kind: 'string' },
+            reason: { kind: 'string' },
+            review: { kind: 'identifier' },
         },
         // Body-statement children apply when `lang="kern"`. Outside that opt-in,
         // body statements are rejected by validateBodyStatements (the schema list
         // is intentionally permissive so the validator can produce a clearer
         // context-aware error).
         allowedChildren: [
+            'cell',
+            'set',
+            'comment',
             'let',
             'assign',
             'destructure',
             'do',
+            'fmt',
             'return',
             'if',
             'else',
@@ -1514,10 +1555,12 @@ export const NODE_SCHEMAS = {
             cond: { required: true, kind: 'expression' },
         },
         allowedChildren: [
+            'comment',
             'let',
             'assign',
             'destructure',
             'do',
+            'fmt',
             'return',
             'if',
             'else',
@@ -1542,10 +1585,12 @@ export const NODE_SCHEMAS = {
             step: { kind: 'expression' },
         },
         allowedChildren: [
+            'comment',
             'let',
             'assign',
             'destructure',
             'do',
+            'fmt',
             'return',
             'if',
             'else',
@@ -2626,8 +2671,9 @@ function checkRequiredProps(node, schema, violations, parent) {
         if (node.type === 'import' && propName === 'from' && parent?.type === 'extern') {
             continue;
         }
-        // each-pair-mode (2026-05-06): `name` becomes optional when both
-        // `pairKey` and `pairValue` are present (Map / iterable-of-pairs form).
+        // keyed-entry modes (2026-05-12): `name` becomes optional when either
+        // pair-mode (`pairKey` + `pairValue`) or one-binding entry-mode
+        // (`entryKey` / `entryValue`) is present.
         // The schema can't express conditional-required, so suppress the
         // `name`-required violation here under that exact shape. Other props
         // (notably `in=`) still error if missing.
@@ -2643,6 +2689,12 @@ function checkRequiredProps(node, schema, violations, parent) {
             props.pairValue.length > 0) {
             continue;
         }
+        if (node.type === 'each' &&
+            propName === 'name' &&
+            ((typeof props.entryKey === 'string' && props.entryKey.length > 0) ||
+                (typeof props.entryValue === 'string' && props.entryValue.length > 0))) {
+            continue;
+        }
         violations.push({
             nodeType: node.type,
             message: `'${node.type}' requires prop '${propName}'`,
@@ -2684,6 +2736,17 @@ function checkCrossProps(node, violations, parent) {
             });
         }
     }
+    if (node.type === 'handler' && ('reason' in props || 'review' in props)) {
+        const lang = typeof props.lang === 'string' ? props.lang.trim().toLowerCase() : '';
+        if (lang === '' || lang === 'kern') {
+            violations.push({
+                nodeType: 'handler',
+                message: '`handler reason=`/`review=` metadata requires an explicit non-kern `lang=` foreign boundary',
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+    }
     if (node.type === 'import' && parent?.type === 'extern') {
         for (const boundaryProp of ['package', 'registry', 'target']) {
             if (boundaryProp in props) {
@@ -3007,7 +3070,7 @@ function checkCrossProps(node, violations, parent) {
         }
     }
     if (node.type === 'each') {
-        // each-pair-mode (2026-05-06): the Map / iterable-of-pairs form uses
+        // keyed-entry modes (2026-05-12): the Map / iterable-of-pairs form uses
         // `pairKey=` + `pairValue=` for `for (const [k, v] of m)`. Three rules:
         //   1. pairKey and pairValue come as a pair — neither alone is meaningful.
         //   2. pair-mode is incompatible with `index=` (entries-with-index form).
@@ -3024,9 +3087,14 @@ function checkCrossProps(node, violations, parent) {
         const isPairProp = (raw) => typeof raw === 'string' && raw.length > 0;
         const hasPairKey = isPairProp(props.pairKey);
         const hasPairValue = isPairProp(props.pairValue);
+        const hasEntryKey = isPairProp(props.entryKey);
+        const hasEntryValue = isPairProp(props.entryValue);
+        const hasFullPair = hasPairKey && hasPairValue;
+        const entryBindingCount = Number(hasFullPair) + Number(hasEntryKey) + Number(hasEntryValue);
         const hasIndex = isPairProp(props.index);
         const hasType = isPairProp(props.type);
         const hasAwait = props.await === true || props.await === 'true';
+        const hasEntries = props.entries === true || props.entries === 'true';
         if (hasPairKey !== hasPairValue) {
             violations.push({
                 nodeType: 'each',
@@ -3035,18 +3103,26 @@ function checkCrossProps(node, violations, parent) {
                 col: node.loc?.col,
             });
         }
-        if (hasPairKey && hasPairValue && hasIndex) {
+        if (entryBindingCount > 1) {
             violations.push({
                 nodeType: 'each',
-                message: "'each' pair-mode ('pairKey'+'pairValue') is mutually exclusive with 'index='",
+                message: "'each' keyed-entry modes are mutually exclusive: use pairKey+pairValue, entryKey, or entryValue",
                 line: node.loc?.line,
                 col: node.loc?.col,
             });
         }
-        if (hasPairKey && hasPairValue && hasType) {
+        if ((hasFullPair || hasEntryKey || hasEntryValue) && hasIndex) {
             violations.push({
                 nodeType: 'each',
-                message: "'each' pair-mode ('pairKey'+'pairValue') is mutually exclusive with 'type='",
+                message: "'each' keyed-entry modes are mutually exclusive with 'index='",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if ((hasFullPair || hasEntryKey || hasEntryValue) && hasType) {
+            violations.push({
+                nodeType: 'each',
+                message: "'each' keyed-entry modes are mutually exclusive with 'type='",
                 line: node.loc?.line,
                 col: node.loc?.col,
             });
@@ -3059,6 +3135,38 @@ function checkCrossProps(node, violations, parent) {
                 col: node.loc?.col,
             });
         }
+        if (hasAwait && (hasEntryKey || hasEntryValue)) {
+            violations.push({
+                nodeType: 'each',
+                message: "'each await=true' is mutually exclusive with one-binding entry modes ('entryKey='/'entryValue=')",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if (hasEntries && !hasFullPair && !hasEntryKey && !hasEntryValue) {
+            violations.push({
+                nodeType: 'each',
+                message: "'each entries=true' requires a keyed-entry mode ('pairKey'+'pairValue', 'entryKey', or 'entryValue')",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if (!hasEntries && (hasEntryKey || hasEntryValue)) {
+            violations.push({
+                nodeType: 'each',
+                message: "'each entryKey='/entryValue=' requires entries=true for object/dict entry semantics",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if (hasEntries && hasAwait) {
+            violations.push({
+                nodeType: 'each',
+                message: "'each entries=true' is mutually exclusive with 'await=true'",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
         // Pair-mode relaxes `name` requirement — handled by checkRequiredProps
         // (suppresses the `name`-required violation when pairKey+pairValue are
         // both present).