@geastack/compiler 1.0.15

package/dist/ir/lower-element.d.ts

@@ -0,0 +1,29 @@
+import type { ElementOperation as SemanticElementOperation } from '../semantics/model/operations.js';
+import { type LoweringContext } from './lower-operands.js';
+import type { PluginInstance } from '../plugins/model.js';
+import type { IrBlockId } from './model.js';
+/**
+ * JSX element construction, lowered as far as the language itself states it.
+ *
+ * TypeScript gives an intrinsic element a meaning of its own: `JSX.IntrinsicElements`
+ * names the tag, the attributes are checked against that declaration, and the
+ * children are ordinary expressions. So an intrinsic element lowers here, to a
+ * host node followed by its properties and its children -- one step at a time,
+ * because there is no props object in the language for it and inventing one in
+ * the IR would be a claim the source never made.
+ *
+ * A tag that names a *value* is where the language stops. The checker resolves
+ * a call or a construct signature, but what happens afterwards -- whether the
+ * result is invoked once, instantiated and re-entered on a later frame, or
+ * compiled into a static structure with patched positions -- is a library's
+ * meaning, not TypeScript's. A compiler that picked one would be picking a
+ * framework. So this file refuses that form, and a plugin claims it: see
+ * `src/plugins/model.ts` for the seam and `src/plugins/gea/` for the claim
+ * that gea's component model actually makes.
+ *
+ * A JSX element's props are ordered pairs in the semantic graph -- `prop-key`
+ * and `prop-value` at the same ordinal -- and they have to stay paired here.
+ * Reading the two roles independently and zipping by position would silently
+ * pair a key with the wrong value the moment one of them is absent.
+ */
+export declare const lowerElement: (ctx: LoweringContext, block: IrBlockId, operation: SemanticElementOperation, plugins?: readonly PluginInstance[]) => void;

package/dist/ir/lower-element.js

