@geastack/compiler 1.0.15

package/dist/ir/lower-protocol.js

@@ -0,0 +1,118 @@
+import { operandOf, resultOf } from '../semantics/model/operands.js';
+import { IrLoweringBlockedError } from './lower-graph.js';
+import { namedOperand, registerResult, requireLineage, requireResultRepresentation, resolveOptionalOperand, resolveRequiredOperand, enter } from './lower-operands.js';
+/**
+ * The iteration protocol's steps.
+ *
+ * Split out of `lower.ts` on the same family boundary `lower-allocation.ts`
+ * and `lower-destructuring.ts` already draw, so the file that dispatches every
+ * family does not also carry one family's whole implementation.
+ */
+export const lowerProtocol = (ctx, block, operation) => {
+    // `CopyDataProperties` (object spread of a source with no statically known
+    // own-property set, `producers/protocol.ts`'s `contributeObjectSpread`) is
+    // not shaped like the other five protocols this file lowers below -- it has
+    // no `step` sequence at all (`step` is fixed to `'next'` for it, reused only
+    // as "the one step this protocol performs"), and its own IR primitive
+    // (`SpreadCopyOperation`) carries `receiver`/`source` directly rather than
+    // the get-method/get-iterator/next/close shape every other protocol shares.
+    // So it is handled here, before the shared guard below, rather than forced
+    // into that step switch. `targets/cpp/emit-spread.ts` renders the actual
+    // copy (a dictionary-armed source's runtime key walk, a record-armed
+    // source's static field unroll) -- this layer only resolves the two
+    // operands and hands them to the IR, exactly as every other lowering here
+    // leaves representation-shape refusals to emission.
+    if (operation.protocol === 'spread') {
+        const lineage = requireLineage(operation);
+        const receiver = resolveRequiredOperand(ctx, block, lineage, namedOperand(operation, 'receiver'));
+        const source = resolveRequiredOperand(ctx, block, lineage, namedOperand(operation, 'source'));
+        ctx.builder.spreadCopy(block, lineage, receiver, source);
+        return;
+    }
+    // `enumerate` -- `for`-`in` -- lowers through the identical three primitives,
+    // and that is not a shortcut: `contributeForOfIn` (producers/control.ts)
+    // mints it with the same get-iterator/next pair and no `get-method`, and
+    // `publish.ts` gives its record the same `gea::Iterator<E>` cursor carrier.
+    // What differs is only what the cursor walks, which is the emitter's
+    // question and not this layer's.
+    if (operation.protocol !== 'iterator' && operation.protocol !== 'async-iterator' && operation.protocol !== 'enumerate') {
+        throw new IrLoweringBlockedError(`no IR primitive lowers the "${operation.protocol}" protocol`);
+    }
+    switch (operation.step) {
+        case 'get-method': {
+            // `GetMethod` (ECMA-262 7.3.11) is `receiver[key]`, plus a
+            // non-callable-check `emit-properties.ts`'s own `[[Get]]` rendering
+            // already performs by construction (the value it builds IS a callable
+            // carrier or the read refuses). It lowers as an ordinary `[[Get]]` --
+            // the same `ctx.builder.get` an object-pattern property read goes
+            // through -- ONLY when `producers/protocol.ts` found a "key" operand to
+            // give it: a resolvable `[Symbol.iterator]`/`[Symbol.asyncIterator]`
+            // member on the source's own type. Nothing else lowers this step yet;
+            // a fully dynamic method lookup off a receiver with no such statically
+            // named member stays unbuilt, exactly as it did before this case
+            // existed.
+            const key = operandOf(operation, 'key');
+            if (!key) {
+                throw new IrLoweringBlockedError('no IR primitive lowers a fully dynamic "get-method" step; the general iterator protocol only lowers when the ' +
+                    "source's own type names a resolvable @@iterator member (producers/protocol.ts's iteratorMethodKeyTextOf)");
+            }
+            const lineage = requireLineage(operation);
+            const target = resolveRequiredOperand(ctx, block, lineage, namedOperand(operation, 'target'));
+            const keyOperand = resolveRequiredOperand(ctx, block, lineage, key);
+            const representation = requireResultRepresentation(ctx, operation, 'value', 'a get-method step');
+            registerResult(ctx, operation, ctx.builder.get(block, lineage, target, keyOperand, representation));
+            return;
+        }
+        case 'get-iterator': {
+            const lineage = requireLineage(operation);
+            const target = resolveRequiredOperand(ctx, block, lineage, namedOperand(operation, 'target'));
+            // The array fast path (`contributeForOfIn`, control.ts) mints no
+            // `get-method` step at all -- there is no `[[Get]]` of `Symbol.iterator`
+            // to perform when the source is a provably plain array, so `method` is
+            // published only for the generic dynamic-protocol path and is absent
+            // here. `getIterator` itself already treats a null method as "no
+            // dynamic call needed" (see build.ts).
+            const method = resolveOptionalOperand(ctx, block, lineage, operandOf(operation, 'method'));
+            const representation = requireResultRepresentation(ctx, operation, 'iterator-record', 'a get-iterator step');
+            registerResult(ctx, operation, ctx.builder.getIterator(block, lineage, operation.protocol, target, method, representation));
+            return;
+        }
+        case 'next': {
+            const lineage = requireLineage(operation);
+            const record = resolveRequiredOperand(ctx, block, lineage, namedOperand(operation, 'iterator-record'));
+            const valueOperand = operandOf(operation, 'value', 0);
+            const resolvedValue = resolveOptionalOperand(ctx, block, lineage, valueOperand);
+            const value = resolvedValue !== null && valueOperand !== undefined
+                ? enter(ctx, block, lineage, operation, valueOperand, resolvedValue)
+                : resolvedValue;
+            const representation = requireResultRepresentation(ctx, operation, 'value', 'a next step');
+            registerResult(ctx, operation, ctx.builder.iteratorNext(block, lineage, record, value, representation));
+            // `IteratorResult`'s `done` half is a second published result
+            // ('completion') on the SAME `next` operation, but this IR's
+            // `resultOfIrOperation` assumes exactly one result per operation
+            // (`operation.result` in its `default` arm), so it cannot live on the
+            // `iteratorNext` op itself. It lowers as its own `iterator-done` op
+            // instead -- see `IteratorDoneOperation`'s doc comment (model.ts) --
+            // ordered after `next` by the operand edge `contributeForOfIn`'s
+            // negation mints over it, not by construction order alone.
+            // `registerResult` only knows the anchor ('value') role, so the
+            // 'completion' role is resolved and registered by hand here.
+            const completion = resultOf(operation, 'completion');
+            if (completion) {
+                const doneRepresentation = requireResultRepresentation(ctx, operation, 'completion', "a next step's completion");
+                ctx.values.set(completion.id, ctx.builder.iteratorDone(block, lineage, record, doneRepresentation));
+            }
+            return;
+        }
+        case 'close': {
+            const lineage = requireLineage(operation);
+            const iterator = resolveRequiredOperand(ctx, block, lineage, namedOperand(operation, 'iterator-record'));
+            const completion = resultOf(operation, 'completion');
+            const representation = completion ? requireResultRepresentation(ctx, operation, 'completion', 'an iterator-close step') : null;
+            ctx.builder.iteratorClose(block, lineage, iterator, representation, false);
+            return;
+        }
+        default:
+            throw new IrLoweringBlockedError(`no IR primitive lowers the "${operation.step}" step of the ${operation.protocol} protocol`);
+    }
+};

