@geastack/compiler 1.0.15

package/dist/ir/queries.js

@@ -0,0 +1,213 @@
+import { nativeAbsentPropertyReadOf } from './native-absent-property.js';
+/**
+ * Uniform queries over an IR operation.
+ *
+ * Split out of `model.ts`: the model states what an operation *is*; these
+ * state what any consumer needs to ask of one -- its successors, the value it
+ * defines, the values it reads -- so no consumer re-derives the answer per
+ * kind and drifts from the others.
+ */
+/**
+ * Whether building this array runs a genuinely dynamic iteration protocol --
+ * a `gather` element drains an already-acquired iterator record
+ * (`ir/model.ts`'s `IrArrayElement`), and GetIterator/IteratorStep/
+ * IteratorValue can each invoke a user-defined method (`producers/
+ * protocol.ts`'s `mintIteratorSteps` marks every one of those steps
+ * `callsUserCode: true`). A `spread` element is the opposite: a native
+ * range-copy off an Array/Set/Map/string/cursor with no protocol dispatch at
+ * all, and an `element`/`hole` is a value the program already has.
+ *
+ * One authority for both DCE passes that ask "is this allocation pure": a
+ * body-local backward slice (`ir/shake.ts`) and a per-value dead-result check
+ * (`ir/dead-values.ts`). Both used to answer `allocate-array-object`
+ * unconditionally `true` -- correct for `[1, 2, 3]`, wrong for
+ * `[...abrupt]`, whose `next()` can throw. An unread `[...abrupt]` then
+ * disappeared whole, silently skipping an iteration the language always runs.
+ */
+export const arrayAllocationDrainsDynamicIterator = (operation) => operation.elements.some((element) => element.kind === 'gather');
+/**
+ * Carrier observations do not expose object fields or invoke coercion methods.
+ * Instance tests qualify only through their sealed native membership recipe;
+ * an arbitrary constructor can still execute Symbol.hasInstance. Both callable
+ * escape and reflection must consume this same effect, or an already-native
+ * test can invent an escape that indirectly restores every reflection hook.
+ */
+export const observesNativeCarrierOnly = (operation) => nativeAbsentPropertyReadOf(operation) !== null ||
+    operation.kind === 'test' ||
+    // Evaluating a native subclass retains its already-evaluated superclass's
+    // prototype owner. It neither calls that constructor nor exposes the
+    // fields of instances the constructor may produce. Captures and unknown
+    // heritage carriers still require their ordinary boundary analysis.
+    (operation.kind === 'allocate-constructor' &&
+        operation.captures.length === 0 &&
+        operation.result.representation.kind === 'constructor-family' &&
+        (operation.heritage === undefined || operation.heritage.representation.kind === 'constructor-family')) ||
+    (operation.kind === 'compute' &&
+        (operation.form === 'typeof' ||
+            (operation.form === 'instanceof' && operation.classInstanceTest?.nativeFieldProtocol === 'unused') ||
+            operation.form === 'require-object-coercible' ||
+            operation.form === 'require-iterable-present' ||
+            operation.form === 'require-tagged-union-arm' ||
+            (operation.form === 'unary' && (operation.operator === '!' || operation.operator === 'void')) ||
+            (operation.form === 'equality' && (operation.operator === '===' || operation.operator === '!=='))));
+/** The block each terminator can transfer control to, in no particular order. */
+export const successorsOfTerminator = (terminator) => {
+    switch (terminator.kind) {
+        case 'branch':
+            return [terminator.whenTrue, terminator.whenFalse];
+        case 'jump':
+            return [terminator.target];
+        case 'return':
+        case 'throw':
+            return [];
+        case 'switch':
+            return [...terminator.cases.map((c) => c.target), terminator.defaultTarget];
+    }
+};
+/** The value this operation defines, or `null` for an operation that only has effects or transfers control. */
+export const resultOfIrOperation = (operation) => {
+    switch (operation.kind) {
+        case 'binding-write':
+        case 'commonjs-binding-set':
+        case 'super-initialize':
+        case 'reparent-constructor':
+        case 'branch':
+        case 'jump':
+        case 'return':
+        case 'throw':
+        case 'switch':
+        // `CopyDataProperties` is not a value a JS consumer ever reads. See
+        // `SpreadCopyOperation`.
+        case 'spread-copy':
+            return null;
+        // A `yield` publishes the RESUME value (what `next(v)`/an abrupt
+        // `.return`/`.throw` sends back), when this generator's `TNext` resolved
+        // to a native carrier -- `null` otherwise, exactly like `operation.result`
+        // itself. Falls to `default` structurally; named here only so a reader
+        // does not have to check that `yield` is not one of the `null` cases
+        // just above.
+        case 'yield':
+            return operation.result;
+        default:
+            return operation.result;
+    }
+};
+/** Every value this operation reads, flattened and stripped of role, for uniform representation-consistency checking. */
+export const operandsOfIrOperation = (operation) => {
+    switch (operation.kind) {
+        case 'get':
+        case 'has-property':
+            return [operation.receiver, operation.key];
+        case 'set':
+        case 'define-own-property':
+            return [operation.receiver, operation.key, operation.value];
+        case 'delete':
+            return [operation.receiver, operation.key];
+        case 'spread-copy':
+            return [operation.receiver, operation.source];
+        case 'own-property-keys':
+            return [operation.receiver];
+        case 'compute':
+            return operation.operands;
+        case 'call':
+            return [operation.callee, ...(operation.receiver ? [operation.receiver] : []), ...operation.arguments];
+        case 'commonjs-require':
+        case 'commonjs-binding':
+            return [];
+        case 'commonjs-binding-set':
+            return [operation.value];
+        case 'super-initialize':
+            return operation.arguments;
+        case 'reparent-constructor':
+            return [operation.classValue, operation.heritage];
+        case 'construct':
+            return [operation.callee, operation.newTarget, ...operation.arguments];
+        case 'constant':
+            return [];
+        case 'binding-read':
+            return [];
+        case 'parameter':
+        case 'receiver':
+        case 'global-this':
+        case 'catch-binding':
+            // The value comes from the frame (or the catch clause's own native
+            // parameter), not from another operation in this body.
+            return [];
+        case 'unresolvable-reference':
+            // Nothing is read: the fact this citation states is that the NAME has
+            // no cell anywhere, which is settled before this operation exists, not
+            // computed from an operand.
+            return [];
+        case 'await':
+            return [operation.operand];
+        case 'yield':
+            return operation.operand ? [operation.operand] : [];
+        case 'binding-write':
+            return [operation.value];
+        case 'phi':
+            return operation.incoming.map((edge) => edge.value);
+        case 'branch':
+            return [operation.condition];
+        case 'jump':
+            return [];
+        case 'return':
+            return operation.value ? [operation.value] : [];
+        case 'throw':
+            return [operation.value];
+        case 'switch':
+            return [operation.discriminant, ...operation.cases.map((c) => c.test)];
+        case 'allocate-ordinary-object':
+            return [];
+        case 'allocate-array-object':
+            // A `spread` element reads its source array exactly as an `element`
+            // reads its value -- `[a, ...b]` evaluates `b`. Matching only
+            // `'element'` here left the spread's source looking unread by every
+            // consumer of this function, and the shaker deleted the operation that
+            // produced it while keeping the allocation that reads it: a body whose
+            // emitter then refused with "read before it is defined". `hole` is the
+            // one arm that really does read nothing.
+            return operation.elements.flatMap((element) => element.kind === 'hole' ? [] : [element.kind === 'gather' ? element.iterator : element.value]);
+        case 'allocate-callable':
+            return operation.captures;
+        case 'bind-callable':
+            return [
+                operation.source,
+                ...(operation.thisArgument ? [operation.thisArgument] : []),
+                ...(operation.receiver ? [operation.receiver] : []),
+                ...operation.bound
+            ];
+        case 'allocate-constructor':
+            return [...operation.captures, ...(operation.heritage ? [operation.heritage] : [])];
+        case 'allocate-proxy':
+            return [operation.target, operation.handler];
+        case 'allocate-record':
+            return operation.fields.map((field) => field.value);
+        case 'allocate-template-object':
+            // The segments are constants the producer read off the source tokens;
+            // nothing in the body is read to build the object.
+            return [];
+        case 'allocate-regexp':
+            // The pattern and its flags are constants the producer read off the
+            // literal's own token; nothing in the body is read to build the object.
+            return [];
+        case 'convert':
+        case 'merge-live-arm-rebuild':
+            return [operation.source];
+        case 'get-iterator':
+            return operation.method ? [operation.receiver, operation.method] : [operation.receiver];
+        case 'iterator-next':
+            return operation.value ? [operation.iterator, operation.value] : [operation.iterator];
+        case 'iterator-done':
+            return [operation.iterator];
+        case 'iterator-close':
+            return [operation.iterator];
+        case 'element':
+            return operation.tag ? [operation.tag] : [];
+        case 'element-prop':
+            return [operation.node, operation.key, operation.value];
+        case 'element-child':
+            return [operation.node, operation.child];
+        case 'test':
+            return [operation.value];
+    }
+};