@@ -0,0 +1,111 @@
+import { operandOf } from '../semantics/model/operands.js';
+import { IrLoweringBlockedError } from './lower-graph.js';
+import { orderedOperandsOf, registerResult, requireLineage, requireResultRepresentation, resolveOptionalOperand, resolveRequiredOperand, enterRequiredOperand } from './lower-operands.js';
+/**
+ * JSX element construction, lowered as far as the language itself states it.
+ *
+ * TypeScript gives an intrinsic element a meaning of its own: `JSX.IntrinsicElements`
+ * names the tag, the attributes are checked against that declaration, and the
+ * children are ordinary expressions. So an intrinsic element lowers here, to a
+ * host node followed by its properties and its children -- one step at a time,
+ * because there is no props object in the language for it and inventing one in
+ * the IR would be a claim the source never made.
+ *
+ * A tag that names a *value* is where the language stops. The checker resolves
+ * a call or a construct signature, but what happens afterwards -- whether the
+ * result is invoked once, instantiated and re-entered on a later frame, or
+ * compiled into a static structure with patched positions -- is a library's
+ * meaning, not TypeScript's. A compiler that picked one would be picking a
+ * framework. So this file refuses that form, and a plugin claims it: see
+ * `src/plugins/model.ts` for the seam and `src/plugins/gea/` for the claim
+ * that gea's component model actually makes.
+ *
+ * A JSX element's props are ordered pairs in the semantic graph -- `prop-key`
+ * and `prop-value` at the same ordinal -- and they have to stay paired here.
+ * Reading the two roles independently and zipping by position would silently
+ * pair a key with the wrong value the moment one of them is absent.
+ */
+export const lowerElement = (ctx, block, operation, plugins = []) => {
+    const lineage = requireLineage(operation);
+    const keys = orderedOperandsOf(operation, 'prop-key');
+    const children = orderedOperandsOf(operation, 'child').map((child) => enterRequiredOperand(ctx, block, lineage, operation, child));
+    const tag = resolveOptionalOperand(ctx, block, lineage, operandOf(operation, 'tag', 0));
+    const representation = requireResultRepresentation(ctx, operation, 'value', 'an element construction');
+    // A fragment is not the same refusal. `<>...</>` is JSX's own form, not a tag
+    // naming somebody's value: it creates a node, takes children, and takes no
+    // props -- the identical three steps below, with nothing about them for a
+    // library to decide. What a fragment *builds* is still the host's answer, and
+    // that is asked at emission (`PluginCapabilities.elementFragment`), where the
+    // host's spelling lives; refusing it here would refuse it in a layer that
+    // has no host to ask.
+    if (operation.form === 'value') {
+        throw new IrLoweringBlockedError("this element's tag names a value rather than an intrinsic the language declares; " +
+            "what such an element means at runtime is a library's, and no installed plugin claimed it");
+    }
+    // Create first, then decorate. The node has to exist before anything can be
+    // put on it, and writing that as three steps rather than one bundled
+    // operation is what leaves room for a consumer to act on the node between
+    // them -- attaching a nested component into it, or holding on to it so a
+    // later update can find it again.
+    // One decision, read by the create and by the child alike: whether the node
+    // this element builds IS its text (`isTextLeaf` below).
+    const textLeaf = isTextLeaf(operation, children, plugins);
+    const node = ctx.builder.element(block, lineage, operation.form, tag, representation, textLeaf);
+    const nodeOperand = { value: node, representation };
+    for (const key of keys) {
+        const value = operandOf(operation, 'prop-value', key.ordinal);
+        if (!value)
+            throw new IrLoweringBlockedError(`an element property at ordinal ${key.ordinal} names a key with no value operand`);
+        // Offered to the plugins first, and only for this one prop. A name like
+        // JSX's `ref` is not a property of the node -- it says where to PUT the
+        // node -- and which names mean that is the library's to say, not this
+        // file's. A prop nobody claims takes the same path it always did.
+        if (plugins.some((plugin) => plugin.lowerElementProp?.(ctx, block, lineage, nodeOperand, key, value) === true))
+            continue;
+        ctx.builder.elementProp(block, lineage, nodeOperand, resolveRequiredOperand(ctx, block, lineage, key), enterRequiredOperand(ctx, block, lineage, operation, value));
+    }
+    for (const child of children)
+        ctx.builder.elementChild(block, lineage, nodeOperand, child, textLeaf);
+    registerResult(ctx, operation, node);
+};
+/**
+ * Whether this element IS its text rather than containing it.
+ *
+ * Two authorities, and both have to say yes. The host names the tags its node
+ * model has a text node for (`PluginCapabilities.elementTextTags`) -- gea's
+ * engine has one whose class and style behave exactly as an element's do, so a
+ * `<span>` holding only characters is that node and a `<div>` never is. The
+ * language then says whether THIS element's contents are a single text run,
+ * which is what the children's carriers already state: a nested element is a
+ * host handle, a list is an array, a conditional child is a union, and none of
+ * those is text.
+ *
+ * Both halves are v1's, split the same way: `isTextNodeTag` is the tag list,
+ * and `canUseTextNodeForElement` is the contents rule -- no element children,
+ * exactly one run. Its own comment records what taught them the multi-run case:
+ * a text node holds ONE run, so baking one run into the parent and appending
+ * the rest as children stacks them all at the parent's origin, and `<span>{a} /
+ * {b}</span>` renders as one garbled glyph.
+ *
+ * Everything not proven is a container. A tag this frame cannot read as a
+ * literal, a child whose carrier is anything but characters, an element with no
+ * children or with several -- all take the path every element took before this
+ * existed. That asymmetry is deliberate: a container one level deeper than v1's
+ * is visible and fails loudly, while an element flattened when it should not be
+ * is a silently wrong tree.
+ */
+const isTextLeaf = (operation, children, plugins) => {
+    if (operation.form !== 'intrinsic')
+        return false;
+    const child = children.length === 1 ? children[0] : undefined;
+    // A run is characters: a string, or a number/boolean the host renders as
+    // one. Every other carrier -- a node, an array of nodes, a union that may be
+    // either -- is content this element contains rather than content it is.
+    if (!child || (child.representation.kind !== 'string' && child.representation.kind !== 'scalar'))
+        return false;
+    const source = operandOf(operation, 'tag', 0)?.source;
+    if (source?.kind !== 'constant' || source.literal !== 'string')
+        return false;
+    const tag = source.text.toLowerCase();
+    return plugins.some((plugin) => plugin.capabilities.elementTextTags.includes(tag));
+};