package/dist/ir/lower-short-circuit.d.ts

@@ -0,0 +1,41 @@
+import type { OperationId, SemanticResultId } from '../identity/ids.js';
+import type { Representation } from '../representation/model.js';
+import type { SemanticOperation } from '../semantics/model/operations.js';
+import type { FlowController } from './lower-flow.js';
+import { type ScopeRef } from './lower-graph.js';
+import { type LoweringContext } from './lower-operands.js';
+import type { IrOperand } from './model.js';
+/**
+ * What `a?.b` evaluates to.
+ *
+ * The `[[Get]]` itself publishes the property, and it runs only where the
+ * receiver was present -- that is the operator's whole meaning, and the graph
+ * states it as a conditional edge on the receiver. What the *expression*
+ * evaluates to is a second value: the property on one branch and `undefined`
+ * on the other. The producer publishes it as the `short-circuit` result
+ * (`producers/properties.ts`) precisely so the two never get confused, and this
+ * is where it becomes a value.
+ *
+ * It cannot be built where the `[[Get]]` is lowered: that point is inside the
+ * present arm, and a merge needs both arms closed. So the merge is recorded
+ * there and settled here, at the first operation that has left the guard --
+ * exactly the moment the flow controller closes the arms anyway.
+ */
+export interface PendingShortCircuit {
+    readonly guard: SemanticResultId;
+    /** The access or call that short-circuits, for the drift row a merge arm the census cannot convert records. */
+    readonly operation: OperationId;
+    readonly result: SemanticResultId;
+    readonly present: IrOperand;
+    readonly representation: Representation;
+}
+/** The pending merge an optional chain's `[[Get]]` or `[[Call]]` leaves behind, or `null` when the operation short-circuits nothing. */
+export declare const pendingShortCircuitOf: (ctx: LoweringContext, operation: SemanticOperation, present: IrOperand) => PendingShortCircuit | null;
+/**
+ * Settles every pending merge whose guard the given scope has left.
+ *
+ * A merge still inside its own guard is left alone: closing its arms while one
+ * of them is open is not a thing the flow controller can do, and the operation
+ * about to run is in that arm.
+ */
+export declare const settleShortCircuits: (ctx: LoweringContext, flow: FlowController, pending: Map<SemanticResultId, PendingShortCircuit>, scope: readonly ScopeRef[]) => void;