package/dist/ir/reflection-demand.d.ts

@@ -0,0 +1,64 @@
+import type { DeclarationId, PhysicalBodyId, StructuralTypeId } from '../identity/ids.js';
+import { type ClassLayout, type PhysicalClassLayout } from '../projection/classes.js';
+import type { BindingPlacement } from '../projection/bindings.js';
+import type { RepresentationDeriver } from '../representation/derive.js';
+import type { Representation } from '../representation/model.js';
+import type { IrBody, IrOperation } from './model.js';
+import { type ConversionCensus } from '../conversion/nodes.js';
+/** Complete retention choices for a generated native object's protocol. */
+export type ReflectionDemandLevel = 'keys-only' | 'full';
+export type ReflectionFieldOperation = 'read' | 'write' | 'native-read' | 'native-write' | 'descriptor' | 'define';
+export type ReflectionFieldOperations = ReadonlyMap<string, ReadonlySet<ReflectionFieldOperation>>;
+export interface ReflectionDemand {
+    readonly level: ReflectionDemandLevel;
+    /** Missing means unrestricted. An explicit map is the sealed per-field operation demand. */
+    readonly fieldOperations?: ReflectionFieldOperations;
+    readonly reasons: ReadonlySet<string>;
+    readonly representations: ReadonlySet<string>;
+}
+export interface ReflectionExposure {
+    readonly classes: ReadonlyMap<DeclarationId, ReflectionDemand>;
+    readonly records: ReadonlyMap<StructuralTypeId, ReflectionDemand>;
+    readonly byRepresentation: ReadonlyMap<string, ReflectionDemand>;
+    readonly complete: boolean;
+    /** Opt-in provenance of full-demand propagation; it never changes the demand decision. */
+    readonly boundaries?: {
+        readonly origins: readonly {
+            readonly reason: string;
+            readonly carrier: Representation;
+            readonly operation: IrOperation | null;
+        }[];
+        readonly affecting: ReadonlyMap<string, ReadonlySet<number>>;
+        /** Reverse propagation edges let diagnostics recover later causes through already-expanded surfaces. */
+        readonly parents: ReadonlyMap<string, ReadonlySet<string>>;
+        /** Loss reasons from the callable census over these exact bodies and layouts. */
+        readonly callableReads: readonly {
+            readonly operation: Extract<IrOperation, {
+                kind: 'get';
+            }>;
+            readonly reason: string;
+        }[];
+    };
+}
+export interface ReflectionExposureOptions {
+    readonly wellKnownSymbols?: ReadonlyMap<DeclarationId, string>;
+    readonly physicalClasses?: ReadonlyMap<DeclarationId, PhysicalClassLayout>;
+    readonly representations: readonly Representation[];
+    readonly shakeComplete: boolean;
+    readonly placements?: ReadonlyMap<DeclarationId, BindingPlacement>;
+    readonly conversions?: Pick<ConversionCensus, 'nodeById'>;
+    readonly trace?: boolean;
+}
+/**
+ * Remove a computed-read candidate whose receiver did not receive a sealed
+ * keys-only demand.  This is deliberately a post-census operation: the
+ * lowering recipe owns finite-key and conversion eligibility, while this
+ * authority decides whether the receiver's emitted protocol makes that recipe
+ * available.  Missing rows fail closed and leave the ordinary dynamic read.
+ */
+export declare const finalizeTypedComputedReads: (bodies: ReadonlyMap<PhysicalBodyId, IrBody>, exposure: ReflectionExposure) => ReadonlyMap<PhysicalBodyId, IrBody>;
+/**
+ * Sealed reflection exposure census. Every emitted candidate is seeded as
+ * `keys-only`; only dynamic/unknown boundaries promote it to `full`.
+ */
+export declare const reflectionExposureOf: (bodies: readonly IrBody[], classes: ReadonlyMap<DeclarationId, ClassLayout>, deriver: RepresentationDeriver | null, options: ReflectionExposureOptions) => ReflectionExposure;