package/dist/ir/lower-exceptions.d.ts

@@ -0,0 +1,47 @@
+import { thrownValueCarrier } from '../representation/model.js';
+import type { BoundaryOperation } from '../semantics/model/operations.js';
+import { type LoweringContext } from './lower-operands.js';
+import type { IrBlockId } from './model.js';
+/**
+ * The one carrier a value travels in between a `throw` and the handler that
+ * catches it.
+ *
+ * It has to be a single fixed carrier, and not either side's own idea of one,
+ * because the two sides cannot see each other: a `throw` in one function is
+ * caught by a `catch` in another, and a native C++ handler catches by TYPE. A
+ * `throw` that emitted its operand's own static carrier and a handler that
+ * named a different one produced C++ that compiled cleanly and could not
+ * catch the exception at all -- `throw v0;` of a `std::string` against
+ * `catch (const gea::Value& v1)` -- so the exception escaped the handler the
+ * source program wrote and reached `std::terminate`. That is the silent
+ * miscompile this constant exists to make impossible; `renderTryRegion`
+ * (`targets/cpp/emit-exceptions.ts`) checks the handler agrees rather than
+ * assuming it.
+ *
+ * `dynamic` is the honest answer rather than a shortcut around the no-boxing
+ * rule: `'thrown-error-carrier'` is one of the four `DynamicReason`s
+ * `representation/model.ts` admits, declared there from the start as "a
+ * thrown value, which JavaScript does not type", and
+ * `producers/boundary.ts` already says in so many words that it publishes the
+ * checker's own `unknown` precisely so "a later layer" can choose this
+ * carrier. This is that layer. Nothing inside the `try` is boxed by this: the
+ * conversion happens at the `throw` itself, which is exactly where
+ * ECMAScript loses the type too.
+ *
+ * The catch side needs no conversion in the other direction. TypeScript
+ * admits only `any` or `unknown` on a catch parameter (`unknown` under
+ * `useUnknownInCatchVariables`, which `program.ts` enables), so the caught
+ * binding's own carrier is already this one physically -- what differs is the
+ * stated reason, not the storage.
+ */
+export { thrownValueCarrier };
+/**
+ * `try`/`catch` and the `await`/`yield` resume points: the boundary forms this
+ * backend lowers.
+ *
+ * `label-target` is not reached here yet: `switch`/`label` both refuse by name
+ * in `lower.ts`'s `lowerControl`, before any operation gated on one of those
+ * boundaries could ever be scheduled. `generator-resume` IS reached, and is a
+ * no-op for the reason its own case states, as is `finally-region`.
+ */
+export declare const lowerBoundary: (ctx: LoweringContext, block: IrBlockId, operation: BoundaryOperation) => void;

package/dist/ir/lower-exceptions.js