package/dist/ir/lower-short-circuit.js

@@ -0,0 +1,63 @@
+import { resultOf, operandOf } from '../semantics/model/operands.js';
+import { IrLoweringBlockedError, requireRepresentation } from './lower-graph.js';
+import { convertOrDrift } from './lower-operands.js';
+/** The pending merge an optional chain's `[[Get]]` or `[[Call]]` leaves behind, or `null` when the operation short-circuits nothing. */
+export const pendingShortCircuitOf = (ctx, operation, present) => {
+    const published = resultOf(operation, 'short-circuit');
+    if (!published)
+        return null;
+    // An access branches on its own receiver, and says so by having one. A call
+    // branches on whichever expression carried the `?.` -- its callee for
+    // `f?.()`, its receiver for `a?.b()` -- which is not a question this layer
+    // re-derives: `producers/invocations.ts` states the answer as an operand, and
+    // this reads it. Preferring the stated guard keeps `host.raf?.()` from
+    // branching on `host` when what the language tests is `host.raf`.
+    const guard = operandOf(operation, 'short-circuit-guard') ?? operandOf(operation, 'receiver');
+    if (guard?.source.kind !== 'result') {
+        throw new IrLoweringBlockedError('an optional chain short-circuits on a guard that produced no result to test');
+    }
+    return {
+        guard: guard.source.result,
+        operation: operation.id,
+        result: published.id,
+        present,
+        representation: requireRepresentation(ctx.plan, published.id, 'an optional chain expression')
+    };
+};
+/**
+ * Settles every pending merge whose guard the given scope has left.
+ *
+ * A merge still inside its own guard is left alone: closing its arms while one
+ * of them is open is not a thing the flow controller can do, and the operation
+ * about to run is in that arm.
+ */
+export const settleShortCircuits = (ctx, flow, pending, scope) => {
+    if (pending.size === 0)
+        return;
+    const open = new Set(scope.filter((ref) => ref.kind === 'guard').map((ref) => ref.guard));
+    for (const [key, entry] of [...pending]) {
+        if (open.has(entry.guard))
+            continue;
+        // Not settleable yet: this guard's own frame is still on the stack, further
+        // out than whichever one just closed. `requireMergeSources` would refuse it
+        // outright, so asking would turn "not my turn" into a blocked body.
+        if (flow.isGuardOpen(entry.guard))
+            continue;
+        pending.delete(key);
+        const sources = flow.requireMergeSources(entry.guard);
+        // The property, in the carrier the expression publishes: `Optional<T>` has
+        // a converting constructor from `T`, so this widening is a real store and
+        // not a reinterpretation.
+        const carried = convertOrDrift(ctx, sources.truthy, entry.result, entry.operation, 'present', 0, entry.present, entry.representation, 'guard');
+        // The other branch is the operator's own answer, `undefined`, in that same
+        // carrier -- written as the language's literal and converted, rather than
+        // as an absent optional conjured directly, so the value the program sees
+        // and the value this emits have one origin.
+        const absent = ctx.builder.constant(sources.falsy, entry.result, 'undefined', 'undefined', { kind: 'undefined' });
+        const converted = convertOrDrift(ctx, sources.falsy, entry.result, entry.operation, 'absent', 0, { value: absent, representation: { kind: 'undefined' } }, entry.representation);
+        ctx.values.set(entry.result, ctx.builder.phi(sources.join, entry.result, [
+            { block: sources.truthy, value: carried },
+            { block: sources.falsy, value: converted }
+        ], entry.representation));
+    }
+};

package/dist/ir/lower.d.ts

