@geastack/compiler 1.0.15

package/dist/semantics/normalize/structural-array-read.d.ts

@@ -0,0 +1,13 @@
+import ts from 'typescript';
+import type { StructuralTypeId } from '../../identity/ids.js';
+import type { StructuralTypeTable } from '../model/structural-type-table.js';
+/** Read an erased indexed type from the receiver's actual structural layout.
+ * A parameter census can refine [Function][] to a native callable tuple array.
+ * Asking the checker again for a[i][0] loses that refinement at each index.
+ * Real checker narrowings remain authoritative; this only fills unstated slots.
+ * The checker can also report `never` for a read from an evolving empty-array
+ * literal after the receiver itself has been recovered as a usable array. In
+ * that case the receiver layout is the evidence for the read; an actual
+ * `never[]` remains `never` because its recovered element is also `never`.
+ */
+export declare const structuralArrayReadAt: (checker: ts.TypeChecker, table: StructuralTypeTable, source: StructuralTypeId | null, node: ts.Node) => StructuralTypeId | null;

package/dist/semantics/normalize/structural-array-read.js

@@ -0,0 +1,124 @@
+import ts from 'typescript';
+import { containsUnstatedPosition } from './derived-expression-type.js';
+/** Read an erased indexed type from the receiver's actual structural layout.
+ * A parameter census can refine [Function][] to a native callable tuple array.
+ * Asking the checker again for a[i][0] loses that refinement at each index.
+ * Real checker narrowings remain authoritative; this only fills unstated slots.
+ * The checker can also report `never` for a read from an evolving empty-array
+ * literal after the receiver itself has been recovered as a usable array. In
+ * that case the receiver layout is the evidence for the read; an actual
+ * `never[]` remains `never` because its recovered element is also `never`.
+ */
+export const structuralArrayReadAt = (checker, table, source, node) => {
+    if (!source || !ts.isElementAccessExpression(node) || node.questionDotToken)
+        return null;
+    const raw = checker.getTypeAtLocation(node);
+    const key = node.argumentExpression;
+    const index = ts.isNumericLiteral(key) || ts.isStringLiteralLike(key) ? Number(key.text) : null;
+    const numeric = index !== null
+        ? Number.isInteger(index) && index >= 0 && (ts.isNumericLiteral(key) || (ts.isStringLiteralLike(key) && String(index) === key.text))
+        : (checker.getTypeAtLocation(key).flags & ts.TypeFlags.NumberLike) !== 0;
+    const symbol = (checker.getTypeAtLocation(key).flags & ts.TypeFlags.ESSymbolLike) !== 0;
+    if (!numeric && !symbol)
+        return null;
+    /**
+     * The type this position reads, and whether the SHAPE proves the read
+     * present.
+     *
+     * `present` is not a second opinion about the type -- it is the same walk
+     * reporting which of its branches ended on a position the shape says always
+     * exists: a non-optional position of a CLOSED tuple, or a position before an
+     * open tuple's rest. Those cannot be out of range and cannot hold a hole, so
+     * the `admitsUndefined` recovery below (right for an array, whose length
+     * nothing here knows) must not put an absence back that this walk just ruled
+     * out. Everything else -- an array element, a union with any unproven arm, an
+     * optional position -- reports `false` and is treated exactly as before.
+     */
+    const visit = (id, seen) => {
+        if (seen.has(id))
+            return null;
+        const next = new Set(seen).add(id);
+        const shape = table.get(id).shape;
+        if (shape.kind === 'declared')
+            return shape.body ? visit(shape.body, next) : null;
+        if (shape.kind === 'object-anchor')
+            return visit(shape.body, next);
+        if (shape.kind === 'object' && symbol) {
+            const indexed = shape.index.find((entry) => entry.key === 'symbol');
+            return indexed ? { id: indexed.value, present: false } : null;
+        }
+        if (shape.kind === 'array' && numeric)
+            return { id: shape.element, present: false };
+        if (shape.kind === 'tuple' && numeric) {
+            // An open-ended tuple is carried as an array of the union of its
+            // positions (`derive.ts`'s `deriveTuple`); a position before the rest
+            // still reads its own stated type, and any other index reads the union.
+            const open = shape.elements.findIndex((element) => element.rest || element.variadic);
+            if (open >= 0) {
+                if (shape.elements.some((element) => element.variadic))
+                    return null;
+                const fixed = index !== null && index < open ? shape.elements[index] : undefined;
+                if (fixed && !fixed.optional)
+                    return { id: fixed.type, present: true };
+                return { id: table.intern({ kind: 'union', members: shape.elements.map((element) => element.type) }), present: false };
+            }
+            if (index === null)
+                return null;
+            const element = shape.elements[index];
+            if (!element)
+                return null;
+            return element.optional
+                ? {
+                    id: table.intern({ kind: 'union', members: [element.type, table.intern({ kind: 'primitive', primitive: 'undefined' })] }),
+                    present: false
+                }
+                : { id: element.type, present: true };
+        }
+        if (shape.kind === 'union') {
+            const members = shape.members.map((member) => visit(member, next));
+            if (members.some((member) => member === null))
+                return null;
+            const answers = members;
+            return {
+                id: table.intern({ kind: 'union', members: answers.map((member) => member.id) }),
+                present: answers.every((member) => member.present)
+            };
+        }
+        return null;
+    };
+    const answer = visit(source, new Set());
+    if (!answer)
+        return null;
+    const result = answer.id;
+    const isNever = (id, seen) => {
+        if (seen.has(id))
+            return false;
+        const next = new Set(seen).add(id);
+        const shape = table.get(id).shape;
+        if (shape.kind === 'primitive')
+            return shape.primitive === 'never';
+        return shape.kind === 'declared' && shape.body ? isNever(shape.body, next) : false;
+    };
+    const staleNever = (raw.flags & ts.TypeFlags.Never) !== 0 && !isNever(result, new Set());
+    if (!containsUnstatedPosition(checker, node, raw) && !staleNever)
+        return null;
+    // `any | undefined` collapses to `any` in the checker, so recovering its
+    // element must also recover the absence that erasure hid. No checker
+    // narrowing proves this read present. Otherwise a valid out-of-range
+    // JavaScript read becomes ArrayObject::elementAt's native abort.
+    //
+    // Except where the walk above PROVED the position present. `children[0]` on
+    // `/** @type {[Object3D]} */` is the case: the tuple branch answers
+    // `Object3D` because position 0 of a closed 1-tuple is not optional, and then
+    // this recovery unioned `undefined` straight back in because the checker's
+    // own answer for the read is `any` -- one rule undoing the other, and the
+    // emitted read paying for it with a presence test and an `Optional` round
+    // trip on a recursive hot path (`recursive-derived-parameter-access.runtime.js`
+    // pins that it does not). A shape that says the position always exists is not
+    // an erasure to recover from.
+    const admitsUndefined = !answer.present &&
+        (raw.isUnion() ? raw.types : [raw]).some((arm) => (arm.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0);
+    return admitsUndefined
+        ? table.intern({ kind: 'union', members: [result, table.intern({ kind: 'primitive', primitive: 'undefined' })] })
+        : result;
+};

package/dist/semantics/normalize/structural-callable.d.ts

@@ -0,0 +1,12 @@
+import ts from 'typescript';
+import type { StructuralTypeId } from '../../identity/ids.js';
+import type { StructuralTypeTable } from '../model/structural-type-table.js';
+import type { SignatureShape } from '../model/structural-types.js';
+/** TypeScript's unchecked-call placeholder has no physical declaration. */
+export declare const isFabricatedSignatureShape: (checker: ts.TypeChecker, signature: ts.Signature) => boolean;
+/** Every alternative must actually declare one callable frame. */
+export declare const structuralCallSignatures: (table: StructuralTypeTable, id: StructuralTypeId, seen?: ReadonlySet<StructuralTypeId>) => readonly SignatureShape[] | null;
+/** A native constructor choice returns every arm's instance, even when the checker merges their identical shapes. */
+export declare const createStructuralConstructResultResolver: (table: StructuralTypeTable, read: (node: ts.Node) => StructuralTypeId) => ((node: ts.Node) => StructuralTypeId | null);
+/** An unchecked call through known native alternatives returns their results. */
+export declare const createStructuralCallResultResolver: (_checker: ts.TypeChecker, table: StructuralTypeTable, read: (node: ts.Node) => StructuralTypeId) => ((node: ts.Node) => StructuralTypeId | null);

package/dist/semantics/normalize/structural-callable.js

@@ -0,0 +1,82 @@
+import ts from 'typescript';
+/** TypeScript's unchecked-call placeholder has no physical declaration. */
+export const isFabricatedSignatureShape = (checker, signature) => signature.declaration === undefined &&
+    signature.getParameters().length === 0 &&
+    (checker.getReturnTypeOfSignature(signature).flags & ts.TypeFlags.Any) !== 0;
+/** Every alternative must actually declare one callable frame. */
+export const structuralCallSignatures = (table, id, seen = new Set()) => {
+    if (seen.has(id))
+        return null;
+    const next = new Set(seen).add(id);
+    const shape = table.get(id).shape;
+    if (shape.kind === 'declared')
+        return shape.body ? structuralCallSignatures(table, shape.body, next) : null;
+    if (shape.kind === 'signature')
+        return shape.call.length === 1 && shape.construct.length === 0 ? shape.call : null;
+    if (shape.kind !== 'union')
+        return null;
+    const arms = shape.members.map((member) => structuralCallSignatures(table, member, next));
+    return arms.length && arms.every((arm) => arm !== null) ? arms.flatMap((arm) => arm ?? []) : null;
+};
+/** A native constructor choice returns every arm's instance, even when the checker merges their identical shapes. */
+export const createStructuralConstructResultResolver = (table, read) => {
+    const pending = new Set();
+    return (node) => {
+        if (!ts.isNewExpression(node) || pending.has(node))
+            return null;
+        pending.add(node);
+        try {
+            const callee = table.get(read(node.expression)).shape;
+            if (callee.kind !== 'union' || callee.members.length < 2)
+                return null;
+            const results = [];
+            for (const member of callee.members) {
+                if (table.isOpen(member))
+                    return null;
+                const arm = table.get(member).shape;
+                if (arm.kind !== 'class-constructor' || arm.construct === null || table.isOpen(arm.construct))
+                    return null;
+                const frame = table.get(arm.construct).shape;
+                if (frame.kind !== 'signature' || frame.construct.length !== 1)
+                    return null;
+                const signature = frame.construct[0];
+                if (!signature)
+                    return null;
+                results.push(signature.result);
+            }
+            return table.intern({ kind: 'union', members: results });
+        }
+        finally {
+            pending.delete(node);
+        }
+    };
+};
+/** An unchecked call through known native alternatives returns their results. */
+export const createStructuralCallResultResolver = (_checker, table, read) => {
+    const pending = new Set();
+    return (node) => {
+        if (!ts.isCallExpression(node) || node.questionDotToken || pending.has(node))
+            return null;
+        // Function.prototype.call/apply is generic in the library and loses the
+        // return when its receiver is a union with no joined signature. Read the
+        // authenticated callable receiver directly. Asking the checker to resolve
+        // every arbitrary call here recursively instantiated Hono's conditional
+        // route types until the host stack overflowed.
+        if (!ts.isPropertyAccessExpression(node.expression))
+            return null;
+        if (node.expression.name.text !== 'call' && node.expression.name.text !== 'apply')
+            return null;
+        pending.add(node);
+        const calls = structuralCallSignatures(table, read(node.expression.expression));
+        pending.delete(node);
+        if (!calls)
+            return null;
+        const members = calls.map((call) => {
+            const result = table.get(call.result).shape;
+            return result.kind === 'primitive' && result.primitive === 'void'
+                ? table.intern({ kind: 'primitive', primitive: 'undefined' })
+                : call.result;
+        });
+        return members.length === 1 ? (members[0] ?? null) : table.intern({ kind: 'union', members });
+    };
+};

package/dist/semantics/normalize/structural-creation-order.d.ts

@@ -0,0 +1,32 @@
+import ts from 'typescript';
+import { type ParameterBindingCensus } from './parameter-bindings.js';
+/**
+ * The order an object LITERAL creates its keys in, which is not the order
+ * TypeScript lists them.
+ *
+ * `{ ...base, ...extra }` runs `base`'s keys first, then `extra`'s, and a key
+ * both objects have keeps the position its FIRST insertion gave it. The
+ * checker's property table for that type comes back `age,name` while the
+ * runtime creates `name,age`: TypeScript's property order is an authority on
+ * the TYPE and not on enumeration, and the literal's own syntax is the only
+ * thing that states what the program builds.
+ *
+ * This is not a cosmetic difference. Member order is part of the structural
+ * interning key, so a wrong order mints a SECOND C++ struct for a type that
+ * already had one -- two shapes with the same members in two orders, and no
+ * conversion between them. It also reaches the emitted program directly:
+ * `records.ts` writes the member list out as the object's
+ * `gea_ownFieldKeys`, which is what `Object.keys` answers with.
+ *
+ * ⛔ The tempting shortcut is to sort the key canonically. That silently
+ * changes `Object.keys` for every program, because the order is genuinely
+ * READ rather than merely compared. Order stays in the key and is made
+ * correct here instead.
+ *
+ * Refuses -- leaving the checker's order untouched -- whenever it cannot
+ * account for the literal exactly: a key it cannot name, a spread whose
+ * operand it cannot walk, or any disagreement between the names the syntax
+ * produces and the members the type actually has. A partially-reconstructed
+ * order is a third answer, not a better one.
+ */
+export declare const creationOrderedProperties: (checker: ts.TypeChecker, type: ts.Type, parameters?: ParameterBindingCensus) => readonly ts.Symbol[];

package/dist/semantics/normalize/structural-creation-order.js

@@ -0,0 +1,111 @@
+import ts from 'typescript';
+import { censusedTypeAt } from './derived-expression-type.js';
+import { emptyParameterBindingCensus } from './parameter-bindings.js';
+/**
+ * The order an object LITERAL creates its keys in, which is not the order
+ * TypeScript lists them.
+ *
+ * `{ ...base, ...extra }` runs `base`'s keys first, then `extra`'s, and a key
+ * both objects have keeps the position its FIRST insertion gave it. The
+ * checker's property table for that type comes back `age,name` while the
+ * runtime creates `name,age`: TypeScript's property order is an authority on
+ * the TYPE and not on enumeration, and the literal's own syntax is the only
+ * thing that states what the program builds.
+ *
+ * This is not a cosmetic difference. Member order is part of the structural
+ * interning key, so a wrong order mints a SECOND C++ struct for a type that
+ * already had one -- two shapes with the same members in two orders, and no
+ * conversion between them. It also reaches the emitted program directly:
+ * `records.ts` writes the member list out as the object's
+ * `gea_ownFieldKeys`, which is what `Object.keys` answers with.
+ *
+ * ⛔ The tempting shortcut is to sort the key canonically. That silently
+ * changes `Object.keys` for every program, because the order is genuinely
+ * READ rather than merely compared. Order stays in the key and is made
+ * correct here instead.
+ *
+ * Refuses -- leaving the checker's order untouched -- whenever it cannot
+ * account for the literal exactly: a key it cannot name, a spread whose
+ * operand it cannot walk, or any disagreement between the names the syntax
+ * produces and the members the type actually has. A partially-reconstructed
+ * order is a third answer, not a better one.
+ */
+export const creationOrderedProperties = (checker, type, parameters = emptyParameterBindingCensus) => {
+    const properties = type.getProperties();
+    if (properties.length < 2)
+        return properties;
+    const declarations = type.getSymbol()?.declarations;
+    const literal = declarations?.length === 1 && declarations[0] && ts.isObjectLiteralExpression(declarations[0]) ? declarations[0] : null;
+    if (!literal)
+        return properties;
+    const order = [];
+    const seen = new Set();
+    const add = (name) => {
+        if (seen.has(name))
+            return;
+        seen.add(name);
+        order.push(name);
+    };
+    // Bounded because a spread's operand can be another literal, and a program
+    // is free to nest them; the depth that matters in practice is one or two,
+    // and an unbounded walk here would be a second recursion in a file whose
+    // termination argument is already about anchors.
+    const walk = (node, depth) => {
+        if (depth > 8)
+            return false;
+        for (const property of node.properties) {
+            if (ts.isSpreadAssignment(property)) {
+                // HOLDS: what the spread SOURCE expression evaluates to. A source
+                // the checker only resolves to `any` (e.g. an unannotated parameter's
+                // call-site evidence) used to fail this walk closed at the very next
+                // line (`getSymbol()` on `any` finds nothing, so the spread's keys
+                // were never accounted for and the whole reconstruction fell back to
+                // the checker's own unordered `properties`) -- asking the shared
+                // authority first lets a census answer recover the real order
+                // exactly where it already recovers the real TYPE.
+                const spread = censusedTypeAt(checker, parameters, property.expression);
+                const spreadDeclarations = spread.getSymbol()?.declarations;
+                const nested = spreadDeclarations?.length === 1 && spreadDeclarations[0] && ts.isObjectLiteralExpression(spreadDeclarations[0])
+                    ? spreadDeclarations[0]
+                    : null;
+                // A spread of something that is not a literal contributes its own
+                // members in the only order available for it -- the declared one,
+                // which for an interface or a class IS its creation order.
+                if (nested) {
+                    if (!walk(nested, depth + 1))
+                        return false;
+                }
+                else {
+                    for (const member of spread.getProperties())
+                        add(member.name);
+                }
+                continue;
+            }
+            const name = property.name;
+            if (!name)
+                return false;
+            if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+                add(name.text);
+            else
+                return false;
+        }
+        return true;
+    };
+    if (!walk(literal, 0))
+        return properties;
+    // The reconstruction must be a PERMUTATION of what the type reports. A
+    // literal whose syntax names a key the type does not have (or misses one it
+    // does) is one this walk did not understand, and reordering on a partial
+    // account would produce an order neither authority states.
+    const byName = new Map(properties.map((property) => [property.name, property]));
+    if (order.length !== properties.length)
+        return properties;
+    const reordered = [];
+    for (const name of order) {
+        const property = byName.get(name);
+        if (!property)
+            return properties;
+        reordered.push(property);
+    }
+    return reordered;
+};