@@ -0,0 +1,92 @@
+import { thrownValueCarrier } from '../representation/model.js';
+import { IrLoweringBlockedError } from './lower-graph.js';
+import { registerResult, requireLineage, requireResultRepresentation } from './lower-operands.js';
+/**
+ * The one carrier a value travels in between a `throw` and the handler that
+ * catches it.
+ *
+ * It has to be a single fixed carrier, and not either side's own idea of one,
+ * because the two sides cannot see each other: a `throw` in one function is
+ * caught by a `catch` in another, and a native C++ handler catches by TYPE. A
+ * `throw` that emitted its operand's own static carrier and a handler that
+ * named a different one produced C++ that compiled cleanly and could not
+ * catch the exception at all -- `throw v0;` of a `std::string` against
+ * `catch (const gea::Value& v1)` -- so the exception escaped the handler the
+ * source program wrote and reached `std::terminate`. That is the silent
+ * miscompile this constant exists to make impossible; `renderTryRegion`
+ * (`targets/cpp/emit-exceptions.ts`) checks the handler agrees rather than
+ * assuming it.
+ *
+ * `dynamic` is the honest answer rather than a shortcut around the no-boxing
+ * rule: `'thrown-error-carrier'` is one of the four `DynamicReason`s
+ * `representation/model.ts` admits, declared there from the start as "a
+ * thrown value, which JavaScript does not type", and
+ * `producers/boundary.ts` already says in so many words that it publishes the
+ * checker's own `unknown` precisely so "a later layer" can choose this
+ * carrier. This is that layer. Nothing inside the `try` is boxed by this: the
+ * conversion happens at the `throw` itself, which is exactly where
+ * ECMAScript loses the type too.
+ *
+ * The catch side needs no conversion in the other direction. TypeScript
+ * admits only `any` or `unknown` on a catch parameter (`unknown` under
+ * `useUnknownInCatchVariables`, which `program.ts` enables), so the caught
+ * binding's own carrier is already this one physically -- what differs is the
+ * stated reason, not the storage.
+ */
+export { thrownValueCarrier };
+/**
+ * `try`/`catch` and the `await`/`yield` resume points: the boundary forms this
+ * backend lowers.
+ *
+ * `label-target` is not reached here yet: `switch`/`label` both refuse by name
+ * in `lower.ts`'s `lowerControl`, before any operation gated on one of those
+ * boundaries could ever be scheduled. `generator-resume` IS reached, and is a
+ * no-op for the reason its own case states, as is `finally-region`.
+ */
+export const lowerBoundary = (ctx, block, operation) => {
+    switch (operation.boundary) {
+        case 'generator-resume':
+            // Where control resumes after a `yield`. The C++20 coroutine transform
+            // owns the resume point itself -- `co_yield` IS the suspend and the
+            // resume, and control simply continues after it -- so there is no block
+            // for this boundary to open. Its `value` result is never cited either:
+            // `producers/control.ts` refuses a `yield` whose own value is read, so
+            // nothing in the body can name what a resume would have carried. Handled
+            // exactly as `async-resume` below is, and for the same reason.
+            return;
+        case 'async-resume':
+            // Where control "resumes" after an `await` -- but this backend's
+            // `await` never suspends (see `lowerControl`'s `'await'` case), so
+            // control already fell straight through here. Its `value` result is
+            // never cited by anything either (`await x`'s consumers cite the
+            // `await` operation's own result), so nothing to register.
+            return;
+        case 'finally-region':
+            // The marker whose SCOPE the gating walk hangs the finally clause's own
+            // operations on (`gating.ts`'s `part: 'finally'`); the flow controller
+            // opens that scope's block from the membership alone. There is nothing
+            // for the marker itself to compute, and it publishes no result: a finally
+            // clause is a statement list, not a value, and unlike `exception-region`
+            // it binds nothing either -- the caught value belongs to `catch`.
+            return;
+        case 'label-target':
+            // A labelled iteration resolves directly to its loop's exit/header;
+            // this boundary remains only for a non-iteration labelled statement,
+            // whose transfer lowering will refuse if a program actually targets it.
+            return;
+        case 'exception-region': {
+            // A bindingless `catch {}` publishes no result: nothing in this body
+            // ever needs the caught value, so there is nothing to materialize. The
+            // emitter renders the handler as a bare `catch (...)` from the block's
+            // presence in `IrBody.tryRegions` alone.
+            if (operation.results.length === 0)
+                return;
+            const lineage = requireLineage(operation);
+            const representation = requireResultRepresentation(ctx, operation, 'value', 'an exception region');
+            registerResult(ctx, operation, ctx.builder.catchBinding(block, lineage, representation));
+            return;
+        }
+        default:
+            throw new IrLoweringBlockedError(`no IR primitive lowers a "${operation.boundary}" boundary yet`);
+    }
+};