@@ -0,0 +1,82 @@
+import type { DeclarationId, FunctionId, PhysicalBodyId, SemanticResultId } from '../identity/ids.js';
+import { type ClassLayout } from '../projection/classes.js';
+import type { SlotCensus } from '../projection/slots.js';
+import type { ConversionCensus } from '../conversion/nodes.js';
+import type { RepresentationDeriver } from '../representation/derive.js';
+import { type CallableAbi } from '../representation/model.js';
+import type { SealedRepresentationPlan } from '../representation/plan.js';
+import type { SemanticGraph } from '../semantics/model/graph.js';
+import { type OwnerId } from './lower-graph.js';
+import type { PluginInstance } from '../plugins/model.js';
+import { type SlotDrift } from './lower-operands.js';
+import { type IrBody } from './model.js';
+/**
+ * Lowering a sealed `SemanticGraph` plus a `SealedRepresentationPlan` into
+ * verified `IrBody` values, one per executable owner.
+ *
+ * Every mapping here is deliberately narrow: `property`/`invocation`/the
+ * sync-iterator steps of `protocol` map onto the object-substrate IR because
+ * that IR exists for them; almost everything else -- arithmetic, `for`/`try`,
+ * destructuring, class lifecycle -- has no IR primitive yet
+ * (`docs/ARCHITECTURE.md`, "Not built": "the typed IR model exists; the
+ * semantic-graph -> IR -> C++ document path does not"), so lowering it would
+ * mean inventing one here, off to the side of whatever `ir/model.ts` actually
+ * declares. Blocking with a stated missing capability is the honest answer;
+ * the alternative is a compiler stage with its own private opinion about what
+ * the IR contains.
+ */
+export interface IrLoweringInput {
+    readonly graph: SemanticGraph;
+    readonly plan: SealedRepresentationPlan;
+    /**
+     * The very deriver that produced `plan`, not an equivalent one.
+     *
+     * A published result's carrier is read from `plan.selected`; an
+     * `OperandSource.constant` is inline data that was never published, so no
+     * row is keyed by it and its carrier has to be derived. Deriving it from a
+     * *separately constructed* deriver is what made this a second authority:
+     * built with default policies it answers `native-record-ref` where the plan
+     * answers `typed-array(float32)` or `native-handle`, for the same
+     * `StructuralTypeId`. Taking the plan's own deriver means "not in the plan"
+     * costs a lookup, never a different opinion.
+     */
+    readonly deriver: RepresentationDeriver;
+    /** Each function's calling convention, projected once before any body lowers. */
+    readonly abis: ReadonlyMap<FunctionId, CallableAbi>;
+    /** The second convention into a body that is both called and `new`ed (`projection/abi.ts`'s `constructs`). */
+    readonly constructs: ReadonlyMap<FunctionId, CallableAbi>;
+    /** Exact callable provenance projected from the semantic graph. */
+    readonly callableOrigins: ReadonlyMap<SemanticResultId, FunctionId>;
+    /** Callable own-property mutations that make `.call`/`.apply` rewrites unsafe. */
+    readonly callableOwnPropertyWrites: ReadonlyMap<FunctionId, ReadonlySet<string>>;
+    readonly functionPrototypePropertyWrites: ReadonlySet<string>;
+    /** Why the projection refused a convention, for the functions it refused, so a body can report the cause instead of the symptom. */
+    readonly abiBlockers: ReadonlyMap<FunctionId, string>;
+    /** What each class is made of, projected once before any body lowers. */
+    readonly classes: ReadonlyMap<DeclarationId, ClassLayout>;
+    readonly slots: SlotCensus;
+    readonly conversions: ConversionCensus;
+    /**
+     * Installed plugins, consulted before this file's own lowering for every
+     * operation.
+     *
+     * They come first, not last, and the difference matters. A plugin that gives
+     * a construct new meaning has to replace what the language alone would do
+     * with it, not patch up the leftovers -- and a fallback ordering would mean a
+     * plugin could only ever claim what the core had already refused, which is
+     * every construct the core got *wrong* for that library and none of the ones
+     * it got merely incompletely.
+     */
+    readonly plugins: readonly PluginInstance[];
+}
+export interface IrLoweringBlocker {
+    readonly owner: OwnerId;
+    readonly reason: string;
+}
+export interface IrLoweringResult {
+    readonly bodies: ReadonlyMap<PhysicalBodyId, IrBody>;
+    readonly blocked: readonly IrLoweringBlocker[];
+    /** Slots lowering could not fill from the census -- see `LoweringProgram.drift`. */
+    readonly slotDrift: readonly SlotDrift[];
+}
+export declare const lowerToIr: (input: IrLoweringInput) => IrLoweringResult;