package/dist/ir/lower-flow.d.ts

@@ -0,0 +1,137 @@
+import type { OperationId, SemanticResultId } from '../identity/ids.js';
+import type { IrBodyBuilder } from './build.js';
+import { type ConditionalMembership, type ScopeRef } from './lower-graph.js';
+import type { IrBlockId, IrOperand } from './model.js';
+export interface GuardMergeSources {
+    readonly truthy: IrBlockId;
+    readonly falsy: IrBlockId;
+    /** The block both arms rejoin in, which is where a merge over them belongs. */
+    readonly join: IrBlockId;
+}
+/** One try statement's blocks, as the C++ emitter needs to know them. */
+export interface RegionBlockInfo {
+    readonly region: OperationId;
+    readonly tryEntry: IrBlockId;
+    readonly catchEntry: IrBlockId | null;
+    readonly finallyEntry: IrBlockId | null;
+    readonly finallyExit: IrBlockId | null;
+    readonly join: IrBlockId | null;
+}
+export interface FlowController {
+    readonly currentBlock: () => IrBlockId;
+    /**
+     * The two blocks that reach this guard's join, opening the branch and closing
+     * either arm if the lowering has not already done so.
+     *
+     * An arm can be empty of operations -- `flag ? 1 : 2` puts a constant on both
+     * sides -- and then nothing ever asked for that arm's scope, so no branch
+     * exists at all. A merge still needs one: the value differs per side, and the
+     * only thing that can decide which side ran is a real branch. Opening it here
+     * keeps that decision with the module that owns block structure.
+     *
+     * Only legal for a guard whose arms are not currently open, which is the case
+     * for every consumer of a guard's merged value: such a consumer runs after the
+     * branch, so its own scope never contains this guard.
+     */
+    readonly requireMergeSources: (guard: SemanticResultId) => GuardMergeSources;
+    /**
+     * Whether one of this guard's arms is still an open frame, which is exactly
+     * when `requireMergeSources` would refuse it.
+     *
+     * Asked so a settle step can SKIP such a guard instead of blocking on it.
+     * Unwinding closes frames innermost-first and a short circuit is settled as
+     * soon as its own frame closes, so at that moment a guard further out is
+     * still open and its pending merge is simply not this frame's turn.
+     */
+    readonly isGuardOpen: (guard: SemanticResultId) => boolean;
+    /**
+     * Where `continue` and `break` land: a loop's header re-runs the test, its
+     * exit is the block its test's failing arm rejoins in. `null` before the loop
+     * has been entered, which for a transfer out of that loop's own body cannot
+     * happen -- the body is inside it.
+     */
+    readonly loopHeaderOf: (loop: OperationId) => IrBlockId | null;
+    readonly loopExitOf: (loop: OperationId) => IrBlockId | null;
+    /**
+     * Where `break` out of a switch lands: the statement's own exit block,
+     * reserved the first time a break asks for it, exactly as a testless
+     * loop's exit is. A switch lowers as a guard chain, and while no clause
+     * could fall through and no statement followed a `break` in its clause,
+     * the end of a clause's arm WAS the exit and `break` needed no jump at
+     * all. Both are ordinary source shapes (tsc's checker writes `if (...) {
+     * break; } // falls through`), and with them a clause's arm end is where
+     * the NEXT clause may start, so a `break` has to name where the switch
+     * itself ends. Reserved lazily so a switch nothing breaks out of grows no
+     * empty block.
+     */
+    readonly switchExitOf: (switchOp: OperationId) => IrBlockId;
+    /**
+     * The switch statement's own close, at its marker: control that fell out
+     * of the last clause joins whatever the breaks reserved, and lowering
+     * continues in that block. A switch whose exit was never reserved closes
+     * as it always did -- in the chain's own join.
+     */
+    readonly closeSwitch: (switchOp: OperationId, lineage: SemanticResultId | null) => void;
+    /**
+     * Where `continue` re-enters a `for` loop that has an incrementor: the
+     * latch block reserved for it, run before the header re-tests the
+     * condition. `null` for a loop with no incrementor (a `while`, or a `for`
+     * with an empty update clause) -- such a loop's `continue` targets the
+     * header directly, exactly as it always has.
+     */
+    readonly loopLatchOf: (loop: OperationId) => IrBlockId | null;
+    /** The branch target selected when a head-tested loop exhausts normally. */
+    readonly loopNormalExitOf: (loop: OperationId) => IrBlockId | null;
+    /** The truthy condition arm, including an empty loop body's synthetic back edge. */
+    readonly loopBodyEntryOf: (loop: OperationId) => IrBlockId | null;
+    /** End the current straight-line block without changing lexical scope. */
+    readonly splitCurrentBlock: (lineage: SemanticResultId | null) => IrBlockId;
+    /** Every try-region this owner opened, for `lowerOwner` to publish on the sealed `IrBody`. */
+    readonly regionsOpened: () => readonly RegionBlockInfo[];
+    /**
+     * Positions `currentBlock` for the next operation's exact guard chain,
+     * opening/closing/switching branches as needed. Must be called before every
+     * operation, including the first, with that operation's own guard chain
+     * (empty for an unconditional operation).   *
+     * `afterUnwind`, if given, runs once this call has closed every frame the
+     * new scope leaves and before it opens any frame the new scope adds. A
+     * guard's own boolean test can itself be a value only settled once its
+     * *previous* guard has closed -- an optional chain used as a `?:` or `&&`
+     * condition is exactly that, since the chain's short-circuit result is a
+     * merge over the chain's own presence guard, and the ternary's guard is that
+     * same result. Settling after this whole call returns is too late for such a
+     * guard: opening it happens inside this call. This module still never decides
+     * what to settle or how -- the callback is opaque to it -- only when the one
+     * legal moment for settling arrives.
+     *
+     * `placesNothing` says the operation being positioned for is a MARKER: it
+     * emits no IR of its own and the transfers it stands for were already built
+     * out of scope membership. Such an operation still has to be positioned --
+     * unwinding the frames its scope leaves is what joins the arms it closes --
+     * but it must not be given a home when every path already ended, because the
+     * home would be an orphan block nothing reaches and nothing fills, and the
+     * body-completion terminator synthesized into it is a valueless `return` in
+     * a function that must return a value.
+     */
+    readonly enterScope: (requiredScope: readonly ScopeRef[], afterUnwind?: () => void, placesNothing?: boolean) => IrBlockId;
+    /** Records that `currentBlock` just received a terminator, so the next `enterScope` opens a fresh block instead of appending to a dead one. */
+    /**
+     * Closes every still-open branch once the owner's operation list is
+     * exhausted. `alreadyTerminated` distinguishes a body every path already
+     * returned/threw from one that fell off the end -- the latter needs a
+     * terminator this controller has no semantic operation to cite as lineage
+     * for, so it is the caller's job to fail closed on it rather than this
+     * module synthesizing an unattributed one.
+     */
+    readonly finish: () => {
+        readonly block: IrBlockId;
+        readonly alreadyTerminated: boolean;
+    };
+}
+export interface FlowControllerDeps {
+    readonly builder: IrBodyBuilder;
+    readonly membership: ConditionalMembership;
+    /** Resolves a guard's own published result to the operand its branch tests. Throws to block when the guard cannot supply one. */
+    readonly resolveGuardOperand: (guard: SemanticResultId) => IrOperand;
+}
+export declare const createFlowController: (deps: FlowControllerDeps) => FlowController;